Airwallex logo
Airwallex logoAirwallex logo

Sample integration

Copy for LLMView as Markdown

Example scenario:

  • PixelAI is a text-to-video AI service that uses a pay-as-you-go model.
  • They charge customers US$0.50 per second of video created
  • Customers are billed at the end of each month based on the total duration of videos created.

1. Create a Meter

Meters aggregate raw usage data into a billable quantity for each customer. For PixelAI, they will sum the duration of every video produced during the month.

Airwallex web app

  1. Go to the usage metering app, select the meters tab and click + Create meter

  2. Complete the information:

    1. Meter name: pixelAI_videos_duration_total
    2. Description: "Measures total seconds of video generated per billing period"
    3. Usage event name: video_generation
    4. Aggregation method: "SUM" (adds up the duration of all events)
    5. Aggregation property: duration_seconds

  3. Click Create Meter

Airwallex Billing APIs

Call the Create A MeterAPI. The API response will return an id that uniquely identifies the Meter object.

Shell
1curl -X POST https://api.sandbox.airwallex.com/api/v1/billing/meters/create \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "request_id": "94303878-53b1-4ff5-87a5-080a4a0327e8",
6    "name": "pixelAI_videos_duration_total",
7    "description": "Measures total seconds of video generated per billing period",
8    "event_name": "video_generation",
9    "aggregation_method": "SUM",
10    "aggregation_property": "duration_seconds"
11  }'

2. Create a Product & Price

Create the product & price and link it to the meter

Airwallex web app

  1. Create a product

    1. Product name: "Pixel AI video"

  2. Select the product from step 1 and create a price for it

    1. Pricing model: "Per unit"
    2. Usage-based pricing: check this box
    3. Meter: Select pixelAI_videos_duration_total created in step 1
    4. Fill in the remaining price information:
      1. Currency: USD
      2. Amount: $0.50
      3. Billing frequency: monthly
    5. Click Create price

Airwallex Billing APIs

Call the Create a ProductAPI with the following parameters. The API response will return an id that uniquely identifies the Product object.

Shell
1curl -X POST https://api.sandbox.airwallex.com/api/v1/billing/products/create \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "name": "Pixel AI video",
6    "request_id": "5feb3bfc-5aac-4c18-9f5b-ab75bad7d50a"
7  }'

Then create a Price for the Product via Create a PriceAPI, specifying metered = true along with the Product ID and Meter ID returned from the last steps.

Shell
1curl -X POST https://api.sandbox.airwallex.com/api/v1/billing/prices/create \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "unit_amount": 0.5,
6    "currency": "USD",
7    "pricing_model": "PER_UNIT",
8    "recurring": {
9      "period": 1,
10      "period_unit": "MONTH"
11    },
12    "metered": true,
13    "meter_id": "{{METER_ID_FROM_PREVIOUS_RESPONSE}}",
14    "product_id": "{{PRODUCT_ID_FROM_PREVIOUS_RESPONSE}}",
15    "request_id": "353f4262-96ec-4146-918f-90eb7832ed77"
16  }'

You have completed the setup of a usage-based product. To start charging customers, follow the steps below:

3. Create a Customer

A Customer represents the entity being billed. Before usage can be tracked, you must create a Customer record in Airwallex to receive the usage events and subsequent invoices.

Airwallex Billing APIs

Create the Billing Customer through the Create a Billing CustomerAPI. The API will return a response containing the created Billing Customer ID.

Shell
1curl -X POST https://api.sandbox.airwallex.com/api/v1/billing/billing_customers/create \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "name": "Patti Metz",
6    "request_id": "44a3f8ed-09d8-4466-9c32-59ecc20bd991"
7  }'

4. Create a Subscription

The Subscription connects the customer to your product and starts the "clock" for billing.

Airwallex web app

  1. Create a new subscription for your customer.

  2. Add the "Pixel AI Video" product as a line item.

Airwallex Billing APIs

