Subscriptions

A Subscription is a customer's recurring purchase record. Airwallex automatically charges the customers on every billing cycle with the provided PaymentConsent until the subscription is cancelled.

A subscription with a free trial moves from IN_TRIAL status to ACTIVE when the trial period ends. Airwallex automatically charges your customer at the start of each subscription billing cycle. The subscription status is UNPAID when a payment fails. In this case, Airwallex will retry payment several times depending on the dunning policy. The default dunning policy is to retry at most 4 times (after 1 day, 2 days, 5 days and 7 days). The subscription moves to ACTIVE if any payment retry attempt has succeeded or CANCELLED after all retries have failed. A subscription moves to CANCELLED if it has ended or been cancelled.

Endpoints

POST /api/v1/billing/subscriptions/create
GET /api/v1/billing/subscriptions/{id}
POST /api/v1/billing/subscriptions/{id}/update
POST /api/v1/billing/subscriptions/{id}/cancel
GET /api/v1/billing/subscriptions
GET /api/v1/billing/subscriptions/{id}/items/{item_id}
GET /api/v1/billing/subscriptions/{id}/items

Create a subscription

POST /api/v1/billing/subscriptions/create

Copy for LLMView as Markdown

Create a new Subscription on an existing Customer to charge the customer on a recurring basis. Before creating a Subscription, you must create a Payment Consent that represents the consent between you and the customer on the future use of the saved payments details.

Request body

customer_idrequiredstring

Unique identifier of the customer who subscribes to this subscription.

itemsrequiredarray

List of SubscriptionItems.

items.price_idrequiredstring

Unique identifier of the Price subscribed by the customer. The Price's recurring values must match the recurring values set out in this subscription.

items.metadataobject

A set of key-value pairs that you can attach to this object for storing additional information.

items.quantitynumber

The product quantity. Defaults to 1.

payment_consent_idrequiredstring

Unique identifier of the PaymentConsent to pay for the subscription at each billing period.

recurringrequiredobject

The billing cycle for recurring charges.

recurring.period_unitrequiredstring

Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.

recurring.periodinteger

The number of period units between subscription billing cycles. For example, the billing cycle is bi-monthly if period=2 and period_unit=MONTH.

request_idrequiredstring

Unique request identifier specified by the merchant.

metadataobject

A set of key-value pairs that you can attach to this object for storing additional information.

total_billing_cyclesinteger

The total number of billing cycles of the subscription. For example, the subscription will last for 1 year if total_billing_cycles=12, period=1 and period_unit=MONTH. The subscription will continue indefinitely if total_billing_cycles is null.

trial_end_atstring

The end time of the trial if applicable.

Response body - 201 Created

cancel_atstring

Time when the subscription is scheduled to be cancelled.

cancel_at_period_endboolean

true if the subscription is scheduled to be cancelled at the end of the current billing period, false otherwise.

cancel_requested_atstring

Time when the cancellation request was received.

created_atstring

Time when the subscription was created.

current_period_end_atstring

The end time of the current period that the subscription has been invoiced for.

current_period_start_atstring

The start time of the current period that the subscription has been invoiced for.

customer_idstring

Unique identifier of the customer who subscribes to this subscription.

idstring

Unique identifier of the Subscription object.

latest_invoice_idstring

The unique identifier of the latest invoice generated for this subscription.

metadataobject

A set of key-value pairs that you can attach to this object for storing additional information.

next_billing_atstring

Time of the next billing date.

payment_consent_idstring

Unique identifier of the PaymentConsent to pay for the subscription at each billing period.

recurringobject

The billing cycle for recurring charges.

recurring.periodinteger

The number of period units between subscription billing cycles. For example, the billing cycle is bi-monthly if period=2 and period_unit=MONTH.

recurring.period_unitstring

Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.

remaining_billing_cyclesinteger

The remaining billing cycles of the subscription.

request_idstring

Unique request identifier specified by the merchant in the last operation.

statusstring

Status of the subscription, one of IN_TRIAL, ACTIVE, UNPAID or CANCELLED.

total_billing_cyclesinteger

trial_end_atstring

