Coupons via API

Copy for LLMView as Markdown

This tutorial will guide you through creating and managing coupons via Billing APIs and applying them to downstream resources such as Subscriptions, Invoices, and Billing Checkout.

Create a Coupon

Call Create a Coupon API to define a reusable discount template that can be applied to a purchase and redeemed for a Discount. Key fields to set:

name: Customer facing name of the coupon, displayed on invoices and checkout pages.
discount_model: Determines how the discount amount is calculated. Use FLAT for a fixed amount off or PERCENTAGE for a percentage reduction.
- If FLAT: Set amount_off + currency
- If PERCENTAGE: Set percentage_off (0–100)
duration_type: ONCE, CUSTOM, or INDEFINITELY
- If CUSTOM: Set duration.period + duration.period_unit
Optional fields: expires_at, description, metadata
- expires_at: Define the last date the coupon can be redeemed.

The example code below shows how to create a "20% off for 3 months" coupon:

Shell

1curl -X POST https://api-demo.airwallex.com/api/v1/coupons/create \
2  -H 'Content-Type: application/json' \
3  -H 'Accept: application/json' \
4  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
5  -d '{
6    "request_id": "6b55c854-eb00-466d-a183-c9bfc015bc9a",
7    "name": "WELCOME 20% 3MO",
8    "discount_model": "PERCENTAGE",
9    "percentage_off": 20,
10    "duration_type": "CUSTOM",
11    "duration": {
12      "period": 3,
13      "period_unit": "MONTH"
14    },
15    "active": true,
16    "description": "20% off for first 3 billing cycles",
17    "metadata": {
18      "campaign": "q1-2026"
19    }
20  }'

The example code below shows how to create a "10 USD off" coupon that applies once:

Shell

1curl -X POST https://api-demo.airwallex.com/api/v1/coupons/create \
2  -H 'Content-Type: application/json' \
3  -H 'Accept: application/json' \
4  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
5  -d '{
6    "request_id": "6b55c854-eb00-466d-a183-c9bfc015bc91",
7    "name": "TAKE10",
8    "discount_model": "FLAT",
9    "amount_off": 10,
10    "currency": "USD",
11    "duration_type": "ONCE",
12    "active": true
13  }'

Archive a coupon

To archive a coupon and prevent new redemptions, use the Update a Coupon API and set active=false.

Shell

1curl -X POST https://api-demo.airwallex.com/api/v1/coupons/coup_abc123/update \
2  -H 'Content-Type: application/json' \
3  -H 'Accept: application/json' \
4  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
5  -d '{
6    "active": false
7  }'

Manage Coupons

After creating a coupon object you can perform the following actions:

Update coupon details using Update a Coupon API.
Retrieve a coupon's details via its ID using Retrieve a Coupon API.
Retrieve a list of coupons using Get list of Coupon API.

Once a Coupon is redeemed, it is attached to the target resource as a Discount object. Coupons can be applied to subscriptions, Subscription Items, Invoices and Invoice Line Items. In Invoice / Subscription API responses, applied_discounts provides the following detail for each discount:

Calculation logic: (discount_model, amount_off / percentage_off)
Duration: (duration_type, plus ends_at when CUSTOM)
Source: (source=COUPON, and source_id = Coupon ID)

This allows you to audit which coupon was used and how the discount was calculated.

Apply coupons to subscriptions

You can apply coupons to a subscription and its items when using the Create Subscription API.

Shell

1curl -X POST https://api-demo.airwallex.com/api/v1/subscriptions/create \
2  -H 'Content-Type: application/json' \
3  -H 'Accept: application/json' \
4  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
5  -d '{
6    "request_id": "6b55c854-eb00-466d-a183-c9bfc015bc9a",
7    "billing_customer_id": "bcus_hkpd7fedfgb004apkvs",
8    "collection_method": "AUTO_CHARGE",
9    "currency": "USD",
10    "discounts": [
11      {
12        "type": "COUPON",
13        "coupon": {
14          "id": "coup_abc123"
15        }
16      }
17    ],
18    "items": [
19      {
20        "price_id": "pri_hkpd1x2gbgazzvcd42w",
21        "quantity": 1
22      },
23      {
24        "price_id": "pri_hkpd7fedfgb004apkvs",
25        "quantity": 2,
26        "discounts": [
27          {
28            "type": "COUPON",
29            "coupon": {
30              "id": "coup_def456"
31            }
32          }
33        ]
34      }
35    ]
36  }'

