Airwallex logo
Airwallex 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 Meter API. The API response will return an id that uniquely identifies the Meter object.

Shell
1curl --location --request POST 'https://api-demo.airwallex.com/api/v1/meters/create' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer <AIRWALLEX_ACCESS_TOKEN>' \
4--data '{
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}
12'

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 Product API with the following parameters. The API response will return an id that uniquely identifies the Product object.

Shell
1curl --location --request POST 'https://api-demo.airwallex.com/api/v1/products/create' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer <AIRWALLEX_ACCESS_TOKEN>' \
4--data '{
5    "name": "Pixel AI video",
6    "request_id": "5feb3bfc-5aac-4c18-9f5b-ab75bad7d50a"
7}'
8

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

Shell
1curl --location --request POST 'https://api-demo.airwallex.com/api/v1/prices/create' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer <AIRWALLEX_ACCESS_TOKEN>' \
4--data '{
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}'
17

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 Customer API. The API will return a response containing the created Billing Customer ID.

Shell
1curl --location --request POST 'https://api-demo.airwallex.com/api/v1/billing_customers/create' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer <AIRWALLEX_ACCESS_TOKEN>' \
4--data '{
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 Subscription API 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 --location --request POST 'https://api-demo.airwallex.com/api/v1/subscriptions/create' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer <AIRWALLEX_ACCESS_TOKEN>' \
4--data '{
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}'
17

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 Event API.

Shell
1curl --location --request POST 'https://api-demo.airwallex.com/api/v1/usage_events/ingest' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer <AIRWALLEX_ACCESS_TOKEN>' \
4--data '{
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}'
13

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

Shell
1curl --location --request POST 'https://api-demo.airwallex.com/api/v1/usage_events/batch_ingest' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer <AIRWALLEX_ACCESS_TOKEN>' \
4--data '{
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}'
35

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. 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 API API. You can specify the time range through the from_happened_at and to_happened_at parameters.

1curl --location --request GET 'https://api-demo.airwallex.com/api/v1/meters/mtr_sgsthrwz6hek3uhzk12/summaries?billing_customer_id=bcus_sgstb4rgrhek7w7o0vd&from_happened_at=2026-01-04T08%3A23%3A00+0000&to_happened_at=2026-01-05T12%3A23%3A00+0000' \
2--header 'Authorization: Bearer <AIRWALLEX_ACCESS_TOKEN>'
3

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?