The end time of the trial if applicable.

trial_start_atstring

The start time of the trial period if applicable.

updated_atstring

Time when the subscription was last updated.

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`, `duplicate_request`, `suspended_from_online_payments`, `currency_not_supported`, `provider_unavailable`, `resource_not_found`(invalid `customer_id` or `payment_consent_id`), `frequency_above_limit`, `configuration_error`, `authentication_declined`, `risk_declined`, `provider_declined`, `quote_expired`, `issuer_declined`, `no_3ds_liability_shift`, `rejected_by_routing_rules`
401	Unauthorized. Possible error codes: `unauthorized`
500	Server Error. Possible error codes: `internal_error`

POST /api/v1/billing/subscriptions/create

$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/billing/subscriptions/create' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "customer_id": "cus_ps8e0ZgQzd2QnCxVpzJrHD6KOVu",
>  "items": [
>    {
>      "metadata": {
>        "foo": "bar"
>      },
>      "price_id": "pri_hkpd7fedfgb004apkvs",
>      "quantity": 2
>    }
>  ],
>  "metadata": {
>    "foo": "bar"
>  },
>  "payment_consent_id": "cst_u79lnfufjxxfdc0",
>  "recurring": {
>    "period": 1,
>    "period_unit": "MONTH"
>  },
>  "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
>  "total_billing_cycles": 12,
>  "trial_end_at": "2022-01-05T10:15:30+0000"
>}'

Response (201 Created)

1{
2  "cancel_at": "null",
3  "cancel_at_period_end": false,
4  "cancel_requested_at": "null",
5  "created_at": "2022-01-01T10:15:30+0000",
6  "current_period_end_at": "2022-02-05T10:15:30+0000",
7  "current_period_start_at": "2022-01-05T10:15:30+0000",
8  "customer_id": "cus_ps8e0ZgQzd2QnCxVpzJrHD6KOVu",
9  "id": "sub_hkpdkcmxdgazzq53jbk",
10  "latest_invoice_id": "inv_hkpdmiq8hgb00f8cpdl",
11  "metadata": {
12    "foo": "bar"
13  },
14  "next_billing_at": "2022-02-05T10:15:30+0000",
15  "payment_consent_id": "cst_u79lnfufjxxfdc0",
16  "recurring": {
17    "period": 1,
18    "period_unit": "MONTH"
19  },
20  "remaining_billing_cycles": 12,
21  "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
22  "status": "ACTIVE",
23  "total_billing_cycles": 12,
24  "trial_end_at": "2022-01-05T10:15:30+0000",
25  "trial_start_at": "2022-01-01T10:15:30+0000",
26  "updated_at": "2022-01-01T10:15:30+0000"
27}

Was this section helpful?

Retrieve a subscription

GET /api/v1/billing/subscriptions/{id}

Copy for LLMView as Markdown

Retrieves the details of a Subscription using the given Subscription unique identifier.

Parameters

idrequiredstring

Unique identifier of the Subscription object.

Response body - 200 OK

cancel_atstring

Time when the subscription is scheduled to be cancelled.

cancel_at_period_endboolean

true if the subscription is scheduled to be cancelled at the end of the current billing period, false otherwise.

cancel_requested_atstring

Time when the cancellation request was received.

created_atstring

Time when the subscription was created.

current_period_end_atstring

The end time of the current period that the subscription has been invoiced for.

current_period_start_atstring

The start time of the current period that the subscription has been invoiced for.

customer_idstring

Unique identifier of the customer who subscribes to this subscription.

idstring

Unique identifier of the Subscription object.

latest_invoice_idstring

The unique identifier of the latest invoice generated for this subscription.

metadataobject

A set of key-value pairs that you can attach to this object for storing additional information.

next_billing_atstring

Time of the next billing date.

payment_consent_idstring

Unique identifier of the PaymentConsent to pay for the subscription at each billing period.

recurringobject

The billing cycle for recurring charges.

recurring.periodinteger

The number of period units between subscription billing cycles. For example, the billing cycle is bi-monthly if period=2 and period_unit=MONTH.

recurring.period_unitstring

Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.

remaining_billing_cyclesinteger

The remaining billing cycles of the subscription.

request_idstring

Unique request identifier specified by the merchant in the last operation.

statusstring

Status of the subscription, one of IN_TRIAL, ACTIVE, UNPAID or CANCELLED.

total_billing_cyclesinteger

trial_end_atstring

The end time of the trial if applicable.

trial_start_atstring

The start time of the trial period if applicable.

updated_atstring

Time when the subscription was last updated.

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`
401	Unauthorized. Possible error codes: `unauthorized`
404	Not Found. Possible error codes: `resource_not_found`
500	Server Error. Possible error codes: `internal_error`

