Airwallex logo
Airwallex logoAirwallex logo

Rate cards via API

Create and manage rate cards with the Billing APIs

Copy for LLMView as Markdown

A rate card prices usage across the dimension keys of one meter. It is only for usage-based billing and always links to a meter. Create the card with its first version, then pin that version on a subscription or checkout.

Before you begin

  • Create a product.
  • Create a meter and set dimension_keys to the event properties you will price by.

Create a rate card

Call Create a Rate CardAPI. This creates the rate card and version 1. A version cannot be changed after it is created.

Provide these fields:

  • name: The rate card name.
  • product_id: The product this rate card belongs to.
  • meter_id: The meter that aggregates usage for every item on this rate card.
  • currency: The currency of the items, as a 3-letter ISO-4217 code.
  • recurring.period and recurring.period_unit: How often the items are billed. period_unit is one of DAY, WEEK, MONTH, or YEAR.
  • dimension_keys: The meter dimension keys this version prices by. Use the meter's full list, or a subset.
  • items: An ordered list of items. At least one item is required. Billing evaluates items from first to last, and the first match wins. Put more specific items above broader ones.

Each item sets dimension_values and a pricing_model of PER_UNIT, VOLUME, or GRADUATED.

  • Include a key in dimension_values to match that exact value.
  • Leave a key out to match any value for that key.
  • Use an empty dimension_values object to match all usage. That item is the fallback price.
  • Set unit_amount for PER_UNIT. Set tiers for VOLUME and GRADUATED.
  • lot applies only to PER_UNIT. It groups quantity into billable lots, for example 1,000,000 tokens.
Shell
1curl -X POST https://api.sandbox.airwallex.com/api/v1/billing/rate_cards/create \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "request_id": "b3a8b688-e223-40dd-b034-4db35caaa6d4",
6    "name": "Model pricing",
7    "description": "Rate card for model usage",
8    "product_id": "prd_hkdmfsd9mhax0w2uakw",
9    "meter_id": "mtr_hkpdwesy9gazzrtqbkg",
10    "currency": "USD",
11    "tax_included": false,
12    "recurring": {
13      "period": 1,
14      "period_unit": "MONTH"
15    },
16    "dimension_keys": ["model", "token_type"],
17    "items": [
18      {
19        "dimension_values": {
20          "model": "standard",
21          "token_type": "input"
22        },
23        "pricing_model": "PER_UNIT",
24        "unit_amount": 2.5,
25        "lot": {
26          "size": 1000000,
27          "rounding_mode": "UP"
28        }
29      },
30      {
31        "dimension_values": {
32          "model": "standard",
33          "token_type": "output"
34        },
35        "pricing_model": "PER_UNIT",
36        "unit_amount": 15
37      },
38      {
39        "dimension_values": {},
40        "pricing_model": "PER_UNIT",
41        "unit_amount": 1
42      }
43    ]
44  }'

The response returns the rate card, including its id. Retrieve version 1 and its items with Retrieve a Rate Card VersionAPI and Get list of Rate Card ItemsAPI.

Publish a new version

Call Create a Rate Card VersionAPI to change pricing. Publishing a version does not change subscriptions or checkouts already pinned to another version.

  • items is the complete ordered list for the new version. Each entry is either the id of an existing item on this rate card, or an inline definition of a new item.
  • dimension_keys is optional. If you omit it, the new version keeps the previous version's keys. If you set it, include every key from the previous version, in the same order, and append any new keys at the end. You cannot rename, reorder, or remove keys.
Shell
1curl -X POST https://api.sandbox.airwallex.com/api/v1/billing/rate_cards/rtc_hkpdwesy9gazzrtqbkg/versions/create \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "request_id": "c4b9c799-f334-51ee-c145-5ec46dbbb7e5",
6    "dimension_keys": ["model", "token_type"],
7    "items": [
8      {
9        "dimension_values": {
10          "model": "standard",
11          "token_type": "input"
12        },
13        "pricing_model": "PER_UNIT",
14        "unit_amount": 3
15      },
16      {
17        "id": "rcit_hkpd7fedfgb004apkvs"
18      }
19    ]
20  }'

The response version is the number you pin on a subscription or checkout.

Update a rate card

Call Update a Rate CardAPI to change name, description, active, or metadata. Product, meter, currency, billing cadence, and items stay as they were. Set active to false so the rate card cannot be used for new subscriptions and checkouts.

Retrieve rate cards

Next steps

Was this page helpful?