Create the Subscription for your Customer through Create a SubscriptionAPI API, along with the following parameters

  • billing_customer_id: ID of the Billing Customer created in step 3.
  • items[].price_id: ID of the Price created in step 2.
  • legal_entity_id: ID of the legal entity to be used as the billing entity. You can find this ID in the Airwallex web app > Settings. Required if you have more than 1 entity in your organisation.
  • linked_payment_account_id: ID of the linked payment account to collect payment. You can find this ID in the Airwallex web app > Settings > Account details, within the Account Information section.
Shell
1curl -X POST https://api.sandbox.airwallex.com/api/v1/billing/subscriptions/create \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "request_id": "126fc736-ea18-47d8-b4b6-5d8879eb349c",
6    "billing_customer_id": "{{BILLING_CUSTOMER_ID}}",
7    "collection_method": "CHARGE_ON_CHECKOUT",
8    "currency": "USD",
9    "items": [
10      {
11        "price_id": "{{PRICE_ID}}"
12      }
13    ],
14    "legal_entity_id": "{{LEGAL_ENTITY_ID}}",
15    "linked_payment_account_id": "{{ACCOUNT_ID}}"
16  }'

Once the subscription is active, Airwallex will begin aggregating any video_generation events sent for this specific customer ID. At the end of the monthly cycle, an invoice will automatically generate based on the total seconds recorded.

5. Ingest Usage Events

Send Usage Events of the created customer to record the usage by calling the Ingest a Usage EventAPI.

Shell
1curl -X POST https://api.sandbox.airwallex.com/api/v1/billing/usage_events/ingest \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "merchant_event_id": "41066ba1-488b-4af8-afc5-22da4df2d81e",
6    "billing_customer_id": "{{BILLING_CUSTOMER_ID}}",
7    "event_name": "video_generation",
8    "happened_at": "2026-01-05T08:23:40+0000",
9    "properties": {
10      "duration_seconds": 350
11    }
12  }'

Or you can batch ingest multiple events for multiple customers in a single API call via the Batch Ingest Usage EventsAPI.

Shell
1curl -X POST https://api.sandbox.airwallex.com/api/v1/billing/usage_events/batch_ingest \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "events": [
6      {
7        "merchant_event_id": "52d4659e-2598-4295-bee1-eafebc52d583",
8        "billing_customer_id": "bcus_sgstb4rgrhek7w7o0vd",
9        "event_name": "video_generation",
10        "happened_at": "2026-01-05T08:23:40+0000",
11        "properties": {
12          "duration_seconds": 200
13        }
14      },
15      {
16        "merchant_event_id": "808acf9e-1bcb-45a9-99d2-d058cff9134d",
17        "billing_customer_id": "bcus_sgstb4rgrhek7w7o0vd",
18        "event_name": "video_generation",
19        "happened_at": "2026-01-05T08:24:20+0000",
20        "properties": {
21          "duration_seconds": 150
22        }
23      },
24      {
25        "merchant_event_id": "e1bc19c1-86d7-4041-a0dd-06414dba3204",
26        "billing_customer_id": "bcus_sgstb4rgrhek7w7o0vd",
27        "event_name": "video_generation",
28        "happened_at": "2026-01-05T08:23:40+0000",
29        "properties": {
30          "duration_seconds": 100
31        }
32      }
33    ]
34  }'

The events will be ingested asynchronously. You can subscribe to the usage_event.aggregation_failed webhook event to monitor failures or validation errors on processing the events.

6. Bill different rates by dimension with a rate card

The steps above bill every second of video at the same rate. To charge different rates for different combinations of usage attributes on the same meter, use a rate card instead of a price.

Say PixelAI charges by the model used and the resolution of the video:

  • standard model at 720p: $0.30 per second.
  • standard model at 1080p: $0.50 per second.
  • pro model at any resolution: $1.00 per second.
  • Anything else: $0.20 per second.

6.1. Add dimension keys to the meter

Add model and resolution as dimension keys on the meter. In the web app, edit the meter and add the keys. With the API, call Update a MeterAPI with the complete dimension_keys list, keeping existing keys in the same order. See Meters via API.

6.2. Create a rate card

