Prices
A Price defines the pricing information for a Product such as amount, currency, and billing frequency. A Product can have multiple Prices. For example, you can offer the following pricing options for a software license Product:
-
- Standard Price: $10 / month
-
- Student Price: $5 / month
-
- Lifetime Access: $200 one-off purchase
Prices are primarily used in Invoice and Subscription APIs.
POST /api/v1/billing/prices/createGET /api/v1/billing/prices/{id}POST /api/v1/billing/prices/{id}/updateGET /api/v1/billing/prices
Create a price
POST /api/v1/billing/prices/create
Create a new Price object.
Currency of the price (in 3-letter ISO-4217 format).
ID of the Product object this price is associated with.
Unique request ID specified by the merchant.
true if the price is available for new purchases, false otherwise. Defaults to true.
Indicates when should the price be billed, one of
IN_ADVANCE: billed at the beginning of the billing cycle.IN_ARREARS: billed at the end of the billing cycle.
Defaults to IN_ADVANCE.
Price description. Used for internal classification and identification.
The fixed amount to be charged. Only required when the pricing model is FLAT.
Defines how quantity is grouped into billable lots. The unit_amount is then applied per lot. If not set, quantity is treated as the number of billable lots. Only applicable for PER_UNIT price.
Specifies how to round the calculated lots when the total quantity is not an exact multiple of the size. One of UP.
The amount of quantity that constitutes a single billable lot.
A set of string key-value pairs that you can attach to this object for storing additional information.
ID of the Meter object specifying how to calculate the usage for this price.
Specify how to determine the quantity of the product used in each billing cycle for subscription payments. true if the quantity is dynamically determined during the billing cycle. The merchant should call the Ingest Usage Events API to submit usage data when the product is used. false if the quantity is determined when creating a subscription.
Specify how to calculate the total billing amount when a quantity is provided. One of
FLAT: a fixed price.PER_UNIT: a fixed price per unit quantity.VOLUME: the unit price is based on which tier the total quantity falls in.GRADUATED: the unit price changes as the quantity increases.
Defaults to PER_UNIT.
The frequency at which the price is charged. null for one-time charge.
Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.
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.
Whether the price includes tax. Defaults to false.
List of quantity-based pricing tiers for this price. Required when the pricing model is VOLUME or GRADUATED.
The flat amount to be charged for this tier when pricing model is GRADUATED, or the overall flat amount to be charged when pricing model is VOLUME.
Defines how quantity is grouped into billable lots. The unit_amount is then applied per lot. If not set, quantity is treated as the number of billable lots. Only applicable for VOLUME and GRADUATED prices.
Specifies how to round the calculated lots when the total quantity is not an exact multiple of the size. One of UP.
The amount of quantity that constitutes a single billable lot.
The per-unit amount to be charged for this tier when pricing model is GRADUATED, or the overall per-unit amount to be charged when pricing model is VOLUME.
Description of the billable unit for the tier.
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.
The amount to be charged per product unit. Only required when the pricing model is PER_UNIT.
Description of the billable unit for the price.
true if the price is available for new purchases, false otherwise.
Indicates when should the price be billed, one of
IN_ADVANCE: billed at the beginning of the billing cycle.IN_ARREARS: billed at the end of the billing cycle.
Time when the price was created.
Currency of the price (in 3-letter ISO-4217 format).
Price description.
The fixed amount to be charged. Only required when the pricing model is FLAT.
ID of the Price object.
Defines how quantity is grouped into billable lots. The unit_amount is then applied per lot. If not set, quantity is treated as the number of billable lots. Only applicable for PER_UNIT price.
Specifies how to round the calculated lots when the total quantity is not an exact multiple of the size. One of UP.
The amount of quantity that constitutes a single billable lot.
A set of string key-value pairs that you can attach to this object for storing additional information.
ID of the Meter object specifying how to calculate the usage for this price.
Specify how to determine the quantity of the product used in each billing cycle for subscription payments. true if the quantity is dynamically determined during the billing cycle. The merchant should call the Ingest Usage Events API to submit usage data when the product is used. false if the quantity is determined when creating a subscription.
Specify how to calculate the total billing amount when a quantity is provided. One of
FLAT: a fixed price.PER_UNIT: a fixed price per unit quantity.VOLUME: the unit price is based on which tier the total quantity falls in.GRADUATED: the unit price changes as the quantity increases.
ID of the Product object this price is associated with.
The frequency at which the price is charged. null for one-time charge.
The number of period units between subscription billing cycles. For example, the billing cycle is bi-monthly if period=2 and period_unit=MONTH.
Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.
Whether the price includes tax.
List of quantity-based pricing tiers for this price. Required when the pricing model is VOLUME or GRADUATED.
The flat amount to be charged for this tier when pricing model is GRADUATED, or the overall flat amount to be charged when pricing model is VOLUME.
Defines how quantity is grouped into billable lots. The unit_amount is then applied per lot. If not set, quantity is treated as the number of billable lots. Only applicable for VOLUME and GRADUATED prices.
Specifies how to round the calculated lots when the total quantity is not an exact multiple of the size. One of UP.
The amount of quantity that constitutes a single billable lot.
The per-unit amount to be charged for this tier when pricing model is GRADUATED, or the overall per-unit amount to be charged when pricing model is VOLUME.
Description of the billable unit for the tier.
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.
One of ONE_OFF or RECURRING depending on whether the price is for a one-off purchase or a recurring (subscription) purchase.
The amount to be charged per product unit. Only required when the pricing model is PER_UNIT.
Description of the billable unit for the price.
Time when the price was last updated.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request POST \> --url 'https://api.sandbox.airwallex.com/api/v1/billing/prices/create' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json' \> --data '{> "active": true,> "billing_type": "IN_ADVANCE",> "currency": "USD",> "description": "Standard option: $10 / month.",> "flat_amount": 0,> "metadata": {> "foo": "bar"> },> "meter_id": "<string>",> "metered": false,> "pricing_model": "GRADUATED",> "product_id": "prd_hkpd1x2gbgazzvcd42w",> "recurring": {> "period": 1,> "period_unit": "MONTH"> },> "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",> "tax_included": false,> "lot": {> "rounding_mode": "UP",> "size": 10> },> "tiers": [> {> "unit_amount": 10,> "upper_bound": 20> },> {> "flat_amount": 20> }> ],> "unit_amount": 0,> "unit_description": "<string>">}'
1{2 "active": true,3 "billing_type": "IN_ADVANCE",4 "created_at": "2022-01-01T10:15:30+0000",5 "currency": "USD",6 "description": "Standard option: $10 / month.",7 "flat_amount": 0,8 "id": "pri_hkpd7fedfgb004apkvs",9 "lot": {10 "rounding_mode": "UP",11 "size": 1012 },13 "metadata": {14 "foo": "bar"15 },16 "meter_id": "<string>",17 "metered": false,18 "pricing_model": "GRADUATED",19 "product_id": "prd_hkpd1x2gbgazzvcd42w",20 "recurring": {21 "period": 1,22 "period_unit": "MONTH"23 },24 "tax_included": false,25 "tiers": [26 {27 "unit_amount": 10,28 "upper_bound": 2029 },30 {31 "flat_amount": 2032 }33 ],34 "type": "RECURRING",35 "unit_amount": 0,36 "unit_description": "<string>",37 "updated_at": "2022-01-01T10:15:30+0000"38}
Retrieve a price
GET /api/v1/billing/prices/{id}
Retrieves the details of a Price object by the ID.
ID of the Price object.
true if the price is available for new purchases, false otherwise.
Indicates when should the price be billed, one of
IN_ADVANCE: billed at the beginning of the billing cycle.IN_ARREARS: billed at the end of the billing cycle.
Time when the price was created.
Currency of the price (in 3-letter ISO-4217 format).
Price description.
The fixed amount to be charged. Only required when the pricing model is FLAT.
ID of the Price object.
Defines how quantity is grouped into billable lots. The unit_amount is then applied per lot. If not set, quantity is treated as the number of billable lots. Only applicable for PER_UNIT price.
Specifies how to round the calculated lots when the total quantity is not an exact multiple of the size. One of UP.
The amount of quantity that constitutes a single billable lot.
A set of string key-value pairs that you can attach to this object for storing additional information.
ID of the Meter object specifying how to calculate the usage for this price.
Specify how to determine the quantity of the product used in each billing cycle for subscription payments. true if the quantity is dynamically determined during the billing cycle. The merchant should call the Ingest Usage Events API to submit usage data when the product is used. false if the quantity is determined when creating a subscription.
Specify how to calculate the total billing amount when a quantity is provided. One of
FLAT: a fixed price.PER_UNIT: a fixed price per unit quantity.VOLUME: the unit price is based on which tier the total quantity falls in.GRADUATED: the unit price changes as the quantity increases.
ID of the Product object this price is associated with.
The frequency at which the price is charged. null for one-time charge.
The number of period units between subscription billing cycles. For example, the billing cycle is bi-monthly if period=2 and period_unit=MONTH.
Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.
Whether the price includes tax.
List of quantity-based pricing tiers for this price. Required when the pricing model is VOLUME or GRADUATED.
The flat amount to be charged for this tier when pricing model is GRADUATED, or the overall flat amount to be charged when pricing model is VOLUME.
Defines how quantity is grouped into billable lots. The unit_amount is then applied per lot. If not set, quantity is treated as the number of billable lots. Only applicable for VOLUME and GRADUATED prices.
Specifies how to round the calculated lots when the total quantity is not an exact multiple of the size. One of UP.
The amount of quantity that constitutes a single billable lot.
The per-unit amount to be charged for this tier when pricing model is GRADUATED, or the overall per-unit amount to be charged when pricing model is VOLUME.
Description of the billable unit for the tier.
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.
One of ONE_OFF or RECURRING depending on whether the price is for a one-off purchase or a recurring (subscription) purchase.
The amount to be charged per product unit. Only required when the pricing model is PER_UNIT.
Description of the billable unit for the price.
Time when the price was last updated.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 404 | Not Found. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request GET \> --url 'https://api.sandbox.airwallex.com/api/v1/billing/prices/price_id' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json'
1{2 "active": true,3 "billing_type": "IN_ADVANCE",4 "created_at": "2022-01-01T10:15:30+0000",5 "currency": "USD",6 "description": "Standard option: $10 / month.",7 "flat_amount": 0,8 "id": "pri_hkpd7fedfgb004apkvs",9 "lot": {10 "rounding_mode": "UP",11 "size": 1012 },13 "metadata": {14 "foo": "bar"15 },16 "meter_id": "<string>",17 "metered": false,18 "pricing_model": "GRADUATED",19 "product_id": "prd_hkpd1x2gbgazzvcd42w",20 "recurring": {21 "period": 1,22 "period_unit": "MONTH"23 },24 "tax_included": false,25 "tiers": [26 {27 "unit_amount": 10,28 "upper_bound": 2029 },30 {31 "flat_amount": 2032 }33 ],34 "type": "RECURRING",35 "unit_amount": 0,36 "unit_description": "<string>",37 "updated_at": "2022-01-01T10:15:30+0000"38}
Update a price
POST /api/v1/billing/prices/{id}/update
Updates a Price by setting the values of the request parameters. Any parameters not provided will be left unchanged. Only fields provided in the request are updated, while omitted fields remain unchanged. Array fields are fully replaced if included. Set a field to null or an empty string (for strings) to clear its value.
ID of the Price object.
true if the price is available for new purchases, false otherwise.
Price description. Used for internal classification and identification.
A set of string key-value pairs that you can attach to this object for storing additional information.
Unique request ID specified by the merchant.
true if the price is available for new purchases, false otherwise.
Indicates when should the price be billed, one of
IN_ADVANCE: billed at the beginning of the billing cycle.IN_ARREARS: billed at the end of the billing cycle.
Time when the price was created.
Currency of the price (in 3-letter ISO-4217 format).
Price description.
The fixed amount to be charged. Only required when the pricing model is FLAT.
ID of the Price object.
Defines how quantity is grouped into billable lots. The unit_amount is then applied per lot. If not set, quantity is treated as the number of billable lots. Only applicable for PER_UNIT price.
Specifies how to round the calculated lots when the total quantity is not an exact multiple of the size. One of UP.
The amount of quantity that constitutes a single billable lot.
A set of string key-value pairs that you can attach to this object for storing additional information.
ID of the Meter object specifying how to calculate the usage for this price.
Specify how to determine the quantity of the product used in each billing cycle for subscription payments. true if the quantity is dynamically determined during the billing cycle. The merchant should call the Ingest Usage Events API to submit usage data when the product is used. false if the quantity is determined when creating a subscription.
Specify how to calculate the total billing amount when a quantity is provided. One of
FLAT: a fixed price.PER_UNIT: a fixed price per unit quantity.VOLUME: the unit price is based on which tier the total quantity falls in.GRADUATED: the unit price changes as the quantity increases.
ID of the Product object this price is associated with.
The frequency at which the price is charged. null for one-time charge.
The number of period units between subscription billing cycles. For example, the billing cycle is bi-monthly if period=2 and period_unit=MONTH.
Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.
Whether the price includes tax.
List of quantity-based pricing tiers for this price. Required when the pricing model is VOLUME or GRADUATED.
The flat amount to be charged for this tier when pricing model is GRADUATED, or the overall flat amount to be charged when pricing model is VOLUME.
Defines how quantity is grouped into billable lots. The unit_amount is then applied per lot. If not set, quantity is treated as the number of billable lots. Only applicable for VOLUME and GRADUATED prices.
Specifies how to round the calculated lots when the total quantity is not an exact multiple of the size. One of UP.
The amount of quantity that constitutes a single billable lot.
The per-unit amount to be charged for this tier when pricing model is GRADUATED, or the overall per-unit amount to be charged when pricing model is VOLUME.
Description of the billable unit for the tier.
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.
One of ONE_OFF or RECURRING depending on whether the price is for a one-off purchase or a recurring (subscription) purchase.
The amount to be charged per product unit. Only required when the pricing model is PER_UNIT.
Description of the billable unit for the price.
Time when the price was last updated.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 404 | Not Found. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request POST \> --url 'https://api.sandbox.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"> },> "request_id": "ee939540-3203-4a2c-9172-89a566485dd9">}'
1{2 "active": true,3 "billing_type": "IN_ADVANCE",4 "created_at": "2022-01-01T10:15:30+0000",5 "currency": "USD",6 "description": "Standard option: $10 / month.",7 "flat_amount": 0,8 "id": "pri_hkpd7fedfgb004apkvs",9 "lot": {10 "rounding_mode": "UP",11 "size": 1012 },13 "metadata": {14 "foo": "bar"15 },16 "meter_id": "<string>",17 "metered": false,18 "pricing_model": "GRADUATED",19 "product_id": "prd_hkpd1x2gbgazzvcd42w",20 "recurring": {21 "period": 1,22 "period_unit": "MONTH"23 },24 "tax_included": false,25 "tiers": [26 {27 "unit_amount": 10,28 "upper_bound": 2029 },30 {31 "flat_amount": 2032 }33 ],34 "type": "RECURRING",35 "unit_amount": 0,36 "unit_description": "<string>",37 "updated_at": "2022-01-01T10:15:30+0000"38}
Get list of prices
GET /api/v1/billing/prices
Retrieves a list of Prices based on the query parameters.
true if the price is available for new purchases, false otherwise.
The currency of the Price in 3-letter ISO-4217 format.
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.
Number of Prices to be listed per page. Defaults to 20.
ID of the Product object this price is associated with.
The number of period units between subscription billing cycles. For example, the billing cycle is bi-monthly if recurring_period=2 and recurring_period_unit=MONTH.
Specifies billing frequency.
DAYWEEKMONTHYEARPaged results.
true if the price is available for new purchases, false otherwise.
Time when the price was created.
Currency of the price (in 3-letter ISO-4217 format).
ID of the Price object.
Specify how to determine the quantity of the product used in each billing cycle for subscription payments. true if the quantity is dynamically determined during the billing cycle. The merchant should call the Ingest Usage Events API to submit usage data when the product is used. false if the quantity is determined when creating a subscription.
Specify how to calculate the total billing amount when a quantity is provided. One of
FLAT: a fixed price.PER_UNIT: a fixed price per unit quantity.VOLUME: the unit price is based on which tier the total quantity falls in.GRADUATED: the unit price changes as the quantity increases.
ID of the Product object this price is associated with.
Whether the price includes tax.
One of ONE_OFF or RECURRING depending on whether the price is for a one-off purchase or a recurring (subscription) purchase.
Time when the price was last updated.
Indicates when should the price be billed, one of
IN_ADVANCE: billed at the beginning of the billing cycle.IN_ARREARS: billed at the end of the billing cycle.
Price description.
The fixed amount to be charged. Only required when the pricing model is FLAT.
Defines how quantity is grouped into billable lots. The unit_amount is then applied per lot. If not set, quantity is treated as the number of billable lots. Only applicable for PER_UNIT price.
Specifies how to round the calculated lots when the total quantity is not an exact multiple of the size. One of UP.
The amount of quantity that constitutes a single billable lot.
A set of string key-value pairs that you can attach to this object for storing additional information.
ID of the Meter object specifying how to calculate the usage for this price.
The frequency at which the price is charged. null for one-time charge.
The number of period units between subscription billing cycles. For example, the billing cycle is bi-monthly if period=2 and period_unit=MONTH.
Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.
List of quantity-based pricing tiers for this price. Required when the pricing model is VOLUME or GRADUATED.
The flat amount to be charged for this tier when pricing model is GRADUATED, or the overall flat amount to be charged when pricing model is VOLUME.
Defines how quantity is grouped into billable lots. The unit_amount is then applied per lot. If not set, quantity is treated as the number of billable lots. Only applicable for VOLUME and GRADUATED prices.
Specifies how to round the calculated lots when the total quantity is not an exact multiple of the size. One of UP.
The amount of quantity that constitutes a single billable lot.
The per-unit amount to be charged for this tier when pricing model is GRADUATED, or the overall per-unit amount to be charged when pricing model is VOLUME.
Description of the billable unit for the tier.
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.
The amount to be charged per product unit. Only required when the pricing model is PER_UNIT.
Description of the billable unit for the price.
The page cursor used for searching after page.
The page cursor used for search before page.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request GET \> --url 'https://api.sandbox.airwallex.com/api/v1/billing/prices' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json'
1{2 "items": [3 {4 "active": true,5 "billing_type": "IN_ADVANCE",6 "created_at": "2022-01-01T10:15:30+0000",7 "currency": "USD",8 "description": "Standard option: $10 / month.",9 "id": "pri_hkpd7fedfgb004apkvs",10 "lot": {11 "rounding_mode": "UP",12 "size": 1013 },14 "metadata": {15 "foo": "bar"16 },17 "metered": false,18 "pricing_model": "GRADUATED",19 "product_id": "prd_hkpd1x2gbgazzvcd42w",20 "recurring": {21 "period": 1,22 "period_unit": "MONTH"23 },24 "tax_included": false,25 "tiers": [26 {27 "unit_amount": 10,28 "upper_bound": 2029 },30 {31 "flat_amount": 2032 }33 ],34 "type": "RECURRING",35 "updated_at": "2022-01-01T10:15:30+0000"36 }37 ],38 "page_after": "<string>",39 "page_before": "<string>"40}