GET /api/v1/billing/subscriptions/{id}

$curl --request GET \
>  --url 'https://api-demo.airwallex.com/api/v1/billing/subscriptions/subscription_id' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Response (200 OK)

1{
2  "cancel_at": "null",
3  "cancel_at_period_end": false,
4  "cancel_requested_at": "null",
5  "created_at": "2022-01-01T10:15:30+0000",
6  "current_period_end_at": "2022-02-05T10:15:30+0000",
7  "current_period_start_at": "2022-01-05T10:15:30+0000",
8  "customer_id": "cus_ps8e0ZgQzd2QnCxVpzJrHD6KOVu",
9  "id": "sub_hkpdkcmxdgazzq53jbk",
10  "latest_invoice_id": "inv_hkpdmiq8hgb00f8cpdl",
11  "metadata": {
12    "foo": "bar"
13  },
14  "next_billing_at": "2022-02-05T10:15:30+0000",
15  "payment_consent_id": "cst_u79lnfufjxxfdc0",
16  "recurring": {
17    "period": 1,
18    "period_unit": "MONTH"
19  },
20  "remaining_billing_cycles": 12,
21  "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
22  "status": "ACTIVE",
23  "total_billing_cycles": 12,
24  "trial_end_at": "2022-01-05T10:15:30+0000",
25  "trial_start_at": "2022-01-01T10:15:30+0000",
26  "updated_at": "2022-01-01T10:15:30+0000"
27}

Was this section helpful?

Update a subscription

POST /api/v1/billing/subscriptions/{id}/update

Copy for LLMView as Markdown

Update an existing Subscription.

Parameters

idrequiredstring

Unique identifier of the Subscription object.

Request body

request_idrequiredstring

Unique request identifier specified by the merchant.

billing_actionstring

Specifies how to handle billing when updating the subscription. One of

DEFER_CHARGE_AND_KEEP_CYCLE: Prorated 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_CYCLE: A 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_CYCLE: Resets 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.

Defaults to DEFER_CHARGE_AND_KEEP_CYCLE.

cancel_at_period_endboolean

true if the subscription is scheduled to be cancelled at the end of the current period, false otherwise.

default_proration_modestring

By default, how to handle credit and fee prorations for all Subscription Item changes. One of

ALL: credits 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.
PRORATED: calculates and applies the proration on both credit and fee for the Subscription's unused time.
NONE: does not issue any credit for the Subscription's unused time, only charges the new fee from the next billing cycle.

Defaults to PRORATED.

itemsarray

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.

items.deletedboolean

If set to true, will delete the specified subscription item.

items.discountsarray

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.

items.idstring

Unique identifier of the Subscription Item to be updated or be deleted. If not provided, a new Subscription Item will be added.

items.metadataobject

A set of string key-value pairs that you can attach to this object for storing additional information.

items.price_idstring

Unique identifier of the Price. Required when adding a new item. You can't update the price_id of the existing item.

items.proration_modestring

Specifies how to handle credit and fee prorations for the Subscription Item. This field overrides the default_proration_mode provided in the update request. One of

ALL: credits 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.
PRORATED: calculates and applies the proration on both credit and fee for the Subscription's unused time.
NONE: does not issue any credit for the Subscription's unused time, only charges the new fee from the next billing cycle.

Defaults to PRORATED.

items.quantityinteger

The quantity of the product.

metadataobject

A set of key-value pairs that you can attach to this object for storing additional information.

payment_consent_idstring

