> ## 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. # Transition subscription to next phase > Update a subscription and transition it to the next available phase. ## OpenAPI ````yaml post /v2/subscriptions/{id}/next-phase 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/{id}/next-phase: post: tags: - Subscriptions > Phases summary: Transition subscription to next phase description: Update a subscription and transition it to the next available phase. operationId: transitionSubscription parameters: - schema: type: string required: true name: id in: path requestBody: content: application/json: schema: type: object properties: transition_date: type: string format: date-time description: >- Date of application of the transition. Use it if different than immediately to calculate pro-rata and display past or future dates on invoices. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-12-20T16:04:11Z' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/SubscriptionDetails' security: - bearer: [] components: schemas: SubscriptionDetails: allOf: - $ref: '#/components/schemas/Subscription' - type: object properties: phases: type: array items: type: object properties: id: type: string description: Subscription phase ID. example: sup_1FoLfIQ5VOMbXf type: type: string enum: - setup - trial - 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: - pending - active - finished 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 - 'null' properties: period: type: string enum: - days - weeks - months - years count: type: number required: - period - count 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 - 'null' 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: null starts_at: type: - string - 'null' 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: null ends_at: type: - string - 'null' 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: null billing_cycle_alignment: type: string enum: - calendar_period - anniversary description: > Alignment of product billing cycles. - `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 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 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 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: oneOf: - $ref: '#/components/schemas/SubscriptionProductFee' - $ref: '#/components/schemas/SubscriptionProductSeat' - $ref: '#/components/schemas/SubscriptionProductDynamic' - $ref: '#/components/schemas/SubscriptionProductCredit' - $ref: '#/components/schemas/SubscriptionProductBundle' discriminator: propertyName: type mapping: flat_fee: $ref: '#/components/schemas/SubscriptionProductFee' seat: $ref: '#/components/schemas/SubscriptionProductSeat' dynamic: $ref: '#/components/schemas/SubscriptionProductDynamic' credit: $ref: '#/components/schemas/SubscriptionProductCredit' bundle: $ref: '#/components/schemas/SubscriptionProductBundle' description: Products comprising the subscription phase. coupons: type: array items: allOf: - anyOf: - type: object properties: description: type: - string - 'null' description: Coupon description. example: null expiration_date: type: - string - 'null' format: date-time description: >- Date corresponding to the expiration of the coupon. example: null redemption_limit: type: - number - 'null' description: >- Maximum number of subscriptions to which a single coupon can be applied. example: null product_ids: type: array items: type: string description: >- List of product IDs the coupon can be applied to. If empty, the coupon can be applied to any product. example: - itm_DKL4Xcb5VSa8CQ - itm_1234567890abcdef repeat: type: - string - 'null' enum: - once - forever - custom - duration description: >- Default repeat behaviour applied when the coupon is attached to a subscription. Valid values: `once`, `forever`, `duration`. Can be overridden at attach time. example: duration duration: type: - object - 'null' properties: count: type: number description: >- Number of periods the coupon applies for. example: 3 period: type: string enum: - days - weeks - months - years description: >- Period unit the coupon applies for. Valid values: `days`, `weeks`, `months`, `years`. example: months required: - count - period description: >- Default duration applied when `repeat` is `duration`. Required when `repeat` is `duration`, must be null otherwise. example: count: 3 period: months created_at: 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: type: string enum: - amount discount_amount: type: number 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 currency: type: - string - 'null' 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 required: - description - expiration_date - redemption_limit - product_ids - repeat - duration - created_at - type - discount_amount - currency title: Coupon amount - type: object properties: description: type: - string - 'null' description: Coupon description. example: null expiration_date: type: - string - 'null' format: date-time description: >- Date corresponding to the expiration of the coupon. example: null redemption_limit: type: - number - 'null' description: >- Maximum number of subscriptions to which a single coupon can be applied. example: null product_ids: type: array items: type: string description: >- List of product IDs the coupon can be applied to. If empty, the coupon can be applied to any product. example: - itm_DKL4Xcb5VSa8CQ - itm_1234567890abcdef repeat: type: - string - 'null' enum: - once - forever - custom - duration description: >- Default repeat behaviour applied when the coupon is attached to a subscription. Valid values: `once`, `forever`, `duration`. Can be overridden at attach time. example: duration duration: type: - object - 'null' properties: count: type: number description: >- Number of periods the coupon applies for. example: 3 period: type: string enum: - days - weeks - months - years description: >- Period unit the coupon applies for. Valid values: `days`, `weeks`, `months`, `years`. example: months required: - count - period description: >- Default duration applied when `repeat` is `duration`. Required when `repeat` is `duration`, must be null otherwise. example: count: 3 period: months created_at: 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: type: string enum: - percent discount_percent: type: number description: >- Percentage to apply as a discount on the amount (excluding taxes) of a product. example: 15 required: - description - expiration_date - redemption_limit - product_ids - repeat - duration - created_at - type - discount_percent title: Coupon percent - type: object properties: id: type: - string - 'null' description: Coupon ID. example: cou_DKL4Xcb5VSa8CQ promotion_code_id: type: - string - 'null' description: >- Promotion code ID if the coupon has been created from a promotion code. example: null name: type: - string - 'null' description: Coupon name. example: Partner discount subscription_coupon_id: type: string description: >- Coupon identifier in the context of the subscription. example: coos_d9pVekhjoGppuX repeat: type: string 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). example: forever duration_period: type: - string - 'null' 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 - 'null' description: >- Number of periods for which the coupon will be applied. Only applies to the `duration` coupon frequency. product_ids: type: array items: type: string description: Product IDs to which the coupon will be applied. example: - itm_FJKlqUb8COXw55 apply_at: type: - string - 'null' 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: null expires_at: type: - string - 'null' 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: null required: - id - promotion_code_id - name - subscription_coupon_id - repeat - duration_period - duration_count - product_ids - apply_at - expires_at description: Coupons comprising the subscription phase. created_at: type: string format: date-time description: >- Subscription phase creation date. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-10-12T07:00:01.860Z' updated_at: type: string format: date-time description: >- Subscription phase last edition date. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-10-12T07:00:01.860Z' required: - id - type - status - order - activation_strategy - end_strategy - duration - billing_date_setting - initial_billing_at - starts_at - ends_at - billing_cycle_alignment - do_not_invoice_phase - transition_calculation_method - transition_invoicing_schedule - products - coupons - created_at - updated_at description: Phases of the subscription. quote: type: - object - 'null' properties: id: type: string description: ID of the quote from which the subscription was created. example: quo_38YwqvItBH3d8a status: type: string enum: - draft - pending_approval - changes_requested - approved - pending_signature - voided - signed description: Status of the quote from which the subscription was created. example: signed required: - id - status plan: type: - object - 'null' properties: id: type: string description: ID of the plan that the subscription is linked to. example: plan_zHmjoDee4ZRmQV name: type: string description: Name of the plan that the subscription is linked to. example: My example plan required: - id - name template: type: - object - 'null' properties: id: type: string description: ID of the template that the subscription is linked to. example: subt_7gdusOkqr5L0B8 name: type: string description: Name of the template that the subscription is linked to. example: My example template configurationId: type: string description: >- ID of the template configuration that the subscription is linked to. example: subtc_7mHWOlPStUogvp required: - id - name - configurationId checkout_session: $ref: '#/components/schemas/CheckoutSession' payment_method_type: type: - string - 'null' enum: - card - apple_pay - google_pay - direct_debit - direct_debit_ach - direct_debit_bacs - stripe_link - transfer - transfer_automated - external description: Payment method type used to pay the subscription. payment_method: allOf: - $ref: '#/components/schemas/PaymentMethod' - description: Payment method details used to pay the subscription. contract_terms: type: - object - 'null' properties: status: type: string enum: - active - pending - finished description: > Contract status. - `active`: The contract is active. - `pending`: The contract is pending. It will be activated according to the activation strategy. - `finished`: The contract has ended. example: active 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 starts_at: type: - string - 'null' 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-31T23:00:00.000Z' ends_at: type: - string - 'null' 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: '2025-06-30T21:59:59.999Z' duration: type: - object - 'null' properties: period: type: string enum: - days - weeks - months - years count: type: number exclusiveMinimum: 0 required: - period - count 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 - 'null' properties: period: type: string enum: - days - weeks - months - years count: type: number exclusiveMinimum: 0 required: - period - count description: > Interval over which the contract will be renewed. Only applies if `renew_automatically` is true. example: count: 1 period: years current_period_started_at: type: - string - 'null' format: date-time description: >- Start date of the current contract period. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2025-06-30T22:00:00.000Z' current_period_ends_at: type: - string - 'null' format: date-time description: >- End date of the current contract period. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2026-06-30T21:59:59.999Z' required: - status - activation_strategy - end_strategy - starts_at - ends_at - duration - renew_automatically - renew_for_duration - current_period_started_at - current_period_ends_at description: Contract terms linked to the subscription. required: - phases - quote - plan - template - checkout_session - payment_method_type - payment_method - contract_terms Subscription: type: object properties: id: type: string description: Subscription ID. example: sub_B6ClkdqNqVNBgY name: type: - string - 'null' description: Subscription custom name. example: Yearly subscription 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 status: type: string enum: - active - cancelled - draft - errored - paused - pending - voided description: >- Subscription status. - `draft`: The subscription is being created, this status is only used in the subscription assignation flow of the UI version of Hyperline. - `pending`: The subscription has been created and won't be charged until it is activated. - `active`: The subscription is running and will be invoiced at the next payment date. - `paused`: The subscription's payment collection is paused. - `cancelled`: The subscription has been canceled from an active state. - `voided`: The subscription has been voided directly from the pending state. - `errored`: We attempted 4 times (3 retries) and failed to charge a subscription's invoice, see [Handling payment errors](https://docs.hyperline.co/docs/payments/payment-errors). We consider the subscription as inactive (as the customer failed to pay you) meaning that we won't invoice the customer in the future nor collect payment. You can choose to reactivate it manually. example: active purchase_order: type: - string - 'null' description: Reference to the purchase order. customer_id: type: string description: ID of the customer. example: cus_QalW2vTAdkR6IY invoicing_entity_id: type: - string - 'null' description: >- ID of the invoicing entity attached to the subscription. If not defined, fallback to customer's invoicing entity. example: ive_jerrb484RHn plan_id: type: - string - 'null' description: ID of the plan that the subscription is linked to. example: plan_zHmjoDee4ZRmQV deprecated: true template_id: type: - string - 'null' description: ID of the template that the subscription is linked to. example: subt_7gdusOkqr5L0B8 checkout_session_id: type: - string - 'null' description: ID of the checkout session. crm_opportunity_id: type: - string - 'null' description: ID of the related opportunity/deal in the connected CRM. example: null minimum_invoice_fee: type: - number - 'null' description: Minimum fee applied to each invoice outside of one time payments. example: 250 commitment_interval: type: - object - 'null' 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 renew_automatically: type: boolean description: Deprecated field, please use `contract_terms`. example: true renew_for: type: - object - 'null' 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 activation_strategy: type: - string - 'null' enum: - start_date - manually - checkout - quote - contract_start_date description: > Strategy used to activate the subscription. - `start_date`: The subscription will become active on the specified start date. If the start date is in the past, it will be activated immediately. - `manually`: The subscription requires activation through a manual action. - `checkout`: The subscription will be activated once the checkout is completed, but only if the start date is in the past. Otherwise, activation will occur later on the specified start date. - `quote`: The subscription will be activated depending on the configuration and the signature of the related quote. example: start_date starts_at: type: - string - 'null' 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' deprecated: true contract_start: type: - string - 'null' format: date-time description: Deprecated field, please use `contract_terms`. example: '2024-01-15T00:00:00Z' contract_end: type: - string - 'null' format: date-time description: Deprecated field, please use `contract_terms`. example: '2025-01-15T00:00:00Z' initial_billing_at: type: - string - 'null' 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' paused_at: type: - string - 'null' format: date-time description: >- Date when the subscription was paused. Only applies to `paused` status. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-12-20T16:04:11Z' reactivate_at: type: - string - 'null' format: date-time description: >- Date when the subscription will be automatically reactivated. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-12-20T16:04:11Z' cancel_at: type: - string - 'null' 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 - 'null' 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 - 'null' description: >- Custom amount used when cancelling the subscription. Only applies to the `charge_custom` or the `refund_custom` cancellation strategy. cancellation_reason: type: - string - 'null' description: Reason for the cancellation. cancellation_source: type: - string - 'null' enum: - portal - app - api - system description: > Origin of the cancellation. - `portal`: customer cancelled themselves from the hosted customer portal. - `app`: admin cancelled from the Hyperline dashboard. - `api`: cancelled programmatically through the public API. - `system`: cancelled by an automated internal process. estimated_arr: type: - number - 'null' description: Estimated Annual Recurring Revenue generated by the subscription. contract_value: type: - number - 'null' description: >- Contract value of the subscription. This value is overridable by the user. current_period_started_at: type: - string - 'null' format: date-time description: >- Start date of 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' current_period_ends_at: type: - string - 'null' format: date-time description: >- End date of 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' next_payment_at: type: - string - 'null' format: date-time description: >- Date on which the next subscription payment will occur. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-12-20T16:04:11Z' next_payment_amount: type: - number - 'null' description: >- The amount of the next subscription payment. The system will generate an invoice to pay on the `next_payment_at`. renews_at: type: - string - 'null' format: date-time description: >- Next subscription commitment renewal date. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-12-20T16:04:11Z' current_phase_id: type: - string - 'null' description: ID of the current subscription phase. display_shipping_details: type: - boolean - 'null' description: >- Indicates if the shipping details should be displayed on the subscription's invoices. 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: >- A list of key value with the slug of the custom property as the key and the custom property value as value. 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. generate_document: type: boolean description: Generate documents instead of invoices for the subscription. 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: type: boolean description: If `generate_document` is turned on, will add taxes to document. generate_draft_invoices: type: boolean description: >- Generate draft invoices for the subscription. Each invoice will need to be reviewed and validated manually before being sent invoice_custom_note: type: - string - 'null' description: Default custom note added to invoices generated by the subscription. created_at: type: string format: date-time description: >- Subscription creation date. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-10-12T07:00:01.860Z' updated_at: type: string format: date-time description: >- Subscription last edition date. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-10-12T07:00:01.860Z' products: type: array items: oneOf: - $ref: '#/components/schemas/SubscriptionProductFee' - $ref: '#/components/schemas/SubscriptionProductSeat' - $ref: '#/components/schemas/SubscriptionProductDynamic' - $ref: '#/components/schemas/SubscriptionProductCredit' - $ref: '#/components/schemas/SubscriptionProductBundle' discriminator: propertyName: type mapping: flat_fee: $ref: '#/components/schemas/SubscriptionProductFee' seat: $ref: '#/components/schemas/SubscriptionProductSeat' dynamic: $ref: '#/components/schemas/SubscriptionProductDynamic' credit: $ref: '#/components/schemas/SubscriptionProductCredit' bundle: $ref: '#/components/schemas/SubscriptionProductBundle' description: Products that make up the subscription. coupons: type: array items: allOf: - anyOf: - type: object properties: description: type: - string - 'null' description: Coupon description. example: null expiration_date: type: - string - 'null' format: date-time description: Date corresponding to the expiration of the coupon. example: null redemption_limit: type: - number - 'null' description: >- Maximum number of subscriptions to which a single coupon can be applied. example: null product_ids: type: array items: type: string description: >- List of product IDs the coupon can be applied to. If empty, the coupon can be applied to any product. example: - itm_DKL4Xcb5VSa8CQ - itm_1234567890abcdef repeat: type: - string - 'null' enum: - once - forever - custom - duration description: >- Default repeat behaviour applied when the coupon is attached to a subscription. Valid values: `once`, `forever`, `duration`. Can be overridden at attach time. example: duration duration: type: - object - 'null' properties: count: type: number description: Number of periods the coupon applies for. example: 3 period: type: string enum: - days - weeks - months - years description: >- Period unit the coupon applies for. Valid values: `days`, `weeks`, `months`, `years`. example: months required: - count - period description: >- Default duration applied when `repeat` is `duration`. Required when `repeat` is `duration`, must be null otherwise. example: count: 3 period: months created_at: 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: type: string enum: - amount discount_amount: type: number 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 currency: type: - string - 'null' 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 required: - description - expiration_date - redemption_limit - product_ids - repeat - duration - created_at - type - discount_amount - currency title: Coupon amount - type: object properties: description: type: - string - 'null' description: Coupon description. example: null expiration_date: type: - string - 'null' format: date-time description: Date corresponding to the expiration of the coupon. example: null redemption_limit: type: - number - 'null' description: >- Maximum number of subscriptions to which a single coupon can be applied. example: null product_ids: type: array items: type: string description: >- List of product IDs the coupon can be applied to. If empty, the coupon can be applied to any product. example: - itm_DKL4Xcb5VSa8CQ - itm_1234567890abcdef repeat: type: - string - 'null' enum: - once - forever - custom - duration description: >- Default repeat behaviour applied when the coupon is attached to a subscription. Valid values: `once`, `forever`, `duration`. Can be overridden at attach time. example: duration duration: type: - object - 'null' properties: count: type: number description: Number of periods the coupon applies for. example: 3 period: type: string enum: - days - weeks - months - years description: >- Period unit the coupon applies for. Valid values: `days`, `weeks`, `months`, `years`. example: months required: - count - period description: >- Default duration applied when `repeat` is `duration`. Required when `repeat` is `duration`, must be null otherwise. example: count: 3 period: months created_at: 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: type: string enum: - percent discount_percent: type: number description: >- Percentage to apply as a discount on the amount (excluding taxes) of a product. example: 15 required: - description - expiration_date - redemption_limit - product_ids - repeat - duration - created_at - type - discount_percent title: Coupon percent - type: object properties: id: type: - string - 'null' description: Coupon ID. example: cou_DKL4Xcb5VSa8CQ promotion_code_id: type: - string - 'null' description: >- Promotion code ID if the coupon has been created from a promotion code. example: null name: type: - string - 'null' description: Coupon name. example: Partner discount subscription_coupon_id: type: string description: Coupon identifier in the context of the subscription. example: coos_d9pVekhjoGppuX repeat: type: string 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). example: forever duration_period: type: - string - 'null' 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 - 'null' description: >- Number of periods for which the coupon will be applied. Only applies to the `duration` coupon frequency. product_ids: type: array items: type: string description: Product IDs to which the coupon will be applied. example: - itm_FJKlqUb8COXw55 apply_at: type: - string - 'null' 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: null expires_at: type: - string - 'null' 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: null required: - id - promotion_code_id - name - subscription_coupon_id - repeat - duration_period - duration_count - product_ids - apply_at - expires_at description: Coupons to be applied to the prices of subscription products. 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 - anrok - chargebee - slack - plain - zendesk - pylon - intercom - claap description: Provider name. provider_account_id: type: string description: ID of the connected provider account. 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 description: >- References to this subscription in external providers (billing, CRM, etc). required: - id - name - currency - status - purchase_order - customer_id - invoicing_entity_id - plan_id - template_id - checkout_session_id - crm_opportunity_id - minimum_invoice_fee - commitment_interval - renew_automatically - renew_for - activation_strategy - starts_at - contract_start - contract_end - initial_billing_at - paused_at - reactivate_at - cancel_at - cancellation_strategy - cancellation_amount - cancellation_reason - cancellation_source - estimated_arr - contract_value - current_period_started_at - current_period_ends_at - next_payment_at - next_payment_amount - renews_at - current_phase_id - display_shipping_details - properties - custom_properties - invoice_schedule - generate_document - document_name - add_tax_to_document - generate_draft_invoices - invoice_custom_note - created_at - updated_at - products - coupons - integrations SubscriptionProductFee: type: object properties: id: type: string description: Product ID. example: itm_FJKlqUb8COXw55 name: type: string description: Product name. This will appear on the final invoices. example: Product name description: type: - string - 'null' description: Product description. This will appear on the final invoices. example: A description of the product. description_display_interval_dates: type: boolean description: >- Indicates if the dates of the interval should be automatically added in the product description on the invoices. attached_at: type: - string - 'null' format: date-time description: >- Date on which the product has been attached to the subscription. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-01-15T00:00:00Z' detached_at: type: - string - 'null' format: date-time description: >- Date on which the product has been detached from the subscription. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-04-15T00:00:00Z' current_period_started_at: type: - string - 'null' format: date-time description: >- Date on which the current period started. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-01-15T00:00:00Z' current_period_ends_at: type: - string - 'null' format: date-time description: >- Date on which the current period will end. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-02-15T00:00:00Z' next_payment_at: type: - string - 'null' format: date-time description: >- Date on which the next subscription invoice will be generated. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-02-15T00:00:00Z' 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: number exclusiveMinimum: 0 required: - period - count title: Period example: period: months count: 1 - type: 'null' 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 - 'null' enum: - start - end description: >- Indicates if the product should be billed at the start or the end of the payment interval. example: start type: type: string enum: - flat_fee count: type: number description: Number of product units. example: 1 prices: type: array items: $ref: '#/components/schemas/PriceFee' maxItems: 1 description: >- Price tiers of the product. If fixed amount, only one price is available. required: - id - name - description - description_display_interval_dates - attached_at - detached_at - current_period_started_at - current_period_ends_at - next_payment_at - payment_interval - payment_schedule - type - count - prices title: Fee product SubscriptionProductSeat: type: object properties: id: type: string description: Product ID. example: itm_FJKlqUb8COXw55 name: type: string description: Product name. This will appear on the final invoices. example: Product name description: type: - string - 'null' description: Product description. This will appear on the final invoices. example: A description of the product. description_display_interval_dates: type: boolean description: >- Indicates if the dates of the interval should be automatically added in the product description on the invoices. attached_at: type: - string - 'null' format: date-time description: >- Date on which the product has been attached to the subscription. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-01-15T00:00:00Z' detached_at: type: - string - 'null' format: date-time description: >- Date on which the product has been detached from the subscription. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-04-15T00:00:00Z' current_period_started_at: type: - string - 'null' format: date-time description: >- Date on which the current period started. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-01-15T00:00:00Z' current_period_ends_at: type: - string - 'null' format: date-time description: >- Date on which the current period will end. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-02-15T00:00:00Z' next_payment_at: type: - string - 'null' format: date-time description: >- Date on which the next subscription invoice will be generated. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-02-15T00:00:00Z' 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: number exclusiveMinimum: 0 required: - period - count title: Period example: period: months count: 1 - type: 'null' 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 - 'null' enum: - start - end description: >- Indicates if the product should be billed at the start or the end of the payment interval. example: start type: type: string enum: - seat unit_name: type: - string - 'null' description: Name of the unit. example: user count: type: number description: Number of product units. example: 2 prices: type: array items: anyOf: - allOf: - $ref: '#/components/schemas/PriceVolume' - title: Volume price - allOf: - $ref: '#/components/schemas/PricePackaged' - title: Packaged price - allOf: - $ref: '#/components/schemas/PriceBulk' - title: Bulk price - allOf: - $ref: '#/components/schemas/PriceBundle' - title: Bundle price description: >- Price tiers of the product. If fixed amount, only one price is available. min_committed_count: type: - number - 'null' description: >- Minimum of units committed. If usage is less than this number, then this value will be used. example: 2000 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. 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. charging_method: type: - string - 'null' enum: - prorata - pay_in_full - do_not_charge description: > Charging method used for seat count updates within the current billing period. Only present for connected seat products. - `prorata`: The price will be calculated proportionally to the time elapsed since the last billing period. - `pay_in_full`: The price will be calculated for the entire billing period. - `do_not_charge`: The price will not be calculated. 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. required: - id - name - description - description_display_interval_dates - attached_at - detached_at - current_period_started_at - current_period_ends_at - next_payment_at - payment_interval - payment_schedule - type - unit_name - count - prices title: Seat product SubscriptionProductDynamic: type: object properties: id: type: string description: Product ID. example: itm_FJKlqUb8COXw55 name: type: string description: Product name. This will appear on the final invoices. example: Product name description: type: - string - 'null' description: Product description. This will appear on the final invoices. example: A description of the product. description_display_interval_dates: type: boolean description: >- Indicates if the dates of the interval should be automatically added in the product description on the invoices. attached_at: type: - string - 'null' format: date-time description: >- Date on which the product has been attached to the subscription. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-01-15T00:00:00Z' detached_at: type: - string - 'null' format: date-time description: >- Date on which the product has been detached from the subscription. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-04-15T00:00:00Z' current_period_started_at: type: - string - 'null' format: date-time description: >- Date on which the current period started. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-01-15T00:00:00Z' current_period_ends_at: type: - string - 'null' format: date-time description: >- Date on which the current period will end. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-02-15T00:00:00Z' next_payment_at: type: - string - 'null' format: date-time description: >- Date on which the next subscription invoice will be generated. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-02-15T00:00:00Z' 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: number exclusiveMinimum: 0 required: - period - count title: Period example: period: months count: 1 - type: 'null' 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 - 'null' enum: - start - end description: >- Indicates if the product should be billed at the start or the end of the payment interval. example: start type: type: string enum: - dynamic unit_name: type: - string - 'null' description: Name of the unit. example: hour min_committed_count: type: - number - 'null' description: >- Minimum of units committed. If usage is less than this number, then this value will be used. example: 2000 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. 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. metering_interval_type: type: - string - 'null' 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. - `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. metering_interval: type: - object - 'null' properties: period: type: string enum: - days - weeks - months - years count: type: number exclusiveMinimum: 0 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). bill_usage_difference: type: boolean 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. metering_period_started_at: type: - string - 'null' format: date description: >- Start date of the current metering period. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. metering_period_ends_at: type: - string - 'null' format: date description: >- End date of the current metering period. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. prices: type: array items: anyOf: - allOf: - $ref: '#/components/schemas/PriceVolume' - type: object properties: metering_filter: 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 that scopes which billable events are eligible for this price tier. Only present when the price is filtered. title: Volume price - allOf: - $ref: '#/components/schemas/PricePackaged' - type: object properties: metering_filter: 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 that scopes which billable events are eligible for this price tier. Only present when the price is filtered. title: Packaged price - allOf: - $ref: '#/components/schemas/PriceBulk' - type: object properties: metering_filter: 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 that scopes which billable events are eligible for this price tier. Only present when the price is filtered. title: Bulk price - allOf: - $ref: '#/components/schemas/PriceBps' - type: object properties: metering_filter: 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 that scopes which billable events are eligible for this price tier. Only present when the price is filtered. title: BPS price description: >- Price tiers of the product. If fixed amount, only one price is available. required: - id - name - description - description_display_interval_dates - attached_at - detached_at - current_period_started_at - current_period_ends_at - next_payment_at - payment_interval - payment_schedule - type - unit_name - min_committed_count - min_amount - max_amount - metering_interval_type - metering_interval - bill_usage_difference - metering_period_started_at - metering_period_ends_at - prices title: Dynamic product SubscriptionProductCredit: type: object properties: id: type: string description: Product ID. example: itm_FJKlqUb8COXw55 name: type: string description: Product name. This will appear on the final invoices. example: Product name description: type: - string - 'null' description: Product description. This will appear on the final invoices. example: A description of the product. description_display_interval_dates: type: boolean description: >- Indicates if the dates of the interval should be automatically added in the product description on the invoices. attached_at: type: - string - 'null' format: date-time description: >- Date on which the product has been attached to the subscription. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-01-15T00:00:00Z' detached_at: type: - string - 'null' format: date-time description: >- Date on which the product has been detached from the subscription. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-04-15T00:00:00Z' current_period_started_at: type: - string - 'null' format: date-time description: >- Date on which the current period started. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-01-15T00:00:00Z' current_period_ends_at: type: - string - 'null' format: date-time description: >- Date on which the current period will end. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-02-15T00:00:00Z' next_payment_at: type: - string - 'null' format: date-time description: >- Date on which the next subscription invoice will be generated. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-02-15T00:00:00Z' 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: number exclusiveMinimum: 0 required: - period - count title: Period example: period: months count: 1 - type: 'null' 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 - 'null' enum: - start - end description: >- Indicates if the product should be billed at the start or the end of the payment interval. example: start type: type: string enum: - credit unit_name: type: - string - 'null' description: Name of the unit. example: hour count: type: number description: Number of product units. example: 2 prices: type: array items: $ref: '#/components/schemas/PriceFee' maxItems: 1 description: >- Price tiers of the product. If fixed amount, only one price is available. 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' - type: 'null' default: false description: >- Automatically set the expiration date to the end of the next period for each topup. Takes priority on `creditsExpirationInDays` required: - id - name - description - description_display_interval_dates - attached_at - detached_at - current_period_started_at - current_period_ends_at - next_payment_at - payment_interval - payment_schedule - type - unit_name - count - prices - credits_expiration_in_days title: Credit product SubscriptionProductBundle: type: object properties: id: type: string description: Product ID. example: itm_FJKlqUb8COXw55 name: type: string description: Product name. This will appear on the final invoices. example: Product name description: type: - string - 'null' description: Product description. This will appear on the final invoices. example: A description of the product. description_display_interval_dates: type: boolean description: >- Indicates if the dates of the interval should be automatically added in the product description on the invoices. attached_at: type: - string - 'null' format: date-time description: >- Date on which the product has been attached to the subscription. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-01-15T00:00:00Z' detached_at: type: - string - 'null' format: date-time description: >- Date on which the product has been detached from the subscription. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-04-15T00:00:00Z' current_period_started_at: type: - string - 'null' format: date-time description: >- Date on which the current period started. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-01-15T00:00:00Z' current_period_ends_at: type: - string - 'null' format: date-time description: >- Date on which the current period will end. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-02-15T00:00:00Z' next_payment_at: type: - string - 'null' format: date-time description: >- Date on which the next subscription invoice will be generated. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2024-02-15T00:00:00Z' 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: number exclusiveMinimum: 0 required: - period - count title: Period example: period: months count: 1 - type: 'null' 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 - 'null' enum: - start - end description: >- Indicates if the product should be billed at the start or the end of the payment interval. example: start type: type: string enum: - bundle count: type: number description: Number of product units. example: 2 display_mode: type: string enum: - single_line - ventilated description: How bundle items are displayed on invoices prices: type: array items: anyOf: - allOf: - $ref: '#/components/schemas/PriceVolume' - title: Volume price - allOf: - $ref: '#/components/schemas/PricePackaged' - title: Packaged price - allOf: - $ref: '#/components/schemas/PriceBulk' - title: Bulk price - allOf: - $ref: '#/components/schemas/PriceBundle' - title: Bundle price description: >- Price tiers of the product. If fixed amount, only one price is available. required: - id - name - description - description_display_interval_dates - attached_at - detached_at - current_period_started_at - current_period_ends_at - next_payment_at - payment_interval - payment_schedule - type - count - display_mode - prices title: Bundle product CheckoutSession: type: - object - 'null' properties: id: type: string description: Checkout session ID. example: che_hEUPdVG7IgjpW1 status: type: string enum: - opened - completed - cancelled - errored description: Checkout session current status. example: opened available_payment_methods: type: array items: type: string enum: - card - apple_pay - google_pay - direct_debit - direct_debit_ach - direct_debit_bacs - stripe_link - transfer - transfer_automated description: Types of payment method available on the checkout session. example: - card redirect_url: type: - string - 'null' format: uri description: >- URL to which the user is automatically redirected after the completion of the checkout. example: https://app.hyperline.co/callback/checkout send_to: type: - object - 'null' properties: email: type: string format: email description: >- Email address to which we'll automatically send a message with the checkout link. example: josh@alpeak.com message: type: - string - 'null' description: >- Custom message to include in the email send. If not provided, we will use a generic one. example: null required: - email - message url: type: string format: uri description: >- URL to access the checkout session. Only defined if the status is `opened`. example: https://billing.hyperline.co/checkout/che_hEUPdVG7IgjpW1 required: - id - status - available_payment_methods - redirect_url - send_to - url description: Checkout session of the subscription. 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' PriceFee: type: object properties: type: type: string enum: - fee id: type: string description: Price ID. amount: type: number description: Monetary amount. Expressed in currency's smallest unit. required: - type - amount PriceVolume: type: object properties: type: type: string enum: - volume id: type: string description: Price ID. 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. required: - type - amount - unit_count - from - to PricePackaged: type: object properties: type: type: string enum: - packaged id: type: string description: Price ID. 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. required: - type - amount - unit_count - from - to PriceBulk: type: object properties: type: type: string enum: - bulk id: type: string description: Price ID. 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. required: - type - amount - unit_count - to PriceBundle: type: object properties: type: type: string enum: - bundle id: type: string description: Price ID. 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 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 PriceBps: type: object properties: type: type: string enum: - bps id: type: string description: Price ID. 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. required: - type - from - to - percentage - per_unit_cap - per_unit_floor - per_unit_fee securitySchemes: bearer: type: http scheme: bearer bearerFormat: JWT ````