Rate Cards

A Rate Card is a versioned container for multi-dimensional pricing. It groups multiple Rate Card Items, each representing the price for one combination of dimensions (e.g. model × token_type), under shared billing fields (product_id, meter_id, currency, recurring). This lets you define pricing for an entire matrix for a single Product and add it to a Subscription as a single item, instead of creating one Price for each combination.

Pricing is organized in three layers:

Rate Card — the container and its shared billing fields.
Rate Card Version — an immutable snapshot of the pricing. Change pricing by publishing a new version; existing subscriptions stay pinned to the version they were created with.
Rate Card Item — one entry in the matrix: the price for a specific set of dimension_values.

When usage is billed, each usage record is matched against the version's items in order and billed at the first item whose dimension_values match (an omitted key matches any value; an empty object matches all usage). So one Rate Card subscription item expands into one invoice line item per priced dimension combination that had usage.

Endpoints

POST /api/v1/billing/rate_cards/create
POST /api/v1/billing/rate_cards/{id}/update
GET /api/v1/billing/rate_cards/{id}
GET /api/v1/billing/rate_cards
POST /api/v1/billing/rate_cards/{id}/versions/create
GET /api/v1/billing/rate_cards/{id}/versions
GET /api/v1/billing/rate_cards/{id}/versions/{version}
GET /api/v1/billing/rate_cards/{id}/versions/{version}/items
GET /api/v1/billing/rate_cards/{id}/versions/{version}/items/{item_id}

Create a Rate Card

POST /api/v1/billing/rate_cards/create

Copy for LLMView as Markdown

Create a new Rate Card with shared billing fields, dimension keys, and a list of items. Each item entry creates a Rate Card Item object.

Request body

currencyrequiredstring

Currency of the items of this rate card (in 3-letter ISO-4217 format).

dimension_keysrequiredarray

Subset of or equal to the Meter's dimension_keys. Defines which dimension keys are used in each item's dimension_values.

itemsrequiredarray

Ordered list of item definitions. Each entry creates a Rate Card Item object. At least one is required.

items.dimension_valuesrequiredobject

The dimension values this item applies to. Each key must be one of the dimension_keys (a subset is allowed). Any key omitted here acts as a wildcard, matching any value for that dimension; an empty object matches all usage (a catch-all).

items.pricing_modelrequiredstring

Specify how to calculate the total billing amount when a quantity is provided. One of

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.

items.lotobject

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.

items.lot.rounding_moderequiredstring

Specifies how to round the calculated lots when the total quantity is not an exact multiple of the size. One of UP.

items.lot.sizerequiredinteger

The amount of quantity that constitutes a single billable lot.

items.tiersarray

List of quantity-based pricing tiers for this item. Required when the pricing model is VOLUME or GRADUATED.

items.tiers.flat_amountnumber

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.

items.tiers.unit_amountnumber

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.

items.tiers.unit_descriptionstring

Description of the billable unit for the tier.

items.tiers.upper_boundnumber

The upper quantity limit of this tier. For the last tier, the upper bound must be left empty.

items.unit_amountnumber

The amount to be charged per product unit. Only required when the pricing model is PER_UNIT.

items.unit_descriptionstring

Description of the billable unit for this item.

meter_idrequiredstring

ID of the shared Meter object specifying how to calculate the usage for the items of this rate card.

namerequiredstring

Rate card name.

product_idrequiredstring

ID of the Product object this rate card is associated with.

recurringrequiredobject

The frequency at which the items of this rate card are charged.

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.

request_idrequiredstring

Unique request ID specified by the merchant.

descriptionstring

Rate card description. Used for internal classification and identification.

metadataobject

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

tax_includedboolean

Whether the item prices include tax. Defaults to false.

Response body - 201 Created

activeboolean

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

created_atstring

Time when this rate card was created.

currencystring

Currency of the items of this rate card (in 3-letter ISO-4217 format).

descriptionstring

Rate card description. Used for internal classification and identification.

idstring

ID of the Rate Card object.

metadataobject

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

meter_idstring

ID of the Meter object specifying how to calculate the usage for the items of this rate card.

namestring

Rate card name.

product_idstring

ID of the Product object this rate card is associated with.