Unique identifier of the PaymentConsent to pay for the subscription at each billing period.

total_billing_cyclesinteger

The total number of billing cycles of the subscription. The subscription will continue indefinitely if total_billing_cycles is null. It only can be updated when status is IN_TRIAL, ACTIVE or UNPAID.

trial_end_atstring

The end time of the trial if applicable. Use NOW to end the trial immediately.

Response body - 200 OK

cancel_atstring

Time when the subscription is scheduled to be cancelled.

cancel_at_period_endboolean

true if the subscription is scheduled to be cancelled at the end of the current billing period, false otherwise.

cancel_requested_atstring

Time when the cancellation request was received.

created_atstring

Time when the subscription was created.

current_period_end_atstring

The end time of the current period that the subscription has been invoiced for.

current_period_start_atstring

The start time of the current period that the subscription has been invoiced for.

customer_idstring

Unique identifier of the customer who subscribes to this subscription.

idstring

Unique identifier of the Subscription object.

latest_invoice_idstring

The unique identifier of the latest invoice generated for this subscription.

metadataobject

A set of key-value pairs that you can attach to this object for storing additional information.

next_billing_atstring

Time of the next billing date.

payment_consent_idstring

Unique identifier of the PaymentConsent to pay for the subscription at each billing period.

recurringobject

The billing cycle for recurring charges.

recurring.periodinteger

The number of period units between subscription billing cycles. For example, the billing cycle is bi-monthly if period=2 and period_unit=MONTH.

recurring.period_unitstring

Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.

remaining_billing_cyclesinteger

The remaining billing cycles of the subscription.

request_idstring

Unique request identifier specified by the merchant in the last operation.

statusstring

Status of the subscription, one of IN_TRIAL, ACTIVE, UNPAID or CANCELLED.

total_billing_cyclesinteger

trial_end_atstring

The end time of the trial if applicable.

trial_start_atstring

The start time of the trial period if applicable.

updated_atstring