Create a rate card on the same product and meter, with one row per rate. Order the rows from most specific to least specific. Billing evaluates rows from top to bottom, and the first match wins. A row that leaves every dimension as * (or the Fallback price toggle) is the fallback price.

With the API, call Create a Rate CardAPI. Leave a key out of dimension_values to match any value for that key. Use an empty dimension_values object for the fallback price. See Rate cards via API.

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": "Pixel AI video pricing",
7    "product_id": "{{PRODUCT_ID}}",
8    "meter_id": "{{METER_ID}}",
9    "currency": "USD",
10    "recurring": {
11      "period": 1,
12      "period_unit": "MONTH"
13    },
14    "dimension_keys": ["model", "resolution"],
15    "items": [
16      {
17        "dimension_values": { "model": "standard", "resolution": "720p" },
18        "pricing_model": "PER_UNIT",
19        "unit_amount": 0.3
20      },
21      {
22        "dimension_values": { "model": "standard", "resolution": "1080p" },
23        "pricing_model": "PER_UNIT",
24        "unit_amount": 0.5
25      },
26      {
27        "dimension_values": { "model": "pro" },
28        "pricing_model": "PER_UNIT",
29        "unit_amount": 1
30      },
31      {
32        "dimension_values": {},
33        "pricing_model": "PER_UNIT",
34        "unit_amount": 0.2
35      }
36    ]
37  }'

6.3. Add the rate card to the subscription

Add the rate card to the subscription instead of the price. With the API, set rate_card_id and rate_card_version on the subscription item. See Subscriptions via API.

Shell
1curl -X POST https://api.sandbox.airwallex.com/api/v1/billing/subscriptions/create \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "request_id": "126fc736-ea18-47d8-b4b6-5d8879eb349c",
6    "billing_customer_id": "{{BILLING_CUSTOMER_ID}}",
7    "collection_method": "CHARGE_ON_CHECKOUT",
8    "currency": "USD",
9    "items": [
10      {
11        "rate_card_id": "{{RATE_CARD_ID}}",
12        "rate_card_version": 1
13      }
14    ],
15    "legal_entity_id": "{{LEGAL_ENTITY_ID}}",
16    "linked_payment_account_id": "{{ACCOUNT_ID}}"
17  }'

6.4. Send usage events with dimension values

Include the dimension values in the event properties object, alongside the aggregation property.

Shell
1curl -X POST https://api.sandbox.airwallex.com/api/v1/billing/usage_events/ingest \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "merchant_event_id": "41066ba1-488b-4af8-afc5-22da4df2d81e",
6    "billing_customer_id": "{{BILLING_CUSTOMER_ID}}",
7    "event_name": "video_generation",
8    "happened_at": "2026-01-05T08:23:40+0000",
9    "properties": {
10      "duration_seconds": 350,
11      "model": "standard",
12      "resolution": "1080p"
13    }
14  }'

At the end of the billing period, the invoice includes one line for every row on the pinned rate card version, including rows with zero usage. Usage billed at the fallback price appears as a line named Other usage.

7. Query Usage Summary

You can check the aggregation result of usage of a customer between a specific time window via the Get summaries of a Meter APIAPI. You can specify the time range through the from_happened_at and to_happened_at parameters.

Shell
1curl -G https://api.sandbox.airwallex.com/api/v1/billing/meters/mtr_sgsthrwz6hek3uhzk12/summaries \
2  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
3  --data-urlencode 'billing_customer_id=bcus_sgstb4rgrhek7w7o0vd' \
4  --data-urlencode 'from_happened_at=2026-01-04T08:23:00 0000' \
5  --data-urlencode 'to_happened_at=2026-01-05T12:23:00 0000'

It will return the aggregated usage result for the customer of a specific meter:

JSON
1{
2    "items": [
3        {
4            "billing_customer_id": "bcus_sgstb4rgrhek7w7o0vd",
5            "event_count": 4,
6            "from_happened_at": "2026-01-04T08:23:00+0000",
7            "meter_id": "mtr_sgsthrwz6hek3uhzk12",
8            "to_happened_at": "2026-01-05T12:23:00+0000",
9            "value": 800.0
10        }
11    ]
12}
Was this page helpful?