Coupons

Coupon management APIs for creating and managing coupon templates

Endpoints

POST /api/v1/coupons/create
POST /api/v1/coupons/{id}/update
GET /api/v1/coupons/{id}
GET /api/v1/coupons

Create a coupon

POST /api/v1/coupons/create

Copy for LLMView as Markdown

Creates a new coupon template that can be redeemed in purchases.

Request body

amount_offnumber

The fixed amount to deduct when discount_model is FLAT.

currencystring

The currency of amount_off when discount_model is FLAT.

descriptionstring

Description of the coupon providing business context.

discount_modelrequiredstring

Specified how to calculate the discount amount when applied, one of

FLAT: fixed amount off.
PERCENTAGE: percentage off.

durationobject

The duration of the coupon to apply, when duration_typeis CUSTOM. null if duration_type is ONCE or INDEFINITELY.

duration.periodrequiredinteger

The number of period_unit.

duration.period_unitrequiredstring

Specifies duration. One of DAY, WEEK, MONTH, YEAR

duration_typerequiredstring

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.

expires_atstring

Time after which the coupon can no longer be redeemed.

metadataobject

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

namerequiredstring

Name of the coupon.

percentage_offnumber

The percentage between 0 to 100 to be applied to deduct when discount_model is PERCENTAGE.

request_idrequiredstring

Unique request ID specified by the merchant.

Response body - 201 Created

activeboolean

true if the coupon is available to be applied to objects. false otherwise.

amount_offnumber

The fixed amount to deduct when discount_model is FLAT.

created_atstring

Time when the coupon was created.

currencystring

The currency of amount_off when discount_model is FLAT.

descriptionstring

Description of the coupon providing business context.

discount_modelstring

Specified how to calculate the discount amount when applied, one of

FLAT: fixed amount off.
PERCENTAGE: percentage off.

durationobject

The duration of the coupon to apply, when duration_typeis CUSTOM. null if duration_type is ONCE or INDEFINITELY.

duration.periodinteger

The number of period units.

duration.period_unitstring

Specifies duration. One of DAY, WEEK, MONTH, YEAR

duration_typestring

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.

expires_atstring

Time after which the coupon can no longer be redeemed.

idstring

ID of the Coupon object.

metadataobject

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

namestring

Name of the coupon.

percentage_offnumber

The percentage between 0 to 100 to be applied to deduct when discount_model is PERCENTAGE.

times_redeemedinteger

The number of times this coupon has been redeemed.

updated_atstring

Time when the coupon was updated.

Errors

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

POST /api/v1/coupons/create

$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/coupons/create' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "amount_off": 10,
>  "currency": "USD",
>  "description": "20% off for Black Friday",
>  "discount_model": "PERCENTAGE",
>  "duration": {
>    "period": 3,
>    "period_unit": "MONTH"
>  },
>  "duration_type": "CUSTOM",
>  "expires_at": "2026-12-31T23:59:59+0000",
>  "metadata": {
>    "campaign": "bf-2026"
>  },
>  "name": "Black Friday 20% Off",
>  "percentage_off": 20,
>  "request_id": "ee939540-3203-4a2c-9172-89a566485dd9"
>}'

Response (201 Created)

1{
2  "active": true,
3  "amount_off": 10,
4  "created_at": "<date-time>",
5  "currency": "USD",
6  "description": "20% off for Black Friday",
7  "discount_model": "PERCENTAGE",
8  "duration": {
9    "period": 3,
10    "period_unit": "MONTH"
11  },
12  "duration_type": "CUSTOM",
13  "expires_at": "2026-12-31T23:59:59+0000",
14  "id": "coup_abc123",
15  "metadata": {
16    "campaign": "bf-2026"
17  },
18  "name": "Black Friday 20% Off",
19  "percentage_off": 20,
20  "times_redeemed": 0,
21  "updated_at": "<date-time>"
22}

Was this section helpful?

Update a coupon

POST /api/v1/coupons/{id}/update

Copy for LLMView as Markdown

Updates a coupon. Before first redemption, all fields can be adjusted; after redemption, only non-billing fields (name, description, expires_at, metadata) can be updated to maintain contractual integrity.

Parameters

idrequiredstring

ID of the Coupon object.

Request body

activeboolean

Whether the coupon is active and can be redeemed. Set to false to deactivate the coupon.