Time when the subscription was last updated.

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`, `invalid_status_for_operation`, `resource_not_found`(invalid `payment_consent_id`)
401	Unauthorized. Possible error codes: `unauthorized`
404	Not Found. Possible error codes: `resource_not_found`
500	Server Error. Possible error codes: `internal_error`

POST /api/v1/billing/subscriptions/{id}/update

$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/billing/subscriptions/subscription_id/update' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "cancel_at_period_end": false,
>  "metadata": {
>    "foo": "bar"
>  },
>  "payment_consent_id": "cst_u79lnfufjxxfdc0",
>  "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
>  "total_billing_cycles": 12,
>  "trial_end_at": "2022-05-20T13:14:00+0000",
>  "items": [
>    {
>      "id": "sit_hkpdwesy9gazzrtqbkg",
>      "price_id": "pri_hkpd7fedfgb004apkvs",
>      "quantity": 2,
>      "metadata": {
>        "foo": "bar"
>      },
>      "discounts": [],
>      "deleted": false,
>      "proration_mode": "PRORATED"
>    }
>  ],
>  "billing_action": "DEFER_CHARGE_AND_KEEP_CYCLE",
>  "default_proration_mode": "PRORATED"
>}'

Response (200 OK)

1{
2  "cancel_at": "null",
3  "cancel_at_period_end": false,
4  "cancel_requested_at": "null",
5  "created_at": "2022-01-01T10:15:30+0000",
6  "current_period_end_at": "2022-02-05T10:15:30+0000",
7  "current_period_start_at": "2022-01-05T10:15:30+0000",
8  "customer_id": "cus_ps8e0ZgQzd2QnCxVpzJrHD6KOVu",
9  "id": "sub_hkpdkcmxdgazzq53jbk",
10  "latest_invoice_id": "inv_hkpdmiq8hgb00f8cpdl",
11  "metadata": {
12    "foo": "bar"
13  },
14  "next_billing_at": "2022-02-05T10:15:30+0000",
15  "payment_consent_id": "cst_u79lnfufjxxfdc0",
16  "recurring": {
17    "period": 1,
18    "period_unit": "MONTH"
19  },
20  "remaining_billing_cycles": 12,
21  "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
22  "status": "ACTIVE",
23  "total_billing_cycles": 12,
24  "trial_end_at": "2022-01-05T10:15:30+0000",
25  "trial_start_at": "2022-01-01T10:15:30+0000",
26  "updated_at": "2022-01-01T10:15:30+0000"
27}

Was this section helpful?

Cancel a subscription

POST /api/v1/billing/subscriptions/{id}/cancel

Copy for LLMView as Markdown

Cancels a customer's Subscription immediately, and provides a refund for any pending prorations.

Parameters

idrequiredstring

Unique identifier of the Subscription object.

Request body

proration_behaviorrequiredstring

Determines how to handle prorations when canceling the Subscription. One of ALL, PRORATED, NONE.
Passing ALL will refund the charge of the current period.
Passing PRORATED will refund the proration.
Passing NONE won't refund for the Subscription's unused time.

request_idrequiredstring

Unique request identifier specified by the merchant.

Response body - 200 OK

cancel_atstring

Time when the subscription is scheduled to be cancelled.

cancel_at_period_endboolean

true if the subscription is scheduled to be cancelled at the end of the current billing period, false otherwise.

cancel_requested_atstring

Time when the cancellation request was received.

created_atstring

Time when the subscription was created.

current_period_end_atstring

The end time of the current period that the subscription has been invoiced for.

current_period_start_atstring

The start time of the current period that the subscription has been invoiced for.

customer_idstring

Unique identifier of the customer who subscribes to this subscription.

idstring

Unique identifier of the Subscription object.

latest_invoice_idstring

The unique identifier of the latest invoice generated for this subscription.

metadataobject

A set of key-value pairs that you can attach to this object for storing additional information.

next_billing_atstring

Time of the next billing date.

payment_consent_idstring

Unique identifier of the PaymentConsent to pay for the subscription at each billing period.

recurringobject

The billing cycle for recurring charges.

recurring.periodinteger

The number of period units between subscription billing cycles. For example, the billing cycle is bi-monthly if period=2 and period_unit=MONTH.

recurring.period_unitstring

Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.

remaining_billing_cyclesinteger

The remaining billing cycles of the subscription.

request_idstring

Unique request identifier specified by the merchant in the last operation.

statusstring

Status of the subscription, one of IN_TRIAL, ACTIVE, UNPAID or CANCELLED.

total_billing_cyclesinteger

trial_end_atstring

The end time of the trial if applicable.

trial_start_atstring

The start time of the trial period if applicable.

updated_atstring

Time when the subscription was last updated.

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`, `invalid_status_for_operation`
401	Unauthorized. Possible error codes: `unauthorized`
404	Not Found. Possible error codes: `resource_not_found`
500	Server Error. Possible error codes: `internal_error`

POST /api/v1/billing/subscriptions/{id}/cancel

$curl --request POST \
>  --url 'https://api-demo.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"
>}'

Response (200 OK)

1{
2  "cancel_at": "null",
3  "cancel_at_period_end": false,
4  "cancel_requested_at": "null",
5  "created_at": "2022-01-01T10:15:30+0000",
6  "current_period_end_at": "2022-02-05T10:15:30+0000",
7  "current_period_start_at": "2022-01-05T10:15:30+0000",
8  "customer_id": "cus_ps8e0ZgQzd2QnCxVpzJrHD6KOVu",
9  "id": "sub_hkpdkcmxdgazzq53jbk",
10  "latest_invoice_id": "inv_hkpdmiq8hgb00f8cpdl",
11  "metadata": {
12    "foo": "bar"
13  },
14  "next_billing_at": "2022-02-05T10:15:30+0000",
15  "payment_consent_id": "cst_u79lnfufjxxfdc0",
16  "recurring": {
17    "period": 1,
18    "period_unit": "MONTH"
19  },
20  "remaining_billing_cycles": 12,
21  "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
22  "status": "ACTIVE",
23  "total_billing_cycles": 12,
24  "trial_end_at": "2022-01-05T10:15:30+0000",
25  "trial_start_at": "2022-01-01T10:15:30+0000",
26  "updated_at": "2022-01-01T10:15:30+0000"
27}

