> ## Documentation Index > Fetch the complete documentation index at: https://docs.useaira.com/llms.txt > Use this file to discover all available pages before exploring further. # Mark invoice as paid > Marks an issued one-off invoice as paid, for a payment made outside Aira. A paid invoice comes back as it is, so a retry is safe. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/invoices/{invoiceId}/pay openapi: 3.1.0 info: title: API Reference version: '1.0' description: Aira API Reference x-logo: url: https://static.useaira.com/images/airalogo.svg backgroundColor: '#FFFFFF' altText: Aira Logo servers: - url: https://api.useaira.com description: API base URL security: - ApiKey: [] paths: /v1/invoices/{invoiceId}/pay: post: tags: - Invoices summary: Mark invoice as paid description: >- Marks an issued one-off invoice as paid, for a payment made outside Aira. A paid invoice comes back as it is, so a retry is safe. parameters: - schema: type: string format: uuid in: path name: invoiceId required: true description: The unique identifier of the invoice to mark as paid. responses: '200': description: >- Schema representing an invoice. Monetary amounts are integers in cents. content: application/json: schema: type: object properties: id: type: string format: uuid description: The unique identifier of the invoice in our system. idempotencyKey: type: string description: >- A unique key that identifies the invoice for idempotent creation. Supplied by the caller for one-off invoices; generated by the billing engine for contract invoices. customerId: type: string format: uuid description: The unique identifier of the customer this invoice bills. paymentAccountId: type: string format: uuid description: >- The unique identifier of the customer payment account used as the billing account for this invoice. contractId: type: string nullable: true format: uuid description: >- The unique identifier of the contract that generated this invoice. Null for invoices not generated from a contract (e.g. one-off and imported invoices). contractInvoiceSequence: type: integer minimum: 1 nullable: true description: >- The number of the invoice within its contract, in the order that Aira created the contract's invoices: 1 for the first, 2 for the next, and so on. Every invoice gets its own number, including each invoice of a split across payment accounts and the replacement of a reopened invoice, and a number never changes and is never reused. Null for invoices without a contract. issuingAccount: type: object description: >- Snapshot of the legal entity issuing the invoice (the seller), captured at invoice creation. properties: tradeName: type: string nullable: true description: >- Trade name (nome fantasia) of the legal entity. Null when absent. businessName: type: string description: >- Registered business name (razão social) of the legal entity. emails: type: array items: type: string format: email description: Billing contact email addresses of the legal entity. taxId: type: string description: >- Tax identification number of the legal entity, digits only. example: '01234567000189' taxIdType: type: string enum: - cnpj - cpf description: >- The kind of tax identification number in taxId (e.g. CNPJ for Brazilian companies, CPF for individuals). zipCode: type: string nullable: true description: >- Postal code of the legal entity address. Null when absent. street: type: string nullable: true description: Street of the legal entity address. Null when absent. number: type: string nullable: true description: >- Street number of the legal entity address. Null when absent. neighborhood: type: string nullable: true description: >- Neighborhood of the legal entity address. Null when absent. city: type: string nullable: true description: City of the legal entity address. Null when absent. state: type: string enum: - AC - AL - AP - AM - BA - CE - DF - ES - GO - MA - MT - MS - MG - PA - PB - PR - PE - PI - RJ - RN - RS - RO - RR - SC - SP - SE - TO - null nullable: true description: >- State of the legal entity address, as a two-letter code. Null when absent. country: type: string enum: - Brasil - null nullable: true description: Country of the legal entity address. Null when absent. complement: type: string nullable: true description: >- Address complement of the legal entity address. Null when absent. required: - tradeName - businessName - emails - taxId - taxIdType - zipCode - street - number - neighborhood - city - state - country - complement additionalProperties: false billingAccount: type: object description: >- Snapshot of the billed party (the legal entity behind the customer payment account), captured at invoice creation. properties: tradeName: type: string nullable: true description: >- Trade name (nome fantasia) of the legal entity. Null when absent. businessName: type: string description: >- Registered business name (razão social) of the legal entity. emails: type: array items: type: string format: email description: Billing contact email addresses of the legal entity. taxId: type: string description: >- Tax identification number of the legal entity, digits only. example: '01234567000189' taxIdType: type: string enum: - cnpj - cpf description: >- The kind of tax identification number in taxId (e.g. CNPJ for Brazilian companies, CPF for individuals). zipCode: type: string nullable: true description: >- Postal code of the legal entity address. Null when absent. street: type: string nullable: true description: Street of the legal entity address. Null when absent. number: type: string nullable: true description: >- Street number of the legal entity address. Null when absent. neighborhood: type: string nullable: true description: >- Neighborhood of the legal entity address. Null when absent. city: type: string nullable: true description: City of the legal entity address. Null when absent. state: type: string enum: - AC - AL - AP - AM - BA - CE - DF - ES - GO - MA - MT - MS - MG - PA - PB - PR - PE - PI - RJ - RN - RS - RO - RR - SC - SP - SE - TO - null nullable: true description: >- State of the legal entity address, as a two-letter code. Null when absent. country: type: string enum: - Brasil - null nullable: true description: Country of the legal entity address. Null when absent. complement: type: string nullable: true description: >- Address complement of the legal entity address. Null when absent. required: - tradeName - businessName - emails - taxId - taxIdType - zipCode - street - number - neighborhood - city - state - country - complement additionalProperties: false invoiceAllocationStrategy: type: string enum: - single - percent_split - subsidiary_usage_split description: >- How the originating contract distributes charges across payment accounts: single bills a single payment account; percent_split divides the total between payment accounts by configured percentages; subsidiary_usage_split divides it according to each subsidiary's usage. lastCalculatedAt: type: string format: date-time nullable: true description: >- When the invoice amounts were last computed by the billing engine. Null when the invoice has never been calculated. invoiceNumber: type: string description: >- Human-readable invoice number, built from the customer's invoice prefix plus a sequential counter. example: ACMEI-0042 invoiceDate: type: string format: date description: >- The date of the invoice. On a contract invoice it is the date of its billing act: the first day of the first billing cycle that the contract invoices for an activation invoice, and the last day of the billing cycle for a closing invoice. Its line items state the periods that it bills. On a one-off or imported invoice it is the date given when the invoice was created. memo: type: string nullable: true description: >- Free-form memo attached to the invoice. On contract invoices, it reads "Período a " with the period of the line item that bills most often, such as the month when a monthly fee is billed with an annual fee. When two line items bill equally often, it uses the earlier period. Null when absent. subtotalAmount: type: number description: >- Sum of the line item subtotals before adjustments, in cents. adjustmentAmount: type: number description: >- Net amount of all adjustments applied to the invoice line items (discounts and allocation offsets), in cents. Negative when adjustments reduce the amount owed. totalAmount: type: number description: >- Final invoice amount, in cents: subtotalAmount + adjustmentAmount. discountAmount: type: number description: >- The discount portion of adjustmentAmount, in cents (sum of monetary discount adjustments only). Negative when discounts were applied. status: type: string enum: - open - in_review - issued - synced - pending - paid - overdue - canceled - failed description: >- Current status of the invoice lifecycle: open (accumulating charges, editable), in_review (flagged for manual review before issuing), issued (finalized and issued to the customer), synced (registered in the external ERP/payment provider), pending (a payment was initiated and awaits settlement), paid, overdue (unpaid past the due date), canceled, or failed (an issue/sync attempt failed and needs attention). isLocked: type: boolean description: >- Whether the invoice contents are locked against edits. Derived from status: issued, synced, pending, paid, overdue, and canceled invoices are locked; open, in_review, and failed invoices are editable. failureReason: type: string nullable: true description: >- Reason for the most recent failure on the invoice (e.g. an ERP sync or payment issue). Null when the invoice has no active failure. source: type: string enum: - contract - one_off - import description: >- How the invoice originated: contract (generated by a contract billing cycle), one_off (created manually or through the API), or import (ingested from an external system). autoIssue: type: boolean description: >- Whether the invoice is issued automatically when its billing cycle closes, without manual review. amountDue: type: number nullable: true description: >- Outstanding amount due on the invoice, in cents. Null when not tracked. dueDate: type: string format: date nullable: true description: >- Payment due date of the invoice. Null when no due date is set (e.g. before the invoice is issued). lineItemGroups: type: array items: type: object description: >- Schema representing a line item group: a container that gathers the line items generated from one plan instance (or created as a group on one-off invoices). Monetary amounts are integers in cents. properties: id: type: string format: uuid description: >- The unique identifier of the line item group in our system. idempotencyKey: type: string description: >- A unique key that identifies the group within the invoice. Supplied by the caller for one-off groups; generated by the billing engine otherwise. customerId: type: string format: uuid description: >- The unique identifier of the customer whose consumption this group bills. productId: type: string format: uuid description: >- The unique identifier of the product this group belongs to. planId: type: string nullable: true format: uuid description: >- The unique identifier of the plan whose instance generated this group. Null for groups not generated from a plan (e.g. on one-off invoices). planInstanceId: type: string nullable: true format: uuid description: >- The unique identifier of the plan instance that generated this group. Null for groups not generated from a plan instance. name: type: string description: >- Display name of the group as it appears on the invoice, typically the plan or product name. startDate: type: string format: date description: >- Start of the period that the group shows. On contract invoices, it is the period of the group's line item that bills most often, such as the month when a monthly fee is billed with an annual fee. When two line items bill equally often, it is the earlier period. endDate: type: string format: date description: >- End of the period that the group shows, which `startDate` describes. subtotalAmount: type: number description: >- Sum of the group's line item subtotals before adjustments, in cents. adjustmentAmount: type: number description: >- Net amount of the adjustments applied to the group's line items (discounts and allocation offsets), in cents. Negative when adjustments reduce the amount owed. totalAmount: type: number description: >- Final group amount, in cents: subtotalAmount + adjustmentAmount. discountAmount: type: number description: >- The discount portion of adjustmentAmount, in cents (sum of monetary discount adjustments only). Negative when discounts were applied. lineItems: type: array items: type: object description: >- Schema representing an invoice line item. Monetary amounts are integers in cents; the price breakdown lives in subLineItems. properties: id: type: string format: uuid description: >- The unique identifier of the line item in our system. idempotencyKey: type: string description: >- A unique key that identifies the line item within the invoice. Supplied by the caller for one-off line items; generated by the billing engine otherwise. customerId: type: string format: uuid description: >- The unique identifier of the customer whose consumption this line item bills. On split or consolidated invoices it may be a subsidiary of the invoice's customer. productId: type: string format: uuid description: >- The unique identifier of the product this line item belongs to. itemId: type: string nullable: true format: uuid description: >- The unique identifier of the catalog item this line bills. Null for line items not backed by a catalog item. resourceId: type: string nullable: true format: uuid description: >- The unique identifier of the metered resource behind a usage_based line item. Null for line items not driven by resource usage. licenseId: type: string nullable: true format: uuid description: >- The unique identifier of the license behind a license_based line item. Null for line items not driven by a license count. lineItemGroupId: type: string nullable: true format: uuid description: >- The unique identifier of the line item group containing this line item. Null for standalone line items. name: type: string description: >- Display name of the line item as it appears on the invoice. scope: type: string enum: - credit_purchase - contract_minimum_commitment - minimum_commitment - fixed - usage_based - license_based - additional_charge - one_off - tax_gross_up description: >- What the line item charges for: usage_based (metered resource consumption), license_based (a license's reported count billed in full), fixed (recurring fixed charge of a plan), minimum_commitment (plan-level minimum top-up), contract_minimum_commitment (contract-level minimum top-up), credit_purchase (credit pool top-up), additional_charge (extra charge added manually), one_off (line item of a one-off invoice), or tax_gross_up (tax gross-up charge). startDate: type: string format: date description: Start of the period covered by this line item. endDate: type: string format: date description: End of the period covered by this line item. totalUsage: type: number nullable: true description: >- Total usage billed by the line item, in the unit given by usageFormat. Null for line items without usage (e.g. fixed charges without a quantity). usageFormat: type: string enum: - unit - currency - null nullable: true description: >- How to read totalUsage and the sub-line usage values: unit means a count of resource units or a fixed charge quantity; currency means a monetary base amount in cents. Null when the line item has no usage. subtotalAmount: type: number description: >- Line item amount before adjustments, in cents (sum of its sub-line item amounts). adjustmentAmount: type: number description: >- Net amount of the adjustments applied to this line item (discounts and allocation offsets), in cents. Negative when adjustments reduce the amount owed. totalAmount: type: number description: >- Final line item amount, in cents: subtotalAmount + adjustmentAmount. discountAmount: type: number description: >- The discount portion of adjustmentAmount, in cents (sum of monetary discount adjustments only). Negative when discounts were applied. metadata: description: >- Pricing metadata for the line item, where the shape is keyed by type. Always present, but null for line items without pricing metadata: credit_purchase, additional_charge, one_off, and tax_gross_up. It is populated for fixed (the billing timing), usage_based, license_based, minimum_commitment, and contract_minimum_commitment line items. anyOf: - title: Fixed type: object properties: type: type: string enum: - fixed description: >- Discriminator: metadata for a fixed line item. billingTiming: type: string enum: - in_advance - in_arrears description: >- Whether the fee was billed in advance of its service period or after it. required: - type - billingTiming - title: Usage-based type: object properties: type: type: string enum: - usage_based description: >- Discriminator: metadata for a usage_based line item. billingModel: type: string enum: - in_full - proration description: >- How the metered resource accrues over the billing period: in_full bills the full usage of the period; proration weighs usage by the fraction of the period each amount was held. priceTierDivision: type: string enum: - unique_tier - progressive description: >- For tier-based pricing models only: how usage was divided across tiers. unique_tier prices all usage at the single tier that contains the total; progressive prices each tier's band separately. Absent for non-tiered models. pricingModel: type: string enum: - fixed - per_unit - per_package - percentage - tiered_per_unit - tiered_percentage - tiered_fixed - advanced - custom description: >- The pricing model of the plan charge that produced this line item. Charges priced before pricing models existed are reported as advanced. required: - type - billingModel - pricingModel - title: License-based type: object properties: type: type: string enum: - license_based description: >- Discriminator: metadata for a license_based line item. billingModel: type: string enum: - in_full - proration description: >- How the license count accrues over the billing period. Always in_full: the latest reported count is billed in full. priceTierDivision: type: string enum: - unique_tier - progressive description: >- For tier-based pricing models only: how the license count was divided across tiers. unique_tier prices the whole count at the single tier that contains the total; progressive prices each tier's band separately. Absent for non-tiered models. pricingModel: type: string enum: - fixed - per_unit - per_package - percentage - tiered_per_unit - tiered_percentage - tiered_fixed - advanced - custom description: >- The pricing model of the plan charge that produced this line item. required: - type - billingModel - pricingModel - title: Contract minimum commitment type: object properties: type: type: string enum: - contract_minimum_commitment description: >- Discriminator: metadata for a contract_minimum_commitment line item. minimumAmount: type: number description: >- The minimum amount committed for the whole contract in the billing period, in cents. minimumAmountApplied: type: number description: >- The top-up charged by this line item to reach the committed minimum, in cents: the difference between minimumAmount and what the contract's consumption amounted to. required: - type - minimumAmount - minimumAmountApplied - title: Minimum commitment type: object properties: type: type: string enum: - minimum_commitment description: >- Discriminator: metadata for a plan-level minimum_commitment line item. minimumAmount: type: number description: >- The minimum amount committed for the plan in the billing period, in cents. minimumAmountApplied: type: number description: >- The top-up charged by this line item to reach the committed minimum, in cents: the difference between minimumAmount and what the plan's consumption amounted to. required: - type - minimumAmount - minimumAmountApplied - title: No metadata type: 'null' subLineItems: type: array items: type: object description: >- Schema representing a sub-line item: one priced row of a line item's breakdown. The row type dictates the shape of metadata. properties: id: type: string format: uuid description: >- The unique identifier of the sub-line item in our system. type: type: string enum: - fixed_price - minimum_amount - price_tier_flat - price_tier_unit - price_tier_package - price_tier_percentage - proration - license_proration - license_proration_tier - unit_price - included_quantity - package_price - percentage - overage - original_amount - fixed_unit_price description: >- The kind of priced row: fixed_price and minimum_amount are companions of usage-based charges; unit_price, package_price, percentage, and included_quantity break down single-model pricing; price_tier_* rows break down tiered pricing; overage bills usage beyond the last tier; proration bills per prorated interval; license_proration bills license deltas (removals are negative); original_amount surfaces the pre-adjustment amount of an adjusted line; fixed_unit_price breaks down a fixed charge billed as a quantity times a unit amount. name: type: string description: >- Display name of the sub-line item as it appears on the invoice breakdown. description: type: string nullable: true description: >- Optional descriptive text for the row. Null when absent. usage: type: number nullable: true description: >- The usage billed by this row: a count of resource units (the quantity for a fixed_unit_price row), or a monetary base amount in cents for percentage-priced rows (see the line item usageFormat). Null for rows without usage (e.g. companions). amount: type: number description: >- Amount billed by this row, in cents. The sum of a line item's sub-line amounts equals its subtotalAmount. metadata: description: >- Pricing details of the row, keyed by the row type (and pricingType for overage rows). anyOf: - type: object description: >- Fixed-price companion row: the charge's configured fixed amount, billed alongside the usage rows. Only rendered when configured greater than zero. properties: type: type: string enum: - fixed_price description: >- Discriminator: fixed-price companion row. fixedPrice: type: number description: >- The fixed amount configured on the charge, in cents. required: - type - fixedPrice - type: object description: >- Minimum-amount companion row: tops the charge up to its configured minimum when usage alone stays below it. Only rendered when the top-up is greater than zero. properties: type: type: string enum: - minimum_amount description: >- Discriminator: minimum-amount companion row. minimumAmount: type: number description: >- The minimum amount configured on the charge, in cents. minimumAmountApplied: type: number description: >- The top-up billed by this row to reach the configured minimum, in cents. required: - type - minimumAmount - minimumAmountApplied - type: object description: >- Flat-priced tier row: usage falling in this tier band is billed at a flat amount, regardless of the exact quantity. properties: type: type: string enum: - price_tier_flat description: 'Discriminator: flat-priced tier row.' from: type: number description: >- Lower bound of the tier band, in resource units (inclusive). to: type: number nullable: true description: >- Upper bound of the tier band, in resource units (inclusive). Null for an unbounded final tier. fixedPrice: type: string description: >- The flat amount billed for the tier, as a decimal currency-unit string. required: - type - from - to - fixedPrice - type: object description: >- Per-unit priced tier row: units attributed to this tier band are billed at the tier's unit price. properties: type: type: string enum: - price_tier_unit description: 'Discriminator: per-unit priced tier row.' from: type: number description: >- Lower bound of the tier band, in resource units (inclusive). to: type: number nullable: true description: >- Upper bound of the tier band, in resource units (inclusive). Null for an unbounded final tier. price: type: string description: >- Price per unit within the tier, as a decimal currency-unit string. fixedPrice: type: string nullable: true description: >- Optional flat fee billed on top when the tier applies, as a decimal currency-unit string. Null when the tier has no flat fee. required: - type - from - to - price - fixedPrice - type: object description: >- Package-priced tier row: units attributed to this tier band are billed per started package of packageSize units. properties: type: type: string enum: - price_tier_package description: 'Discriminator: package-priced tier row.' from: type: number description: >- Lower bound of the tier band, in resource units (inclusive). to: type: number nullable: true description: >- Upper bound of the tier band, in resource units (inclusive). Null for an unbounded final tier. packageSize: type: number description: Number of resource units per package. price: type: string description: >- Price per package, as a decimal currency-unit string. required: - type - from - to - packageSize - price - type: object description: >- Percentage-priced tier row: the monetary base amount attributed to this tier band is billed at a percentage. properties: type: type: string enum: - price_tier_percentage description: >- Discriminator: percentage-priced tier row. from: type: number description: >- Lower bound of the tier band, in cents of the monetary base amount (inclusive). to: type: number nullable: true description: >- Upper bound of the tier band, in cents of the monetary base amount (inclusive). Null for an unbounded final tier. percentage: type: string pattern: ^(100(\.0{1,6})?|\d{1,2}(\.\d{1,6})?)$ description: >- Percentage applied to the base amount within the tier, as a decimal string from 0 to 100 (up to 6 decimal places). required: - type - from - to - percentage - type: object description: >- Proration interval row: for charges on prorated resources, each interval bills the usage held during it, priced as if held for the whole cycle and scaled by the interval's share of the cycle. properties: type: type: string enum: - proration description: 'Discriminator: proration interval row.' intervalSize: type: number description: >- Length of the interval, in days of the billing cycle. amount: type: string description: >- The prorated amount of the interval, as a decimal currency-unit string: the interval usage priced as if held for the whole cycle, scaled by intervalSize over the cycle length. usage: type: number description: The usage held during the interval. intervalStart: type: string format: date description: First day of the interval. intervalEnd: type: string format: date description: Last day of the interval. required: - type - intervalSize - amount - usage - intervalStart - intervalEnd - type: object description: >- License proration delta row: for per_unit license charges billing under the proration model, the cycle-start row bills the starting quantity at its full-cycle price, and each change row bills the quantity delta prorated over the days remaining in the cycle. Tiered charges use license_proration_tier instead. quantityDelta and the row's amount are signed — removals are negative. properties: type: type: string enum: - license_proration description: >- Discriminator: license proration delta row. changeDate: type: string format: date nullable: true description: >- The day the combined license quantity changed. Null on the cycle-start row. quantityDelta: type: number description: >- Signed change in the combined license quantity (the starting quantity on the cycle-start row). Negative for removals. quantity: type: number description: >- The combined license quantity after this change. remainingDays: type: number description: >- Days from the change (inclusive) to the end of the cycle. Equals cycleDays on the cycle-start row. cycleDays: type: number description: Length of the billing cycle, in days. proratedUnitRate: type: string description: >- Absolute effective per-unit rate of the row over the remaining window, as a decimal currency-unit string: |amount| / |quantityDelta|. amount: type: string description: >- The signed prorated amount of the row, as a decimal currency-unit string. required: - type - changeDate - quantityDelta - quantity - remainingDays - cycleDays - proratedUnitRate - amount - type: object description: >- Tiered license proration delta row: one price band of a license charge billing under the proration model with tiered_per_unit pricing. The cycle-start rows bill each band's opening occupancy at its full-cycle unit price, and each change row bills that band's occupancy delta prorated over the days remaining in the cycle. quantityDelta and the row's amount are signed — removals are negative. properties: type: type: string enum: - license_proration_tier description: >- Discriminator: tiered license proration delta row. changeDate: type: string format: date nullable: true description: >- The day the combined license quantity changed. Null on a cycle-start row. quantityDelta: type: number description: >- Signed change in the units this band holds (the band's opening occupancy on a cycle-start row). Negative for removals. quantity: type: number description: >- The combined license quantity across every band after this change. remainingDays: type: number description: >- Days from the change (inclusive) to the end of the cycle. Equals cycleDays on a cycle-start row. cycleDays: type: number description: Length of the billing cycle, in days. proratedUnitRate: type: string description: >- Absolute effective per-unit rate of the row over the remaining window, as a decimal currency-unit string: |amount| / |quantityDelta|. amount: type: string description: >- The signed prorated amount of the row, as a decimal currency-unit string. planChargeTierId: type: string description: >- The unique identifier of the plan charge tier this row moved through. from: type: number description: >- Inclusive lower bound of the band, in licenses. to: type: number nullable: true description: >- Inclusive upper bound of the band, in licenses. Null on the last, open-ended band. unitPrice: type: string description: >- The band's full-cycle price per unit, as a decimal currency-unit string. proratedUnitRate is this scaled by remainingDays over cycleDays. required: - type - changeDate - quantityDelta - quantity - remainingDays - cycleDays - proratedUnitRate - amount - planChargeTierId - from - to - unitPrice - type: object description: >- Unit-price row: billable units multiplied by a single price per unit. The row's usage holds the billable units. properties: type: type: string enum: - unit_price description: 'Discriminator: unit-price row.' price: type: string pattern: ^\d+(\.\d{1,6})?$ description: >- Price per unit, as a decimal currency-unit string (up to 6 decimal places). required: - type - price - type: object description: >- Included-quantity row: the free allotment of the charge. The row's usage holds the units consumed within the allotment and its amount is always zero. properties: type: type: string enum: - included_quantity description: 'Discriminator: included-quantity row.' includedQuantity: type: number description: >- Number of resource units included at no charge before billing starts. required: - type - includedQuantity - type: object description: >- Package-price row: billable units charged per started package of packageSize units. The row's usage holds the billable units. properties: type: type: string enum: - package_price description: 'Discriminator: package-price row.' packageSize: type: number description: Number of resource units per package. price: type: string pattern: ^\d+(\.\d{1,6})?$ description: >- Price per package, as a decimal currency-unit string (up to 6 decimal places). packagesBilled: type: number description: >- Number of packages billed: the billable units divided by packageSize, rounded up. required: - type - packageSize - price - packagesBilled - type: object description: >- Percentage row: a percentage applied over a monetary base amount. The row's usage holds the base amount, in cents. properties: type: type: string enum: - percentage description: 'Discriminator: percentage row.' percentage: type: string pattern: ^(100(\.0{1,6})?|\d{1,2}(\.\d{1,6})?)$ description: >- Percentage applied to the base amount, as a decimal string from 0 to 100 (up to 6 decimal places). required: - type - percentage - type: object description: >- Per-unit overage row: units beyond the last tier boundary, billed at the configured excess unit price. The row's usage holds the units over the boundary. properties: type: type: string enum: - overage description: 'Discriminator: overage row.' pricingType: type: string enum: - per_unit description: 'Discriminator: overage billed per unit.' from: type: number description: >- The boundary the overage starts from: the upper bound of the last tier, in resource units. price: type: string pattern: ^\d+(\.\d{1,6})?$ description: >- Price per excess unit, as a decimal currency-unit string (up to 6 decimal places). required: - type - pricingType - from - price - type: object description: >- Percentage overage row: the monetary base amount beyond the last tier boundary, billed at the configured excess percentage. The row's usage holds the base amount over the boundary, in cents. properties: type: type: string enum: - overage description: 'Discriminator: overage row.' pricingType: type: string enum: - percentage description: >- Discriminator: overage billed as a percentage. from: type: number description: >- The boundary the overage starts from: the upper bound of the last tier, in cents of the monetary base amount. percentage: type: string pattern: ^(100(\.0{1,6})?|\d{1,2}(\.\d{1,6})?)$ description: >- Percentage applied to the excess base amount, as a decimal string from 0 to 100 (up to 6 decimal places). required: - type - pricingType - from - percentage - type: object description: >- Original-amount row: surfaces the line item's pre-adjustment amount when the line has adjustments (e.g. a discount) but no price-component rows of its own. The row's amount equals the line item's subtotalAmount. properties: type: type: string enum: - original_amount description: 'Discriminator: original-amount row.' required: - type - type: object description: >- Fixed unit price row: the quantity of a fixed charge multiplied by its unit amount. The row's usage holds the quantity. properties: type: type: string enum: - fixed_unit_price description: 'Discriminator: fixed unit price row.' amount: type: integer minimum: 0 description: Amount of one unit, in cents. required: - type - amount required: - id - type - name - description - usage - amount - metadata additionalProperties: false description: >- Breakdown of the line item amount into priced rows (included quantities, unit/package/tier prices, prorations, companions). Empty for line items without a breakdown. adjustments: type: array items: type: object description: >- Schema representing an adjustment applied on top of a line item subtotal, such as a discount or an allocation offset. properties: id: type: string format: uuid description: >- The unique identifier of the adjustment in our system. name: type: string description: >- Display name of the adjustment as it appears on the invoice. type: type: string enum: - monetary_discount - allocation_offset description: >- The kind of adjustment: monetary_discount (a discount applied to the line item) or allocation_offset (the share of the amount moved to another payment account's invoice under a split allocation strategy). amount: type: number description: >- Amount of the adjustment, in cents. Negative when the adjustment reduces the line item total. required: - id - name - type - amount additionalProperties: false description: >- Adjustments applied on top of the line item subtotal, such as discounts and allocation offsets. required: - id - idempotencyKey - customerId - productId - resourceId - licenseId - lineItemGroupId - name - scope - startDate - endDate - totalUsage - usageFormat - subtotalAmount - adjustmentAmount - totalAmount - discountAmount - metadata - subLineItems - adjustments additionalProperties: false description: The line items contained in this group. required: - id - idempotencyKey - customerId - productId - planId - planInstanceId - name - startDate - endDate - subtotalAmount - adjustmentAmount - totalAmount - discountAmount - lineItems additionalProperties: false description: >- Line item groups on the invoice. Each group gathers the line items generated from one plan instance (or created as a group on one-off invoices). standaloneLineItems: type: array items: type: object description: >- Schema representing an invoice line item. Monetary amounts are integers in cents; the price breakdown lives in subLineItems. properties: id: type: string format: uuid description: >- The unique identifier of the line item in our system. idempotencyKey: type: string description: >- A unique key that identifies the line item within the invoice. Supplied by the caller for one-off line items; generated by the billing engine otherwise. customerId: type: string format: uuid description: >- The unique identifier of the customer whose consumption this line item bills. On split or consolidated invoices it may be a subsidiary of the invoice's customer. productId: type: string format: uuid description: >- The unique identifier of the product this line item belongs to. itemId: type: string nullable: true format: uuid description: >- The unique identifier of the catalog item this line bills. Null for line items not backed by a catalog item. resourceId: type: string nullable: true format: uuid description: >- The unique identifier of the metered resource behind a usage_based line item. Null for line items not driven by resource usage. licenseId: type: string nullable: true format: uuid description: >- The unique identifier of the license behind a license_based line item. Null for line items not driven by a license count. lineItemGroupId: type: string nullable: true format: uuid description: >- The unique identifier of the line item group containing this line item. Null for standalone line items. name: type: string description: >- Display name of the line item as it appears on the invoice. scope: type: string enum: - credit_purchase - contract_minimum_commitment - minimum_commitment - fixed - usage_based - license_based - additional_charge - one_off - tax_gross_up description: >- What the line item charges for: usage_based (metered resource consumption), license_based (a license's reported count billed in full), fixed (recurring fixed charge of a plan), minimum_commitment (plan-level minimum top-up), contract_minimum_commitment (contract-level minimum top-up), credit_purchase (credit pool top-up), additional_charge (extra charge added manually), one_off (line item of a one-off invoice), or tax_gross_up (tax gross-up charge). startDate: type: string format: date description: Start of the period covered by this line item. endDate: type: string format: date description: End of the period covered by this line item. totalUsage: type: number nullable: true description: >- Total usage billed by the line item, in the unit given by usageFormat. Null for line items without usage (e.g. fixed charges without a quantity). usageFormat: type: string enum: - unit - currency - null nullable: true description: >- How to read totalUsage and the sub-line usage values: unit means a count of resource units or a fixed charge quantity; currency means a monetary base amount in cents. Null when the line item has no usage. subtotalAmount: type: number description: >- Line item amount before adjustments, in cents (sum of its sub-line item amounts). adjustmentAmount: type: number description: >- Net amount of the adjustments applied to this line item (discounts and allocation offsets), in cents. Negative when adjustments reduce the amount owed. totalAmount: type: number description: >- Final line item amount, in cents: subtotalAmount + adjustmentAmount. discountAmount: type: number description: >- The discount portion of adjustmentAmount, in cents (sum of monetary discount adjustments only). Negative when discounts were applied. metadata: description: >- Pricing metadata for the line item, where the shape is keyed by type. Always present, but null for line items without pricing metadata: credit_purchase, additional_charge, one_off, and tax_gross_up. It is populated for fixed (the billing timing), usage_based, license_based, minimum_commitment, and contract_minimum_commitment line items. anyOf: - title: Fixed type: object properties: type: type: string enum: - fixed description: >- Discriminator: metadata for a fixed line item. billingTiming: type: string enum: - in_advance - in_arrears description: >- Whether the fee was billed in advance of its service period or after it. required: - type - billingTiming - title: Usage-based type: object properties: type: type: string enum: - usage_based description: >- Discriminator: metadata for a usage_based line item. billingModel: type: string enum: - in_full - proration description: >- How the metered resource accrues over the billing period: in_full bills the full usage of the period; proration weighs usage by the fraction of the period each amount was held. priceTierDivision: type: string enum: - unique_tier - progressive description: >- For tier-based pricing models only: how usage was divided across tiers. unique_tier prices all usage at the single tier that contains the total; progressive prices each tier's band separately. Absent for non-tiered models. pricingModel: type: string enum: - fixed - per_unit - per_package - percentage - tiered_per_unit - tiered_percentage - tiered_fixed - advanced - custom description: >- The pricing model of the plan charge that produced this line item. Charges priced before pricing models existed are reported as advanced. required: - type - billingModel - pricingModel - title: License-based type: object properties: type: type: string enum: - license_based description: >- Discriminator: metadata for a license_based line item. billingModel: type: string enum: - in_full - proration description: >- How the license count accrues over the billing period. Always in_full: the latest reported count is billed in full. priceTierDivision: type: string enum: - unique_tier - progressive description: >- For tier-based pricing models only: how the license count was divided across tiers. unique_tier prices the whole count at the single tier that contains the total; progressive prices each tier's band separately. Absent for non-tiered models. pricingModel: type: string enum: - fixed - per_unit - per_package - percentage - tiered_per_unit - tiered_percentage - tiered_fixed - advanced - custom description: >- The pricing model of the plan charge that produced this line item. required: - type - billingModel - pricingModel - title: Contract minimum commitment type: object properties: type: type: string enum: - contract_minimum_commitment description: >- Discriminator: metadata for a contract_minimum_commitment line item. minimumAmount: type: number description: >- The minimum amount committed for the whole contract in the billing period, in cents. minimumAmountApplied: type: number description: >- The top-up charged by this line item to reach the committed minimum, in cents: the difference between minimumAmount and what the contract's consumption amounted to. required: - type - minimumAmount - minimumAmountApplied - title: Minimum commitment type: object properties: type: type: string enum: - minimum_commitment description: >- Discriminator: metadata for a plan-level minimum_commitment line item. minimumAmount: type: number description: >- The minimum amount committed for the plan in the billing period, in cents. minimumAmountApplied: type: number description: >- The top-up charged by this line item to reach the committed minimum, in cents: the difference between minimumAmount and what the plan's consumption amounted to. required: - type - minimumAmount - minimumAmountApplied - title: No metadata type: 'null' subLineItems: type: array items: type: object description: >- Schema representing a sub-line item: one priced row of a line item's breakdown. The row type dictates the shape of metadata. properties: id: type: string format: uuid description: >- The unique identifier of the sub-line item in our system. type: type: string enum: - fixed_price - minimum_amount - price_tier_flat - price_tier_unit - price_tier_package - price_tier_percentage - proration - license_proration - license_proration_tier - unit_price - included_quantity - package_price - percentage - overage - original_amount - fixed_unit_price description: >- The kind of priced row: fixed_price and minimum_amount are companions of usage-based charges; unit_price, package_price, percentage, and included_quantity break down single-model pricing; price_tier_* rows break down tiered pricing; overage bills usage beyond the last tier; proration bills per prorated interval; license_proration bills license deltas (removals are negative); original_amount surfaces the pre-adjustment amount of an adjusted line; fixed_unit_price breaks down a fixed charge billed as a quantity times a unit amount. name: type: string description: >- Display name of the sub-line item as it appears on the invoice breakdown. description: type: string nullable: true description: >- Optional descriptive text for the row. Null when absent. usage: type: number nullable: true description: >- The usage billed by this row: a count of resource units (the quantity for a fixed_unit_price row), or a monetary base amount in cents for percentage-priced rows (see the line item usageFormat). Null for rows without usage (e.g. companions). amount: type: number description: >- Amount billed by this row, in cents. The sum of a line item's sub-line amounts equals its subtotalAmount. metadata: description: >- Pricing details of the row, keyed by the row type (and pricingType for overage rows). anyOf: - type: object description: >- Fixed-price companion row: the charge's configured fixed amount, billed alongside the usage rows. Only rendered when configured greater than zero. properties: type: type: string enum: - fixed_price description: >- Discriminator: fixed-price companion row. fixedPrice: type: number description: >- The fixed amount configured on the charge, in cents. required: - type - fixedPrice - type: object description: >- Minimum-amount companion row: tops the charge up to its configured minimum when usage alone stays below it. Only rendered when the top-up is greater than zero. properties: type: type: string enum: - minimum_amount description: >- Discriminator: minimum-amount companion row. minimumAmount: type: number description: >- The minimum amount configured on the charge, in cents. minimumAmountApplied: type: number description: >- The top-up billed by this row to reach the configured minimum, in cents. required: - type - minimumAmount - minimumAmountApplied - type: object description: >- Flat-priced tier row: usage falling in this tier band is billed at a flat amount, regardless of the exact quantity. properties: type: type: string enum: - price_tier_flat description: 'Discriminator: flat-priced tier row.' from: type: number description: >- Lower bound of the tier band, in resource units (inclusive). to: type: number nullable: true description: >- Upper bound of the tier band, in resource units (inclusive). Null for an unbounded final tier. fixedPrice: type: string description: >- The flat amount billed for the tier, as a decimal currency-unit string. required: - type - from - to - fixedPrice - type: object description: >- Per-unit priced tier row: units attributed to this tier band are billed at the tier's unit price. properties: type: type: string enum: - price_tier_unit description: 'Discriminator: per-unit priced tier row.' from: type: number description: >- Lower bound of the tier band, in resource units (inclusive). to: type: number nullable: true description: >- Upper bound of the tier band, in resource units (inclusive). Null for an unbounded final tier. price: type: string description: >- Price per unit within the tier, as a decimal currency-unit string. fixedPrice: type: string nullable: true description: >- Optional flat fee billed on top when the tier applies, as a decimal currency-unit string. Null when the tier has no flat fee. required: - type - from - to - price - fixedPrice - type: object description: >- Package-priced tier row: units attributed to this tier band are billed per started package of packageSize units. properties: type: type: string enum: - price_tier_package description: 'Discriminator: package-priced tier row.' from: type: number description: >- Lower bound of the tier band, in resource units (inclusive). to: type: number nullable: true description: >- Upper bound of the tier band, in resource units (inclusive). Null for an unbounded final tier. packageSize: type: number description: Number of resource units per package. price: type: string description: >- Price per package, as a decimal currency-unit string. required: - type - from - to - packageSize - price - type: object description: >- Percentage-priced tier row: the monetary base amount attributed to this tier band is billed at a percentage. properties: type: type: string enum: - price_tier_percentage description: >- Discriminator: percentage-priced tier row. from: type: number description: >- Lower bound of the tier band, in cents of the monetary base amount (inclusive). to: type: number nullable: true description: >- Upper bound of the tier band, in cents of the monetary base amount (inclusive). Null for an unbounded final tier. percentage: type: string pattern: ^(100(\.0{1,6})?|\d{1,2}(\.\d{1,6})?)$ description: >- Percentage applied to the base amount within the tier, as a decimal string from 0 to 100 (up to 6 decimal places). required: - type - from - to - percentage - type: object description: >- Proration interval row: for charges on prorated resources, each interval bills the usage held during it, priced as if held for the whole cycle and scaled by the interval's share of the cycle. properties: type: type: string enum: - proration description: 'Discriminator: proration interval row.' intervalSize: type: number description: >- Length of the interval, in days of the billing cycle. amount: type: string description: >- The prorated amount of the interval, as a decimal currency-unit string: the interval usage priced as if held for the whole cycle, scaled by intervalSize over the cycle length. usage: type: number description: The usage held during the interval. intervalStart: type: string format: date description: First day of the interval. intervalEnd: type: string format: date description: Last day of the interval. required: - type - intervalSize - amount - usage - intervalStart - intervalEnd - type: object description: >- License proration delta row: for per_unit license charges billing under the proration model, the cycle-start row bills the starting quantity at its full-cycle price, and each change row bills the quantity delta prorated over the days remaining in the cycle. Tiered charges use license_proration_tier instead. quantityDelta and the row's amount are signed — removals are negative. properties: type: type: string enum: - license_proration description: >- Discriminator: license proration delta row. changeDate: type: string format: date nullable: true description: >- The day the combined license quantity changed. Null on the cycle-start row. quantityDelta: type: number description: >- Signed change in the combined license quantity (the starting quantity on the cycle-start row). Negative for removals. quantity: type: number description: >- The combined license quantity after this change. remainingDays: type: number description: >- Days from the change (inclusive) to the end of the cycle. Equals cycleDays on the cycle-start row. cycleDays: type: number description: Length of the billing cycle, in days. proratedUnitRate: type: string description: >- Absolute effective per-unit rate of the row over the remaining window, as a decimal currency-unit string: |amount| / |quantityDelta|. amount: type: string description: >- The signed prorated amount of the row, as a decimal currency-unit string. required: - type - changeDate - quantityDelta - quantity - remainingDays - cycleDays - proratedUnitRate - amount - type: object description: >- Tiered license proration delta row: one price band of a license charge billing under the proration model with tiered_per_unit pricing. The cycle-start rows bill each band's opening occupancy at its full-cycle unit price, and each change row bills that band's occupancy delta prorated over the days remaining in the cycle. quantityDelta and the row's amount are signed — removals are negative. properties: type: type: string enum: - license_proration_tier description: >- Discriminator: tiered license proration delta row. changeDate: type: string format: date nullable: true description: >- The day the combined license quantity changed. Null on a cycle-start row. quantityDelta: type: number description: >- Signed change in the units this band holds (the band's opening occupancy on a cycle-start row). Negative for removals. quantity: type: number description: >- The combined license quantity across every band after this change. remainingDays: type: number description: >- Days from the change (inclusive) to the end of the cycle. Equals cycleDays on a cycle-start row. cycleDays: type: number description: Length of the billing cycle, in days. proratedUnitRate: type: string description: >- Absolute effective per-unit rate of the row over the remaining window, as a decimal currency-unit string: |amount| / |quantityDelta|. amount: type: string description: >- The signed prorated amount of the row, as a decimal currency-unit string. planChargeTierId: type: string description: >- The unique identifier of the plan charge tier this row moved through. from: type: number description: >- Inclusive lower bound of the band, in licenses. to: type: number nullable: true description: >- Inclusive upper bound of the band, in licenses. Null on the last, open-ended band. unitPrice: type: string description: >- The band's full-cycle price per unit, as a decimal currency-unit string. proratedUnitRate is this scaled by remainingDays over cycleDays. required: - type - changeDate - quantityDelta - quantity - remainingDays - cycleDays - proratedUnitRate - amount - planChargeTierId - from - to - unitPrice - type: object description: >- Unit-price row: billable units multiplied by a single price per unit. The row's usage holds the billable units. properties: type: type: string enum: - unit_price description: 'Discriminator: unit-price row.' price: type: string pattern: ^\d+(\.\d{1,6})?$ description: >- Price per unit, as a decimal currency-unit string (up to 6 decimal places). required: - type - price - type: object description: >- Included-quantity row: the free allotment of the charge. The row's usage holds the units consumed within the allotment and its amount is always zero. properties: type: type: string enum: - included_quantity description: 'Discriminator: included-quantity row.' includedQuantity: type: number description: >- Number of resource units included at no charge before billing starts. required: - type - includedQuantity - type: object description: >- Package-price row: billable units charged per started package of packageSize units. The row's usage holds the billable units. properties: type: type: string enum: - package_price description: 'Discriminator: package-price row.' packageSize: type: number description: Number of resource units per package. price: type: string pattern: ^\d+(\.\d{1,6})?$ description: >- Price per package, as a decimal currency-unit string (up to 6 decimal places). packagesBilled: type: number description: >- Number of packages billed: the billable units divided by packageSize, rounded up. required: - type - packageSize - price - packagesBilled - type: object description: >- Percentage row: a percentage applied over a monetary base amount. The row's usage holds the base amount, in cents. properties: type: type: string enum: - percentage description: 'Discriminator: percentage row.' percentage: type: string pattern: ^(100(\.0{1,6})?|\d{1,2}(\.\d{1,6})?)$ description: >- Percentage applied to the base amount, as a decimal string from 0 to 100 (up to 6 decimal places). required: - type - percentage - type: object description: >- Per-unit overage row: units beyond the last tier boundary, billed at the configured excess unit price. The row's usage holds the units over the boundary. properties: type: type: string enum: - overage description: 'Discriminator: overage row.' pricingType: type: string enum: - per_unit description: 'Discriminator: overage billed per unit.' from: type: number description: >- The boundary the overage starts from: the upper bound of the last tier, in resource units. price: type: string pattern: ^\d+(\.\d{1,6})?$ description: >- Price per excess unit, as a decimal currency-unit string (up to 6 decimal places). required: - type - pricingType - from - price - type: object description: >- Percentage overage row: the monetary base amount beyond the last tier boundary, billed at the configured excess percentage. The row's usage holds the base amount over the boundary, in cents. properties: type: type: string enum: - overage description: 'Discriminator: overage row.' pricingType: type: string enum: - percentage description: >- Discriminator: overage billed as a percentage. from: type: number description: >- The boundary the overage starts from: the upper bound of the last tier, in cents of the monetary base amount. percentage: type: string pattern: ^(100(\.0{1,6})?|\d{1,2}(\.\d{1,6})?)$ description: >- Percentage applied to the excess base amount, as a decimal string from 0 to 100 (up to 6 decimal places). required: - type - pricingType - from - percentage - type: object description: >- Original-amount row: surfaces the line item's pre-adjustment amount when the line has adjustments (e.g. a discount) but no price-component rows of its own. The row's amount equals the line item's subtotalAmount. properties: type: type: string enum: - original_amount description: 'Discriminator: original-amount row.' required: - type - type: object description: >- Fixed unit price row: the quantity of a fixed charge multiplied by its unit amount. The row's usage holds the quantity. properties: type: type: string enum: - fixed_unit_price description: 'Discriminator: fixed unit price row.' amount: type: integer minimum: 0 description: Amount of one unit, in cents. required: - type - amount required: - id - type - name - description - usage - amount - metadata additionalProperties: false description: >- Breakdown of the line item amount into priced rows (included quantities, unit/package/tier prices, prorations, companions). Empty for line items without a breakdown. adjustments: type: array items: type: object description: >- Schema representing an adjustment applied on top of a line item subtotal, such as a discount or an allocation offset. properties: id: type: string format: uuid description: >- The unique identifier of the adjustment in our system. name: type: string description: >- Display name of the adjustment as it appears on the invoice. type: type: string enum: - monetary_discount - allocation_offset description: >- The kind of adjustment: monetary_discount (a discount applied to the line item) or allocation_offset (the share of the amount moved to another payment account's invoice under a split allocation strategy). amount: type: number description: >- Amount of the adjustment, in cents. Negative when the adjustment reduces the line item total. required: - id - name - type - amount additionalProperties: false description: >- Adjustments applied on top of the line item subtotal, such as discounts and allocation offsets. required: - id - idempotencyKey - customerId - productId - resourceId - licenseId - lineItemGroupId - name - scope - startDate - endDate - totalUsage - usageFormat - subtotalAmount - adjustmentAmount - totalAmount - discountAmount - metadata - subLineItems - adjustments additionalProperties: false description: >- Line items that do not belong to any line item group (e.g. contract-level minimum commitments, additional charges, and ungrouped one-off items). customFields: type: object description: >- The values of the tenant's custom fields for invoices, keyed by the key of each custom field. The object is empty when the invoice holds no value. A user edits them in the billing app, in any status of the invoice, and no public route writes them. additionalProperties: anyOf: - type: string - type: array items: type: string default: {} example: customField1: value1 customField2: - value2 - value3 required: - id - idempotencyKey - customerId - paymentAccountId - contractId - contractInvoiceSequence - issuingAccount - billingAccount - invoiceAllocationStrategy - lastCalculatedAt - invoiceNumber - invoiceDate - memo - subtotalAmount - adjustmentAmount - totalAmount - discountAmount - status - isLocked - failureReason - source - autoIssue - amountDue - dueDate - lineItemGroups - standaloneLineItems - customFields additionalProperties: false '400': description: Error object returned to the client. content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error code: type: string description: A unique identifier for the type of error details: oneOf: - type: object additionalProperties: true - type: array description: >- Additional context about the error, such as invalid fields or constraints. Each endpoint may include specific error details in their documentation causations: type: array description: >- Optional array of error objects following the same structure as the parent error. Only present when there's a meaningful chain of related errors to expose items: type: object properties: message: type: string description: >- A human-readable description of the underlying error cause code: type: string description: A unique identifier for the type of underlying error details: type: object additionalProperties: true description: Additional context about the underlying error required: - message - code additionalProperties: false required: - code - message additionalProperties: false '404': description: Error object returned to the client when a resource is not found. content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error components: securitySchemes: ApiKey: type: apiKey description: API Key Authentication. name: X-API-KEY in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.