amount_offnumber

The fixed amount to deduct when discount_model is FLAT. This field cannot be updated once the coupon has been redeemed.

currencystring

The currency of amount_off when discount_model is FLAT. This field cannot be updated once the coupon has been redeemed.

descriptionstring

Description of the coupon providing business context.

discount_modelstring

Specified how to calculate the discount amount when applied, one of

FLAT: fixed amount off.
PERCENTAGE: percentage off. This field cannot be updated once the coupon has been redeemed.

durationobject

The duration of the coupon to apply, when duration_typeis CUSTOM. null if duration_type is ONCE or INDEFINITELY. This field cannot be updated once the coupon has been redeemed.

duration.periodrequiredinteger

The number of period_unit.

duration.period_unitrequiredstring

Specifies duration. One of DAY, WEEK, MONTH, YEAR

duration_typestring

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. This field cannot be updated once the coupon has been redeemed.

expires_atstring

Time after which the coupon can no longer be redeemed.

metadataobject

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

namestring

Name of the coupon.

percentage_offnumber

The percentage to deduct when discount_model is PERCENTAGE. This field cannot be updated once the coupon has been redeemed.

Response body - 200 OK

activeboolean

true if the coupon is available to be applied to objects. false otherwise.

amount_offnumber

The fixed amount to deduct when discount_model is FLAT.

created_atstring

Time when the coupon was created.

currencystring

The currency of amount_off when discount_model is FLAT.

descriptionstring

Description of the coupon providing business context.

discount_modelstring

Specified how to calculate the discount amount when applied, one of

FLAT: fixed amount off.
PERCENTAGE: percentage off.

durationobject

The duration of the coupon to apply, when duration_typeis CUSTOM. null if duration_type is ONCE or INDEFINITELY.

duration.periodinteger

The number of period units.

duration.period_unitstring

Specifies duration. One of DAY, WEEK, MONTH, YEAR

duration_typestring

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.

expires_atstring

Time after which the coupon can no longer be redeemed.

idstring

ID of the Coupon object.

metadataobject

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

namestring

Name of the coupon.

percentage_offnumber

The percentage between 0 to 100 to be applied to deduct when discount_model is PERCENTAGE.

times_redeemedinteger

The number of times this coupon has been redeemed.

updated_atstring

Time when the coupon was updated.

Errors

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

POST /api/v1/coupons/{id}/update

$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/coupons/coupon_id/update' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "active": true,
>  "amount_off": 10,
>  "currency": "USD",
>  "description": "20% off for Black Friday",
>  "discount_model": "PERCENTAGE",
>  "duration": {
>    "period": 3,
>    "period_unit": "MONTH"
>  },
>  "duration_type": "ONCE",
>  "expires_at": "2026-12-31T23:59:59+0000",
>  "metadata": {
>    "campaign": "bf-2026"
>  },
>  "name": "Once Black Friday 20% Off",
>  "percentage_off": 20
>}'

Response (200 OK)

1{
2  "active": true,
3  "amount_off": 10,
4  "created_at": "<date-time>",
5  "currency": "USD",
6  "description": "20% off for Black Friday",
7  "discount_model": "PERCENTAGE",
8  "duration": {
9    "period": 3,
10    "period_unit": "MONTH"
11  },
12  "duration_type": "CUSTOM",
13  "expires_at": "2026-12-31T23:59:59+0000",
14  "id": "coup_abc123",
15  "metadata": {
16    "campaign": "bf-2026"
17  },
18  "name": "Black Friday 20% Off",
19  "percentage_off": 20,
20  "times_redeemed": 0,
21  "updated_at": "<date-time>"
22}

Was this section helpful?

Retrieve a coupon

GET /api/v1/coupons/{id}

Copy for LLMView as Markdown

Retrieves the coupon details by the ID.

Parameters

idrequiredstring

ID of the Coupon object.

Response body - 200 OK

activeboolean

true if the coupon is available to be applied to objects. false otherwise.

amount_offnumber

The fixed amount to deduct when discount_model is FLAT.

created_atstring

Time when the coupon was created.

currencystring

The currency of amount_off when discount_model is FLAT.

descriptionstring

Description of the coupon providing business context.

discount_modelstring

Specified how to calculate the discount amount when applied, one of