Was this section helpful?

Get list of subscriptions

GET /api/v1/billing/subscriptions

Copy for LLMView as Markdown

Retrieves a list of Subscriptions based on the query parameters.

Parameters

customer_idstring

Unique identifier of the customer who subscribes to this subscription.

from_created_atstring

The start date of created_at in ISO8601 format (inclusive).

page_numinteger

Page number starting from 0. Defaults to 0.

page_sizeinteger

Number of Subscriptions per page. Defaults to 20.

recurring_periodinteger

The number of period units between subscription billing cycles. For example, the billing cycle is bi-monthly if period=2 and period_unit=MONTH.

recurring_period_unitstring

Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.

statusstring

Status of the subscription, one of IN_TRIAL, ACTIVE, UNPAID or CANCELLED.

to_created_atstring

The end date of created_at in ISO8601 format (exclusive).

Response body - 200 OK

has_moreboolean

A flag which identifies whether there are more results.

itemsarray

Paged results.

items.cancel_atstring

Time when the subscription is scheduled to be cancelled.

items.cancel_at_period_endboolean

true if the subscription is scheduled to be cancelled at the end of the current billing period, false otherwise.

items.cancel_requested_atstring

Time when the cancellation request was received.

items.created_atstring

Time when the subscription was created.

items.current_period_end_atstring

The end time of the current period that the subscription has been invoiced for.

items.current_period_start_atstring

The start time of the current period that the subscription has been invoiced for.

items.customer_idstring

Unique identifier of the customer who subscribes to this subscription.

items.idstring

Unique identifier of the Subscription object.

items.latest_invoice_idstring

The unique identifier of the latest invoice generated for this subscription.

items.metadataobject

A set of key-value pairs that you can attach to this object for storing additional information.

items.next_billing_atstring

Time of the next billing date.

items.payment_consent_idstring

Unique identifier of the PaymentConsent to pay for the subscription at each billing period.

items.recurringobject

The billing cycle for recurring charges.

items.recurring.periodinteger

The number of period units between subscription billing cycles. For example, the billing cycle is bi-monthly if period=2 and period_unit=MONTH.

items.recurring.period_unitstring

Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.

items.remaining_billing_cyclesinteger

The remaining billing cycles of the subscription.

items.request_idstring

Unique request identifier specified by the merchant in the last operation.

items.statusstring

Status of the subscription, one of IN_TRIAL, ACTIVE, UNPAID or CANCELLED.

items.total_billing_cyclesinteger

items.trial_end_atstring

The end time of the trial if applicable.

items.trial_start_atstring

The start time of the trial period if applicable.

items.updated_atstring

