Subscriptions via API

• 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.

Use the following API resources to build and manage subscriptions.

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.

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.

Call Update a subscription API to update information for a subscription except customer, billing entity, billing currency, line items, or tax rate.

The information that can be updated will be dependent on the current status of the subscription.

• PENDING: Allows updates to starts_at, trial_ends_at, days_until_due, cancel_at_period_end, metadata, payment_source_id.
• IN_TRIAL: Allows updates to trial_ends_at.
• ACTIVE: Allows updates to: days_until_due, cancel_at_period_end, metadata, payment_source_id, invoice_memo.

Any changes you make to your subscription details will be used for all future invoices for this subscription. Any previously created invoices will not be impacted by the changes.

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 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.