recurringobject

The frequency at which the items of this rate card are charged.

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.

tax_includedboolean

Whether the item prices include tax.

updated_atstring

Time when this rate card was last updated.

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`, `duplicate_request_id`
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/rate_cards/create

$curl --request POST \
>  --url 'https://api.sandbox.airwallex.com/api/v1/billing/rate_cards/create' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "request_id": "b3a8b688-e223-40dd-b034-4db35caaa6d4",
>  "name": "GPT Model Pricing",
>  "description": "Rate card for GPT model family.",
>  "product_id": "prd_hkpd1x2gbgazzvcd42w",
>  "meter_id": "mtr_hkpdwesy9gazzrtqbkg",
>  "currency": "USD",
>  "tax_included": false,
>  "recurring": {
>    "period": 1,
>    "period_unit": "MONTH"
>  },
>  "dimension_keys": [
>    "model",
>    "token_type"
>  ],
>  "items": [
>    {
>      "dimension_values": {
>        "model": "gpt-5.4",
>        "token_type": "input"
>      },
>      "pricing_model": "PER_UNIT",
>      "unit_amount": 2.5,
>      "lot": {
>        "size": 1000000,
>        "rounding_mode": "UP"
>      }
>    },
>    {
>      "dimension_values": {
>        "model": "gpt-5.4",
>        "token_type": "output"
>      },
>      "pricing_model": "PER_UNIT",
>      "unit_amount": 15,
>      "lot": {
>        "size": 1000000,
>        "rounding_mode": "UP"
>      }
>    }
>  ],
>  "metadata": {
>    "foo": "bar"
>  }
>}'

Response (201 Created)

1{
2  "id": "rtc_hkpdwesy9gazzrtqbkg",
3  "active": true,
4  "name": "GPT Model Pricing",
5  "description": "Rate card for GPT model family.",
6  "product_id": "prd_hkpd1x2gbgazzvcd42w",
7  "meter_id": "mtr_hkpdwesy9gazzrtqbkg",
8  "currency": "USD",
9  "tax_included": false,
10  "recurring": {
11    "period": 1,
12    "period_unit": "MONTH"
13  },
14  "metadata": {
15    "foo": "bar"
16  },
17  "created_at": "2026-06-01T00:00:00+0000",
18  "updated_at": "2026-06-01T00:00:00+0000"
19}

Was this section helpful?

Update a Rate Card

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

Copy for LLMView as Markdown

Update a Rate Card. Only name, active, description, and metadata are updatable. Other fields are immutable.

Path parameters

idrequiredstring

ID of the Rate Card object.

Request body

activeboolean

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

descriptionstring

Rate card description. Used for internal classification and identification.

metadataobject

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

namestring

Rate card name.

Response body - 200 OK

activeboolean

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

created_atstring

Time when this rate card was created.

currencystring

Currency of the items of this rate card (in 3-letter ISO-4217 format).

descriptionstring

Rate card description. Used for internal classification and identification.

idstring

ID of the Rate Card object.

metadataobject

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

meter_idstring

ID of the Meter object specifying how to calculate the usage for the items of this rate card.

namestring

Rate card name.

product_idstring

ID of the Product object this rate card is associated with.

recurringobject

The frequency at which the items of this rate card are charged.

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.

tax_includedboolean

Whether the item prices include tax.

updated_atstring

Time when this rate card was last 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`

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

$curl --request POST \
>  --url 'https://api.sandbox.airwallex.com/api/v1/billing/rate_cards/rtc_hkpdwesy9gazzrtqbkg/update' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "active": true,
>  "name": "GPT Model Pricing",
>  "description": "Rate card for GPT model family.",
>  "metadata": {
>    "foo": "bar"
>  }
>}'

Response (200 OK)

1{
2  "id": "rtc_hkpdwesy9gazzrtqbkg",
3  "active": true,
4  "name": "GPT Model Pricing",
5  "description": "Rate card for GPT model family.",
6  "product_id": "prd_hkpd1x2gbgazzvcd42w",
7  "meter_id": "mtr_hkpdwesy9gazzrtqbkg",
8  "currency": "USD",
9  "tax_included": false,
10  "recurring": {
11    "period": 1,
12    "period_unit": "MONTH"
13  },
14  "metadata": {
15    "foo": "bar"
16  },
17  "created_at": "2026-06-01T00:00:00+0000",
18  "updated_at": "2026-06-01T01:00:00+0000"
19}