Time when the subscription was last updated.

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`
401	Unauthorized. Possible error codes: `unauthorized`
500	Server Error. Possible error codes: `internal_error`

GET /api/v1/billing/subscriptions

$curl --request GET \
>  --url 'https://api-demo.airwallex.com/api/v1/billing/subscriptions' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Response (200 OK)

1{
2  "has_more": false,
3  "items": [
4    {
5      "cancel_at": "null",
6      "cancel_at_period_end": false,
7      "cancel_requested_at": "null",
8      "created_at": "2022-01-01T10:15:30+0000",
9      "current_period_end_at": "2022-02-05T10:15:30+0000",
10      "current_period_start_at": "2022-01-05T10:15:30+0000",
11      "customer_id": "cus_ps8e0ZgQzd2QnCxVpzJrHD6KOVu",
12      "id": "sub_hkpdkcmxdgazzq53jbk",
13      "latest_invoice_id": "inv_hkpdmiq8hgb00f8cpdl",
14      "metadata": {
15        "foo": "bar"
16      },
17      "next_billing_at": "2022-02-05T10:15:30+0000",
18      "payment_consent_id": "cst_u79lnfufjxxfdc0",
19      "recurring": {
20        "period": 1,
21        "period_unit": "MONTH"
22      },
23      "remaining_billing_cycles": 12,
24      "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
25      "status": "ACTIVE",
26      "total_billing_cycles": 12,
27      "trial_end_at": "2022-01-05T10:15:30+0000",
28      "trial_start_at": "2022-01-01T10:15:30+0000",
29      "updated_at": "2022-01-01T10:15:30+0000"
30    }
31  ]
32}

Was this section helpful?

Retrieve a SubscriptionItem

GET /api/v1/billing/subscriptions/{id}/items/{item_id}

Copy for LLMView as Markdown

Retrieves the details of a SubscriptionItem.

Parameters

idrequiredstring

Unique identifier of the Subscription object that this subscription item belongs to.

item_idrequiredstring

Unique identifier of the SubscriptionItem object.

Response body - 200 OK

idstring

Unique identifier of the SubscriptionItem object.

metadataobject

A set of key-value pairs that you can attach to this object for storing additional information.

priceobject

The price on a subscription item.

price.activeboolean

true if the price is available for new purchases, false otherwise.

price.currencystring

Currency of the price (in 3-letter ISO-4217 format).

price.descriptionstring

Price description.

price.flat_amountnumber

The fixed amount to be charged. Applicable for flat pricing model only.

price.idstring

Unique identifier of the Price object.

price.metadataobject

A set of key-value pairs that you can attach to this object for storing additional information.

price.namestring

Price name.

price.pricing_modelstring

Specify how to calculate the total billing amount when a quantity is provided.

flat: a fixed price.
per_unit: a fixed price per unit quantity.
volume: the unit price is taken based on which tier the total quantity falls in.
tiered: the unit price changes as the quantity grows.

price.product_idstring

Unique identifier of the Product object this price is associated with.

price.recurringobject

The billing cycle for recurring charges. Exists when type=RECURRING.

price.recurring.periodinteger

The number of period units between subscription billing cycles. For example, the billing cycle is bi-monthly if period=2 and period_unit=MONTH.

price.recurring.period_unitstring

Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.

price.request_idstring

Unique request identifier specified by the merchant in the last operation.

price.tiersarray

List of quantity-based pricing tiers for this price. Applicable for volume and tiered pricing models.

price.tiers.amountnumber

The per-unit amount to be charged for this tier when the pricing model is volume or tiered.

price.tiers.flat_amountnumber

The fixed amount to be charged for this tier when the pricing model is volume or tiered.

price.tiers.upper_boundnumber

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.

price.typestring

The type of the Price. Use ONE_OFF for one-off purchases and RECURRING for recurring purchases (subscriptions).

price.unit_amountnumber

The amount to be charged per product unit. Applicable for per_unit pricing model only.

quantitynumber

The product quantity.

subscription_idstring

Unique identifier of the Subscription object that this subscription item belongs to.

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`
401	Unauthorized. Possible error codes: `unauthorized`
404	Not Found. Possible error codes: `resource_not_found`
500	Server Error. Possible error codes: `internal_error`

GET /api/v1/billing/subscriptions/{id}/items/{item_id}

$curl --request GET \
>  --url 'https://api-demo.airwallex.com/api/v1/billing/subscriptions/subscription_id/items/item_id' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Response (200 OK)

1{
2  "id": "sit_hkpdwesy9gazzrtqbkg",
3  "metadata": {
4    "foo": "bar"
5  },
6  "price": {
7    "active": true,
8    "currency": "USD",
9    "description": "Standard option: $10 / month.",
10    "flat_amount": "null",
11    "id": "pri_hkpd7fedfgb004apkvs",
12    "metadata": {
13      "foo": "bar"
14    },
15    "name": "Standard option",
16    "pricing_model": "tiered",
17    "product_id": "prd_hkpd1x2gbgazzvcd42w",
18    "recurring": {
19      "period": 1,
20      "period_unit": "MONTH"
21    },
22    "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
23    "tiers": [
24      {
25        "amount": 10,
26        "upper_bound": 20
27      },
28      {
29        "amount": 20
30      }
31    ],
32    "type": "RECURRING",
33    "unit_amount": "null"
34  },
35  "quantity": 2,
36  "subscription_id": "sub_hkpdkcmxdgazzq53jbk"
37}

Was this section helpful?

