Prices

Prices define the unit cost, currency, and billing cycle (optional) for Product. Each price is associated with a product and a product can have multiple pricing options. A price supports either one-off or recurring purchases. For example, you can offer the following pricing options for a software license Product:

Standard option: $10 / month
Student discount option: $5 / month
Lifetime option: $200 one-off purchase

Prices are primarily used in Invoice and Subscription APIs.

Endpoints

POST /api/v1/billing/prices/create
GET /api/v1/billing/prices/{id}
POST /api/v1/billing/prices/{id}/update
GET /api/v1/billing/prices

Create a price

POST /api/v1/billing/prices/create

Copy for LLMView as Markdown

Create a new Price object.

Request body

currencyrequiredstring

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

product_idrequiredstring

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

request_idrequiredstring

Unique request identifier specified by the merchant.

activeboolean

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

descriptionstring

Price description.

flat_amountnumber

The fixed amount to be charged. Required when the pricing model is flat.

metadataobject

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

namestring

Price name.

pricing_modelstring

Specify how to calculate the total billing amount when a quantity is provided. One of per_unit, volume, tiered, or flat. Defaults to per_unit.

recurringobject

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. Defaults to 1.

tiersarray

List of quantity-based pricing tiers for this price. Required when the pricing model is volume or tiered.

tiers.amountrequirednumber

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

tiers.flat_amountnumber

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

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.

unit_amountnumber

The amount to be charged per product unit. Required when the pricing model is per_unit.

Response body - 201 Created

activeboolean

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

currencystring

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

descriptionstring

Price description.

flat_amountnumber

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

idstring

Unique identifier of the Price object.

metadataobject

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

namestring

Price name.

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.

product_idstring

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

recurringobject

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

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.

request_idstring

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

tiersarray

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

tiers.amountnumber

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

tiers.flat_amountnumber

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

tiers.upper_boundnumber

typestring

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

unit_amountnumber

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

Errors

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

POST /api/v1/billing/prices/create

$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/billing/prices/create' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "active": true,
>  "currency": "USD",
>  "description": "Standard option: $10 / month.",
>  "flat_amount": "null",
>  "metadata": {
>    "foo": "bar"
>  },
>  "name": "Standard option",
>  "pricing_model": "tiered",
>  "product_id": "prd_hkpd1x2gbgazzvcd42w",
>  "recurring": {
>    "period": 1,
>    "period_unit": "MONTH"
>  },
>  "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
>  "tiers": [
>    {
>      "amount": 10,
>      "upper_bound": 20
>    },
>    {
>      "amount": 20
>    }
>  ],
>  "unit_amount": "null"
>}'

Response (201 Created)

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

Was this section helpful?

Retrieve a price

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

Copy for LLMView as Markdown

Retrieves the details of a Price object by the unique identifier.

Parameters

idrequiredstring

Unique identifier of the Price object.

Response body - 200 OK

activeboolean

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

currencystring

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

descriptionstring

Price description.

flat_amountnumber

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

idstring

Unique identifier of the Price object.

metadataobject

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

namestring

Price name.

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.

product_idstring

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

recurringobject

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

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.

request_idstring

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

tiersarray

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

tiers.amountnumber

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

tiers.flat_amountnumber

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

tiers.upper_boundnumber

typestring

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

unit_amountnumber

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

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/prices/{id}

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

Response (200 OK)

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

Was this section helpful?

Update a price

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

Copy for LLMView as Markdown

Updates the attributes of an existing Price by setting the values of the request parameters. Any parameters not provided will be left unchanged.

Parameters

idrequiredstring

Unique identifier of the Price object.

Request body

request_idrequiredstring

Unique request identifier specified by the merchant.

activeboolean

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

descriptionstring

Price description.

metadataobject

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

namestring

Price name.

Response body - 200 OK

activeboolean

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

currencystring

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

descriptionstring

Price description.

flat_amountnumber

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

idstring

Unique identifier of the Price object.

metadataobject

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

namestring

Price name.

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.

product_idstring

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

recurringobject

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

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.

request_idstring

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

tiersarray

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

tiers.amountnumber

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

tiers.flat_amountnumber

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

tiers.upper_boundnumber

typestring

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

unit_amountnumber

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

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`

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

$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/billing/prices/price_id/update' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "active": true,
>  "description": "Standard option: $10 / month.",
>  "metadata": {
>    "foo": "bar"
>  },
>  "name": "Standard option",
>  "request_id": "ee939540-3203-4a2c-9172-89a566485dd9"
>}'

Response (200 OK)

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

Was this section helpful?

Get list of prices

GET /api/v1/billing/prices

Copy for LLMView as Markdown

Retrieve a list of Prices based on the query parameters.

Parameters

activeboolean

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

currencystring

The currency of Price (in 3-letter ISO-4217 format).

page_numinteger

Page number starting from 0. Defaults to 0.

page_sizeinteger

Number of Prices to be listed per page. Defaults to 20.

product_idstring

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

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. Either DAY, WEEK, MONTH or YEAR.

Response body - 200 OK

has_moreboolean

A flag which identifies whether there are more results.

itemsarray

Paged results.

items.activeboolean

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

items.currencystring

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

items.descriptionstring

Price description.

items.flat_amountnumber

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

items.idstring

Unique identifier of the Price object.

items.metadataobject

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

items.namestring

Price name.

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

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

items.recurringobject

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

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

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

items.tiersarray

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

items.tiers.amountnumber

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

items.tiers.flat_amountnumber

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

items.tiers.upper_boundnumber

items.typestring

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

items.unit_amountnumber

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

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

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

Response (200 OK)

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

Was this section helpful?