Was this section helpful?

Retrieve a Rate Card

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

Copy for LLMView as Markdown

Retrieves the details of a Rate Card.

Path parameters

idrequiredstring

ID of the Rate Card object.

Response body - 200 OK

activeboolean

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

created_atstring

Time when this rate card was created.

currencystring

Currency of the items of this rate card (in 3-letter ISO-4217 format).

descriptionstring

Rate card description. Used for internal classification and identification.

idstring

ID of the Rate Card object.

metadataobject

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

meter_idstring

ID of the Meter object specifying how to calculate the usage for the items of this rate card.

namestring

Rate card name.

product_idstring

ID of the Product object this rate card is associated with.

recurringobject

The frequency at which the items of this rate card are charged.

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.

tax_includedboolean

Whether the item prices include tax.

updated_atstring

Time when this rate card was last 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/billing/rate_cards/{id}

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

Response (200 OK)

1{
2  "id": "rtc_hkpdwesy9gazzrtqbkg",
3  "active": true,
4  "name": "GPT Model Pricing",
5  "description": "Rate card for GPT model family.",
6  "product_id": "prd_hkpd1x2gbgazzvcd42w",
7  "meter_id": "mtr_hkpdwesy9gazzrtqbkg",
8  "currency": "USD",
9  "tax_included": false,
10  "recurring": {
11    "period": 1,
12    "period_unit": "MONTH"
13  },
14  "metadata": {
15    "foo": "bar"
16  },
17  "created_at": "2026-06-01T00:00:00+0000",
18  "updated_at": "2026-06-01T01:00:00+0000"
19}

Was this section helpful?

List all Rate Cards

GET /api/v1/billing/rate_cards

Copy for LLMView as Markdown

Retrieves a list of Rate Cards, based on the query parameters.

Query parameters

activeboolean

The rate card's active status, either true or false.

currencystring

The currency of the Rate Card in 3-letter ISO-4217 format.

from_created_atstring

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

meter_idstring

ID of the shared Meter object specifying how to calculate the usage for the items of this rate card.

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.

product_idstring

ID of the Product object this rate card is associated with.

recurring_periodinteger

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.

recurring_period_unitstring

Specifies billing frequency. One of DAY, WEEK, MONTH, or YEAR.

to_created_atstring

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

Response body - 200 OK

itemsarray

Paged results.

items.activeboolean

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

items.created_atstring

Time when this rate card was created.

items.currencystring

Currency of the items of this rate card (in 3-letter ISO-4217 format).

items.idstring

ID of the Rate Card object.

items.meter_idstring

ID of the Meter object specifying how to calculate the usage for the items of this rate card.

items.namestring

Rate card name.

items.product_idstring

ID of the Product object this rate card is associated with.

items.recurringobject

The frequency at which the items of this rate card are charged.

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

Whether the item prices include tax.

items.updated_atstring

Time when this rate card was last updated.

items.descriptionstring

Rate card description. Used for internal classification and identification.

items.metadataobject

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

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/billing/rate_cards

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

Response (200 OK)

1{
2  "items": [
3    {
4      "id": "rtc_hkpdwesy9gazzrtqbkg",
5      "active": true,
6      "name": "GPT Model Pricing",
7      "description": "Rate card for GPT model family.",
8      "product_id": "prd_hkpd1x2gbgazzvcd42w",
9      "meter_id": "mtr_hkpdwesy9gazzrtqbkg",
10      "currency": "USD",
11      "tax_included": false,
12      "recurring": {
13        "period": 1,
14        "period_unit": "MONTH"
15      },
16      "metadata": {
17        "foo": "bar"
18      },
19      "created_at": "2026-06-01T00:00:00+0000",
20      "updated_at": "2026-06-01T01:00:00+0000"
21    }
22  ],
23  "page_after": "<string>",
24  "page_before": "<string>"
25}

Was this section helpful?

Create a Rate Card Version

POST /api/v1/billing/rate_cards/{id}/versions/create