The response has an applied_discounts list that describes where the discount was applied:

applied_to = SUBSCRIPTION for the subscription-level discount
applied_to = SUBSCRIPTION_ITEM for the item-level discount

When both are present, Airwallex applies subscription item discounts first, then subscription-level discounts.

Apply coupons to invoices

You can apply coupons to one-off invoices via Create an Invoice API and Update an Invoice API, or apply to invoice Line Items via Create Invoice Line Items and add them to an Invoice API or Update Invoice Line Items in an Invoice API.

Example 1: apply coupon to a one-off invoice:

Shell

1curl -X POST https://api-demo.airwallex.com/api/v1/invoices/create \
2  -H 'Content-Type: application/json' \
3  -H 'Accept: application/json' \
4  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
5  -d '{
6    "request_id": "6b55c854-eb00-466d-a183-c9bfc015bc92",
7    "billing_customer_id": "bcus_hkdmz2plrhawrfeqdth",
8    "currency": "USD",
9    "collection_method": "CHARGE_ON_CHECKOUT",
10    "discounts": [
11      {
12        "type": "COUPON",
13        "coupon": {
14          "id": "coup_hkdmfsd9mhax0kg5"
15        }
16      }
17    ],
18    "legal_entity_id": "le_98rJYVupN7e9miV36aZ_BQ",
19    "linked_payment_account_id": "acct_44Y0oX8lMbCe7cLe_QoAXQ"
20  }'

Example 2: Apply coupon to invoice line items:

Shell

1curl -X POST https://api-demo.airwallex.com/api/v1/invoices/inv_hkpd49cskgblns6iimw/add_line_items \
2  -H 'Content-Type: application/json' \
3  -H 'Accept: application/json' \
4  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
5  -d '{
6    "line_items": [
7      {
8        "price_id": "pri_hkpd7fedfgb004apkvs",
9        "quantity": 2,
10        "discounts": [
11          {
12            "type": "COUPON",
13            "coupon": {
14              "id": "coup_hkdmfsd9mhax0kg5"
15            }
16          }
17        ]
18      }
19    ]
20  }'

The response includes an applied_discounts list that describes where the discount was applied:

applied_to = INVOICE for the invoice-level discount
applied_to = INVOICE_LINE_ITEM for the item-level discount

When both are present, Airwallex applies invoice item discounts first, then invoice-level discounts.

Apply coupons to billing checkout

Billing checkout supports applying coupons at:

checkout-level discounts (discounts)
line-item discounts (line_items[].discounts)

To do so, call the Create a Billing Checkout API.

The example code demonstrates how to create a subscription checkout with two coupons, one applied to the entire subscription, and another to a subscription item.

Shell

1curl -X POST https://api-demo.airwallex.com/api/v1/billing_checkouts/create \
2  -H 'Content-Type: application/json' \
3  -H 'Accept: application/json' \
4  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
5  -d '{
6    "request_id": "{{RANDOMUUID}}",
7    "mode": "SUBSCRIPTION",
8    "legal_entity_id": "{{LEGALENTITYID}}",
9    "linked_payment_account_id": "{{LINKEDPAYMENTACCOUNTID}}",
10    "success_url": "https://example.com/success",
11    "back_url": "https://example.com/back",
12    "line_items": [
13      {
14        "price_id": "pri_sgstsfvl4hek56rey8g",
15        "quantity": 1,
16        "discounts": [
17          {
18            "type": "COUPON",
19            "coupon": {
20              "id": "coup_sgstsfvl4helcivw9vy"
21            }
22          }
23        ]
24      }
25    ],
26    "discounts": [
27      {
28        "type": "COUPON",
29        "coupon": {
30          "id": "coup_sgstpzfmlhelcrercan"
31        }
32      }
33    ],
34    "subscription_data": {
35      "days_until_due": 0
36    }
37  }'

Pro-rata distribution

When a discount is applied to the entire invoice, subscription (applied_to=INVOICE/SUBSCRIPTION), the system distributes the discount amount across all line items based on their relative value to the subtotal. This ensures that any line-item calculations (e.g. line-item tax) reconcile with the final invoice total.

This distributed value is reflected in the discount_amount field of each invoice line-item.

Was this page helpful?