> ## Documentation Index > Fetch the complete documentation index at: https://docs.hyperline.co/llms.txt > Use this file to discover all available pages before exploring further. # Preview subscription transition > Preview all invoices and credit notes emitted by a subscription transition and the next renewal invoice without applying the transition. ## OpenAPI ````yaml post /v2/subscriptions/transitions/preview openapi: 3.1.0 info: title: Hyperline API version: 0.0.0 servers: - url: https://api.hyperline.co - url: https://sandbox.api.hyperline.co security: [] paths: /v2/subscriptions/transitions/preview: post: tags: - Subscriptions > Transitions summary: Preview subscription transition description: >- Preview all invoices and credit notes emitted by a subscription transition and the next renewal invoice without applying the transition. operationId: previewSubscriptionTransition requestBody: content: application/json: schema: anyOf: - type: object properties: transition_id: type: string description: >- The ID of an existing subscription transition to preview. Use this instead of providing a full payload to preview a transition that has already been scheduled. required: - transition_id title: From existing transition - type: object properties: source_subscription_id: type: string description: The ID of the subscription to transition from name: type: string description: An optional name for the transition calculation_method: type: string enum: - do_not_charge - pro_rata - pro_rata_separate_documents description: >- The calculation method to use for the transition. 'do_not_charge' will not generate any transition invoice. 'pro_rata' will generate a prorated invoice for the remaining period. 'pro_rata_separate_documents' issues a credit note for the current period (the amount invoiced when 'last_renewal', otherwise a prorated cancellation credit) and a separate invoice for the new configuration. billing_cycle_transition_method: type: string enum: - keep_current_billing_cycle - align_to_new_billing_cycle description: >- The billing cycle transition method to use. 'keep_current_billing_cycle' (the default) keeps the current billing cycle dates; the request is rejected when the phases share no product billing periodicity, as the cycle cannot then be preserved — use 'align_to_new_billing_cycle' in that case. 'align_to_new_billing_cycle' aligns the billing cycle to the transition date. application_schedule: type: string enum: - scheduled - immediately - last_renewal description: >- When the transition should be applied: 'immediately', 'scheduled' for a specific date, or 'last_renewal' to apply it retroactively to the start of the current billing period (refunding what was already invoiced for that period and re-charging the new configuration). Past dates within the current billing period are supported and will be applied immediately. transition_date: type: string format: date-time description: >- The date at which the transition should occur. Only applicable if the application schedule is 'scheduled'. Can be a past date within the current billing period. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-12-20T16:04:11Z' target_subscription: allOf: - type: object properties: name: type: string description: Subscription custom name. purchase_order: type: string description: Reference to the purchase order. invoicing_entity_id: type: string description: >- ID of the invoicing entity attached to the subscription. If not defined, fallback to customer's invoicing entity. example: ive_jerrb484RHn crm_opportunity_id: type: string description: >- ID of the related opportunity/deal in the connected CRM. commitment_interval: type: object properties: period: type: string enum: - days - weeks - months - years count: type: number minimum: 1 required: - period - count description: Deprecated field, please use `contract_terms`. example: period: years count: 1 deprecated: true renew_for: type: object properties: period: type: string enum: - days - weeks - months - years count: type: number required: - period - count description: Deprecated field, please use `contract_terms`. example: period: years count: 1 deprecated: true minimum_invoice_fee: type: - number - 'null' description: >- Minimum fee applied to each invoice outside of one time payments. example: 250 contract_terms: allOf: - type: object properties: starts_at: type: string format: date-time description: >- Start date of the contract. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-12-20T16:04:11Z' ends_at: type: string format: date-time description: >- End date of the contract. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-12-20T16:04:11Z' duration: type: object properties: period: type: string enum: - days - weeks - months - years count: type: integer minimum: 1 default: 1 required: - period description: >- Interval over which the contract initially spans. Only applies to `duration` end strategy. example: count: 6 period: months renew_automatically: anyOf: - type: boolean - type: string enum: - 'true' - 'false' description: > Indicates if the contract should be renewed automatically. - `true`: The contract will be renewed automatically. - `false`: The contract will not be renewed automatically. example: true renew_for_duration: type: object properties: period: type: string enum: - days - weeks - months - years count: type: integer minimum: 1 default: 1 required: - period description: > Interval over which the contract will be renewed. Only applies if `renew_automatically` is true. example: count: 1 period: years - type: object properties: activation_strategy: type: string enum: - start_date - immediately - manual - quote_signature - checkout description: > Activation strategy of the contract. - `immediately`: The contract will be activated immediately. - `manual`: The contract will be activated when a user manually activates it. - `start_date`: The contract will be activated on a specified date. - `quote_signature`: The contract will be activated when the subscription quote is signed. - `checkout`: The contract will be activated when the subscription checkout is completed. example: start_date end_strategy: type: string enum: - end_date - duration - manual description: > End strategy of contract. - `manual`: The contract ends when a user manually stops it. - `end_date`: The contract ends on a specified date. - `duration`: The contract ends after a specific relative duration, unless `renew_automatically` is true. example: duration required: - activation_strategy - end_strategy description: Contract terms linked to the subscription. starts_at: type: string format: date-time description: >- Applies only if the activation strategy is `start_date`. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-12-20T16:04:11Z' contract_start: type: string format: date-time description: Deprecated field, please use `contract_terms`. example: '2024-01-15T00:00:00Z' deprecated: true contract_end: type: string format: date-time description: Deprecated field, please use `contract_terms`. example: '2025-01-15T00:00:00Z' deprecated: true initial_billing_at: type: string format: date-time description: >- Date when the subscription will start being billed. If not specified, it will correspond to the `starts_at` date. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-12-20T16:04:11Z' shipping_address_id: type: string description: >- Active shipping address ID belonging to the subscription customer. Omit to use the customer shipping destination: billing address or default shipping address. example: cad_abc123 display_shipping_details: anyOf: - type: boolean - type: string enum: - 'true' - 'false' description: >- Indicates if the shipping details should be displayed on the subscription's invoices. cancel_at: type: string format: date-time description: >- Subscription cancel date. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-12-20T16:04:11Z' cancellation_strategy: type: string enum: - refund_prorata - refund_custom - charge_prorata - charge_custom - end_of_period - do_nothing description: > Strategy used to cancel the subscription. If not specified `do_nothing` is used. - `charge_prorata`: Will charge the customer the unpaid amount for the prorated period up to the end of the current period. - `charge_custom`: Will charge the customer a custom amount. - `refund_prorata`: Will refund to the customer the overpaid subscription amount using prorated calculations on the cancellation date. - `refund_custom`: Will refund to the customer a custom amount. - `end_of_period`: Will cancel the subscription at the end date of the current billing period. - `do_nothing`: Will only cease the subscription without any additional actions. cancellation_amount: type: number description: >- Custom amount used when cancelling the subscription. Only applies to the `charge_custom` or the `refund_custom` cancellation strategy. cancellation_refund_method: type: string enum: - wallet - original_payment_method - external description: >- Override the refund destination for credit notes generated by `refund_prorata` / `refund_custom` cancellation strategies. When omitted, falls back to the invoicing entity's `creditNoteWalletRefundEnabled` setting. properties: type: object additionalProperties: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: array items: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: 'null' - type: 'null' description: >- Key/value pairs to store any metadata useful in your context. custom_properties: type: object additionalProperties: anyOf: - type: string - type: number - type: boolean - type: string format: date-time description: >- UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-12-20T16:04:11Z' - type: array items: type: string - type: 'null' description: >- A list of key value with the slug of the custom property as the key and the custom property value as value. tax_only: anyOf: - type: boolean - type: string enum: - 'true' - 'false' description: Only tax will be charged on this subscription. generate_draft_invoices: anyOf: - type: boolean - type: string enum: - 'true' - 'false' description: >- Generate draft invoices for the subscription. Each invoice will need to be reviewed and validated manually before being sent generate_document: anyOf: - type: boolean - type: string enum: - 'true' - 'false' description: >- Generate non-legal documents instead of invoices. document_name: type: - string - 'null' description: >- If `generate_document` is turned on, allows you to give a name to your document. add_tax_to_document: anyOf: - type: boolean - type: string enum: - 'true' - 'false' description: >- If `generate_document` is turned on, will add taxes to document. do_not_charge_subscription: anyOf: - type: boolean - type: string enum: - 'true' - 'false' description: >- Subscription will be invoiced but not charged (invoices/documents will be settled directly). invoice_custom_note: type: - string - 'null' description: >- Default custom note added to invoices generated by the subscription. invoice_schedule: type: - string - 'null' enum: - period_start - period_end description: > Defines when invoices are generated relative to the billing period. - `period_start`: Invoices are generated at the start of the billing period. - `period_end`: Invoices are generated at the end of the billing period. - type: object properties: plan_id: type: string description: Deprecated field, please use `template_id`. example: plan_zHmjoDee4ZRmQV deprecated: true template_id: type: string description: >- ID of the template that the subscription is linked to. example: subt_7gdusOkqr5L0B8 template_configuration_id: type: string description: >- ID of the template configuration that the subscription is linked to. example: subtc_7mHWOlPStUogvp - anyOf: - type: object properties: phases: type: array items: type: object properties: name: type: string description: Name of the subscription phase. example: Initial term type: type: string enum: - setup - trial - standard default: standard description: > Type of subscription phase. - `setup`: The phase represents a non-recurring service setup period, often used before the actual recurring subscription begins. - `trial`: The phase represents a non-recurring trial period, often used to allow users to opt out or experience a free test. - `standard`: The phase represents a standard recurring billing. example: standard status: type: string enum: - finished - pending default: pending description: > Status of subscription phase. - `pending`: The phase is waiting to start (not started yet). - `active`: The phase is currently in progress. - `finished`: The phase has ended and is complete. example: pending order: type: number description: >- Order in which the phase is executed within all subscription phases. example: 0 activation_strategy: type: string enum: - immediately - manual - start_date - quote_signature - checkout - contract_start_date - previous_phase_end description: > Activation strategy of subscription phase. - `immediately`: The phase starts as soon as the subscription is activated. - `manual`: The phase starts when a user manually activates it. - `start_date`: The phase starts on a specified date. - `quote_signature`: The phase starts when the subscription quote is signed. - `checkout`: The phase starts when the subscription checkout is completed. - `contract_start_date`: The phase starts on the start date of the related subscription contract. - `previous_phase_end`: The phase starts when the previous phase ends. example: manual end_strategy: type: string enum: - manual - end_date - duration - contract_end_date description: > End strategy of subscription phase. - `manual`: The phase ends when a user manually stops it. - `end_date`: The phase ends on a specified date. - `duration`: The phase ends after a specific relative duration. - `contract_end_date`: The phase ends on the end date of the related subscription contract. example: duration duration: type: object properties: period: type: string enum: - days - weeks - months - years count: type: integer minimum: 1 default: 1 required: - period description: >- Interval over which the subscription phase spans. Only applies to `duration` end strategy. example: count: 1 period: years billing_date_setting: type: string enum: - phase_start - specific_date description: > Represents when the first billing date occurs. - `phase_start`: Aligns with the start of the phase. - `specific_date`: Occurs on a specified date. example: phase_start initial_billing_at: type: string format: date-time description: >- Date when the subscription phase will start being billed. Only applies to `specific_date` billing date setting. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-12-20T16:04:11Z' starts_at: type: string format: date-time description: >- Actual start date of the phase. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-12-20T16:04:11Z' ends_at: type: string format: date-time description: >- Actual end date of the phase. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-12-20T16:04:11Z' billing_cycle_alignment: type: string enum: - calendar_period - anniversary description: > Alignment of product billing cycles. If omitted at creation, the billing cycles alignment configured in the account subscription settings applies. - `calendar_period`: The billing cycles of the products will be aligned on the calendar period, after the first period which will be invoiced taking into account the prorata of the first cycle compared to the product periodicity. - `anniversary`: The billing cycles of the products will be aligned on the anniversary of the phase initial billing date. example: anniversary do_not_invoice_phase: type: boolean default: false description: >- Indicates if the phase should be invoiced. If set to true, the phase will not generate any invoices. example: false transition_calculation_method: type: string enum: - prorata - pay_in_full - none default: prorata description: > Calculation method used when transitioning from one phase to the next one. - `prorata`: The prorated amount between the two phases relative to the end date (the transition date) must be paid. - `pay_in_full`: The full amount for the phase billing period must be paid. - `none`: No amount will need to be paid, phase will simply transition from one to the next. example: prorata transition_invoicing_schedule: type: string enum: - immediately default: immediately description: > Represents when the transition amount will be invoiced. - `immediately`: An invoice will be generated immediately with the corresponding amount. example: immediately products: type: array items: type: object properties: id: type: string description: Product ID. example: itm_FJKlqUb8COXw55 catalog_version_id: type: - string - 'null' description: >- ID of a published catalog version to price this product from, instead of the live products catalog. Ignored when `price` or `prices` is set. The product must be priced in that version. example: pcv_9x8v7u6t5s4r name: type: string description: >- Product name. This will appear on the final invoices. example: Product name description: type: string description: >- Product description. This will appear on the final invoices. example: A description of the product. description_display_interval_dates: type: boolean default: false description: >- Indicates if the dates of the interval should be automatically added in the product description on the invoices. payment_interval: anyOf: - type: object properties: period: type: string enum: - once required: - period title: Once example: period: once - type: object properties: period: type: string enum: - days - weeks - months - years count: type: integer minimum: 1 default: 1 required: - period title: Period example: period: months count: 1 description: >- Interval on which the product is billed. This interval can be different between products and can differ from the subscription commitment interval. payment_schedule: type: string enum: - start - end description: >- Indicates if the product should be billed at the start or the end of the payment interval. example: start price: type: object properties: type: type: string enum: - fee amount: type: number description: >- Monetary amount. Expressed in currency's smallest unit. required: - type - amount description: >- Similar to `prices`, allow to apply a single fee price more easily. example: type: fee amount: 200 prices: type: array items: oneOf: - type: object properties: type: type: string enum: - fee amount: type: number description: >- Monetary amount. Expressed in currency's smallest unit. required: - type - amount title: Fee price - type: object properties: type: type: string enum: - volume amount: type: number description: >- Monetary amount of the price for the number of units defined by `unit_count`. Expressed in currency's smallest unit. unit_count: type: number description: >- Number of units considered for the amount. from: type: number description: From limit. to: type: - number - 'null' description: To limit. on_tier_incomplete: type: - string - 'null' enum: - pro_rata - pay_in_full - do_not_charge default: pro_rata description: >- Logic used to compute the amount when usage on the tier is incomplete. - `pro_rata`: The amount is computed using the pro rata of the tier's consumption. - `pay_in_full`: The amount corresponds to the full payment of the tier. - `do_not_charge`: The tier is not charged and ignored. metering_filter: allOf: - $ref: '#/components/schemas/MeteringFilter' - type: object description: >- Metering filter that scopes which billable events are eligible for this price tier. Only present when the price is filtered. required: - type - amount - unit_count - from - to title: Volume price - type: object properties: type: type: string enum: - packaged amount: type: number description: >- Monetary amount of the price for the number of units defined by `unit_count`. Expressed in currency's smallest unit. unit_count: type: number description: >- Number of units considered for the amount. from: type: number description: From limit. to: type: - number - 'null' description: To limit. on_bucket_incomplete: type: - string - 'null' enum: - pro_rata - pay_in_full - do_not_charge default: pro_rata description: >- Logic used to compute the amount when usage reaches an incomplete bucket (the bucket size corresponds to the `unitCount`). - `pro_rata`: The amount is computed using the pro rata of the bucket's consumption. - `pay_in_full`: The amount corresponds to the full payment of the bucket. - `do_not_charge`: The bucket is not charged and ignored. metering_filter: allOf: - $ref: '#/components/schemas/MeteringFilter' - type: object description: >- Metering filter that scopes which billable events are eligible for this price tier. Only present when the price is filtered. required: - type - amount - unit_count - from - to title: Packaged price - type: object properties: type: type: string enum: - bulk amount: type: number description: >- Monetary amount of the price for the number of units defined by `unit_count`. Expressed in currency's smallest unit. unit_count: type: number description: >- Number of units considered for the amount. to: type: - number - 'null' description: To limit. on_tier_incomplete: type: - string - 'null' enum: - pro_rata - pay_in_full - do_not_charge default: pro_rata description: >- Logic used to compute the amount when usage on the tier is incomplete. - `pro_rata`: The amount is computed using the pro rata of the tier's consumption. - `pay_in_full`: The amount corresponds to the full payment of the tier. - `do_not_charge`: The tier is not charged and ignored. metering_filter: allOf: - $ref: '#/components/schemas/MeteringFilter' - type: object description: >- Metering filter that scopes which billable events are eligible for this price tier. Only present when the price is filtered. required: - type - amount - unit_count - to title: Bulk price - type: object properties: type: type: string enum: - bps from: type: number description: From limit. to: type: - number - 'null' description: To limit. percentage: type: number description: >- Percentage applied on each unit to compute the usage. per_unit_cap: type: - number - 'null' description: >- Maximum amount for one unit. Expressed in currency's smallest unit. per_unit_floor: type: - number - 'null' description: >- Minimum amount for one unit. Expressed in currency's smallest unit. per_unit_fee: type: - number - 'null' description: >- Fee amount applied per unit. Expressed in currency's smallest unit. metering_filter: allOf: - $ref: '#/components/schemas/MeteringFilter' - type: object description: >- Metering filter that scopes which billable events are eligible for this price tier. Only present when the price is filtered. required: - type - from - to - percentage - per_unit_cap - per_unit_floor - per_unit_fee title: BPS price - type: object properties: type: type: string enum: - bundle amount: type: number description: >- Monetary amount of the price for the number of units defined by `unit_count`. Expressed in currency's smallest unit. unit_count: type: number description: >- Number of units considered for the amount. required: - type - amount - unit_count title: Bundle price description: >- For seat products only, if you are looking for credits, use a fee price description: >- Prices of the product. If not specified, the matching prices (depending on the currency, interval, etc) of the product defined in the products catalog/plan are used. example: - type: volume from: 0 to: 20 amount: 200 unit_count: 1 on_tier_incomplete: null - type: volume from: 20 to: null amount: 150 unit_count: 1 on_tier_incomplete: null count: type: number minimum: 1 description: >- Number of product units. Only applies to products of type `flat_fee`, `seat` or `credit`. example: 2 unit_name: type: string description: >- Product name. This will appear on the final invoices. Only applies to products of type `seat` or `usage`. example: user min_committed_count: type: number minimum: 1 description: >- Minimum of units committed. If usage is less than this number, then this value will be used. Only applies to products of type `usage`. min_amount: type: - number - 'null' description: >- Minimum amount billed. If the final computed amount from the usage for this product is less than this amount, then this value will be used. Only applies to products of type `usage`. max_amount: type: - number - 'null' description: >- Maximum amount billed. If the final computed amount from the usage for this product is greater than this amount, then this value will be used. Only applies to products of type `usage`. charging_method: type: - string - 'null' enum: - prorata - pay_in_full - do_not_charge description: >- Charging method for seat count updates within the current billing period. Only applies to connected seat products. - `prorata`: Price calculated proportionally to time elapsed in the billing period. - `pay_in_full`: Price calculated for the entire billing period. - `do_not_charge`: No charge for the update. seat_invoicing_schedule: type: - string - 'null' enum: - immediately - next_invoice - custom description: > Policy defining when seat count changes are invoiced. Only applies to connected seat products. - `immediately`: Seat changes are invoiced immediately. - `next_invoice`: Seat changes are invoiced at the next invoice. - `custom`: Seat changes are invoiced on a custom schedule. metering_interval_type: type: string enum: - subscription_commitment - payment_interval - full_database - phase_duration - custom description: >- Indicates on which type of interval the usage should be aggregated. - `subscription_commitment`: For the usage contained within the subscription commitment period. - `payment_interval`: For the usage contained within the payment interval of the product. - `full_database`: For all the usage we ingested for this product, no matter the period. - `phase_duration`: For the usage contained within the subscription phase. - `custom`: For the usage contained within a custom interval that starts with the phase and renews independently of the billing interval. Requires `metering_interval` to be set. Only applies to products of type `usage`. metering_interval: type: object properties: period: type: string enum: - days - weeks - months - years count: type: integer minimum: 1 required: - period - count description: >- Custom interval for usage aggregation. Required when `metering_interval_type` is `custom`. The interval starts at the phase start and renews on its own cycle (e.g. `{ period: 'months', count: 3 }` for quarterly metering with monthly billing). Only applies to products of type `usage`. bill_usage_difference: anyOf: - type: boolean - type: string enum: - 'true' - 'false' default: false description: >- Only bill the usage difference comparing to the previous period (i.e. actual amount minus last invoice amount). Doesn't apply to `payment_interval` metering interval type. Only applies to products of type `usage`. children_usage_aggregation: type: - string - 'null' enum: - sum - max description: >- Controls whether a parent organization's metered usage is billed on the combined usage of the parent and its direct children, and how per-member values are combined. - `null`: Organization-based usage is disabled. Only the subscription customer's own usage is billed. - `sum`: The usage values of the parent and each direct child are added together (organization total). - `max`: Only the single highest-consuming member (parent or one direct child) is billed. Only applies to products of type `usage`. credits_expiration_in_days: type: - number - 'null' description: >- Validity in days for credits that will be topped-up automatically. Once the period has passed, they'll expire. expire_credits_at_end_of_period: anyOf: - type: boolean - type: string enum: - 'true' - 'false' default: false description: >- Automatically set the expiration date to the end of the next period for each topup. Takes priority on `creditsExpirationInDays` credits_balance_auto_creation_enabled: anyOf: - type: boolean - type: string enum: - 'true' - 'false' description: >- Whether to create the customer credit balance as soon as the product is added to the subscription. Defaults to the credit product's `credits_balance_auto_creation_enabled` (`true` when unset). Set to `false` to create the balance by hand before activation, e.g. on quote-based renewals where the balance must not start consuming before signature; the first top-up creates it if still missing. required: - id description: >- Products comprising the subscription phase. coupons: type: array items: allOf: - anyOf: - type: object properties: id: type: string description: Coupon ID. required: - id title: Existing coupon - type: object properties: type: type: string enum: - amount name: type: string description: Coupon name. discount_amount: type: number exclusiveMinimum: 0 description: >- Coupon discount amount. Expressed in currency's smallest unit. required: - type - discount_amount title: Coupon amount - type: object properties: type: type: string enum: - percent name: type: string description: Coupon name. discount_percent: type: number exclusiveMinimum: 0 maximum: 100 description: Coupon discount percentage. required: - type - discount_percent title: Coupon percent - type: object properties: repeat: type: - string - 'null' enum: - once - forever - custom - duration description: > Coupon frequency. Required for inline coupons. Optional when an existing coupon `id` is provided: if omitted, defaults to the catalog coupon's repeat value. - `once`: Will apply the coupon only to the first one invoice. - `forever`: Will apply the coupon to all invoices. - `custom`: Will apply to coupon until a specified expiration date. - `duration`: Will apply the coupon for a specific duration (e.g., 3 months). duration_period: type: string enum: - days - weeks - months - years description: >- Period of time for which the coupon will be applied. Only applies to the `duration` coupon frequency. duration_count: type: number description: >- Number of periods for which the coupon will be applied. Only applies to the `duration` coupon frequency. expires_at: type: string format: date-time description: >- Coupon expiration date. Only applies to the `custom` coupon frequency. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-12-20T16:04:11Z' apply_at: type: string format: date-time description: >- Coupon first application date. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-12-20T16:04:11Z' product_ids: type: - array - 'null' items: type: string minItems: 1 description: >- Product IDs to which the coupon will be applied, or null if applies to all products. description: >- Coupons comprising the subscription phase. required: - activation_strategy - end_strategy - billing_date_setting - products required: - phases title: With phases - allOf: - type: object properties: products: type: array items: type: object properties: id: type: string description: Product ID. example: itm_FJKlqUb8COXw55 catalog_version_id: type: - string - 'null' description: >- ID of a published catalog version to price this product from, instead of the live products catalog. Ignored when `price` or `prices` is set. The product must be priced in that version. example: pcv_9x8v7u6t5s4r name: type: string description: >- Product name. This will appear on the final invoices. example: Product name description: type: string description: >- Product description. This will appear on the final invoices. example: A description of the product. description_display_interval_dates: type: boolean default: false description: >- Indicates if the dates of the interval should be automatically added in the product description on the invoices. payment_interval: anyOf: - type: object properties: period: type: string enum: - once required: - period title: Once example: period: once - type: object properties: period: type: string enum: - days - weeks - months - years count: type: integer minimum: 1 default: 1 required: - period title: Period example: period: months count: 1 description: >- Interval on which the product is billed. This interval can be different between products and can differ from the subscription commitment interval. payment_schedule: type: string enum: - start - end description: >- Indicates if the product should be billed at the start or the end of the payment interval. example: start price: type: object properties: type: type: string enum: - fee amount: type: number description: >- Monetary amount. Expressed in currency's smallest unit. required: - type - amount description: >- Similar to `prices`, allow to apply a single fee price more easily. example: type: fee amount: 200 prices: type: array items: oneOf: - type: object properties: type: type: string enum: - fee amount: type: number description: >- Monetary amount. Expressed in currency's smallest unit. required: - type - amount title: Fee price - type: object properties: type: type: string enum: - volume amount: type: number description: >- Monetary amount of the price for the number of units defined by `unit_count`. Expressed in currency's smallest unit. unit_count: type: number description: >- Number of units considered for the amount. from: type: number description: From limit. to: type: - number - 'null' description: To limit. on_tier_incomplete: type: - string - 'null' enum: - pro_rata - pay_in_full - do_not_charge default: pro_rata description: >- Logic used to compute the amount when usage on the tier is incomplete. - `pro_rata`: The amount is computed using the pro rata of the tier's consumption. - `pay_in_full`: The amount corresponds to the full payment of the tier. - `do_not_charge`: The tier is not charged and ignored. metering_filter: allOf: - $ref: '#/components/schemas/MeteringFilter' - type: object description: >- Metering filter that scopes which billable events are eligible for this price tier. Only present when the price is filtered. required: - type - amount - unit_count - from - to title: Volume price - type: object properties: type: type: string enum: - packaged amount: type: number description: >- Monetary amount of the price for the number of units defined by `unit_count`. Expressed in currency's smallest unit. unit_count: type: number description: >- Number of units considered for the amount. from: type: number description: From limit. to: type: - number - 'null' description: To limit. on_bucket_incomplete: type: - string - 'null' enum: - pro_rata - pay_in_full - do_not_charge default: pro_rata description: >- Logic used to compute the amount when usage reaches an incomplete bucket (the bucket size corresponds to the `unitCount`). - `pro_rata`: The amount is computed using the pro rata of the bucket's consumption. - `pay_in_full`: The amount corresponds to the full payment of the bucket. - `do_not_charge`: The bucket is not charged and ignored. metering_filter: allOf: - $ref: '#/components/schemas/MeteringFilter' - type: object description: >- Metering filter that scopes which billable events are eligible for this price tier. Only present when the price is filtered. required: - type - amount - unit_count - from - to title: Packaged price - type: object properties: type: type: string enum: - bulk amount: type: number description: >- Monetary amount of the price for the number of units defined by `unit_count`. Expressed in currency's smallest unit. unit_count: type: number description: >- Number of units considered for the amount. to: type: - number - 'null' description: To limit. on_tier_incomplete: type: - string - 'null' enum: - pro_rata - pay_in_full - do_not_charge default: pro_rata description: >- Logic used to compute the amount when usage on the tier is incomplete. - `pro_rata`: The amount is computed using the pro rata of the tier's consumption. - `pay_in_full`: The amount corresponds to the full payment of the tier. - `do_not_charge`: The tier is not charged and ignored. metering_filter: allOf: - $ref: '#/components/schemas/MeteringFilter' - type: object description: >- Metering filter that scopes which billable events are eligible for this price tier. Only present when the price is filtered. required: - type - amount - unit_count - to title: Bulk price - type: object properties: type: type: string enum: - bps from: type: number description: From limit. to: type: - number - 'null' description: To limit. percentage: type: number description: >- Percentage applied on each unit to compute the usage. per_unit_cap: type: - number - 'null' description: >- Maximum amount for one unit. Expressed in currency's smallest unit. per_unit_floor: type: - number - 'null' description: >- Minimum amount for one unit. Expressed in currency's smallest unit. per_unit_fee: type: - number - 'null' description: >- Fee amount applied per unit. Expressed in currency's smallest unit. metering_filter: allOf: - $ref: '#/components/schemas/MeteringFilter' - type: object description: >- Metering filter that scopes which billable events are eligible for this price tier. Only present when the price is filtered. required: - type - from - to - percentage - per_unit_cap - per_unit_floor - per_unit_fee title: BPS price - type: object properties: type: type: string enum: - bundle amount: type: number description: >- Monetary amount of the price for the number of units defined by `unit_count`. Expressed in currency's smallest unit. unit_count: type: number description: >- Number of units considered for the amount. required: - type - amount - unit_count title: Bundle price description: >- For seat products only, if you are looking for credits, use a fee price description: >- Prices of the product. If not specified, the matching prices (depending on the currency, interval, etc) of the product defined in the products catalog/plan are used. example: - type: volume from: 0 to: 20 amount: 200 unit_count: 1 on_tier_incomplete: null - type: volume from: 20 to: null amount: 150 unit_count: 1 on_tier_incomplete: null count: type: number minimum: 1 description: >- Number of product units. Only applies to products of type `flat_fee`, `seat` or `credit`. example: 2 unit_name: type: string description: >- Product name. This will appear on the final invoices. Only applies to products of type `seat` or `usage`. example: user min_committed_count: type: number minimum: 1 description: >- Minimum of units committed. If usage is less than this number, then this value will be used. Only applies to products of type `usage`. min_amount: type: - number - 'null' description: >- Minimum amount billed. If the final computed amount from the usage for this product is less than this amount, then this value will be used. Only applies to products of type `usage`. max_amount: type: - number - 'null' description: >- Maximum amount billed. If the final computed amount from the usage for this product is greater than this amount, then this value will be used. Only applies to products of type `usage`. charging_method: type: - string - 'null' enum: - prorata - pay_in_full - do_not_charge description: >- Charging method for seat count updates within the current billing period. Only applies to connected seat products. - `prorata`: Price calculated proportionally to time elapsed in the billing period. - `pay_in_full`: Price calculated for the entire billing period. - `do_not_charge`: No charge for the update. seat_invoicing_schedule: type: - string - 'null' enum: - immediately - next_invoice - custom description: > Policy defining when seat count changes are invoiced. Only applies to connected seat products. - `immediately`: Seat changes are invoiced immediately. - `next_invoice`: Seat changes are invoiced at the next invoice. - `custom`: Seat changes are invoiced on a custom schedule. metering_interval_type: type: string enum: - subscription_commitment - payment_interval - full_database - phase_duration - custom description: >- Indicates on which type of interval the usage should be aggregated. - `subscription_commitment`: For the usage contained within the subscription commitment period. - `payment_interval`: For the usage contained within the payment interval of the product. - `full_database`: For all the usage we ingested for this product, no matter the period. - `phase_duration`: For the usage contained within the subscription phase. - `custom`: For the usage contained within a custom interval that starts with the phase and renews independently of the billing interval. Requires `metering_interval` to be set. Only applies to products of type `usage`. metering_interval: type: object properties: period: type: string enum: - days - weeks - months - years count: type: integer minimum: 1 required: - period - count description: >- Custom interval for usage aggregation. Required when `metering_interval_type` is `custom`. The interval starts at the phase start and renews on its own cycle (e.g. `{ period: 'months', count: 3 }` for quarterly metering with monthly billing). Only applies to products of type `usage`. bill_usage_difference: anyOf: - type: boolean - type: string enum: - 'true' - 'false' default: false description: >- Only bill the usage difference comparing to the previous period (i.e. actual amount minus last invoice amount). Doesn't apply to `payment_interval` metering interval type. Only applies to products of type `usage`. children_usage_aggregation: type: - string - 'null' enum: - sum - max description: >- Controls whether a parent organization's metered usage is billed on the combined usage of the parent and its direct children, and how per-member values are combined. - `null`: Organization-based usage is disabled. Only the subscription customer's own usage is billed. - `sum`: The usage values of the parent and each direct child are added together (organization total). - `max`: Only the single highest-consuming member (parent or one direct child) is billed. Only applies to products of type `usage`. credits_expiration_in_days: type: - number - 'null' description: >- Validity in days for credits that will be topped-up automatically. Once the period has passed, they'll expire. expire_credits_at_end_of_period: anyOf: - type: boolean - type: string enum: - 'true' - 'false' default: false description: >- Automatically set the expiration date to the end of the next period for each topup. Takes priority on `creditsExpirationInDays` credits_balance_auto_creation_enabled: anyOf: - type: boolean - type: string enum: - 'true' - 'false' description: >- Whether to create the customer credit balance as soon as the product is added to the subscription. Defaults to the credit product's `credits_balance_auto_creation_enabled` (`true` when unset). Set to `false` to create the balance by hand before activation, e.g. on quote-based renewals where the balance must not start consuming before signature; the first top-up creates it if still missing. required: - id description: Products that make up the subscription. coupons: type: array items: allOf: - anyOf: - type: object properties: id: type: string description: Coupon ID. required: - id title: Existing coupon - type: object properties: type: type: string enum: - amount name: type: string description: Coupon name. discount_amount: type: number exclusiveMinimum: 0 description: >- Coupon discount amount. Expressed in currency's smallest unit. required: - type - discount_amount title: Coupon amount - type: object properties: type: type: string enum: - percent name: type: string description: Coupon name. discount_percent: type: number exclusiveMinimum: 0 maximum: 100 description: Coupon discount percentage. required: - type - discount_percent title: Coupon percent - type: object properties: repeat: type: - string - 'null' enum: - once - forever - custom - duration description: > Coupon frequency. Required for inline coupons. Optional when an existing coupon `id` is provided: if omitted, defaults to the catalog coupon's repeat value. - `once`: Will apply the coupon only to the first one invoice. - `forever`: Will apply the coupon to all invoices. - `custom`: Will apply to coupon until a specified expiration date. - `duration`: Will apply the coupon for a specific duration (e.g., 3 months). duration_period: type: string enum: - days - weeks - months - years description: >- Period of time for which the coupon will be applied. Only applies to the `duration` coupon frequency. duration_count: type: number description: >- Number of periods for which the coupon will be applied. Only applies to the `duration` coupon frequency. expires_at: type: string format: date-time description: >- Coupon expiration date. Only applies to the `custom` coupon frequency. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-12-20T16:04:11Z' apply_at: type: string format: date-time description: >- Coupon first application date. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-12-20T16:04:11Z' product_ids: type: - array - 'null' items: type: string minItems: 1 description: >- Product IDs to which the coupon will be applied, or null if applies to all products. - type: object properties: trial: type: object properties: end_strategy: type: string enum: - manual - end_date - duration description: Defines how the free trial will end. starts_at: type: string format: date-time description: >- Free trial start date. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-12-20T16:04:11Z' ends_at: type: string format: date-time description: >- Free trial end date. Only applies if the end strategy is `end_date`. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-12-20T16:04:11Z' duration: type: object properties: period: type: string enum: - days - weeks - months - years description: >- Free trial duration period. Only applies if the end strategy is `duration`. count: type: number minimum: 1 description: >- Free trial duration count. Only applies if the end strategy is `duration`. required: - period - count required: - end_strategy description: >- Create a free trial phase based on the plan configuration. Only applies if a `plan_id` is provided. title: Without phases description: The configuration of the subscription to transition to required: - source_subscription_id - application_schedule - target_subscription title: From new payload responses: '200': description: '' content: application/json: schema: type: object properties: transition_documents: type: array items: $ref: '#/components/schemas/SimulateInvoiceDetails' description: >- All invoices and credit notes that would be emitted at transition time, including each credit note when a proration refund is split across source invoices. Empty when no transition documents are emitted, for example with `do_not_charge`. Use each document's `type` to distinguish invoices from credit notes. next_invoice_after_transition: allOf: - $ref: '#/components/schemas/SimulateInvoiceDetails' - anyOf: - allOf: - allOf: - $ref: '#/components/schemas/InvoiceDeprecated' - type: object properties: public_url: type: - string - 'null' format: uri description: >- Public URL of the invoice page where the customer can pay the invoice. - type: object properties: integrations: type: array items: type: object properties: entity_id: type: string description: ID of the entity in the provider. provider_name: type: string enum: - adyen - stripe - mollie - gocardless - airwallex - salesforce - hubspot - attio - xero - pennylane - zoho-books - exact-online - quickbooks - netsuite - rillet - datev - anrok - chargebee - slack - plain - zendesk - pylon - intercom - front - helpscout - claap - grain - gong - jiminny - modjo - posthog description: Provider name. provider_account_id: type: string description: ID of the connected provider account. created_at: type: - string - 'null' format: date-time description: >- Creation date of the entity in the provider, when it was imported from there. Exposed on products and coupons; `null` when the provider does not report one. example: '2024-12-20T16:04:11Z' required: - entity_id - provider_name - provider_account_id description: >- Reference to the entity in an external provider. example: entity_id: '123456789' provider_name: stripe provider_account_id: acc_1234567890 required: - integrations - type: 'null' description: >- The invoice that would be emitted at the next renewal after the transition. Null if no renewal invoice would be emitted. required: - transition_documents - next_invoice_after_transition security: - bearer: [] components: schemas: MeteringFilter: type: - object - 'null' properties: name: type: string description: Name of the metering filter. example: VISA credit cards configuration: $ref: '#/components/schemas/MeteringFilterConfiguration' required: - name - configuration description: Metering filter to scope eligible billable events. SimulateInvoiceDetails: allOf: - allOf: - $ref: '#/components/schemas/InvoiceDeprecated' - type: object properties: public_url: type: - string - 'null' format: uri description: >- Public URL of the invoice page where the customer can pay the invoice. - type: object properties: integrations: type: array items: type: object properties: entity_id: type: string description: ID of the entity in the provider. provider_name: type: string enum: - adyen - stripe - mollie - gocardless - airwallex - salesforce - hubspot - attio - xero - pennylane - zoho-books - exact-online - quickbooks - netsuite - rillet - datev - anrok - chargebee - slack - plain - zendesk - pylon - intercom - front - helpscout - claap - grain - gong - jiminny - modjo - posthog description: Provider name. provider_account_id: type: string description: ID of the connected provider account. created_at: type: - string - 'null' format: date-time description: >- Creation date of the entity in the provider, when it was imported from there. Exposed on products and coupons; `null` when the provider does not report one. example: '2024-12-20T16:04:11Z' required: - entity_id - provider_name - provider_account_id description: Reference to the entity in an external provider. example: entity_id: '123456789' provider_name: stripe provider_account_id: acc_1234567890 required: - integrations InvoiceDeprecated: type: object properties: id: type: string description: Invoice ID. example: inv_1eTaiytfA0i2Va number: type: string description: >- Invoice number. Generated by Hyperline using the sequential numbering and format defined in your settings. example: INV-35 type: type: string enum: - invoice - credit_note - document - child_invoice_ref - child_creditnote_ref description: >- Type of the invoice. - `invoice`: Legal invoice to be paid by your customer. - `credit_note`: Legal credit note cancelling an invoice and refunding your customer. - `document`: Custom document with no legal value. Can be generated from a subscription to meet specific needs. example: invoice document_name: type: - string - 'null' description: >- If the invoice is of type `document` you can give it a custom name (displayed on the final PDF). example: null status: type: string enum: - draft - pending_approval - changes_requested - open - to_pay - grace_period - partially_paid - paid - voided - closed - error - missing_info - archived - charged_on_parent - pending_parent_concat - pending_consolidation - consolidated - uncollectible description: > Current invoice status. - `draft`: Invoice is in draft mode (not finalized yet). - `open`: Invoice for the current billing period, which will be issued at the end of the period (used for invoices with usage-based data). - `grace_period`: Invoice is in a review period after being issued for the billing period and before becoming due for payment. - `to_pay`: Invoice is awaiting payment. - `partially_paid`: Invoice is partially paid. - `paid`: Invoice is fully paid. - `voided`: Invoice has been voided and is no longer valid. - `closed`: Invoice was not issued and has been discarded. - `error`: Invoice failed to be paid. - `archived`: A previous version of an invoice. - `charged_on_parent`: Invoice is charged on the parent customer. - `pending_parent_concat`: Invoice is pending invoices concatenation on the parent customer to be grouped. - `uncollectible`: Invoice is uncollectible (bad debt). Only metadata (properties, custom_note, custom_properties) can be updated in this status. example: paid reference: type: - string - 'null' description: >- Unique identifier to ease reconciliation with payment. Useful for bank transfer. example: V0KAHOU6J3 purchase_order: type: - string - 'null' description: Reference to the purchase order linked to the invoice. example: PO-12345 currency: type: string enum: - EUR - AED - AFN - XCD - ALL - AMD - AOA - ARS - USD - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - XOF - BMD - BND - BOB - BRL - BSD - BTN - NOK - BWP - BYR - BZD - CAD - CDF - XAF - CHF - NZD - CLP - CNY - COP - CRC - CUP - CVE - ANG - CZK - DJF - DKK - DOP - DZD - EGP - MAD - ERN - ETB - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MUR - MVR - MWK - MXN - MYR - MZN - NAD - XPF - NGN - NIO - NPR - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - UYU - UZS - VEF - VND - VUV - WST - YER - ZAR - ZMW - ZWL description: >- Currency code. See [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes). example: EUR source: type: string enum: - hyperline - api - pennylane - chargebee - stripe - lago - sequence - other description: | Source of the invoice. - `hyperline`: Invoice created by Hyperline. - `api`: Invoice created through the API. - `other`: Invoice created by an external source. example: hyperline total_amount: type: number description: >- Sum of the amount and taxes amount of all products on the invoice. Expressed in currency's smallest unit. example: 24000 amount_due: type: number description: >- Amount still need to be paid for the invoice. Expressed in currency's smallest unit. example: 0 amount_paid: type: number description: >- Amount already paid for the invoice. Expressed in currency's smallest unit. example: 24000 amount_fixed: type: number description: >- Amount corresponding to the recurring non-variable part of the total amount. Expressed in currency's smallest unit. example: 20000 amount_excluding_tax: type: number description: >- Total amount without the taxes amount. Expressed in currency's smallest unit. example: 20000 tax_rate: type: number description: Deprecated field, please use `line_items[].tax_rate`. deprecated: true tax_amount: type: number description: Tax amount of the invoice. Expressed in currency's smallest unit. example: 4000 tax_scheme: type: string enum: - exempt - standard - reverse_charge - manual - not_eligible description: >- Tax scheme of the invoice. - `standard`: Tax rate is resolved depending on local tax regulations. - `exempt`: No tax rate applied because the customer country doesn't require it. - `reverse_charge`: No tax rate applied because the customer is eligible to EU reverse charge. - `manual`: Tax rate has been manually specified when creating the invoice. - `not_eligible`: Tax collection is disabled for the invoice. example: standard discount_amount: type: number description: >- Amount corresponding to the discounted part of the total amount. Expressed in currency's smallest unit. example: 0 conversion_rate: type: - number - 'null' description: >- Conversion rate used between the invoice currency and your accounting currency. example: 1 converted_amount: type: - number - 'null' description: >- Amount converted using the conversion rate. Expressed in currency's smallest unit. example: 24000 converted_at: type: - string - 'null' format: date-time description: Date of the conversion of the amount. example: '2024-10-13T02:00:00.000Z' payment_method_id: type: - string - 'null' description: >- ID of the default payment method used to pay the invoice. Transactions related to the invoice may use different payment methods. example: pm_1ryTrMj4TTAT1N bank_account_id: type: - string - 'null' description: >- ID of the bank account displayed on the invoice. Transactions related to the invoice may use different bank accounts. example: bac_KJyPrMA1toAqRG custom_note: type: - string - 'null' description: Custom note added to the invoice. example: Thank you for your purchase! additional_info: type: - string - 'null' description: >- Additional information added to the invoice. If not defined, it will be inherited from the invoicing entity's settings. example: >- This invoice must be paid within the payment delay indicated. After this period a late payment penalty of 10% will be applied. footer: type: - string - 'null' description: >- Footer added to the invoice. If not defined, it will be inherited from the invoicing entity's settings. example: ACME (Acme SAS) is a company registered in France | SIREN N°123456 customer: type: object properties: id: type: string description: Customer ID. example: cus_Typ0px2W0aiEtl name: type: string description: Customer name. example: Acme email: type: - string - 'null' description: Email to which all communications will be sent. example: billing@acme.com external_id: type: - string - 'null' description: >- ID of the customer in your system. This helps matching your customer with the one on Hyperline. example: null vat_number: type: - string - 'null' description: Deprecated field, please use `tax_id`. deprecated: true tax_id: type: - string - 'null' description: Value of the customer tax ID. example: FR123456789 local_tax_number: type: - string - 'null' description: Customer local tax number. example: 12/345/67890 registration_number: type: - string - 'null' description: Customer registration number. example: '36252187900034' address: $ref: '#/components/schemas/Address' required: - id - name - email - external_id - vat_number - tax_id - local_tax_number - registration_number - address seller: type: object properties: id: type: string description: ID of the invoicing entity attached to the invoice. example: ive_47484fjdhy5 name: type: string description: Name of the invoicing entity example: Name of the invoicing entity tax_id: type: - string - 'null' description: Tax identifier / VAT number of the invoicing entity example: FR5878986578 registration_number: type: - string - 'null' description: >- Legal registration number of the invoicing entity, as it stood when the invoice was emitted. example: '87898657800016' address: allOf: - $ref: '#/components/schemas/Address' - description: Seller address. required: - id - name - tax_id - registration_number - address subscription_id: type: - string - 'null' description: ID of the subscription related to the invoice. example: sub_amiaWZ3lzDIWaoT period_starts_at: type: - string - 'null' format: date-time description: Start date of the billing period of the invoice. example: '2024-10-13T00:00:00.000Z' period_ends_at: type: - string - 'null' format: date-time description: End date of the billing period of the invoice. example: '2024-11-13T00:00:00.000Z' emitted_at: type: string format: date-time description: Issue date of the invoice. example: '2024-10-13T00:00:00.000Z' due_at: type: string format: date-time description: >- Due date of the invoice. Computed from the issue date and the payment delay configured in your settings. example: '2024-11-12T00:00:00.000Z' issuing_method: type: string enum: - manual - scheduled description: > How the invoice is issued. - `manual`: Issued when finalized, by a user or by the invoicing flow. - `scheduled`: Draft finalized automatically at the start of its issue date (`issued_at`), in the invoice timezone. example: manual refunded_at: type: - string - 'null' format: date-time description: >- Date corresponding to the refund of the invoice, previously paid. A credit note exists with an original invoice ID equals to this invoice ID. example: null grace_period_ended_at: type: - string - 'null' format: date-time description: >- Date the invoice grace period ended. This happens at the issue date + the grace period duration configured in your settings. example: null settled_at: type: - string - 'null' format: date-time description: Date the invoice was fully paid. example: '2024-10-15T14:01:56.000Z' updated_at: type: - string - 'null' format: date-time description: Date of the last update. example: '2024-10-15T14:01:56.000Z' properties: type: - object - 'null' additionalProperties: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: array items: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: 'null' - type: 'null' description: Key/value pairs to store any metadata useful in your context. example: null custom_properties: type: - object - 'null' additionalProperties: anyOf: - type: string - type: number - type: boolean - type: string format: date-time description: >- UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-12-20T16:04:11Z' - type: array items: type: string - type: 'null' description: >- Values for custom properties defined for the `invoice` entity, keyed by slug. example: null additional_display_fields: type: - array - 'null' items: oneOf: - type: object properties: type: type: string enum: - standard description: Display a standard invoice field. field: type: string enum: - customer_id - subscription_id - quote_id description: Standard invoice field to display. required: - type - field - type: object properties: type: type: string enum: - custom_property description: Display an invoice or customer custom property. slug: type: string description: >- Slug of the invoice or customer custom property to display. required: - type - slug - type: object properties: type: type: string enum: - custom description: Display a custom label and value. label: type: string minLength: 1 maxLength: 100 description: Label displayed on the invoice. value: type: string maxLength: 500 description: Value displayed on the invoice. required: - type - label - value maxItems: 20 description: >- Ordered additional fields displayed on the invoice PDF. Invoice and customer custom properties are referenced by slug. example: null original_invoice_id: type: - string - 'null' description: >- ID of the reference invoice this entity is linked to. For credit notes, this is not necessarily an invoice receiving credit; use `allocations` for applications. example: null original_invoice_number: type: - string - 'null' description: >- Number of the original invoice this entity is linked to (only used for credit note). example: null line_items: type: array items: $ref: '#/components/schemas/InvoiceLineItem' description: List of line items composing the invoice. allocations: type: array items: type: object properties: invoice_id: type: string description: ID of the invoice receiving the credit. example: inv_2QdJDDUej969ev amount: type: number description: >- Credit amount applied to the invoice, in the currency's smallest unit. example: 780000 required: - invoice_id - amount description: >- Current invoice applications made by this credit note. Only present for credit notes. coupons: type: array items: $ref: '#/components/schemas/InvoiceCoupon' description: List of coupons applied to the invoice. transactions: type: array items: allOf: - type: object properties: id: type: string description: Transaction ID. example: tra_2QdJDDUej969ev type: type: string enum: - subscription - one_time - refund - chargeback description: >- Transaction type. - `subscription`: The transaction is related to a subscription payment. - `one_time`: The transaction is related to a one-time payment. - `refund`: The transaction is related to a refund payment. - `chargeback`: The transaction records funds withdrawn after a payment dispute. example: subscription amount: type: number description: Transaction amount. example: 31500 currency: type: string enum: - EUR - AED - AFN - XCD - ALL - AMD - AOA - ARS - USD - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - XOF - BMD - BND - BOB - BRL - BSD - BTN - NOK - BWP - BYR - BZD - CAD - CDF - XAF - CHF - NZD - CLP - CNY - COP - CRC - CUP - CVE - ANG - CZK - DJF - DKK - DOP - DZD - EGP - MAD - ERN - ETB - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MUR - MVR - MWK - MXN - MYR - MZN - NAD - XPF - NGN - NIO - NPR - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - UYU - UZS - VEF - VND - VUV - WST - YER - ZAR - ZMW - ZWL description: Transaction currency. example: EUR customer_id: type: string description: ID of the customer linked to the transaction. example: cus_QalW2vTAdkR6IY provider_id: type: - string - 'null' description: Deprecated field, please use `integrations[].entity_id`. deprecated: true process_at: type: string format: date-time description: >- Date corresponding to the processing of the transaction. If in the future, the transaction is scheduled to be processed. example: '2024-11-12T07:38:39.222Z' settled_at: type: - string - 'null' format: date-time description: >- Date when the transaction was settled. For provider transactions, this is derived from provider settlement data when available. example: '2024-11-12T07:38:39.222Z' refunded_at: type: - string - 'null' format: date-time description: Date corresponding to the refund of the transaction. example: null original_transaction_id: type: - string - 'null' description: >- Original payment transaction ID for a refund or chargeback. example: null reversed_at: type: - string - 'null' format: date-time description: Date when a chargeback withdrawal was reversed. example: null last_refreshed_at: type: - string - 'null' format: date-time description: >- Date corresponding to the last synchronization of the details with the payment provider. example: null provider_fee: type: - object - 'null' properties: amount: type: number description: >- Monetary amount. Expressed in currency's smallest unit. currency: type: string enum: - EUR - AED - AFN - XCD - ALL - AMD - AOA - ARS - USD - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - XOF - BMD - BND - BOB - BRL - BSD - BTN - NOK - BWP - BYR - BZD - CAD - CDF - XAF - CHF - NZD - CLP - CNY - COP - CRC - CUP - CVE - ANG - CZK - DJF - DKK - DOP - DZD - EGP - MAD - ERN - ETB - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MUR - MVR - MWK - MXN - MYR - MZN - NAD - XPF - NGN - NIO - NPR - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - UYU - UZS - VEF - VND - VUV - WST - YER - ZAR - ZMW - ZWL description: >- Currency code. See [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes). example: EUR exchange_rate: type: - number - 'null' required: - amount - currency - exchange_rate description: >- Fee applied by the Payment Service Provider. Only supported for Stripe. example: null chargeback: type: - object - 'null' properties: amount: type: number description: Total chargeback loss amount. example: 31500 last_chargeback_at: type: string format: date-time description: Date corresponding to the last chargeback loss event. example: '2024-10-13T10:00:01.860Z' required: - amount - last_chargeback_at description: >- Deprecated field. Use transactions where `type` is `chargeback`; `original_transaction_id` identifies the affected payment transaction. deprecated: true example: null integrations: type: array items: type: object properties: entity_id: type: string description: ID of the entity in the provider. provider_name: type: string enum: - adyen - stripe - mollie - gocardless - airwallex - salesforce - hubspot - attio - xero - pennylane - zoho-books - exact-online - quickbooks - netsuite - rillet - datev - anrok - chargebee - slack - plain - zendesk - pylon - intercom - front - helpscout - claap - grain - gong - jiminny - modjo - posthog description: Provider name. provider_account_id: type: string description: ID of the connected provider account. created_at: type: - string - 'null' format: date-time description: >- Creation date of the entity in the provider, when it was imported from there. Exposed on products and coupons; `null` when the provider does not report one. example: '2024-12-20T16:04:11Z' required: - entity_id - provider_name - provider_account_id description: Reference to the entity in an external provider. example: entity_id: '123456789' provider_name: stripe provider_account_id: acc_1234567890 required: - id - type - amount - currency - customer_id - provider_id - process_at - settled_at - refunded_at - original_transaction_id - reversed_at - last_refreshed_at - provider_fee - chargeback - integrations - oneOf: - type: object properties: payment_method_type: type: string enum: - card - direct_debit - direct_debit_ach - direct_debit_bacs description: Payment method type used for the transaction. payment_method: $ref: '#/components/schemas/PaymentMethod' required: - payment_method_type - payment_method - type: object properties: payment_method_type: type: string enum: - transfer - transfer_automated description: Payment method type used for the transaction. bank_account: allOf: - $ref: '#/components/schemas/BankAccount' - anyOf: - $ref: '#/components/schemas/StandardBankAccount' - $ref: '#/components/schemas/ConnectedBankAccount' - type: 'null' description: Bank account used for a bank transfer transaction. required: - payment_method_type - bank_account - type: object properties: payment_method_type: type: string enum: - wallet description: Payment method type used for the transaction. wallet_id: type: string description: ID of the wallet used for a wallet transaction. example: wal_PPpxP5d3uvgiTT required: - payment_method_type - wallet_id - type: object properties: payment_method_type: type: string enum: - external description: Payment method type used for the transaction. required: - payment_method_type - anyOf: - type: object properties: status: type: string enum: - scheduled - to_process - pending - settled - cancelled description: >- Transaction status. - `scheduled`: The transaction is scheduled to be processed in the future. - `to_process`: The transaction is waiting to be processed by our system. - `pending`: The transaction has been authorized by the related payment processor, but the banking transaction is not yet settled. - `settled`: The transaction has been cleared on the banking side, the money transfer is fully completed. - `cancelled`: The transaction has been cancelled and won't be processed again. example: settled required: - status - type: object properties: status: type: string enum: - failed description: |- Transaction status. - `failed`: The transaction failed. example: failed error_type: type: - string - 'null' enum: - authentication_required - declined - fraud - insufficient_funds - mandate_invalid - payment_method_authorization_error - payment_method_declined - payment_method_expired - payment_method_invalid - payment_method_not_supported - processing_error - provider_error - unknown description: >- Transaction error type. - `authentication_required`: The card was declined as the transaction requires authentication (e.g. 3-D Secure). The customer should go to their portal page and authenticate their card. If the error happened on an already authenticated transaction, the customer needs to contact their card issuer for more information. - `payment_method_authorization_error`: A transaction authorization cannot be created for a variety of reasons such as the card issuer couldn't be reached, or the card requires a PIN. - `payment_method_declined`: The payment method was declined for a variety of reasons such as a card reported as lost or stolen, insufficient funds or reaching the limit available on the method to complete the purchase, a payment method on a known block list, etc. - `payment_method_expired`: The payment method is expired. The customer should go to their portal page and change their payment method. - `payment_method_invalid`: The payment method is invalid in most cases because of incorrect details (card/account number, CVC, expiration date, postal code). - `payment_method_not_supported`: The payment method doesn't support this type of purchase (e.g. currency, online payment). - `declined`: The payment was declined for a variety of reasons such as security violation, banking service not available, transaction not allowed, etc. - `fraud`: The payment provider suspected the transaction was fraudulent and has been blocked. Don't report more detailed information to your customer, and check on your provider account. - `processing_error`: The payment couldn't be processed by the issuer for an unknown reason. - `provider_error`: An error occurred when contacting the payment provider to initiate the transaction. - `unknown`: A generic error happened on the payment provider side. example: null error_message: type: - string - 'null' description: Details of the error. example: null required: - status - error_type - error_message description: List of transactions related to the invoice. public_url: type: string format: uri description: >- Public URL of the invoice page where the customer can pay the invoice. required: - id - number - type - document_name - status - reference - purchase_order - currency - source - total_amount - amount_due - amount_paid - amount_fixed - amount_excluding_tax - tax_rate - tax_amount - tax_scheme - discount_amount - conversion_rate - converted_amount - converted_at - payment_method_id - bank_account_id - custom_note - additional_info - footer - customer - seller - subscription_id - period_starts_at - period_ends_at - emitted_at - due_at - issuing_method - refunded_at - grace_period_ended_at - settled_at - updated_at - properties - custom_properties - additional_display_fields - original_invoice_id - original_invoice_number - line_items - coupons - transactions - public_url MeteringFilterConfiguration: type: object properties: conditional: type: string enum: - and - or description: >- Logical operator used to combine multiple filter fields. `and` requires all fields to match, `or` requires at least one. fields: type: array items: allOf: - type: object properties: property: type: string description: Name of the event property to filter on. required: - property - oneOf: - type: object properties: operator: type: string enum: - is_null - is_not_null description: Comparison operator to apply on the property value. required: - operator title: Null check - type: object properties: operator: type: string enum: - in - not_in description: Comparison operator to apply on the property value. value: type: string required: - operator - value title: List match - type: object properties: operator: type: string enum: - gte - gt - lt - lte description: Comparison operator to apply on the property value. value: type: number required: - operator - value title: Numeric comparison - type: object properties: operator: type: string enum: - equals - not_equal description: Comparison operator to apply on the property value. value: anyOf: - type: string - type: number - type: boolean required: - operator - value title: Equality check required: - conditional - fields description: Configuration of the rules used to filter eligible events. example: conditional: and fields: - property: card_type operator: equals value: visa - property: kind operator: equals value: credit_card Address: type: - object - 'null' properties: name: type: - string - 'null' description: Address name. example: Acme line1: type: - string - 'null' description: Address first line. example: 5 rue de Paradis line2: type: - string - 'null' description: Address second line (optional). example: null city: type: - string - 'null' description: Address city. example: Paris zip: type: - string - 'null' description: Address ZIP code. example: '75010' state: type: - string - 'null' enum: - AA - AE - AK - AL - AP - AR - AS - AZ - CA - CO - CT - DC - DE - FL - GA - GU - HI - IA - ID - IL - IN - KS - KY - LA - MA - MD - ME - MI - MN - MO - MP - MS - MT - NC - ND - NE - NH - NJ - NM - NV - NY - OH - OK - OR - PA - PR - RI - SC - SD - TN - TX - UT - VA - VI - VT - WA - WI - WV - WY description: >- Only for US country. Second part of subdivision code in ISO format. See [ISO 3166-2:US](https://en.wikipedia.org/wiki/ISO_3166-2:US). example: CA country: type: - string - 'null' enum: - AD - AE - AF - AG - AI - AL - AM - AO - AQ - AR - AS - AT - AU - AW - AX - AZ - BA - BB - BD - BE - BG - BH - BI - BJ - BL - BM - BN - BO - BQ - BR - BS - BT - BF - BV - BW - BY - BZ - CA - CC - CD - CF - CG - CH - CI - CK - CL - CM - CN - CO - CR - CU - CV - CW - CX - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - EH - ER - ES - ES-CE - ES-ML - ET - FI - FJ - FK - FM - FO - FR - GA - GB - GD - GE - GF - GG - GH - GI - GL - GM - GN - GP - GQ - GR - GS - GT - GU - GW - GY - HK - HM - HN - HR - HT - HU - IC - ID - IE - IL - IM - IN - IO - IQ - IR - IS - IT - JE - JM - JO - JP - KE - KG - KH - KI - KM - KN - KP - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MF - MG - MH - MK - ML - MM - MN - MO - MP - MQ - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NC - NE - NF - NG - NI - NL - 'NO' - NP - NR - NU - NZ - OM - PA - PE - PF - PG - PH - PK - PL - PM - PN - PR - PS - PT - PT-20 - PT-30 - PW - PY - QA - RE - RO - RS - RU - RW - SA - SB - SC - SD - SE - SG - SH - SI - SJ - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SY - SZ - TC - TD - TF - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - UM - US - UY - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - XK - YE - YT - ZA - ZM - ZW description: >- Two-letter country code in ISO format. See [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). example: FR description: Customer billing address. InvoiceLineItem: type: object properties: id: type: string description: Invoice line item ID. example: ili_0FACNpeoEFkGu3 name: type: string description: Name of the line item, corresponding to the related product. example: Platform access entry_type: type: string enum: - debit - credit description: Indicates whether the line item is a debit or credit. example: debit product_id: type: - string - 'null' description: Product ID related to the invoice line item. example: itm_KbLcWt2qm5p1S2 product_type: type: - string - 'null' enum: - flat_fee - seat - dynamic - credit - bundle description: Product type related to the invoice line item. example: flat_fee units_count: type: number description: Count of units of the product related to the invoice line item. example: 1 unit_amount: type: number description: >- Amount of one unit of the product related to the invoice line item. Expressed in currency's smallest unit. example: 24000 amount: type: number description: >- Total amount of the invoice line item. Debit or credit can be distinguished using the `entry_type` field. Expressed in currency's smallest unit. example: 24000 amount_excluding_tax: type: number description: >- Total amount without the taxes amount of the invoice line item. Expressed in currency's smallest unit. example: 20000 tax_rate: type: number description: Tax rate of the invoice line item. example: 20 tax_rate_id: type: - string - 'null' description: Custom tax rate ID applied to the invoice line item. example: null tax_amount: type: number description: >- Tax amount of the invoice line item. Expressed in currency's smallest unit. example: 4000 discount_amount: type: number description: >- Amount corresponding to the discounted part of the total amount of the invoice line item. Expressed in currency's smallest unit. example: 0 discount_percent: type: - number - 'null' description: >- Percentage applied to compute the discounted part of the invoice line amount. Only if coupons applied are percentage based. period_starts_at: type: - string - 'null' format: date-time description: Start date of the period corresponding to the line item charge. example: '2024-10-13T00:00:00.000Z' period_ends_at: type: - string - 'null' format: date-time description: End date of the period corresponding to the line item charge. example: '2024-11-13T00:00:00.000Z' revenue_type: type: - string - 'null' enum: - recurring - variable - one_off description: >- Revenue type classification of the line item. - `recurring`: Recurring revenue (MRR) from subscription products billed at regular intervals. - `variable`: Variable revenue from usage-based products. - `one_off`: One-time revenue from single charges or products billed once. example: recurring revenue_interval_count: type: - number - 'null' description: >- For recurring revenue, the number of interval periods between billings (e.g., 1 for monthly, 12 for annual). example: 1 revenue_interval_period: type: - string - 'null' enum: - days - weeks - months - quarters - years - once - all description: >- For recurring revenue, the interval period (days, weeks, months, quarters, years). example: months display_unit_amount: type: boolean description: >- Whether the unit amount is displayed on the invoice PDF. Defaults to true. example: true display_service_period: type: boolean description: >- Whether the service period dates are displayed in the line item description on the invoice PDF. Defaults to true. example: true original_line_item_id: type: - string - 'null' description: >- ID of the original line item this line item is linked to (used for organisation-based billing). example: null required: - id - name - entry_type - product_id - product_type - units_count - unit_amount - amount - amount_excluding_tax - tax_rate - tax_rate_id - tax_amount - discount_amount - discount_percent - period_starts_at - period_ends_at - revenue_type - revenue_interval_count - revenue_interval_period - display_unit_amount - display_service_period - original_line_item_id InvoiceCoupon: type: object properties: id: type: - string - 'null' description: Coupon ID. example: cou_DKL4Xcb5VSa8CQ name: type: - string - 'null' description: Coupon name. example: Partner discount discount_amount: type: - number - 'null' description: >- Amount to apply as a discount on the total amount (excluding taxes) of a subscription. Expressed in the currency's smallest unit. example: 2000 discount_percent: type: - number - 'null' description: >- Percentage to apply as a discount on the amount (excluding taxes) of a product. example: null line_item_ids: type: - array - 'null' items: type: string description: >- IDs of the line items to which the coupon applies. Null means all line items. example: - ili_0FACNpeoEFkGu3 required: - id - name - discount_amount - discount_percent - line_item_ids PaymentMethod: anyOf: - type: object properties: id: type: string description: Payment method ID. example: pm_1xMpj5bwRqN7LM status: type: string enum: - active - pending - expired - errored description: >- Payment method status. - `active`: The payment method is ready to be used. - `pending`: The payment method is pending activation or being validated. example: active type: type: string enum: - card - apple_pay - google_pay description: |- Payment method type. - `card`: Credit or debit card - `apple_pay`: Apple Pay - `google_pay`: Google Pay - `direct_debit_sepa`: SEPA Direct Debit - `direct_debit_ach`: ACH Direct Debit - `direct_debit_bacs`: Bacs Direct Debit - `stripe_link`: Stripe Link example: card last_4_digits: type: - number - 'null' description: Last four digits of the card. example: 2718 expiration_date: type: - string - 'null' description: Expiration date of the card using YYYY-MM format. example: 2027-11 brand: type: - string - 'null' description: Brand of the card. examples: - visa - mastercard - amex required: - id - status - type - last_4_digits - expiration_date - brand title: Card - type: object properties: id: type: string description: Payment method ID. example: pm_1xMpj5bwRqN7LM status: type: string enum: - errored description: >- Payment method status. - `errored`: The payment method has failed and can no longer be used. example: errored error_type: type: string enum: - authentication_required - authorization_error - insufficient_funds - declined - expired - fraud - invalid - mandate_invalid - not_supported - unknown description: >- Payment method error type. - `authentication_required`: The card was declined as the transaction requires authentication (e.g. 3-D Secure). The customer should go to their portal page and authenticate their card. If the error happened on an already authenticated transaction, the customer needs to contact their card issuer for more information. - `authorization_error`: A transaction authorization cannot be created for a variety of reasons such as the card issuer couldn't be reached, or the card requires a PIN. - `declined`: The payment method was declined for a variety of reasons such as a card reported as lost or stolen, insufficient funds or reaching the limit available on the method to complete the purchase, a payment method on a known block list, etc. - `expired`: The payment method is expired. The customer should go to their portal page and change their payment method. - `fraud`: The payment provider suspected the payment method was fraudulent and has been blocked. Don't report more detailed information to your customer, and check on your provider account. - `invalid`: The payment method is invalid in most cases because of incorrect details (card/account number, CVC, expiration date, postal code). - `not_supported`: The payment method doesn't support this type of purchase (e.g. currency, online payment). - `unknown`: A generic error happened on the payment provider side. example: expired type: type: string enum: - card - apple_pay - google_pay description: |- Payment method type. - `card`: Credit or debit card - `apple_pay`: Apple Pay - `google_pay`: Google Pay - `direct_debit_sepa`: SEPA Direct Debit - `direct_debit_ach`: ACH Direct Debit - `direct_debit_bacs`: Bacs Direct Debit - `stripe_link`: Stripe Link example: card last_4_digits: type: - number - 'null' description: Last four digits of the card. example: 2718 expiration_date: type: - string - 'null' description: Expiration date of the card using YYYY-MM format. example: 2027-11 brand: type: - string - 'null' description: Brand of the card. examples: - visa - mastercard - amex required: - id - status - error_type - type - last_4_digits - expiration_date - brand title: Card (errored) - type: object properties: id: type: string description: Payment method ID. example: pm_1xMpj5bwRqN7LM status: type: string enum: - active - pending - expired - errored description: >- Payment method status. - `active`: The payment method is ready to be used. - `pending`: The payment method is pending activation or being validated. example: active type: type: string enum: - direct_debit - direct_debit_ach - direct_debit_bacs description: |- Payment method type. - `card`: Credit or debit card - `apple_pay`: Apple Pay - `google_pay`: Google Pay - `direct_debit_sepa`: SEPA Direct Debit - `direct_debit_ach`: ACH Direct Debit - `direct_debit_bacs`: Bacs Direct Debit - `stripe_link`: Stripe Link example: direct_debit account_number_ending: type: - string - 'null' description: Last characters of the account number. example: '6789' required: - id - status - type - account_number_ending title: Direct Debit - type: object properties: id: type: string description: Payment method ID. example: pm_1xMpj5bwRqN7LM status: type: string enum: - errored description: >- Payment method status. - `errored`: The payment method has failed and can no longer be used. example: errored error_type: type: string enum: - authentication_required - authorization_error - insufficient_funds - declined - expired - fraud - invalid - mandate_invalid - not_supported - unknown description: >- Payment method error type. - `authentication_required`: The card was declined as the transaction requires authentication (e.g. 3-D Secure). The customer should go to their portal page and authenticate their card. If the error happened on an already authenticated transaction, the customer needs to contact their card issuer for more information. - `authorization_error`: A transaction authorization cannot be created for a variety of reasons such as the card issuer couldn't be reached, or the card requires a PIN. - `declined`: The payment method was declined for a variety of reasons such as a card reported as lost or stolen, insufficient funds or reaching the limit available on the method to complete the purchase, a payment method on a known block list, etc. - `expired`: The payment method is expired. The customer should go to their portal page and change their payment method. - `fraud`: The payment provider suspected the payment method was fraudulent and has been blocked. Don't report more detailed information to your customer, and check on your provider account. - `invalid`: The payment method is invalid in most cases because of incorrect details (card/account number, CVC, expiration date, postal code). - `not_supported`: The payment method doesn't support this type of purchase (e.g. currency, online payment). - `unknown`: A generic error happened on the payment provider side. example: expired type: type: string enum: - direct_debit - direct_debit_ach - direct_debit_bacs description: |- Payment method type. - `card`: Credit or debit card - `apple_pay`: Apple Pay - `google_pay`: Google Pay - `direct_debit_sepa`: SEPA Direct Debit - `direct_debit_ach`: ACH Direct Debit - `direct_debit_bacs`: Bacs Direct Debit - `stripe_link`: Stripe Link example: direct_debit account_number_ending: type: - string - 'null' description: Last characters of the account number. example: '6789' required: - id - status - error_type - type - account_number_ending title: Direct Debit (errored) - type: object properties: id: type: string description: Payment method ID. example: pm_1xMpj5bwRqN7LM status: type: string enum: - active - pending - expired - errored description: >- Payment method status. - `active`: The payment method is ready to be used. - `pending`: The payment method is pending activation or being validated. example: active type: type: string enum: - stripe_link description: |- Payment method type. - `card`: Credit or debit card - `apple_pay`: Apple Pay - `google_pay`: Google Pay - `direct_debit_sepa`: SEPA Direct Debit - `direct_debit_ach`: ACH Direct Debit - `direct_debit_bacs`: Bacs Direct Debit - `stripe_link`: Stripe Link example: stripe_link required: - id - status - type title: Stripe Link - type: object properties: id: type: string description: Payment method ID. example: pm_1xMpj5bwRqN7LM status: type: string enum: - errored description: >- Payment method status. - `errored`: The payment method has failed and can no longer be used. example: errored error_type: type: string enum: - authentication_required - authorization_error - insufficient_funds - declined - expired - fraud - invalid - mandate_invalid - not_supported - unknown description: >- Payment method error type. - `authentication_required`: The card was declined as the transaction requires authentication (e.g. 3-D Secure). The customer should go to their portal page and authenticate their card. If the error happened on an already authenticated transaction, the customer needs to contact their card issuer for more information. - `authorization_error`: A transaction authorization cannot be created for a variety of reasons such as the card issuer couldn't be reached, or the card requires a PIN. - `declined`: The payment method was declined for a variety of reasons such as a card reported as lost or stolen, insufficient funds or reaching the limit available on the method to complete the purchase, a payment method on a known block list, etc. - `expired`: The payment method is expired. The customer should go to their portal page and change their payment method. - `fraud`: The payment provider suspected the payment method was fraudulent and has been blocked. Don't report more detailed information to your customer, and check on your provider account. - `invalid`: The payment method is invalid in most cases because of incorrect details (card/account number, CVC, expiration date, postal code). - `not_supported`: The payment method doesn't support this type of purchase (e.g. currency, online payment). - `unknown`: A generic error happened on the payment provider side. example: expired type: type: string enum: - stripe_link description: |- Payment method type. - `card`: Credit or debit card - `apple_pay`: Apple Pay - `google_pay`: Google Pay - `direct_debit_sepa`: SEPA Direct Debit - `direct_debit_ach`: ACH Direct Debit - `direct_debit_bacs`: Bacs Direct Debit - `stripe_link`: Stripe Link example: stripe_link required: - id - status - error_type - type title: Stripe Link (errored) - type: 'null' description: Payment method used for a card or direct debit transaction. BankAccount: anyOf: - $ref: '#/components/schemas/StandardBankAccount' - $ref: '#/components/schemas/ConnectedBankAccount' StandardBankAccount: allOf: - type: object properties: type: type: string enum: - standard description: | Bank account type. - `standard`: Bank account not connected through open banking. - `connected`: Bank account connected through open banking. example: standard required: - type - type: object properties: id: type: string description: Bank account ID. example: bac_KJyPrMA1toAqRG currency: type: string enum: - EUR - AED - AFN - XCD - ALL - AMD - AOA - ARS - USD - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - XOF - BMD - BND - BOB - BRL - BSD - BTN - NOK - BWP - BYR - BZD - CAD - CDF - XAF - CHF - NZD - CLP - CNY - COP - CRC - CUP - CVE - ANG - CZK - DJF - DKK - DOP - DZD - EGP - MAD - ERN - ETB - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MUR - MVR - MWK - MXN - MYR - MZN - NAD - XPF - NGN - NIO - NPR - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - UYU - UZS - VEF - VND - VUV - WST - YER - ZAR - ZMW - ZWL description: Bank account currency. example: EUR bank_name: type: - string - 'null' description: Bank name. example: Fake bank name: type: - string - 'null' description: Bank account display name. example: Main account country: type: - string - 'null' description: Bank account country. example: FR required: - id - currency - bank_name - name - country - anyOf: - type: object properties: format: type: string enum: - iban_bic_swift description: Bank account details format. example: iban_bic_swift iban: type: string description: IBAN. example: FR7630006000011234567890189 bic_swift: type: - string - 'null' description: BIC or SWIFT code. example: BNPAFRPP required: - format - iban - bic_swift - type: object properties: format: type: string enum: - sort_code_account_number description: Bank account details format. example: sort_code_account_number sort_code: type: string description: Sort code. example: '123456' account_number: type: string description: Account number. example: '000123456789' required: - format - sort_code - account_number - type: object properties: format: type: string enum: - account_number_routing_number description: Bank account details format. example: account_number_routing_number account_number: type: string description: Account number. example: '000123456789' routing_number: type: string description: Routing number. example: '021000021' required: - format - account_number - routing_number - type: object properties: format: type: string enum: - account_number_bic_swift description: Bank account details format. example: account_number_bic_swift account_number: type: string description: Account number. example: '000123456789' bic_swift: type: string description: BIC or SWIFT code. example: BNPAFRPP required: - format - account_number - bic_swift example: format: iban_bic_swift iban: FR7630006000011234567890189 bic_swift: BNPAFRPP ConnectedBankAccount: allOf: - type: object properties: type: type: string enum: - connected description: | Bank account type. - `standard`: Bank account not connected through open banking. - `connected`: Bank account connected through open banking. example: connected status: type: string enum: - active - error description: Bank account connection status. example: active balance: type: - number - 'null' description: >- Latest known balance for connected bank accounts, expressed in the currency's smallest unit. example: 120500 last_refreshed_at: type: - string - 'null' format: date-time description: Date when the connected bank account was last refreshed. example: '2026-01-15T10:30:00.000Z' last_error_type: type: - string - 'null' enum: - provider_error - invalid_credentials - unknown description: Latest connection error type, when the account is errored. example: null required: - type - status - balance - last_refreshed_at - last_error_type - type: object properties: id: type: string description: Bank account ID. example: bac_KJyPrMA1toAqRG currency: type: string enum: - EUR - AED - AFN - XCD - ALL - AMD - AOA - ARS - USD - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - XOF - BMD - BND - BOB - BRL - BSD - BTN - NOK - BWP - BYR - BZD - CAD - CDF - XAF - CHF - NZD - CLP - CNY - COP - CRC - CUP - CVE - ANG - CZK - DJF - DKK - DOP - DZD - EGP - MAD - ERN - ETB - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MUR - MVR - MWK - MXN - MYR - MZN - NAD - XPF - NGN - NIO - NPR - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - UYU - UZS - VEF - VND - VUV - WST - YER - ZAR - ZMW - ZWL description: Bank account currency. example: EUR bank_name: type: - string - 'null' description: Bank name. example: Fake bank name: type: - string - 'null' description: Bank account display name. example: Main account country: type: - string - 'null' description: Bank account country. example: FR required: - id - currency - bank_name - name - country - anyOf: - type: object properties: format: type: string enum: - iban_bic_swift description: Bank account details format. example: iban_bic_swift iban: type: string description: IBAN. example: FR7630006000011234567890189 bic_swift: type: - string - 'null' description: BIC or SWIFT code. example: BNPAFRPP required: - format - iban - bic_swift - type: object properties: format: type: string enum: - sort_code_account_number description: Bank account details format. example: sort_code_account_number sort_code: type: string description: Sort code. example: '123456' account_number: type: string description: Account number. example: '000123456789' required: - format - sort_code - account_number - type: object properties: format: type: string enum: - account_number_routing_number description: Bank account details format. example: account_number_routing_number account_number: type: string description: Account number. example: '000123456789' routing_number: type: string description: Routing number. example: '021000021' required: - format - account_number - routing_number - type: object properties: format: type: string enum: - account_number_bic_swift description: Bank account details format. example: account_number_bic_swift account_number: type: string description: Account number. example: '000123456789' bic_swift: type: string description: BIC or SWIFT code. example: BNPAFRPP required: - format - account_number - bic_swift example: format: iban_bic_swift iban: FR7630006000011234567890189 bic_swift: BNPAFRPP securitySchemes: bearer: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.