Copy for LLMView as Markdown

Publish a new Rate Card version. items is the complete ordered list; each entry is either the id of an existing Rate Card Item (carried forward by reference) or an inline definition of a new item.

Path parameters

idrequiredstring

ID of the Rate Card object.

Request body

itemsrequiredarray

Ordered list of item definitions. Each entry is either an existing Rate Card Item (carried forward by specifying an id) or an inline definition of a new item, but not both. At least one is required.

items.dimension_valuesobject

The dimension values this item applies to. Each key must be one of the version's dimension_keys (a subset is allowed). Any key omitted here acts as a wildcard, matching any value for that dimension; an empty object matches all usage (a catch-all).

items.idstring

ID of an existing Rate Card Item from this Rate Card to carry forward into the new version.

items.lotobject

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.

items.lot.rounding_moderequiredstring

Specifies how to round the calculated lots when the total quantity is not an exact multiple of the size. One of UP.

items.lot.sizerequiredinteger

The amount of quantity that constitutes a single billable lot.

items.pricing_modelstring

Specify how to calculate the total billing amount when a quantity is provided. One of

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.

items.tiersarray

List of quantity-based pricing tiers for this item. Required when the pricing model is VOLUME or GRADUATED.

items.tiers.flat_amountnumber

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.

items.tiers.unit_amountnumber

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.

items.tiers.unit_descriptionstring

Description of the billable unit for the tier.

items.tiers.upper_boundnumber

The upper quantity limit of this tier. For the last tier, the upper bound must be left empty.

items.unit_amountnumber

The amount to be charged per product unit. Only required when the pricing model is PER_UNIT.

items.unit_descriptionstring

Description of the billable unit for this item.

request_idrequiredstring

Unique request ID specified by the merchant.

dimension_keysarray

The dimension keys this version prices by — a subset of the Meter's dimension_keys. Append-only across versions — must be a superset of the previous version's. Inherits the previous version's set if omitted.

Response body - 201 Created

created_atstring

Time when this rate card version was created.

dimension_keysarray

Subset of or equal to the Meter's dimension_keys. Defines which dimension keys are used in each item's dimension_values. Append-only across versions — a new version's set must contain all keys from the previous version.

rate_card_idstring

ID of the Rate Card this version belongs to.

versioninteger

The version number within the Rate Card, starting from 1.

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`, `duplicate_request_id`
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/rate_cards/{id}/versions/create

$curl --request POST \
>  --url 'https://api.sandbox.airwallex.com/api/v1/billing/rate_cards/rtc_hkpdwesy9gazzrtqbkg/versions/create' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "request_id": "b3a8b688-e223-40dd-b034-4db35caaa6d4",
>  "dimension_keys": [
>    "model",
>    "token_type"
>  ],
>  "items": [
>    {
>      "dimension_values": {
>        "model": "gpt-5.4",
>        "token_type": "input"
>      },
>      "pricing_model": "PER_UNIT",
>      "unit_amount": 2.5,
>      "lot": {
>        "size": 1000000,
>        "rounding_mode": "UP"
>      }
>    },
>    {
>      "id": "rcit_hkpd7fedfgb004apkvs"
>    }
>  ]
>}'

Response (201 Created)

1{
2  "version": 4,
3  "rate_card_id": "rtc_hkpdwesy9gazzrtqbkg",
4  "dimension_keys": [
5    "model",
6    "token_type"
7  ],
8  "created_at": "2026-06-01T00:00:00+0000"
9}

Was this section helpful?

List all Rate Card Versions

GET /api/v1/billing/rate_cards/{id}/versions

Copy for LLMView as Markdown

Retrieves the list of a Rate Card's versions.

Path parameters

idrequiredstring

ID of the Rate Card object.

Query parameters

pagestring

page_sizeinteger

Number of results per page. Defaults to 20.

Response body - 200 OK

itemsarray

Paged results.

items.created_atstring

Time when this rate card version was created.

items.dimension_keysarray

items.rate_card_idstring

ID of the Rate Card this version belongs to.

items.versioninteger

The version number within the Rate Card, starting from 1.

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`
404	Not Found. Possible error codes: `resource_not_found`
500	Server Error. Possible error codes: `internal_error`