Get list of SubscriptionItems

GET /api/v1/billing/subscriptions/{id}/items

Copy for LLMView as Markdown

Retrieves a list of SubscriptionItems based on the query parameters.

Parameters

idrequiredstring

Unique identifier of the Subscription object that the subscription items belong to.

page_numinteger

Page number starting from 0. Defaults to 0.

page_sizeinteger

Number of SubscriptionItems per page. Defaults to 20.

Response body - 200 OK

has_moreboolean

A flag which identifies whether there are more results.

itemsarray

Paged results.

items.idstring

Unique identifier of the SubscriptionItem object.

items.metadataobject

A set of key-value pairs that you can attach to this object for storing additional information.

items.priceobject

The price on a subscription item.

items.price.activeboolean

true if the price is available for new purchases, false otherwise.

items.price.currencystring

Currency of the price (in 3-letter ISO-4217 format).

items.price.descriptionstring

Price description.

items.price.flat_amountnumber

The fixed amount to be charged. Applicable for flat pricing model only.

items.price.idstring

Unique identifier of the Price object.

items.price.metadataobject

A set of key-value pairs that you can attach to this object for storing additional information.

items.price.namestring

Price name.

items.price.pricing_modelstring

Specify how to calculate the total billing amount when a quantity is provided.

flat: a fixed price.
per_unit: a fixed price per unit quantity.
volume: the unit price is taken based on which tier the total quantity falls in.
tiered: the unit price changes as the quantity grows.

items.price.product_idstring

Unique identifier of the Product object this price is associated with.

items.price.recurringobject

The billing cycle for recurring charges. Exists when type=RECURRING.

items.price.recurring.periodinteger

The number of period units between subscription billing cycles. For example, the billing cycle is bi-monthly if period=2 and period_unit=MONTH.

items.price.recurring.period_unitstring

Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.

items.price.request_idstring

Unique request identifier specified by the merchant in the last operation.

items.price.tiersarray

List of quantity-based pricing tiers for this price. Applicable for volume and tiered pricing models.

items.price.tiers.amountnumber

The per-unit amount to be charged for this tier when the pricing model is volume or tiered.

items.price.tiers.flat_amountnumber

The fixed amount to be charged for this tier when the pricing model is volume or tiered.

items.price.tiers.upper_boundnumber

items.price.typestring

The type of the Price. Use ONE_OFF for one-off purchases and RECURRING for recurring purchases (subscriptions).

items.price.unit_amountnumber

The amount to be charged per product unit. Applicable for per_unit pricing model only.

items.quantitynumber

The product quantity.

items.subscription_idstring

Unique identifier of the Subscription object that this subscription item belongs to.

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`
401	Unauthorized. Possible error codes: `unauthorized`
500	Server Error. Possible error codes: `internal_error`

GET /api/v1/billing/subscriptions/{id}/items

$curl --request GET \
>  --url 'https://api-demo.airwallex.com/api/v1/billing/subscriptions/subscription_id/items' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Response (200 OK)

1{
2  "has_more": false,
3  "items": [
4    {
5      "id": "sit_hkpdwesy9gazzrtqbkg",
6      "metadata": {
7        "foo": "bar"
8      },
9      "price": {
10        "active": true,
11        "currency": "USD",
12        "description": "Standard option: $10 / month.",
13        "flat_amount": "null",
14        "id": "pri_hkpd7fedfgb004apkvs",
15        "metadata": {
16          "foo": "bar"
17        },
18        "name": "Standard option",
19        "pricing_model": "tiered",
20        "product_id": "prd_hkpd1x2gbgazzvcd42w",
21        "recurring": {
22          "period": 1,
23          "period_unit": "MONTH"
24        },
25        "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
26        "tiers": [
27          {
28            "amount": 10,
29            "upper_bound": 20
30          },
31          {
32            "amount": 20
33          }
34        ],
35        "type": "RECURRING",
36        "unit_amount": "null"
37      },
38      "quantity": 2,
39      "subscription_id": "sub_hkpdkcmxdgazzq53jbk"
40    }
41  ]
42}

Was this section helpful?