Subscriptions
A Subscription manages the billing lifecycle for the recurring products or services that a customer purchases. One or more Products and Prices can be added as Subscription Items to a Subscription.
Customers can be charged automatically, or be issued invoices that they will pay manually every billing cycle.
If a Subscription is set to charge a Billing Customer's Payment Source automatically, the charge will either happen at the start or end of a billing cycle depending on whether a Price's billing type is IN_ADVANCE or IN_ARREARS:
IN_ADVANCE: billed at the beginning of the billing cycle.IN_ARREARS: billed at the end of the billing cycle.
A Subscription with a free trial moves from IN_TRIAL status to ACTIVE status when the trial period ends. If a Subscription is created with a future start time, it will be in PENDING status until the trial period or paid billing period starts. The status of a Subscription is UNPAID when a payment initially fails. When this happens, Airwallex will retry payment up to 4 times (after 1 day, 2 days, 5 days and 7 days).
The status of a Subscription moves to ACTIVE if a payment retry attempt succeeds, or CANCELLED if all retries fail. A Subscription moves to CANCELLED when it ends or if cancelled.
POST /api/v1/billing/subscriptions/createGET /api/v1/billing/subscriptions/{id}GET /api/v1/billing/subscriptionsPOST /api/v1/billing/subscriptions/{id}/updatePOST /api/v1/billing/subscriptions/{id}/cancelGET /api/v1/billing/subscriptions/{id}/items/{item_id}GET /api/v1/billing/subscriptions/{id}/items
Create a Subscription
POST /api/v1/billing/subscriptions/create
Create a new Subscription for an existing Billing Customer to charge the customer on a recurring basis.
ID of the Billing Customer who subscribes to this subscription.
Specify how payment is collected, one of AUTO_CHARGE, CHARGE_ON_CHECKOUT or OUT_OF_BAND.
List of Subscription Items.
List of discounts to be applied to the Subscription Item. Discounts of subscription items are applied before subscription discounts. Currently, only one element is supported.
Coupon to redeem into a discount for this resource. Only required when type = COUPON.
Id of the Coupon object.
Specifies how to obtain the discount. One of: COUPON.
A set of string key-value pairs that you can attach to this object for storing additional information.
One-time price definition following the same schema as the Price resource. Exactly one of price_id or price is required.
Currency of the price (in 3-letter ISO-4217 format).
Price description. Used for internal classification and identification.
The fixed amount to be charged. Only required when the pricing model is FLAT.
Custom key-value pairs attached to the price.
Specify how to calculate the total billing amount when a quantity is provided. One of
FLAT: a fixed price.PER_UNIT: a fixed price per unit quantity. Defaults toPER_UNIT.
One-time product definition following the same schema as the Product. Exactly one of product_id or product is required.
Product name.
Product description. Used for internal classification and identification.
A set of string key-value pairs that you can attach to this object for storing additional information.
The tax category of the product.
Product unit.
ID of the Product object. Exactly one of product_id or product is required.
Whether the price includes tax. Defaults to false.
The amount to be charged per product unit. Only required when the pricing model is PER_UNIT.
ID of the Price subscribed by the customer. All Prices in the subscription must have recurring frequencies that are compatible - meaning they must be exact multiples or divisors of one another (e.g., 1 MONTH and 1 YEAR are compatible; 1 WEEK and 1 MONTH are not). Exactly one of price_id or price is required.
The quantity of the product. Defaults to 1.
The effective tax percent of this subscription item.
Unique request ID specified by the merchant.
A future timestamp in the first billing cycle as the reference point to align the future billing date.
The currency of the subscription in 3-letter ISO-4217 format.
Number of days from invoice finalization until payment is due. Defaults to 0.
Invoices for this subscription will be created using the specified settings.
Memo to be used for the invoices that are generated by this Subscription.
The tax percent between 0 and 100 to be applied to invoices to be generated. The tax will be exclusive. Defaults to 0.
List of discounts to be applied to the subscription. Discounts of subscription items are applied before subscription discounts. Currently, only one element is supported.
Coupon to redeem into a discount for this resource. Only required when type = COUPON.
Id of the Coupon object.
Specifies how to obtain the discount. One of: COUPON.
The total billing duration of the subscription. The subscription will continue indefinitely if both of duration and ends_at are null.
It is only applicable when ends_at is empty.
The number of period units.
Specifies billing duration. One of DAY, WEEK, MONTH or YEAR.
Whether automatic tax is enabled for this subscription. When enabled, the system attempts to calculate taxes for this subscription's invoice automatically. Defaults to false.
Time when the subscription is scheduled to end. The subscription will continue indefinitely if both of duration and ends_at are null.
It is only applicable when duration is empty.
ID of the legal entity to be used as billing entity. You can find this ID in the Airwallex web app > Settings. Required if you have more than 1 entity in your organisation.
ID of the linked payment account to collect payment. You can find this ID in the Airwallex web app > Settings > Account details, within the Account Information section. Required if collection_method is CHARGE_ON_CHECKOUT and if you have more than 1 payment account in your organisation.
A set of string key-value pairs that you can attach to this object for storing additional information.
Payment settings applied to invoices generated by this Subscription. Only applicable when collection_method is CHARGE_ON_CHECKOUT or AUTO_CHARGE.
Settings that control whether and how a payment method provided by a customer while paying a subscription invoice is saved for future use.
Only applicable when the Subscription uses the AUTO_CHARGE collection method.
When not provided, defaults to mode=ENABLED and next_triggered_by=MERCHANT.
Controls whether the payment method can be saved for future use. Possible values: ENABLED, DISABLED, or COLLECT_CONSENT.
ENABLED: The payment method will be saved for future use.DISABLED: The payment method will not be saved.COLLECT_CONSENT: The invoice UI asks the customer whether they want to save the payment method. Only applicable to cards.
Indicates who will use the saved payment source to trigger future payments. One of MERCHANT or CUSTOMER.
If MERCHANT, a Payment Source is created for future use. If CUSTOMER, the payment method is saved only with the payment provider.
Specify the payment methods and their order for display on the digital invoice pages of this Subscription. Note: Only payment methods supported for the specified currency and the customer's country code will be shown.
Possible enum values: card, applepay, googlepay, alipaycn, alipayhk, dana, gcash, kakaopay, klarna, rabbit_line_pay, tng, truemoney.
ID of the Payment Source to pay for the subscription at each billing period. Required if collection_method is AUTO_CHARGE.
Time when the subscription started or scheduled to start. Defaults to start immediately after creation.
The end time of the trial if applicable.
List of the discounts that are applied to the Subscription. Discounts of subscription items are applied before the subscription discounts.
Specifies the type of object this discount applies to. Possible values:
SUBSCRIPTION: Applies to an entire subscription.SUBSCRIPTION_ITEM: Applies to a specific item within a subscription.INVOICE: Applies to an entire invoice.INVOICE_LINE_ITEM: Applies to a specific line item on an invoice.
ID of the specific target object the discount is applied to. Must correspond to the object type defined in applied_to.
The ID of the billing customer to whom the coupon is applied.
Time when the Discount was created.
Specified how to calculate the discount amount when applied, one of
FLAT: fixed amount off.PERCENTAGE: percentage off.
Determines how long the coupon's discount remains active after being applied. Possible values:
ONCE: Applies only to the first charge of a subscription or a one-off invoice.CUSTOM: Applies to all charges within a specified number of billing cycles, as defined by duration.INDEFINITELY: Applies to all future charges for the subscription until it is removed.
ID of the Discount object.
Name of the discount. For discounts created from a coupon, defaults to the coupon name at creation time.
Source of the Discount. Possible values:
COUPON: the discount is applied through a coupon.
Time when the discount takes effect. For discounts applied to a subscription or subscription item, this corresponds to the start date of the first billing period.
Time when the Discount was updated.
The fixed amount to deduct when discount_model is FLAT.
The ID of the Checkout where this discount was redeemed, if applicable.
The currency of amount_off when discount_model is FLAT.
The duration of the discount to apply, when duration_type is CUSTOM. null if duration_type is ONCE or INDEFINITELY.
The number of period units.
Specifies duration. One of DAY, WEEK, MONTH, YEAR
The timestamp when the discount expires. Present only when the associated coupon's duration_type is CUSTOM.
The percentage between 0 to 100 to be applied to deduct when discount_model is PERCENTAGE.
ID of the creating source, e.g. is the ID of the coupon if source = COUPON.
The automatic tax status of this subscription.
APPLIEDThe automatic tax is applied.
LOCATION_NOT_SUPPORTEDAutomatic tax calculation isn't supported in the customer's location.
LOCATION_NOT_REGISTERED_BY_MERCHANTThe merchant isn't registered to collect tax in the customer's location.
ADDRESS_INCOMPLETEThe customer address was insufficient or invalid to determine the correct tax.
DISABLEDThe automatic tax is disabled.
ID of the Billing Customer who subscribes to this subscription.
A future timestamp in the first billing cycle as the reference point to align the future billing date.
true if the subscription is scheduled to be cancelled at the end of the current billing period, false otherwise.
Time when the cancellation request was received.
Specify how payment is collected, one of AUTO_CHARGE, CHARGE_ON_CHECKOUT or OUT_OF_BAND.
Time when the subscription was created.
The currency of the Subscription in 3-letter ISO-4217 format.
The end time of the current period that the subscription has been invoiced for.
The start time of the current period that the subscription has been invoiced for.
Number of days from invoice finalization until payment is due.
Invoices for this subscription will be created using the specified settings.
Memo to be used for the invoices that are generated by this Subscription.
The tax percent between 0 and 100 to be applied to invoices to be generated. The tax will be exclusive.
The duration of the subscription.
The number of period units.
Specifies billing duration. One of DAY, WEEK, MONTH or YEAR.
Whether automatic tax is enabled for this subscription. When enabled, the system attempts to calculate taxes for this subscription's invoice automatically.
Time when the subscription ended or scheduled to end.
ID of the Subscription object.
The ID of the latest invoice generated for this subscription.
ID of the legal entity to be used as billing entity. You can find this ID in the Airwallex web app > Settings.
ID of the linked payment account to collect payment.
A set of string key-value pairs that you can attach to this object for storing additional information.
Time of the next billing date.
Payment settings applied to invoices generated by this Subscription. Only applicable when collection_method is CHARGE_ON_CHECKOUT or AUTO_CHARGE.
Settings that control whether and how a payment method provided by a customer while paying a subscription invoice is saved for future use.
Controls whether the payment method can be saved for future use. Possible values: ENABLED, DISABLED, or COLLECT_CONSENT.
ENABLED: The payment method will be saved for future use.DISABLED: The payment method will not be saved.COLLECT_CONSENT: The invoice UI asks the customer whether they want to save the payment method. Only applicable to cards.
Indicates who will use the saved payment source to trigger future payments. One of MERCHANT or CUSTOMER.
If MERCHANT, a Payment Source is created for future use. If CUSTOMER, the payment method is saved only with the payment provider.
The payment methods and their order for display on the digital invoice pages of this Subscription.
Possible enum values: card, applepay, googlepay, alipaycn, alipayhk, dana, gcash, kakaopay, klarna, rabbit_line_pay, tng, truemoney.
ID of the Payment Source to pay for the subscription at each billing period. Required if collection_method is AUTO_CHARGE.
The frequency at which the price is charged. null for one-time charge.
The number of period units between subscription billing cycles. For example, the billing cycle is bi-monthly if period=2 and period_unit=MONTH.
Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.
Time when the subscription started or scheduled to start.
Status of the subscription
PENDINGIN_TRIALACTIVEUNPAIDCANCELLEDThe end time of the trial period if applicable.
The start time of the trial period if applicable.
Time when the subscription was last updated.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: For payment-related error codes ( |
| 401 | Unauthorized. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request POST \> --url 'https://api.sandbox.airwallex.com/api/v1/billing/subscriptions/create' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json' \> --data '{> "billing_customer_id": "bcus_hkpd7fedfgb004apkvs",> "billing_cycle_anchor_at": "2022-01-15T10:15:30+0000",> "collection_method": "AUTO_CHARGE",> "currency": "USD",> "days_until_due": 0,> "default_invoice_template": {> "invoice_memo": "Thanks for your purchase."> },> "default_tax_percent": 10,> "discounts": [> {> "coupon": {> "id": "coup_abc123"> },> "type": "COUPON"> }> ],> "duration": {> "period": 12,> "period_unit": "MONTH"> },> "enable_automatic_tax": false,> "ends_at": "2023-01-01T10:15:30+0000",> "items": [> {> "discounts": [> {> "coupon": {> "id": "coup_abc123"> },> "type": "COUPON"> }> ],> "metadata": {> "foo": "bar"> },> "price": {> "currency": "USD",> "description": "Standard option: $10 / month.",> "pricing_model": "PER_UNIT",> "product": {> "description": "The license to use software in one month.",> "metadata": {> "foo": "bar"> },> "name": "Software License",> "tax_code": "pct_0504010000",> "unit": "month"> },> "product_id": "prd_hkpd1x2gbgazzvcd42w",> "tax_included": false> },> "price_id": "pri_hkpd7fedfgb004apkvs",> "quantity": 2,> "tax_percent": 5> }> ],> "legal_entity_id": "le_ib2DZgZJN72T7bObvNuMYQ",> "linked_payment_account_id": "acct_ncI2nypPKSq2VXKxscAcg",> "metadata": {> "foo": "bar"> },> "payment_options": {> "payment_method_types": [> "card",> "googlepay",> "applepay"> ],> "payment_method_save": {> "mode": "ENABLED",> "next_triggered_by": "MERCHANT"> }> },> "payment_source_id": "psrc_sgpdkxpn2h6anetrb5s",> "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",> "starts_at": "2022-01-01T10:15:30+0000",> "trial_ends_at": "2022-01-05T10:15:30+0000">}'
1{2 "applied_discounts": [3 {4 "amount_off": 10,5 "applied_to": "SUBSCRIPTION",6 "applied_to_id": "sub_hkpdkcmxdgazzq53jbk",7 "billing_customer_id": "bcus_7fz9qm2n4k",8 "checkout_id": "bco_sgstcdcpnh8sv3awiwo",9 "currency": "USD",10 "discount_model": "PERCENTAGE",11 "duration": {12 "period": 3,13 "period_unit": "MONTH"14 },15 "duration_type": "CUSTOM",16 "ends_at": "2027-01-01T00:00:00+0000",17 "id": "disc_hkpdkcmxdgazzq53jbk",18 "name": "Black Friday 20% Off",19 "percentage_off": 20,20 "source": "COUPON",21 "source_id": "coup_hkpdkcmxdgazzq53jbk",22 "starts_at": "2026-01-01T00:00:00+0000"23 }24 ],25 "automatic_tax_status": "APPLIED",26 "billing_customer_id": "bcus_hkpd7fedfgb004apkvs",27 "billing_cycle_anchor_at": "2022-01-15T10:15:30+0000",28 "cancel_at_period_end": false,29 "cancel_requested_at": "null",30 "collection_method": "AUTO_CHARGE",31 "created_at": "2022-01-01T10:15:30+0000",32 "currency": "USD",33 "current_period_ends_at": "2022-02-05T10:15:30+0000",34 "current_period_starts_at": "2022-01-05T10:15:30+0000",35 "days_until_due": 0,36 "default_invoice_template": {37 "invoice_memo": "Thanks for your purchase."38 },39 "default_tax_percent": 10,40 "duration": {41 "period": 12,42 "period_unit": "MONTH"43 },44 "enable_automatic_tax": true,45 "ends_at": "null",46 "id": "sub_hkpdkcmxdgazzq53jbk",47 "latest_invoice_id": "inv_hkpdmiq8hgb00f8cpdl",48 "legal_entity_id": "le_ib2DZgZJN72T7bObvNuMYQ",49 "linked_payment_account_id": "acct_ncI2nypPKSq2VXKxscAcg",50 "metadata": {51 "foo": "bar"52 },53 "next_billing_at": "2022-02-05T10:15:30+0000",54 "payment_options": {55 "payment_method_types": [56 "card",57 "googlepay",58 "applepay"59 ],60 "payment_method_save": {61 "mode": "ENABLED",62 "next_triggered_by": "MERCHANT"63 }64 },65 "payment_source_id": "psrc_sgpdkxpn2h6anetrb5s",66 "recurring": {67 "period": 1,68 "period_unit": "MONTH"69 },70 "starts_at": "2022-01-01T10:15:30+0000",71 "status": "ACTIVE",72 "trial_ends_at": "2022-01-05T10:15:30+0000",73 "trial_starts_at": "2022-01-01T10:15:30+0000",74 "updated_at": "2022-01-01T10:15:30+0000"75}
Retrieve a Subscription
GET /api/v1/billing/subscriptions/{id}
Retrieves the details of a Subscription using the given Subscription ID.
ID of the Subscription object.
List of the discounts that are applied to the Subscription. Discounts of subscription items are applied before the subscription discounts.
Specifies the type of object this discount applies to. Possible values:
SUBSCRIPTION: Applies to an entire subscription.SUBSCRIPTION_ITEM: Applies to a specific item within a subscription.INVOICE: Applies to an entire invoice.INVOICE_LINE_ITEM: Applies to a specific line item on an invoice.
ID of the specific target object the discount is applied to. Must correspond to the object type defined in applied_to.
The ID of the billing customer to whom the coupon is applied.
Time when the Discount was created.
Specified how to calculate the discount amount when applied, one of
FLAT: fixed amount off.PERCENTAGE: percentage off.
Determines how long the coupon's discount remains active after being applied. Possible values:
ONCE: Applies only to the first charge of a subscription or a one-off invoice.CUSTOM: Applies to all charges within a specified number of billing cycles, as defined by duration.INDEFINITELY: Applies to all future charges for the subscription until it is removed.
ID of the Discount object.
Name of the discount. For discounts created from a coupon, defaults to the coupon name at creation time.
Source of the Discount. Possible values:
COUPON: the discount is applied through a coupon.
Time when the discount takes effect. For discounts applied to a subscription or subscription item, this corresponds to the start date of the first billing period.
Time when the Discount was updated.
The fixed amount to deduct when discount_model is FLAT.
The ID of the Checkout where this discount was redeemed, if applicable.
The currency of amount_off when discount_model is FLAT.
The duration of the discount to apply, when duration_type is CUSTOM. null if duration_type is ONCE or INDEFINITELY.
The number of period units.
Specifies duration. One of DAY, WEEK, MONTH, YEAR
The timestamp when the discount expires. Present only when the associated coupon's duration_type is CUSTOM.
The percentage between 0 to 100 to be applied to deduct when discount_model is PERCENTAGE.
ID of the creating source, e.g. is the ID of the coupon if source = COUPON.
The automatic tax status of this subscription.
APPLIEDThe automatic tax is applied.
LOCATION_NOT_SUPPORTEDAutomatic tax calculation isn't supported in the customer's location.
LOCATION_NOT_REGISTERED_BY_MERCHANTThe merchant isn't registered to collect tax in the customer's location.
ADDRESS_INCOMPLETEThe customer address was insufficient or invalid to determine the correct tax.
DISABLEDThe automatic tax is disabled.
ID of the Billing Customer who subscribes to this subscription.
A future timestamp in the first billing cycle as the reference point to align the future billing date.
true if the subscription is scheduled to be cancelled at the end of the current billing period, false otherwise.
Time when the cancellation request was received.
Specify how payment is collected, one of AUTO_CHARGE, CHARGE_ON_CHECKOUT or OUT_OF_BAND.
Time when the subscription was created.
The currency of the Subscription in 3-letter ISO-4217 format.
The end time of the current period that the subscription has been invoiced for.
The start time of the current period that the subscription has been invoiced for.
Number of days from invoice finalization until payment is due.
Invoices for this subscription will be created using the specified settings.
Memo to be used for the invoices that are generated by this Subscription.
The tax percent between 0 and 100 to be applied to invoices to be generated. The tax will be exclusive.
The duration of the subscription.
The number of period units.
Specifies billing duration. One of DAY, WEEK, MONTH or YEAR.
Whether automatic tax is enabled for this subscription. When enabled, the system attempts to calculate taxes for this subscription's invoice automatically.
Time when the subscription ended or scheduled to end.
ID of the Subscription object.
The ID of the latest invoice generated for this subscription.
ID of the legal entity to be used as billing entity. You can find this ID in the Airwallex web app > Settings.
ID of the linked payment account to collect payment.
A set of string key-value pairs that you can attach to this object for storing additional information.
Time of the next billing date.
Payment settings applied to invoices generated by this Subscription. Only applicable when collection_method is CHARGE_ON_CHECKOUT or AUTO_CHARGE.
Settings that control whether and how a payment method provided by a customer while paying a subscription invoice is saved for future use.
Controls whether the payment method can be saved for future use. Possible values: ENABLED, DISABLED, or COLLECT_CONSENT.
ENABLED: The payment method will be saved for future use.DISABLED: The payment method will not be saved.COLLECT_CONSENT: The invoice UI asks the customer whether they want to save the payment method. Only applicable to cards.
Indicates who will use the saved payment source to trigger future payments. One of MERCHANT or CUSTOMER.
If MERCHANT, a Payment Source is created for future use. If CUSTOMER, the payment method is saved only with the payment provider.
The payment methods and their order for display on the digital invoice pages of this Subscription.
Possible enum values: card, applepay, googlepay, alipaycn, alipayhk, dana, gcash, kakaopay, klarna, rabbit_line_pay, tng, truemoney.
ID of the Payment Source to pay for the subscription at each billing period. Required if collection_method is AUTO_CHARGE.
The frequency at which the price is charged. null for one-time charge.
The number of period units between subscription billing cycles. For example, the billing cycle is bi-monthly if period=2 and period_unit=MONTH.
Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.
Time when the subscription started or scheduled to start.
Status of the subscription
PENDINGIN_TRIALACTIVEUNPAIDCANCELLEDThe end time of the trial period if applicable.
The start time of the trial period if applicable.
Time when the subscription was last updated.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 404 | Not Found. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request GET \> --url 'https://api.sandbox.airwallex.com/api/v1/billing/subscriptions/subscription_id' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json'
1{2 "applied_discounts": [3 {4 "amount_off": 10,5 "applied_to": "SUBSCRIPTION",6 "applied_to_id": "sub_hkpdkcmxdgazzq53jbk",7 "billing_customer_id": "bcus_7fz9qm2n4k",8 "checkout_id": "bco_sgstcdcpnh8sv3awiwo",9 "currency": "USD",10 "discount_model": "PERCENTAGE",11 "duration": {12 "period": 3,13 "period_unit": "MONTH"14 },15 "duration_type": "CUSTOM",16 "ends_at": "2027-01-01T00:00:00+0000",17 "id": "disc_hkpdkcmxdgazzq53jbk",18 "name": "Black Friday 20% Off",19 "percentage_off": 20,20 "source": "COUPON",21 "source_id": "coup_hkpdkcmxdgazzq53jbk",22 "starts_at": "2026-01-01T00:00:00+0000"23 }24 ],25 "automatic_tax_status": "APPLIED",26 "billing_customer_id": "bcus_hkpd7fedfgb004apkvs",27 "billing_cycle_anchor_at": "2022-01-15T10:15:30+0000",28 "cancel_at_period_end": false,29 "cancel_requested_at": "null",30 "collection_method": "AUTO_CHARGE",31 "created_at": "2022-01-01T10:15:30+0000",32 "currency": "USD",33 "current_period_ends_at": "2022-02-05T10:15:30+0000",34 "current_period_starts_at": "2022-01-05T10:15:30+0000",35 "days_until_due": 0,36 "default_invoice_template": {37 "invoice_memo": "Thanks for your purchase."38 },39 "default_tax_percent": 10,40 "duration": {41 "period": 12,42 "period_unit": "MONTH"43 },44 "enable_automatic_tax": true,45 "ends_at": "null",46 "id": "sub_hkpdkcmxdgazzq53jbk",47 "latest_invoice_id": "inv_hkpdmiq8hgb00f8cpdl",48 "legal_entity_id": "le_ib2DZgZJN72T7bObvNuMYQ",49 "linked_payment_account_id": "acct_ncI2nypPKSq2VXKxscAcg",50 "metadata": {51 "foo": "bar"52 },53 "next_billing_at": "2022-02-05T10:15:30+0000",54 "payment_options": {55 "payment_method_types": [56 "card",57 "googlepay",58 "applepay"59 ]60 },61 "payment_source_id": "psrc_sgpdkxpn2h6anetrb5s",62 "recurring": {63 "period": 1,64 "period_unit": "MONTH"65 },66 "starts_at": "2022-01-01T10:15:30+0000",67 "status": "ACTIVE",68 "trial_ends_at": "2022-01-05T10:15:30+0000",69 "trial_starts_at": "2022-01-01T10:15:30+0000",70 "updated_at": "2022-01-01T10:15:30+0000"71}
List all Subscriptions
GET /api/v1/billing/subscriptions
Retrieves a list of Subscriptions based on the query parameters.
ID of the Billing Customer who subscribes to this subscription.
The start date of created_at in ISO8601 format (inclusive).
A bookmark for use in pagination to retrieve either the next page or the previous page of results. You can fetch the value for this identifier from the response of the previous API call. To retrieve the next page of results, pass the value of page_after (if not null) from the response to a subsequent call. To retrieve the previous page of results, pass the value of page_before (if not null) from the response to a subsequent call.
Number of Subscriptions per page. Defaults to 20.
The number of period units between subscription billing cycles.
Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.
Status of the subscription, one of PENDING, IN_TRIAL, ACTIVE, UNPAID or CANCELLED.
The end date of created_at in ISO8601 format (exclusive).
Paged results.
List of the discounts that are applied to the Subscription. Discounts of subscription items are applied before the subscription discounts.
Specifies the type of object this discount applies to. Possible values:
SUBSCRIPTION: Applies to an entire subscription.SUBSCRIPTION_ITEM: Applies to a specific item within a subscription.INVOICE: Applies to an entire invoice.INVOICE_LINE_ITEM: Applies to a specific line item on an invoice.
ID of the specific target object the discount is applied to. Must correspond to the object type defined in applied_to.
The ID of the billing customer to whom the coupon is applied.
Time when the Discount was created.
Specified how to calculate the discount amount when applied, one of
FLAT: fixed amount off.PERCENTAGE: percentage off.
Determines how long the coupon's discount remains active after being applied. Possible values:
ONCE: Applies only to the first charge of a subscription or a one-off invoice.CUSTOM: Applies to all charges within a specified number of billing cycles, as defined by duration.INDEFINITELY: Applies to all future charges for the subscription until it is removed.
ID of the Discount object.
Name of the discount. For discounts created from a coupon, defaults to the coupon name at creation time.
Source of the Discount. Possible values:
COUPON: the discount is applied through a coupon.
Time when the discount takes effect. For discounts applied to a subscription or subscription item, this corresponds to the start date of the first billing period.
Time when the Discount was updated.
The fixed amount to deduct when discount_model is FLAT.
The ID of the Checkout where this discount was redeemed, if applicable.
The currency of amount_off when discount_model is FLAT.
The duration of the discount to apply, when duration_type is CUSTOM. null if duration_type is ONCE or INDEFINITELY.
The number of period units.
Specifies duration. One of DAY, WEEK, MONTH, YEAR
The timestamp when the discount expires. Present only when the associated coupon's duration_type is CUSTOM.
The percentage between 0 to 100 to be applied to deduct when discount_model is PERCENTAGE.
ID of the creating source, e.g. is the ID of the coupon if source = COUPON.
The automatic tax status of this subscription.
APPLIEDThe automatic tax is applied.
LOCATION_NOT_SUPPORTEDAutomatic tax calculation isn't supported in the customer's location.
LOCATION_NOT_REGISTERED_BY_MERCHANTThe merchant isn't registered to collect tax in the customer's location.
ADDRESS_INCOMPLETEThe customer address was insufficient or invalid to determine the correct tax.
DISABLEDThe automatic tax is disabled.
ID of the Billing Customer who subscribes to this subscription.
true if the subscription is scheduled to be cancelled at the end of the current billing period, false otherwise.
Specify how payment is collected, one of AUTO_CHARGE, CHARGE_ON_CHECKOUT or OUT_OF_BAND.
Time when the subscription was created.
The currency of the Subscription in 3-letter ISO-4217 format.
Number of days from invoice finalization until payment is due.
Whether automatic tax is enabled for this subscription. When enabled, the system attempts to calculate taxes for this subscription's invoice automatically.
ID of the Subscription object.
The frequency at which the price is charged. null for one-time charge.
The number of period units between subscription billing cycles. For example, the billing cycle is bi-monthly if period=2 and period_unit=MONTH.
Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.
Time when the subscription started or scheduled to start.
Status of the subscription
PENDINGIN_TRIALACTIVEUNPAIDCANCELLEDTime when the subscription was last updated.
A future timestamp in the first billing cycle as the reference point to align the future billing date.
Time when the cancellation request was received.
The end time of the current period that the subscription has been invoiced for.
The start time of the current period that the subscription has been invoiced for.
Invoices for this subscription will be created using the specified settings.
Memo to be used for the invoices that are generated by this Subscription.
The tax percent between 0 and 100 to be applied to invoices to be generated. The tax will be exclusive.
The duration of the subscription.
The number of period units.
Specifies billing duration. One of DAY, WEEK, MONTH or YEAR.
Time when the subscription ended or scheduled to end.
The ID of the latest invoice generated for this subscription.
ID of the legal entity to be used as billing entity. You can find this ID in the Airwallex web app > Settings.
ID of the linked payment account to collect payment.
A set of string key-value pairs that you can attach to this object for storing additional information.
Time of the next billing date.
Payment settings applied to invoices generated by this Subscription. Only applicable when collection_method is CHARGE_ON_CHECKOUT or AUTO_CHARGE.
Settings that control whether and how a payment method provided by a customer while paying a subscription invoice is saved for future use.
Controls whether the payment method can be saved for future use. Possible values: ENABLED, DISABLED, or COLLECT_CONSENT.
ENABLED: The payment method will be saved for future use.DISABLED: The payment method will not be saved.COLLECT_CONSENT: The invoice UI asks the customer whether they want to save the payment method. Only applicable to cards.
Indicates who will use the saved payment source to trigger future payments. One of MERCHANT or CUSTOMER.
If MERCHANT, a Payment Source is created for future use. If CUSTOMER, the payment method is saved only with the payment provider.
The payment methods and their order for display on the digital invoice pages of this Subscription.
Possible enum values: card, applepay, googlepay, alipaycn, alipayhk, dana, gcash, kakaopay, klarna, rabbit_line_pay, tng, truemoney.
ID of the Payment Source to pay for the subscription at each billing period. Required if collection_method is AUTO_CHARGE.
The end time of the trial period if applicable.
The start time of the trial period if applicable.
The page cursor used for searching after page.
The page cursor used for search before page.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request GET \> --url 'https://api.sandbox.airwallex.com/api/v1/billing/subscriptions' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json'
1{2 "items": [3 {4 "applied_discounts": [5 {6 "amount_off": 10,7 "applied_to": "SUBSCRIPTION",8 "applied_to_id": "sub_hkpdkcmxdgazzq53jbk",9 "billing_customer_id": "bcus_7fz9qm2n4k",10 "checkout_id": "bco_sgstcdcpnh8sv3awiwo",11 "currency": "USD",12 "discount_model": "PERCENTAGE",13 "duration": {14 "period": 3,15 "period_unit": "MONTH"16 },17 "duration_type": "CUSTOM",18 "ends_at": "2027-01-01T00:00:00+0000",19 "id": "disc_hkpdkcmxdgazzq53jbk",20 "name": "Black Friday 20% Off",21 "percentage_off": 20,22 "source": "COUPON",23 "source_id": "coup_hkpdkcmxdgazzq53jbk",24 "starts_at": "2026-01-01T00:00:00+0000"25 }26 ],27 "automatic_tax_status": "APPLIED",28 "billing_customer_id": "bcus_hkpd7fedfgb004apkvs",29 "billing_cycle_anchor_at": "2022-01-15T10:15:30+0000",30 "cancel_at_period_end": false,31 "cancel_requested_at": "null",32 "collection_method": "AUTO_CHARGE",33 "created_at": "2022-01-01T10:15:30+0000",34 "currency": "USD",35 "current_period_ends_at": "2022-02-05T10:15:30+0000",36 "current_period_starts_at": "2022-01-05T10:15:30+0000",37 "days_until_due": 0,38 "default_invoice_template": {39 "invoice_memo": "Thanks for your purchase."40 },41 "default_tax_percent": 10,42 "duration": {43 "period": 12,44 "period_unit": "MONTH"45 },46 "enable_automatic_tax": true,47 "ends_at": "null",48 "id": "sub_hkpdkcmxdgazzq53jbk",49 "latest_invoice_id": "inv_hkpdmiq8hgb00f8cpdl",50 "legal_entity_id": "le_ib2DZgZJN72T7bObvNuMYQ",51 "linked_payment_account_id": "acct_ncI2nypPKSq2VXKxscAcg",52 "metadata": {53 "foo": "bar"54 },55 "next_billing_at": "2022-02-05T10:15:30+0000",56 "payment_options": {57 "payment_method_types": [58 "card",59 "googlepay",60 "applepay"61 ]62 },63 "payment_source_id": "psrc_sgpdkxpn2h6anetrb5s",64 "recurring": {65 "period": 1,66 "period_unit": "MONTH"67 },68 "starts_at": "2022-01-01T10:15:30+0000",69 "status": "ACTIVE",70 "trial_ends_at": "2022-01-05T10:15:30+0000",71 "trial_starts_at": "2022-01-01T10:15:30+0000",72 "updated_at": "2022-01-01T10:15:30+0000"73 }74 ],75 "page_after": "<string>",76 "page_before": "<string>"77}
Update a Subscription
POST /api/v1/billing/subscriptions/{id}/update
Updates a Subscription. Only fields provided in the request are updated, while omitted fields remain unchanged. Array fields are fully replaced if included. Set a field to null or an empty string (for strings) to clear its value.
ID of the Subscription object.
Unique request ID specified by the merchant.
Specifies how to handle billing when updating the subscription.
Defaults to DEFER_CHARGE_AND_KEEP_CYCLE.
DEFER_CHARGE_AND_KEEP_CYCLEProrated in-advance fees are applied to the next upcoming invoice. In-arrears fees are still billed on its original billing date. Keep the current billing cycle anchor unchanged.
IMMEDIATE_CHARGE_AND_KEEP_CYCLEA one-time adjustment invoice is generated and attempted for payment upon the subscription update. Keep the current billing cycle anchor unchanged.
IMMEDIATE_CHARGE_AND_RESET_CYCLEResets the subscription's billing_cycle_anchor_at to the time of update request. After you reset the billing cycle anchor, the subscription immediately sends an invoice for prorations. The upcoming billing cycles will be aligned on the new billing cycle anchor.
true if the subscription is scheduled to be cancelled at the end of the current period, false otherwise.
Specify how payment is collected, one of AUTO_CHARGE, CHARGE_ON_CHECKOUT or OUT_OF_BAND.
Number of days from invoice finalization until payment is due.
Invoices for this subscription will be created using the specified settings.
Memo to be used for the invoices that are generated by this Subscription.
By default, how to handle credit and fee prorations for all Subscription Item changes.
Defaults to PRORATED.
NONEDoes not issue any credit for the Subscription's unused time, only charges the new fee from the next billing cycle.
PRORATEDCalculates and applies the proration on both credit and fee for the Subscription's unused time.
ALLCredits the full remaining creditable amount of the old items for the current billing cycle, and charges the full amount of the new items for the current billing cycle.
The tax percent between 0 and 100 to be applied to invoices to be generated. The tax will be exclusive.
Desired set of subscription-level discounts. If provided, replaces all existing subscription-level discounts. Currently, only one element is supported.
Coupon to redeem into a discount for this resource. Only required when type = COUPON.
Id of the Coupon object.
Specifies how to obtain a new discount. One of: COUPON.
The total billing duration of the subscription.
The subscription will continue indefinitely if duration, remaining_duration and ends_at are all null in the update request.
The number of period units.
Specifies billing duration. One of DAY, WEEK, MONTH or YEAR.
Whether automatic tax is enabled for this subscription. When enabled, the system attempts to calculate taxes for this subscription's invoice automatically.
Time when the subscription is scheduled to end.
The subscription will continue indefinitely if duration, remaining_duration and ends_at are all null in the update request.
List of Subscription Items to be added, updated, or deleted. It may trigger credit and proration when the subscription status is ACTIVE. If an existing item is not included in the list, it remains unchanged. You may add 100 items at a time.
If set to true, will delete the specified subscription item.
List of discounts to be applied to the Subscription Item. Discounts of subscription items are applied before subscription discounts. Currently, only one element is supported.
Coupon to redeem into a discount for this resource. Only required when type = COUPON.
Id of the Coupon object.
Specifies how to obtain the discount. One of: COUPON.
ID of the Subscription Item to be updated or be deleted. If not provided, a new Subscription Item will be added.
A set of string key-value pairs that you can attach to this object for storing additional information.
ID of the Price. Required when adding a new item. You can't update the price_id of the existing item.
Specifies how to handle credit and fee prorations for the Subscription Item. This field overrides the default_proration_mode provided in the update request.
Defaults to PRORATED.
NONEDoes not issue any credit for the Subscription's unused time, only charges the new fee from the next billing cycle.
PRORATEDCalculates and applies the proration on both credit and fee for the Subscription's unused time.
ALLCredits the full remaining creditable amount of the old items for the current billing cycle, and charges the full amount of the new items for the current billing cycle.
The quantity of the product.
The effective tax percent of this subscription item.
ID of the legal entity to be used as billing entity. You can find this ID in the Airwallex web app > Settings.
ID of the linked payment account to collect payment. You can find this ID in the Airwallex web app > Settings > Account details, within the Account Information section.
A set of string key-value pairs that you can attach to this object for storing additional information.
Payment settings applied to invoices generated by this Subscription. Only applicable when collection_method is CHARGE_ON_CHECKOUT or AUTO_CHARGE.
Settings that control whether and how a payment method provided by a customer while paying a subscription invoice is saved for future use.
Only applicable when the Subscription uses the AUTO_CHARGE collection method.
When not provided, defaults to mode=ENABLED and next_triggered_by=MERCHANT.
Controls whether the payment method can be saved for future use. Possible values: ENABLED, DISABLED, or COLLECT_CONSENT.
ENABLED: The payment method will be saved for future use.DISABLED: The payment method will not be saved.COLLECT_CONSENT: The invoice UI asks the customer whether they want to save the payment method. Only applicable to cards.
Indicates who will use the saved payment source to trigger future payments. One of MERCHANT or CUSTOMER.
If MERCHANT, a Payment Source is created for future use. If CUSTOMER, the payment method is saved only with the payment provider.
Specify the payment methods and their order for display on the digital invoice pages of this Subscription. Note: Only payment methods supported for the specified currency and the customer's country code will be shown.
Possible enum values: card, applepay, googlepay, alipaycn, alipayhk, dana, gcash, kakaopay, klarna, rabbit_line_pay, tng, truemoney.
ID of the Payment Source to pay for the subscription at each billing period. Required if collection_method is AUTO_CHARGE. If the payment_source_id is updated, the last failed invoice payment associated with this subscription will be retried immediately.
Update the remaining billing duration of the subscription after the time of request.
The subscription will continue indefinitely if duration, remaining_duration and ends_at are all null in the update request.
The number of period units.
Specifies billing duration. One of DAY, WEEK, MONTH or YEAR.
Time when the subscription started or is scheduled to start. Use NOW to start the subscription immediately. Only applicable when status is PENDING.
The end time of the trial if applicable. Use NOW to end the trial immediately.
List of the discounts that are applied to the Subscription. Discounts of subscription items are applied before the subscription discounts.
Specifies the type of object this discount applies to. Possible values:
SUBSCRIPTION: Applies to an entire subscription.SUBSCRIPTION_ITEM: Applies to a specific item within a subscription.INVOICE: Applies to an entire invoice.INVOICE_LINE_ITEM: Applies to a specific line item on an invoice.
ID of the specific target object the discount is applied to. Must correspond to the object type defined in applied_to.
The ID of the billing customer to whom the coupon is applied.
Time when the Discount was created.
Specified how to calculate the discount amount when applied, one of
FLAT: fixed amount off.PERCENTAGE: percentage off.
Determines how long the coupon's discount remains active after being applied. Possible values:
ONCE: Applies only to the first charge of a subscription or a one-off invoice.CUSTOM: Applies to all charges within a specified number of billing cycles, as defined by duration.INDEFINITELY: Applies to all future charges for the subscription until it is removed.
ID of the Discount object.
Name of the discount. For discounts created from a coupon, defaults to the coupon name at creation time.
Source of the Discount. Possible values:
COUPON: the discount is applied through a coupon.
Time when the discount takes effect. For discounts applied to a subscription or subscription item, this corresponds to the start date of the first billing period.
Time when the Discount was updated.
The fixed amount to deduct when discount_model is FLAT.
The ID of the Checkout where this discount was redeemed, if applicable.
The currency of amount_off when discount_model is FLAT.
The duration of the discount to apply, when duration_type is CUSTOM. null if duration_type is ONCE or INDEFINITELY.
The number of period units.
Specifies duration. One of DAY, WEEK, MONTH, YEAR
The timestamp when the discount expires. Present only when the associated coupon's duration_type is CUSTOM.
The percentage between 0 to 100 to be applied to deduct when discount_model is PERCENTAGE.
ID of the creating source, e.g. is the ID of the coupon if source = COUPON.
The automatic tax status of this subscription.
APPLIEDThe automatic tax is applied.
LOCATION_NOT_SUPPORTEDAutomatic tax calculation isn't supported in the customer's location.
LOCATION_NOT_REGISTERED_BY_MERCHANTThe merchant isn't registered to collect tax in the customer's location.
ADDRESS_INCOMPLETEThe customer address was insufficient or invalid to determine the correct tax.
DISABLEDThe automatic tax is disabled.
ID of the Billing Customer who subscribes to this subscription.
A future timestamp in the first billing cycle as the reference point to align the future billing date.
true if the subscription is scheduled to be cancelled at the end of the current billing period, false otherwise.
Time when the cancellation request was received.
Specify how payment is collected, one of AUTO_CHARGE, CHARGE_ON_CHECKOUT or OUT_OF_BAND.
Time when the subscription was created.
The currency of the Subscription in 3-letter ISO-4217 format.
The end time of the current period that the subscription has been invoiced for.
The start time of the current period that the subscription has been invoiced for.
Number of days from invoice finalization until payment is due.
Invoices for this subscription will be created using the specified settings.
Memo to be used for the invoices that are generated by this Subscription.
The tax percent between 0 and 100 to be applied to invoices to be generated. The tax will be exclusive.
The duration of the subscription.
The number of period units.
Specifies billing duration. One of DAY, WEEK, MONTH or YEAR.
Whether automatic tax is enabled for this subscription. When enabled, the system attempts to calculate taxes for this subscription's invoice automatically.
Time when the subscription ended or scheduled to end.
ID of the Subscription object.
The ID of the latest invoice generated for this subscription.
ID of the legal entity to be used as billing entity. You can find this ID in the Airwallex web app > Settings.
ID of the linked payment account to collect payment.
A set of string key-value pairs that you can attach to this object for storing additional information.
Time of the next billing date.
Payment settings applied to invoices generated by this Subscription. Only applicable when collection_method is CHARGE_ON_CHECKOUT or AUTO_CHARGE.
Settings that control whether and how a payment method provided by a customer while paying a subscription invoice is saved for future use.
Controls whether the payment method can be saved for future use. Possible values: ENABLED, DISABLED, or COLLECT_CONSENT.
ENABLED: The payment method will be saved for future use.DISABLED: The payment method will not be saved.COLLECT_CONSENT: The invoice UI asks the customer whether they want to save the payment method. Only applicable to cards.
Indicates who will use the saved payment source to trigger future payments. One of MERCHANT or CUSTOMER.
If MERCHANT, a Payment Source is created for future use. If CUSTOMER, the payment method is saved only with the payment provider.
The payment methods and their order for display on the digital invoice pages of this Subscription.
Possible enum values: card, applepay, googlepay, alipaycn, alipayhk, dana, gcash, kakaopay, klarna, rabbit_line_pay, tng, truemoney.
ID of the Payment Source to pay for the subscription at each billing period. Required if collection_method is AUTO_CHARGE.
The frequency at which the price is charged. null for one-time charge.
The number of period units between subscription billing cycles. For example, the billing cycle is bi-monthly if period=2 and period_unit=MONTH.
Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.
Time when the subscription started or scheduled to start.
Status of the subscription
PENDINGIN_TRIALACTIVEUNPAIDCANCELLEDThe end time of the trial period if applicable.
The start time of the trial period if applicable.
Time when the subscription was last updated.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 404 | Not Found. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request POST \> --url 'https://api.sandbox.airwallex.com/api/v1/billing/subscriptions/subscription_id/update' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json' \> --data '{> "billing_action": "DEFER_CHARGE_AND_KEEP_CYCLE",> "cancel_at_period_end": false,> "collection_method": "AUTO_CHARGE",> "days_until_due": 0,> "default_invoice_template": {> "invoice_memo": "Thanks for your purchase."> },> "default_proration_mode": "PRORATED",> "default_tax_percent": 10,> "discounts": [> {> "coupon": {> "id": "coup_abc123"> },> "type": "COUPON"> }> ],> "duration": {> "period": 12,> "period_unit": "MONTH"> },> "enable_automatic_tax": true,> "ends_at": "2023-01-01T10:15:30+0000",> "items": [> {> "deleted": false,> "discounts": [> {> "coupon": {> "id": "coup_abc123"> },> "type": "COUPON"> }> ],> "id": "sit_hkpdwesy9gazzrtqbkg",> "metadata": {> "foo": "bar"> },> "price_id": "pri_hkpd7fedfgb004apkvs",> "proration_mode": "PRORATED",> "quantity": 2,> "tax_percent": 10> }> ],> "legal_entity_id": "le_ib2DZgZJN72T7bObvNuMYQ",> "linked_payment_account_id": "acct_ncI2nypPKSq2VXKxscAcg",> "metadata": {> "foo": "bar"> },> "payment_options": {> "payment_method_types": [> "card",> "googlepay",> "applepay"> ],> "payment_method_save": {> "mode": "ENABLED",> "next_triggered_by": "MERCHANT"> }> },> "payment_source_id": "psrc_sgpdkxpn2h6anetrb5s",> "remaining_duration": {> "period": 12,> "period_unit": "MONTH"> },> "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",> "starts_at": "2022-01-01T10:15:30+0000",> "trial_ends_at": "2022-05-20T13:14:00+0000">}'
1{2 "applied_discounts": [3 {4 "amount_off": 10,5 "applied_to": "SUBSCRIPTION",6 "applied_to_id": "sub_hkpdkcmxdgazzq53jbk",7 "billing_customer_id": "bcus_7fz9qm2n4k",8 "checkout_id": "bco_sgstcdcpnh8sv3awiwo",9 "currency": "USD",10 "discount_model": "PERCENTAGE",11 "duration": {12 "period": 3,13 "period_unit": "MONTH"14 },15 "duration_type": "CUSTOM",16 "ends_at": "2027-01-01T00:00:00+0000",17 "id": "disc_hkpdkcmxdgazzq53jbk",18 "name": "Black Friday 20% Off",19 "percentage_off": 20,20 "source": "COUPON",21 "source_id": "coup_hkpdkcmxdgazzq53jbk",22 "starts_at": "2026-01-01T00:00:00+0000"23 }24 ],25 "automatic_tax_status": "APPLIED",26 "billing_customer_id": "bcus_hkpd7fedfgb004apkvs",27 "billing_cycle_anchor_at": "2022-01-15T10:15:30+0000",28 "cancel_at_period_end": false,29 "cancel_requested_at": "null",30 "collection_method": "AUTO_CHARGE",31 "created_at": "2022-01-01T10:15:30+0000",32 "currency": "USD",33 "current_period_ends_at": "2022-02-05T10:15:30+0000",34 "current_period_starts_at": "2022-01-05T10:15:30+0000",35 "days_until_due": 0,36 "default_invoice_template": {37 "invoice_memo": "Thanks for your purchase."38 },39 "default_tax_percent": 10,40 "duration": {41 "period": 12,42 "period_unit": "MONTH"43 },44 "enable_automatic_tax": true,45 "ends_at": "null",46 "id": "sub_hkpdkcmxdgazzq53jbk",47 "latest_invoice_id": "inv_hkpdmiq8hgb00f8cpdl",48 "legal_entity_id": "le_ib2DZgZJN72T7bObvNuMYQ",49 "linked_payment_account_id": "acct_ncI2nypPKSq2VXKxscAcg",50 "metadata": {51 "foo": "bar"52 },53 "next_billing_at": "2022-02-05T10:15:30+0000",54 "payment_options": {55 "payment_method_types": [56 "card",57 "googlepay",58 "applepay"59 ],60 "payment_method_save": {61 "mode": "ENABLED",62 "next_triggered_by": "MERCHANT"63 }64 },65 "payment_source_id": "psrc_sgpdkxpn2h6anetrb5s",66 "recurring": {67 "period": 1,68 "period_unit": "MONTH"69 },70 "starts_at": "2022-01-01T10:15:30+0000",71 "status": "ACTIVE",72 "trial_ends_at": "2022-01-05T10:15:30+0000",73 "trial_starts_at": "2022-01-01T10:15:30+0000",74 "updated_at": "2022-01-01T10:15:30+0000"75}
Cancel a Subscription
POST /api/v1/billing/subscriptions/{id}/cancel
Cancels a Subscription immediately and refunds based on specified proration behavior.
ID of the Subscription object.
Determines how to handle prorations when canceling the Subscription. One of ALL, PRORATED, NONE.
ALL: refund the charge of the current period.PRORATED: refund the proration.NONE: won't refund for the Subscription's unused time.
Unique request ID specified by the merchant.
List of the discounts that are applied to the Subscription. Discounts of subscription items are applied before the subscription discounts.
Specifies the type of object this discount applies to. Possible values:
SUBSCRIPTION: Applies to an entire subscription.SUBSCRIPTION_ITEM: Applies to a specific item within a subscription.INVOICE: Applies to an entire invoice.INVOICE_LINE_ITEM: Applies to a specific line item on an invoice.
ID of the specific target object the discount is applied to. Must correspond to the object type defined in applied_to.
The ID of the billing customer to whom the coupon is applied.
Time when the Discount was created.
Specified how to calculate the discount amount when applied, one of
FLAT: fixed amount off.PERCENTAGE: percentage off.
Determines how long the coupon's discount remains active after being applied. Possible values:
ONCE: Applies only to the first charge of a subscription or a one-off invoice.CUSTOM: Applies to all charges within a specified number of billing cycles, as defined by duration.INDEFINITELY: Applies to all future charges for the subscription until it is removed.
ID of the Discount object.
Name of the discount. For discounts created from a coupon, defaults to the coupon name at creation time.
Source of the Discount. Possible values:
COUPON: the discount is applied through a coupon.
Time when the discount takes effect. For discounts applied to a subscription or subscription item, this corresponds to the start date of the first billing period.
Time when the Discount was updated.
The fixed amount to deduct when discount_model is FLAT.
The ID of the Checkout where this discount was redeemed, if applicable.
The currency of amount_off when discount_model is FLAT.
The duration of the discount to apply, when duration_type is CUSTOM. null if duration_type is ONCE or INDEFINITELY.
The number of period units.
Specifies duration. One of DAY, WEEK, MONTH, YEAR
The timestamp when the discount expires. Present only when the associated coupon's duration_type is CUSTOM.
The percentage between 0 to 100 to be applied to deduct when discount_model is PERCENTAGE.
ID of the creating source, e.g. is the ID of the coupon if source = COUPON.
The automatic tax status of this subscription.
APPLIEDThe automatic tax is applied.
LOCATION_NOT_SUPPORTEDAutomatic tax calculation isn't supported in the customer's location.
LOCATION_NOT_REGISTERED_BY_MERCHANTThe merchant isn't registered to collect tax in the customer's location.
ADDRESS_INCOMPLETEThe customer address was insufficient or invalid to determine the correct tax.
DISABLEDThe automatic tax is disabled.
ID of the Billing Customer who subscribes to this subscription.
A future timestamp in the first billing cycle as the reference point to align the future billing date.
true if the subscription is scheduled to be cancelled at the end of the current billing period, false otherwise.
Time when the cancellation request was received.
Specify how payment is collected, one of AUTO_CHARGE, CHARGE_ON_CHECKOUT or OUT_OF_BAND.
Time when the subscription was created.
The currency of the Subscription in 3-letter ISO-4217 format.
The end time of the current period that the subscription has been invoiced for.
The start time of the current period that the subscription has been invoiced for.
Number of days from invoice finalization until payment is due.
Invoices for this subscription will be created using the specified settings.
Memo to be used for the invoices that are generated by this Subscription.
The tax percent between 0 and 100 to be applied to invoices to be generated. The tax will be exclusive.
The duration of the subscription.
The number of period units.
Specifies billing duration. One of DAY, WEEK, MONTH or YEAR.
Whether automatic tax is enabled for this subscription. When enabled, the system attempts to calculate taxes for this subscription's invoice automatically.
Time when the subscription ended or scheduled to end.
ID of the Subscription object.
The ID of the latest invoice generated for this subscription.
ID of the legal entity to be used as billing entity. You can find this ID in the Airwallex web app > Settings.
ID of the linked payment account to collect payment.
A set of string key-value pairs that you can attach to this object for storing additional information.
Time of the next billing date.
Payment settings applied to invoices generated by this Subscription. Only applicable when collection_method is CHARGE_ON_CHECKOUT or AUTO_CHARGE.
Settings that control whether and how a payment method provided by a customer while paying a subscription invoice is saved for future use.
Controls whether the payment method can be saved for future use. Possible values: ENABLED, DISABLED, or COLLECT_CONSENT.
ENABLED: The payment method will be saved for future use.DISABLED: The payment method will not be saved.COLLECT_CONSENT: The invoice UI asks the customer whether they want to save the payment method. Only applicable to cards.
Indicates who will use the saved payment source to trigger future payments. One of MERCHANT or CUSTOMER.
If MERCHANT, a Payment Source is created for future use. If CUSTOMER, the payment method is saved only with the payment provider.
The payment methods and their order for display on the digital invoice pages of this Subscription.
Possible enum values: card, applepay, googlepay, alipaycn, alipayhk, dana, gcash, kakaopay, klarna, rabbit_line_pay, tng, truemoney.
ID of the Payment Source to pay for the subscription at each billing period. Required if collection_method is AUTO_CHARGE.
The frequency at which the price is charged. null for one-time charge.
The number of period units between subscription billing cycles. For example, the billing cycle is bi-monthly if period=2 and period_unit=MONTH.
Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.
Time when the subscription started or scheduled to start.
Status of the subscription
PENDINGIN_TRIALACTIVEUNPAIDCANCELLEDThe end time of the trial period if applicable.
The start time of the trial period if applicable.
Time when the subscription was last updated.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 404 | Not Found. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request POST \> --url 'https://api.sandbox.airwallex.com/api/v1/billing/subscriptions/subscription_id/cancel' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json' \> --data '{> "proration_behavior": "NONE",> "request_id": "ee939540-3203-4a2c-9172-89a566485dd9">}'
1{2 "applied_discounts": [3 {4 "amount_off": 10,5 "applied_to": "SUBSCRIPTION",6 "applied_to_id": "sub_hkpdkcmxdgazzq53jbk",7 "billing_customer_id": "bcus_7fz9qm2n4k",8 "checkout_id": "bco_sgstcdcpnh8sv3awiwo",9 "currency": "USD",10 "discount_model": "PERCENTAGE",11 "duration": {12 "period": 3,13 "period_unit": "MONTH"14 },15 "duration_type": "CUSTOM",16 "ends_at": "2027-01-01T00:00:00+0000",17 "id": "disc_hkpdkcmxdgazzq53jbk",18 "name": "Black Friday 20% Off",19 "percentage_off": 20,20 "source": "COUPON",21 "source_id": "coup_hkpdkcmxdgazzq53jbk",22 "starts_at": "2026-01-01T00:00:00+0000"23 }24 ],25 "automatic_tax_status": "APPLIED",26 "billing_customer_id": "bcus_hkpd7fedfgb004apkvs",27 "billing_cycle_anchor_at": "2022-01-15T10:15:30+0000",28 "cancel_at_period_end": false,29 "cancel_requested_at": "null",30 "collection_method": "AUTO_CHARGE",31 "created_at": "2022-01-01T10:15:30+0000",32 "currency": "USD",33 "current_period_ends_at": "2022-02-05T10:15:30+0000",34 "current_period_starts_at": "2022-01-05T10:15:30+0000",35 "days_until_due": 0,36 "default_invoice_template": {37 "invoice_memo": "Thanks for your purchase."38 },39 "default_tax_percent": 10,40 "duration": {41 "period": 12,42 "period_unit": "MONTH"43 },44 "enable_automatic_tax": true,45 "ends_at": "null",46 "id": "sub_hkpdkcmxdgazzq53jbk",47 "latest_invoice_id": "inv_hkpdmiq8hgb00f8cpdl",48 "legal_entity_id": "le_ib2DZgZJN72T7bObvNuMYQ",49 "linked_payment_account_id": "acct_ncI2nypPKSq2VXKxscAcg",50 "metadata": {51 "foo": "bar"52 },53 "next_billing_at": "2022-02-05T10:15:30+0000",54 "payment_options": {55 "payment_method_types": [56 "card",57 "googlepay",58 "applepay"59 ]60 },61 "payment_source_id": "psrc_sgpdkxpn2h6anetrb5s",62 "recurring": {63 "period": 1,64 "period_unit": "MONTH"65 },66 "starts_at": "2022-01-01T10:15:30+0000",67 "status": "ACTIVE",68 "trial_ends_at": "2022-01-05T10:15:30+0000",69 "trial_starts_at": "2022-01-01T10:15:30+0000",70 "updated_at": "2022-01-01T10:15:30+0000"71}
Retrieve a Subscription Item
GET /api/v1/billing/subscriptions/{id}/items/{item_id}
Retrieves the details of a Subscription Item.
ID of the Subscription object that this Subscription Item belongs to.
ID of the Subscription Item object.
List of the discounts that are applied to the Subscription Item. Discounts of subscription items are applied before the subscription discounts.
Specifies the type of object this discount applies to. Possible values:
SUBSCRIPTION: Applies to an entire subscription.SUBSCRIPTION_ITEM: Applies to a specific item within a subscription.INVOICE: Applies to an entire invoice.INVOICE_LINE_ITEM: Applies to a specific line item on an invoice.
ID of the specific target object the discount is applied to. Must correspond to the object type defined in applied_to.
The ID of the billing customer to whom the coupon is applied.
Time when the Discount was created.
Specified how to calculate the discount amount when applied, one of
FLAT: fixed amount off.PERCENTAGE: percentage off.
Determines how long the coupon's discount remains active after being applied. Possible values:
ONCE: Applies only to the first charge of a subscription or a one-off invoice.CUSTOM: Applies to all charges within a specified number of billing cycles, as defined by duration.INDEFINITELY: Applies to all future charges for the subscription until it is removed.
ID of the Discount object.
Name of the discount. For discounts created from a coupon, defaults to the coupon name at creation time.
Source of the Discount. Possible values:
COUPON: the discount is applied through a coupon.
Time when the discount takes effect. For discounts applied to a subscription or subscription item, this corresponds to the start date of the first billing period.
Time when the Discount was updated.
The fixed amount to deduct when discount_model is FLAT.
The ID of the Checkout where this discount was redeemed, if applicable.
The currency of amount_off when discount_model is FLAT.
The duration of the discount to apply, when duration_type is CUSTOM. null if duration_type is ONCE or INDEFINITELY.
The number of period units.
Specifies duration. One of DAY, WEEK, MONTH, YEAR
The timestamp when the discount expires. Present only when the associated coupon's duration_type is CUSTOM.
The percentage between 0 to 100 to be applied to deduct when discount_model is PERCENTAGE.
ID of the creating source, e.g. is the ID of the coupon if source = COUPON.
Time when the Subscription Item was created.
The end time of the current period that the subscription item has been invoiced for.
The start time of the current period that the subscription item has been invoiced for.
ID of the Subscription Item object.
A set of string key-value pairs that you can attach to this object for storing additional information.
The price on a Subscription Item.
true if the price is available for new purchases, false otherwise.
Time when the price was created.
Currency of the price (in 3-letter ISO-4217 format).
ID of the Price object.
Specify how to determine the quantity of the product used in each billing cycle for subscription payments. true if the quantity is dynamically determined during the billing cycle. The merchant should call the Ingest Usage Events API to submit usage data when the product is used. false if the quantity is determined when creating a subscription.
Specify how to calculate the total billing amount when a quantity is provided. One of
FLAT: a fixed price.PER_UNIT: a fixed price per unit quantity.VOLUME: the unit price is based on which tier the total quantity falls in.GRADUATED: the unit price changes as the quantity increases.
Details of the Product object this price is associated with.
true if the product is available for new purchases, false otherwise.
Time when this product was created.
ID of the Product object.
Product name.
Product unit.
Time when this product was last updated.
Product description.
A set of string key-value pairs that you can attach to this object for storing additional information.
The tax category of the product.
ID of the Product object this price is associated with.
Whether the price includes tax.
One of ONE_OFF or RECURRING depending on whether the price is for a one-off purchase or a recurring (subscription) purchase.
Time when the price was last updated.
Indicates when should the price be billed, one of
IN_ADVANCE: billed at the beginning of the billing cycle.IN_ARREARS: billed at the end of the billing cycle.
Price description.
The fixed amount to be charged. Only required when the pricing model is FLAT.
Defines how quantity is grouped into billable lots. The unit_amount is then applied per lot. If not set, quantity is treated as the number of billable lots. Only applicable for PER_UNIT price.
Specifies how to round the calculated lots when the total quantity is not an exact multiple of the size. One of UP.
The amount of quantity that constitutes a single billable lot.
A set of string key-value pairs that you can attach to this object for storing additional information.
ID of the Meter object specifying how to calculate the usage for this price.
The frequency at which the price is charged. null for one-time charge.
The number of period units between subscription billing cycles. For example, the billing cycle is bi-monthly if period=2 and period_unit=MONTH.
Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.
List of quantity-based pricing tiers for this price. Required when the pricing model is VOLUME or GRADUATED.
The sequential position of the tier within the price definition. Starts from 1.
The flat amount to be charged for this tier when pricing model is GRADUATED, or the overall flat amount to be charged when pricing model is VOLUME.
Defines how quantity is grouped into billable lots. The unit_amount is then applied per lot. If not set, quantity is treated as the number of billable lots. Only applicable for VOLUME and GRADUATED prices.
Specifies how to round the calculated lots when the total quantity is not an exact multiple of the size. One of UP.
The amount of quantity that constitutes a single billable lot.
The per-unit amount to be charged for this tier when pricing model is GRADUATED, or the overall per-unit amount to be charged when pricing model is VOLUME.
Description of the billable unit for the tier.
The upper quantity limit of this tier. This tier is applicable when the quantity does not exceed the upper bound of this tier, and is greater than the upper bound of the tier below it(or 0 if this is the first tier). For the last tier, the upper bound must be left empty.
The amount to be charged per product unit. Only required when the pricing model is PER_UNIT.
Description of the billable unit for the price.
The quantity of the product.
ID of the Subscription object that this Subscription Item belongs to.
The effective tax percent of this subscription item.
Time when the Subscription Item was updated.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 404 | Not Found. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request GET \> --url 'https://api.sandbox.airwallex.com/api/v1/billing/subscriptions/subscription_id/items/item_id' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json'
1{2 "applied_discounts": [3 {4 "amount_off": 10,5 "applied_to": "SUBSCRIPTION",6 "applied_to_id": "sub_hkpdkcmxdgazzq53jbk",7 "billing_customer_id": "bcus_7fz9qm2n4k",8 "checkout_id": "bco_sgstcdcpnh8sv3awiwo",9 "currency": "USD",10 "discount_model": "PERCENTAGE",11 "duration": {12 "period": 3,13 "period_unit": "MONTH"14 },15 "duration_type": "CUSTOM",16 "ends_at": "2027-01-01T00:00:00+0000",17 "id": "disc_hkpdkcmxdgazzq53jbk",18 "name": "Black Friday 20% Off",19 "percentage_off": 20,20 "source": "COUPON",21 "source_id": "coup_hkpdkcmxdgazzq53jbk",22 "starts_at": "2026-01-01T00:00:00+0000"23 }24 ],25 "created_at": "2022-01-01T10:15:30+0000",26 "current_period_ends_at": "2022-02-01T10:15:30+0000",27 "current_period_starts_at": "2022-01-01T10:15:30+0000",28 "id": "sit_hkpdwesy9gazzrtqbkg",29 "metadata": {30 "foo": "bar"31 },32 "price": {33 "active": true,34 "billing_type": "IN_ADVANCE",35 "created_at": "2022-01-01T10:15:30+0000",36 "currency": "USD",37 "description": "Standard option: $10 / month.",38 "flat_amount": 0,39 "id": "pri_hkpd7fedfgb004apkvs",40 "lot": {41 "rounding_mode": "UP",42 "size": 1043 },44 "metadata": {45 "foo": "bar"46 },47 "meter_id": "<string>",48 "metered": false,49 "pricing_model": "GRADUATED",50 "product": {51 "active": true,52 "created_at": "2022-01-01T10:15:30+0000",53 "description": "The license to use software in one month.",54 "id": "prd_hkpd1x2gbgazzvcd42w",55 "metadata": {56 "foo": "bar"57 },58 "name": "Software License",59 "tax_code": "pct_0504010000",60 "unit": "month",61 "updated_at": "2022-01-01T10:15:30+0000"62 },63 "product_id": "prd_hkpd1x2gbgazzvcd42w",64 "recurring": {65 "period": 1,66 "period_unit": "MONTH"67 },68 "tax_included": false,69 "tiers": [70 {71 "unit_amount": 10,72 "upper_bound": 2073 },74 {75 "flat_amount": 2076 }77 ],78 "type": "RECURRING",79 "unit_amount": 0,80 "unit_description": "<string>",81 "updated_at": "2022-01-01T10:15:30+0000"82 },83 "quantity": 2,84 "subscription_id": "sub_hkpdkcmxdgazzq53jbk",85 "tax_percent": 5,86 "updated_at": "2022-01-01T10:15:30+0000"87}
List all Subscription Items
GET /api/v1/billing/subscriptions/{id}/items
Retrieves a list of Subscription Items based on the query parameters.
ID of the Subscription object that the Subscription Items belong to.
A bookmark for use in pagination to retrieve either the next page or the previous page of results. You can fetch the value for this identifier from the response of the previous API call. To retrieve the next page of results, pass the value of page_after (if not null) from the response to a subsequent call. To retrieve the previous page of results, pass the value of page_before (if not null) from the response to a subsequent call.
Number of Subscription Items per page. Defaults to 20.
Paged results.
List of the discounts that are applied to the Subscription Item. Discounts of subscription items are applied before the subscription discounts.
Specifies the type of object this discount applies to. Possible values:
SUBSCRIPTION: Applies to an entire subscription.SUBSCRIPTION_ITEM: Applies to a specific item within a subscription.INVOICE: Applies to an entire invoice.INVOICE_LINE_ITEM: Applies to a specific line item on an invoice.
ID of the specific target object the discount is applied to. Must correspond to the object type defined in applied_to.
The ID of the billing customer to whom the coupon is applied.
Time when the Discount was created.
Specified how to calculate the discount amount when applied, one of
FLAT: fixed amount off.PERCENTAGE: percentage off.
Determines how long the coupon's discount remains active after being applied. Possible values:
ONCE: Applies only to the first charge of a subscription or a one-off invoice.CUSTOM: Applies to all charges within a specified number of billing cycles, as defined by duration.INDEFINITELY: Applies to all future charges for the subscription until it is removed.
ID of the Discount object.
Name of the discount. For discounts created from a coupon, defaults to the coupon name at creation time.
Source of the Discount. Possible values:
COUPON: the discount is applied through a coupon.
Time when the discount takes effect. For discounts applied to a subscription or subscription item, this corresponds to the start date of the first billing period.
Time when the Discount was updated.
The fixed amount to deduct when discount_model is FLAT.
The ID of the Checkout where this discount was redeemed, if applicable.
The currency of amount_off when discount_model is FLAT.
The duration of the discount to apply, when duration_type is CUSTOM. null if duration_type is ONCE or INDEFINITELY.
The number of period units.
Specifies duration. One of DAY, WEEK, MONTH, YEAR
The timestamp when the discount expires. Present only when the associated coupon's duration_type is CUSTOM.
The percentage between 0 to 100 to be applied to deduct when discount_model is PERCENTAGE.
ID of the creating source, e.g. is the ID of the coupon if source = COUPON.
Time when the Subscription Item was created.
ID of the Subscription Item object.
The price on a Subscription Item.
true if the price is available for new purchases, false otherwise.
Time when the price was created.
Currency of the price (in 3-letter ISO-4217 format).
ID of the Price object.
Specify how to determine the quantity of the product used in each billing cycle for subscription payments. true if the quantity is dynamically determined during the billing cycle. The merchant should call the Ingest Usage Events API to submit usage data when the product is used. false if the quantity is determined when creating a subscription.
Specify how to calculate the total billing amount when a quantity is provided. One of
FLAT: a fixed price.PER_UNIT: a fixed price per unit quantity.VOLUME: the unit price is based on which tier the total quantity falls in.GRADUATED: the unit price changes as the quantity increases.
Details of the Product object this price is associated with.
true if the product is available for new purchases, false otherwise.
Time when this product was created.
ID of the Product object.
Product name.
Product unit.
Time when this product was last updated.
Product description.
A set of string key-value pairs that you can attach to this object for storing additional information.
The tax category of the product.
ID of the Product object this price is associated with.
Whether the price includes tax.
One of ONE_OFF or RECURRING depending on whether the price is for a one-off purchase or a recurring (subscription) purchase.
Time when the price was last updated.
Indicates when should the price be billed, one of
IN_ADVANCE: billed at the beginning of the billing cycle.IN_ARREARS: billed at the end of the billing cycle.
Price description.
The fixed amount to be charged. Only required when the pricing model is FLAT.
Defines how quantity is grouped into billable lots. The unit_amount is then applied per lot. If not set, quantity is treated as the number of billable lots. Only applicable for PER_UNIT price.
Specifies how to round the calculated lots when the total quantity is not an exact multiple of the size. One of UP.
The amount of quantity that constitutes a single billable lot.
A set of string key-value pairs that you can attach to this object for storing additional information.
ID of the Meter object specifying how to calculate the usage for this price.
The frequency at which the price is charged. null for one-time charge.
The number of period units between subscription billing cycles. For example, the billing cycle is bi-monthly if period=2 and period_unit=MONTH.
Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.
List of quantity-based pricing tiers for this price. Required when the pricing model is VOLUME or GRADUATED.
The sequential position of the tier within the price definition. Starts from 1.
The flat amount to be charged for this tier when pricing model is GRADUATED, or the overall flat amount to be charged when pricing model is VOLUME.
Defines how quantity is grouped into billable lots. The unit_amount is then applied per lot. If not set, quantity is treated as the number of billable lots. Only applicable for VOLUME and GRADUATED prices.
Specifies how to round the calculated lots when the total quantity is not an exact multiple of the size. One of UP.
The amount of quantity that constitutes a single billable lot.
The per-unit amount to be charged for this tier when pricing model is GRADUATED, or the overall per-unit amount to be charged when pricing model is VOLUME.
Description of the billable unit for the tier.
The upper quantity limit of this tier. This tier is applicable when the quantity does not exceed the upper bound of this tier, and is greater than the upper bound of the tier below it(or 0 if this is the first tier). For the last tier, the upper bound must be left empty.
The amount to be charged per product unit. Only required when the pricing model is PER_UNIT.
Description of the billable unit for the price.
ID of the Subscription object that this Subscription Item belongs to.
Time when the Subscription Item was updated.
The end time of the current period that the subscription item has been invoiced for.
The start time of the current period that the subscription item has been invoiced for.
A set of string key-value pairs that you can attach to this object for storing additional information.
The quantity of the product.
The effective tax percent of this subscription item.
The page cursor used for searching after page.
The page cursor used for search before page.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request GET \> --url 'https://api.sandbox.airwallex.com/api/v1/billing/subscriptions/subscription_id/items' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json'
1{2 "items": [3 {4 "applied_discounts": [5 {6 "amount_off": 10,7 "applied_to": "SUBSCRIPTION",8 "applied_to_id": "sub_hkpdkcmxdgazzq53jbk",9 "billing_customer_id": "bcus_7fz9qm2n4k",10 "checkout_id": "bco_sgstcdcpnh8sv3awiwo",11 "currency": "USD",12 "discount_model": "PERCENTAGE",13 "duration": {14 "period": 3,15 "period_unit": "MONTH"16 },17 "duration_type": "CUSTOM",18 "ends_at": "2027-01-01T00:00:00+0000",19 "id": "disc_hkpdkcmxdgazzq53jbk",20 "name": "Black Friday 20% Off",21 "percentage_off": 20,22 "source": "COUPON",23 "source_id": "coup_hkpdkcmxdgazzq53jbk",24 "starts_at": "2026-01-01T00:00:00+0000"25 }26 ],27 "created_at": "2022-01-01T10:15:30+0000",28 "current_period_ends_at": "2022-02-01T10:15:30+0000",29 "current_period_starts_at": "2022-01-01T10:15:30+0000",30 "id": "sit_hkpdwesy9gazzrtqbkg",31 "metadata": {32 "foo": "bar"33 },34 "price": {35 "active": true,36 "billing_type": "IN_ADVANCE",37 "created_at": "2022-01-01T10:15:30+0000",38 "currency": "USD",39 "description": "Standard option: $10 / month.",40 "id": "pri_hkpd7fedfgb004apkvs",41 "lot": {42 "rounding_mode": "UP",43 "size": 1044 },45 "metadata": {46 "foo": "bar"47 },48 "metered": false,49 "pricing_model": "GRADUATED",50 "product": {51 "active": true,52 "created_at": "2022-01-01T10:15:30+0000",53 "description": "The license to use software in one month.",54 "id": "prd_hkpd1x2gbgazzvcd42w",55 "metadata": {56 "foo": "bar"57 },58 "name": "Software License",59 "tax_code": "pct_0504010000",60 "unit": "month",61 "updated_at": "2022-01-01T10:15:30+0000"62 },63 "product_id": "prd_hkpd1x2gbgazzvcd42w",64 "recurring": {65 "period": 1,66 "period_unit": "MONTH"67 },68 "tax_included": false,69 "tiers": [70 {71 "unit_amount": 10,72 "upper_bound": 2073 },74 {75 "flat_amount": 2076 }77 ],78 "type": "RECURRING",79 "updated_at": "2022-01-01T10:15:30+0000"80 },81 "quantity": 2,82 "subscription_id": "sub_hkpdkcmxdgazzq53jbk",83 "tax_percent": 5,84 "updated_at": "2022-01-01T10:15:30+0000"85 }86 ],87 "page_after": "<string>",88 "page_before": "<string>"89}