GET /api/v1/billing/rate_cards/{id}/versions

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

Response (200 OK)

1{
2  "items": [
3    {
4      "version": 3,
5      "rate_card_id": "rtc_hkpdwesy9gazzrtqbkg",
6      "dimension_keys": [
7        "model",
8        "token_type",
9        "context_length"
10      ],
11      "created_at": "2026-06-03T00:00:00+0000"
12    },
13    {
14      "version": 2,
15      "rate_card_id": "rtc_hkpdwesy9gazzrtqbkg",
16      "dimension_keys": [
17        "model",
18        "token_type"
19      ],
20      "created_at": "2026-06-02T00:00:00+0000"
21    },
22    {
23      "version": 1,
24      "rate_card_id": "rtc_hkpdwesy9gazzrtqbkg",
25      "dimension_keys": [
26        "model",
27        "token_type"
28      ],
29      "created_at": "2026-06-01T00:00:00+0000"
30    }
31  ],
32  "page_after": "<string>",
33  "page_before": "<string>"
34}

Was this section helpful?

Retrieve a Rate Card Version

GET /api/v1/billing/rate_cards/{id}/versions/{version}

Copy for LLMView as Markdown

Retrieves a specific Rate Card Version of a Rate Card by its version number.

Path parameters

idrequiredstring

ID of the Rate Card object.

versionrequiredinteger

The version number within the Rate Card.

Response body - 200 OK

created_atstring

Time when this rate card version was created.

dimension_keysarray

rate_card_idstring

ID of the Rate Card this version belongs to.

versioninteger

The version number within the Rate Card, starting from 1.

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/rate_cards/{id}/versions/{version}

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

Response (200 OK)

1{
2  "version": 4,
3  "rate_card_id": "rtc_hkpdwesy9gazzrtqbkg",
4  "dimension_keys": [
5    "model",
6    "token_type"
7  ],
8  "created_at": "2026-06-01T00:00:00+0000"
9}

Was this section helpful?

List all Rate Card Version Items

GET /api/v1/billing/rate_cards/{id}/versions/{version}/items

Copy for LLMView as Markdown

Retrieves the Rate Card Items belonging to a specific version of a Rate Card. Items are returned in rank order, which determines first-match evaluation.

Path parameters

idrequiredstring

ID of the Rate Card object.

versionrequiredinteger

The version number within the Rate Card.

Query parameters

dimension_filtersobject

Filters the items by dimension values. Each key must be one of the version's dimension_keys.

pagestring

page_sizeinteger

Number of results per page. Defaults to 20.

Response body - 200 OK

itemsarray

Paged results.

items.created_atstring

Time when this rate card item was created.

items.dimension_valuesobject

The dimension values this item applies to. Each key must be one of the Rate Card Version's dimension_keys (a subset is allowed). Any key omitted here acts as a wildcard, matching any value for that dimension; an empty object matches all usage (a catch-all).

items.idstring

ID of the Rate Card Item object.

items.pricing_modelstring

Specify how to calculate the total billing amount when a quantity is provided. One of

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.

items.rate_card_idstring

ID of the Rate Card this item belongs to.

items.lotobject

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.

items.lot.rounding_modestring

Specifies how to round the calculated lots when the total quantity is not an exact multiple of the size. One of UP.

items.lot.sizeinteger

The amount of quantity that constitutes a single billable lot.

items.tiersarray

List of quantity-based pricing tiers for this item. Only present when the pricing model is VOLUME or GRADUATED.

items.tiers.levelinteger

The sequential position of the tier within the item definition. Starts from 1.

items.tiers.flat_amountnumber

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.

items.tiers.lotobject

Defines how quantity is grouped into billable lots. The unit_amount is then applied per lot. Only applicable for VOLUME and GRADUATED.

items.tiers.lot.rounding_modestring

Specifies how to round the calculated lots when the total quantity is not an exact multiple of the size. One of UP.

items.tiers.lot.sizeinteger

The amount of quantity that constitutes a single billable lot.

items.tiers.unit_amountnumber

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.

items.tiers.unit_descriptionstring

Description of the billable unit for the tier.

items.tiers.upper_boundnumber

