Subscriptions via API

This tutorial will guide you through the steps to create and manage subscriptions via Billing APIs.

Before you begin

• Obtain your access token API by authenticating to Airwallex using your unique Client ID and API key. You will need the access token to make API calls.
• Check out Supported currencies for supported regions and currencies.
• Create the required objects. See Subscription objects.

Subscription objects

Use the following API resources to build and manage subscriptions.

Create a subscription

Call Create a subscription API with the following required fields:

• billing_customer_id: Provide the ID of the billing customer created using Create a Billing Customer API.
• collection_method: Specify how the payment for the subscription will be collected, AUTO_CHARGE, CHARGE_ON_CHECKOUT or OUT_OF_BAND. For more information on these methods, see Subscription payment collection methods.
  • If AUTO_CHARGE, you must specify linked_payment_account_id and payment_source_id fields.
  • If CHARGE_ON_CHECKOUT you must specify the linked_payment_account_id field.
• items.price_id: Provide the ID of the price object created using Create a price API. This includes all the product details associated with the subscription. You can add multiple line items with custom frequencies to a single subscription, given billing cycles are compatible.
• duration.period_unit: Specify the billing frequency for recurring charges. The recurring frequency must be the smallest frequency among all the Prices specified in the subscription items. One of DAY, WEEK, MONTH or YEAR.
• legal_entity_id: 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 one entity in your organization.

The example code shows how to create a subscription with CHARGE_ON_CHECKOUT collection method.

1curl -X POST https://api-demo.airwallex.com/api/v1/subscriptions/create \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "request_id": "fa97edc4-fb6f-430a-a0eb-a0c12d4c61af",
6    "billing_customer_id": "bcus_hkdmz2plrhawrfeqdth",
7    "collection_method": "CHARGE_ON_CHECKOUT",
8    "currency": "USD",
9    "days_until_due": 10,
10    "default_invoice_template": {
11      "invoice_memo": "Thank you for your purchase."
12    },
13    "default_tax_percent": 0,
14    "items": [
15      {
16        "price_id": "pri_hkdmfsd9mhax0vappnb",
17        "quantity": 1
18      }
19    ],
20    "duration": {
21      "period_unit": "MONTH",
22      "period": 12
23    },
24    "legal_entity_id": "le_98rJYVupN7e9miV36aZ_BQ",
25    "linked_payment_account_id": "acct_44Y0oX8lMbCe7cLe_QoAXQ"
26  }'

Free trials

Free trials are exclusive of the billing duration, meaning the total subscription duration will be the Free Trial Duration + the Billing Duration.

The start date of the trial will be the time set in starts_at, which defaults to the time when the subscription is created. Specify trial_ends_at to specify the end timestamp of the trial.

Custom tax rate

Specify a tax percentage between 0 and 100 in default_tax_percent field. This value will be applied to generated invoices. The tax will be exclusive.

Recurring subscriptions

For recurring charges, specify the frequency of the billing cycle using the following fields. The smallest frequency among all the Prices specified in the subscription items will be used.

• duration.period_unit: Specifies billing frequency. Possible values: DAY, WEEK, MONTH or YEAR.
• duration.period: Optional. The number of period units between subscription billing cycles. For example, if period_unit=MONTH and period=2 then the billing cycle is bi-monthly. Defaults to 1.

Memo

Specify the memo to be used for the invoices that are generated by the subscription using invoice_memo field.

1 "default_invoice_template": {
2    "invoice_memo": "Thanks for your purchase."
3  },

Update a subscription

Call Update a subscription API to update an existing subscription without cancelling and recreating it. You cannot update a subscription's customer, billing entity, or billing currency.

The fields you can update depend on the current status of the subscription:

• PENDING: starts_at, trial_ends_at, duration, ends_at, days_until_due, collection_method, payment_source_id, default_invoice_template.invoice_memo, metadata, items, discounts
• IN_TRIAL: trial_ends_at, duration, ends_at, days_until_due, collection_method, payment_source_id, default_invoice_template.invoice_memo, metadata, items, discounts
• ACTIVE: duration, ends_at, days_until_due, collection_method, payment_source_id, default_invoice_template.invoice_memo, metadata, items, discounts

Any changes you make apply to future billing for this subscription. Previously created invoices are not changed.

Proration behaviour for ACTIVE subscriptions

When updating an ACTIVE subscription with item changes, use default_proration_mode to control how the current billing period is handled. You can override this per item using the proration_mode field on each entry in items.

Use billing_action to control when the adjustment is applied:

The example code shows how to update an ACTIVE subscription by adding an item with immediate proration.

1curl -X POST https://api-demo.airwallex.com/api/v1/subscriptions/{id}/update \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "request_id": "c3f1a2b4-9e8d-4c7b-b5a6-d1e2f3a4b5c6",
6    "billing_action": "IMMEDIATE_CHARGE_AND_KEEP_CYCLE",
7    "default_proration_mode": "PRORATED",
8    "items": [
9      {
10        "price_id": "pri_hkdmfsd9mhax0vappnb",
11        "quantity": 2
12      }
13    ]
14  }'

Cancel a subscription

Call Cancel a subscription API using the subscription ID to permanently cancel a subscription. Once cancelled a subscription cannot be reactivated. Any pending automatic payments will be stopped for the subscription.

To determine how Airwallex must handle paid and unpaid fees for the current billing cycle of the subscription, you must set the proration_behavior field in the your cancellation request.

Pro-ration works by calculating the amount the customer would’ve owed you up until the date of the cancellation for their fees. This amount is calculated as a percentage of the total billing cycle. For example, if the price was $90 with a billing frequency of 1 month, and the subscription is cancelled on the 15th day of the month (in a month that had 30 days), the pro-rated fee for the customer would be $45 [15/30 = 0.5, and 0.5 x 90 = 45].

The options include:

• ALL: Refund the charge of the current period.
• PRORATED: Refund the proration.
• NONE: Won't refund for the subscription's unused time.

Manage subscriptions

Manage your subscriptions by providing the subscription ID as url parameter.

• Retrieve subscription details and status anytime using Retrieve a subscription API.
• Retrieve the list of subscriptions you've created using Get list of subscriptions API.

You can also retrieve subscription items by providing the subscription ID and subscription item ID as url parameters.

• Retrieve subscription item details using Retrieve a subscription item API.
• Retrieve the list of subscriptions items associated with your account using Get list of subscriptions API.