FLAT: fixed amount off.
PERCENTAGE: percentage off.

durationobject

The duration of the coupon to apply, when duration_typeis CUSTOM. null if duration_type is ONCE or INDEFINITELY.

duration.periodinteger

The number of period units.

duration.period_unitstring

Specifies duration. One of DAY, WEEK, MONTH, YEAR

duration_typestring

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.

expires_atstring

Time after which the coupon can no longer be redeemed.

idstring

ID of the Coupon object.

metadataobject

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

namestring

Name of the coupon.

percentage_offnumber

The percentage between 0 to 100 to be applied to deduct when discount_model is PERCENTAGE.

times_redeemedinteger

The number of times this coupon has been redeemed.

updated_atstring

Time when the coupon was 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/coupons/{id}

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

Response (200 OK)

1{
2  "active": true,
3  "amount_off": 10,
4  "created_at": "<date-time>",
5  "currency": "USD",
6  "description": "20% off for Black Friday",
7  "discount_model": "PERCENTAGE",
8  "duration": {
9    "period": 3,
10    "period_unit": "MONTH"
11  },
12  "duration_type": "CUSTOM",
13  "expires_at": "2026-12-31T23:59:59+0000",
14  "id": "coup_abc123",
15  "metadata": {
16    "campaign": "bf-2026"
17  },
18  "name": "Black Friday 20% Off",
19  "percentage_off": 20,
20  "times_redeemed": 0,
21  "updated_at": "<date-time>"
22}

Was this section helpful?

Get list of coupons

GET /api/v1/coupons

Copy for LLMView as Markdown

Get a list of coupons.

Parameters

discount_modelstring

Specified how to calculate the discount amount when applied, one of

FLAT: fixed amount off.
PERCENTAGE: percentage off.

activeboolean

true if the coupon is available to be applied to objects. false otherwise.

duration_typestring

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.

from_expires_atstring

The start time of expires_at in ISO8601 format (inclusive).

to_expires_atstring

The end time of expires_at in ISO8601 format (exclusive).

from_created_atstring

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

to_created_atstring

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

pagestring

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.

page_sizeinteger

Number of results per page. Defaults to 20.

Response body - 200 OK

itemsarray

Paged results.

items.activeboolean

true if the coupon is available to be applied to objects. false otherwise.

items.amount_offnumber

The fixed amount to deduct when discount_model is FLAT.

items.created_atstring

Time when the coupon was created.

items.currencystring

The currency of amount_off when discount_model is FLAT.

items.descriptionstring

Description of the coupon providing business context.

items.discount_modelstring

Specified how to calculate the discount amount when applied, one of

FLAT: fixed amount off.
PERCENTAGE: percentage off.

items.durationobject

The duration of the coupon to apply, when duration_typeis CUSTOM. null if duration_type is ONCE or INDEFINITELY.

items.duration.periodinteger

The number of period units.

items.duration.period_unitstring

Specifies duration. One of DAY, WEEK, MONTH, YEAR

items.duration_typestring

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.

items.expires_atstring

Time after which the coupon can no longer be redeemed.

items.idstring

ID of the Coupon object.

items.metadataobject

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

items.namestring

Name of the coupon.

items.percentage_offnumber

The percentage between 0 to 100 to be applied to deduct when discount_model is PERCENTAGE.

items.times_redeemedinteger

The number of times this coupon has been redeemed.

items.updated_atstring

Time when the coupon was updated.

page_afterstring

The page cursor used for searching after page.

page_beforestring

The page cursor used for search before page.

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/coupons

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

Response (200 OK)

1{
2  "items": [
3    {
4      "active": true,
5      "amount_off": 10,
6      "currency": "USD",
7      "description": "20% off for Black Friday",
8      "discount_model": "PERCENTAGE",
9      "duration": {
10        "period": 3,
11        "period_unit": "MONTH"
12      },
13      "duration_type": "CUSTOM",
14      "expires_at": "2026-12-31T23:59:59+0000",
15      "id": "coup_abc123",
16      "metadata": {
17        "campaign": "bf-2026"
18      },
19      "name": "Black Friday 20% Off",
20      "percentage_off": 20,
21      "times_redeemed": 0
22    }
23  ],
24  "page_after": "<string>",
25  "page_before": "<string>"
26}

Was this section helpful?