The upper quantity limit of this tier. For the last tier, the upper bound must be left empty.

items.unit_amountnumber

The amount to be charged per product unit. Only present when the pricing model is PER_UNIT.

items.unit_descriptionstring

Description of the billable unit for this item.

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`
404	Not Found. Possible error codes: `resource_not_found`
500	Server Error. Possible error codes: `internal_error`

GET /api/v1/billing/rate_cards/{id}/versions/{version}/items

$curl --request GET \
>  --url 'https://api.sandbox.airwallex.com/api/v1/billing/rate_cards/rtc_hkpdwesy9gazzrtqbkg/versions/4/items' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Response (200 OK)

1{
2  "items": [
3    {
4      "id": "rcit_hkpd7fedfgb004apkvs",
5      "rate_card_id": "rtc_hkpdwesy9gazzrtqbkg",
6      "dimension_values": {
7        "model": "gpt-5.4",
8        "token_type": "input"
9      },
10      "pricing_model": "PER_UNIT",
11      "unit_amount": 10,
12      "unit_description": "per 1M tokens",
13      "lot": {
14        "size": 1000000,
15        "rounding_mode": "UP"
16      },
17      "created_at": "2026-06-01T00:00:00+0000"
18    }
19  ],
20  "page_after": "<string>",
21  "page_before": "<string>"
22}

Was this section helpful?

Retrieve a Rate Card Version Item

GET /api/v1/billing/rate_cards/{id}/versions/{version}/items/{item_id}

Copy for LLMView as Markdown

Retrieves the details of a Rate Card Item within a specific version, validating that the item belongs to that version.

Path parameters

idrequiredstring

ID of the Rate Card object.

item_idrequiredstring

ID of the Rate Card Item object.

versionrequiredinteger

The version number within the Rate Card.

Response body - 200 OK

created_atstring

Time when this rate card item was created.

dimension_valuesobject

idstring

ID of the Rate Card Item object.

lotobject

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.

lot.rounding_modestring

Specifies how to round the calculated lots when the total quantity is not an exact multiple of the size. One of UP.

lot.sizeinteger

The amount of quantity that constitutes a single billable lot.

pricing_modelstring

Specify how to calculate the total billing amount when a quantity is provided. One of

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.

rate_card_idstring

ID of the Rate Card this item belongs to.

tiersarray

List of quantity-based pricing tiers for this item. Only present when the pricing model is VOLUME or GRADUATED.

tiers.levelinteger

The sequential position of the tier within the item definition. Starts from 1.

tiers.flat_amountnumber

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.

tiers.lotobject

Defines how quantity is grouped into billable lots. The unit_amount is then applied per lot. Only applicable for VOLUME and GRADUATED.

tiers.lot.rounding_modestring

Specifies how to round the calculated lots when the total quantity is not an exact multiple of the size. One of UP.

tiers.lot.sizeinteger

The amount of quantity that constitutes a single billable lot.

tiers.unit_amountnumber

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.

tiers.unit_descriptionstring

Description of the billable unit for the tier.

tiers.upper_boundnumber

The upper quantity limit of this tier. For the last tier, the upper bound must be left empty.

unit_amountnumber

The amount to be charged per product unit. Only present when the pricing model is PER_UNIT.

unit_descriptionstring

Description of the billable unit for this item.

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/rate_cards/{id}/versions/{version}/items/{item_id}

$curl --request GET \
>  --url 'https://api.sandbox.airwallex.com/api/v1/billing/rate_cards/rtc_hkpdwesy9gazzrtqbkg/versions/4/items/rcit_hkpd7fedfgb004apkvs' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Response (200 OK)

1{
2  "id": "rcit_hkpd7fedfgb004apkvs",
3  "rate_card_id": "rtc_hkpdwesy9gazzrtqbkg",
4  "dimension_values": {
5    "model": "gpt-5.4",
6    "token_type": "input"
7  },
8  "pricing_model": "PER_UNIT",
9  "unit_amount": 10,
10  "unit_description": "per 1M tokens",
11  "lot": {
12    "size": 1000000,
13    "rounding_mode": "UP"
14  },
15  "created_at": "2026-06-01T00:00:00+0000"
16}

Was this section helpful?