Invoices

An invoice records a one-off sales transaction between you and your customers. It includes the units and price of the product that you sell, as well as relevant payment information.

Endpoints

GET /api/v1/billing/invoices/{id}
GET /api/v1/billing/invoices
POST /api/v1/billing/invoices/preview
GET /api/v1/billing/invoices/{id}/items/{item_id}
GET /api/v1/billing/invoices/{id}/items

Retrieve an invoice

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

Copy for LLMView as Markdown

Retrieves the details of an Invoice.

Parameters

idrequiredstring

Unique identifier of the Invoice object.

Response body - 200 OK

created_atstring

Time when this invoice was created.

currencystring

The currency of the invoice (in 3-letter ISO-4217 format).

customer_idstring

Unique identifier of the customer who will be charged.

idstring

Unique identifier of the Invoice object.

last_payment_attempt_atstring

Time of last payment attempt.

next_payment_attempt_atstring

Time of next payment attempt.

paid_atstring

Time when this invoice was paid.

past_payment_attempt_countinteger

The number of payment attempts made on this invoice so far.

payment_intent_idstring

Unique identifier of the PaymentIntent that is associated with this invoice, if any.

period_end_atstring

The end of the billing period associated with this invoice. This value is exclusive.

period_start_atstring

The start of the billing period associated with this invoice. This value is inclusive.

remaining_payment_attempt_countinteger

The number of the remaining payment attempts. If 0, no more payment attempts would be triggered automatically for this invoice.

statusstring

The status of the invoice, one of SENT, PAID and PAYMENT_FAILED.
Once the invoice is sent out for payment, its status is SENT. If the payment is successful, the status becomes PAID. If Airwallex is unable to collect the payment after exhausted all charge attempts, then the status becomes PAYMENT_FAILED.

subscription_idstring

Unique identifier of the subscription which generated this invoice, if any.

total_amountnumber

The total amount of the invoice.

updated_atstring

Time when this invoice 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/invoices/{id}

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

Response (200 OK)

1{
2  "created_at": "2022-01-01T10:15:30Z",
3  "currency": "USD",
4  "customer_id": "cus_ps8e0ZgQzd2QnCxVpzJrHD6KOVu",
5  "id": "inv_hkpd49cskgblns6iimw",
6  "last_payment_attempt_at": "2022-12-05T10:15:30+0000",
7  "next_payment_attempt_at": "2022-12-05T10:15:30+0000",
8  "paid_at": "2022-12-05T10:15:30+0000",
9  "past_payment_attempt_count": 1,
10  "payment_intent_id": "int_e65tkXCSzJrsMpTrzoFrjaau53",
11  "period_end_at": "2022-01-05T10:15:30+0000",
12  "period_start_at": "2022-01-01T10:15:30+0000",
13  "remaining_payment_attempt_count": 1,
14  "status": "SENT",
15  "subscription_id": "sub_hkpdkcmxdgazzq53jbk",
16  "total_amount": 100,
17  "updated_at": "2022-01-01T10:15:30Z"
18}

Was this section helpful?

Get list of invoices

GET /api/v1/billing/invoices

Copy for LLMView as Markdown

Retrieve a list of Invoices based on the query parameters.

Parameters

customer_idstring

Unique identifier of the customer who will be charged.

from_created_atstring

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

page_numinteger

Page number starting from 0. Defaults to 0.

page_sizeinteger

Number of Invoices per page. Defaults to 20.

statusstring

The status of the invoice, one of SENT, PAID and PAYMENT_FAILED.
When the invoice is sent out for payment, its status is SENT. If the payment is successful, the invoice moves to PAID status. If Airwallex cannot collect the payment from the customer after all attempts, the invoice moves to PAYMENT_FAILED status.

subscription_idstring

Unique identifier of the subscription which generated this invoice, if any.

to_created_atstring

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

Response body - 200 OK

has_moreboolean

A flag which identifies whether there are more results.

itemsarray

Paged results.

items.created_atstring

Time when this invoice was created.

items.currencystring

The currency of the invoice (in 3-letter ISO-4217 format).

items.customer_idstring

Unique identifier of the customer who will be charged.

items.idstring

Unique identifier of the Invoice object.

items.last_payment_attempt_atstring

Time of last payment attempt.

items.next_payment_attempt_atstring

Time of next payment attempt.

items.paid_atstring

Time when this invoice was paid.

items.past_payment_attempt_countinteger

The number of payment attempts made on this invoice so far.

items.payment_intent_idstring

Unique identifier of the PaymentIntent that is associated with this invoice, if any.

items.period_end_atstring

The end of the billing period associated with this invoice. This value is exclusive.

items.period_start_atstring

The start of the billing period associated with this invoice. This value is inclusive.

items.remaining_payment_attempt_countinteger

The number of the remaining payment attempts. If 0, no more payment attempts would be triggered automatically for this invoice.

items.statusstring

items.subscription_idstring

Unique identifier of the subscription which generated this invoice, if any.

items.total_amountnumber

The total amount of the invoice.

items.updated_atstring

Time when this invoice was last updated.

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/invoices

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

Response (200 OK)

1{
2  "has_more": false,
3  "items": [
4    {
5      "created_at": "2022-01-01T10:15:30Z",
6      "currency": "USD",
7      "customer_id": "cus_ps8e0ZgQzd2QnCxVpzJrHD6KOVu",
8      "id": "inv_hkpd49cskgblns6iimw",
9      "last_payment_attempt_at": "2022-12-05T10:15:30+0000",
10      "next_payment_attempt_at": "2022-12-05T10:15:30+0000",
11      "paid_at": "2022-12-05T10:15:30+0000",
12      "past_payment_attempt_count": 1,
13      "payment_intent_id": "int_e65tkXCSzJrsMpTrzoFrjaau53",
14      "period_end_at": "2022-01-05T10:15:30+0000",
15      "period_start_at": "2022-01-01T10:15:30+0000",
16      "remaining_payment_attempt_count": 1,
17      "status": "SENT",
18      "subscription_id": "sub_hkpdkcmxdgazzq53jbk",
19      "total_amount": 100,
20      "updated_at": "2022-01-01T10:15:30Z"
21    }
22  ]
23}

Was this section helpful?

Preview an upcoming invoice

POST /api/v1/billing/invoices/preview

Copy for LLMView as Markdown

Preview the upcoming invoice of an existing subscription (specified by the subscription_id), or the first invoice before creating a new subscription (when the subscription_id is not provided).

Request body

customer_idstring

Unique identifier of the customer who subscribes to this subscription.

itemsarray

List of SubscriptionItems.

items.price_idrequiredstring

Unique identifier of the Price subscribed by the customer. The Price's recurring values must match the recurring values set out in this subscription.

items.quantitynumber

The product quantity. Defaults to 1.

recurringobject

The billing cycle for recurring charges.

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.

subscription_idstring

Unique identifier of the Subscription object.

trial_end_atstring

The end time of the trial if applicable.

Response body - 200 OK

created_atstring

Time when this invoice will be created.

currencystring

The currency of the invoice (in 3-letter ISO-4217 format).

customer_idstring

Unique identifier of the customer who will be charged.

itemsarray

The InvoiceItems of this invoice.

items.amountnumber

The amount of the invoice item.

items.currencystring

The currency of the invoice item (in 3-letter ISO-4217 format).

items.period_end_atstring

The end of the billing period associated with this invoice item. This value is exclusive.

items.period_start_atstring

The start of the billing period associated with this invoice item. This value is inclusive.

items.priceobject

Price subscribed by the customer.

items.price.activeboolean

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

items.price.currencystring

Currency of the price (in 3-letter ISO-4217 format).

items.price.descriptionstring

Price description.

items.price.flat_amountnumber

The fixed amount to be charged. Applicable for flat pricing model only.

items.price.idstring

Unique identifier of the Price object.

items.price.metadataobject

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

items.price.namestring

Price name.

items.price.pricing_modelstring

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

flat: a fixed price.
per_unit: a fixed price per unit quantity.
volume: the unit price is taken based on which tier the total quantity falls in.
tiered: the unit price changes as the quantity grows.

items.price.product_idstring

Unique identifier of the Product object this price is associated with.

items.price.recurringobject

The billing cycle for recurring charges. Exists when type=RECURRING.

items.price.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.price.recurring.period_unitstring

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

items.price.request_idstring

Unique request identifier specified by the merchant in the last operation.

items.price.tiersarray

List of quantity-based pricing tiers for this price. Applicable for volume and tiered pricing models.

items.price.tiers.amountnumber

The per-unit amount to be charged for this tier when the pricing model is volume or tiered.

items.price.tiers.flat_amountnumber

The fixed amount to be charged for this tier when the pricing model is volume or tiered.

items.price.tiers.upper_boundnumber

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.

items.price.typestring

The type of the Price. Use ONE_OFF for one-off purchases and RECURRING for recurring purchases (subscriptions).

items.price.unit_amountnumber

The amount to be charged per product unit. Applicable for per_unit pricing model only.

items.quantitynumber

The product quantity.

subscription_idstring

Unique identifier of the subscription which generated this invoice, if any.

total_amountnumber

The total amount of the invoice.

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`, `resource_not_found`(invalid `subscription_id` or `price_id`)
401	Unauthorized. Possible error codes: `unauthorized`
404	Not Found. No upcoming invoice for the subscription
500	Server Error. Possible error codes: `internal_error`

POST /api/v1/billing/invoices/preview

$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/billing/invoices/preview' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "customer_id": "cus_ps8e0ZgQzd2QnCxVpzJrHD6KOVu",
>  "items": [
>    {
>      "price_id": "pri_hkpd7fedfgb004apkvs",
>      "quantity": 1
>    }
>  ],
>  "recurring": {
>    "period": 1,
>    "period_unit": "MONTH"
>  },
>  "subscription_id": "sub_hkpdkcmxdgazzq53jbk",
>  "trial_end_at": "2022-01-01T10:15:30+0000"
>}'

Response (200 OK)

1{
2  "created_at": "2022-01-01T10:15:30+0000",
3  "currency": "USD",
4  "customer_id": "cus_ps8e0ZgQzd2QnCxVpzJrHD6KOVu",
5  "items": [
6    {
7      "amount": 10,
8      "currency": "USD",
9      "period_end_at": "2022-01-05T10:15:30+0000",
10      "period_start_at": "2022-01-01T10:15:30+0000",
11      "price": {
12        "active": true,
13        "currency": "USD",
14        "description": "Standard option: $10 / month.",
15        "flat_amount": "null",
16        "id": "pri_hkpd7fedfgb004apkvs",
17        "metadata": {
18          "foo": "bar"
19        },
20        "name": "Standard option",
21        "pricing_model": "tiered",
22        "product_id": "prd_hkpd1x2gbgazzvcd42w",
23        "recurring": {
24          "period": 1,
25          "period_unit": "MONTH"
26        },
27        "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
28        "tiers": [
29          {
30            "amount": 10,
31            "upper_bound": 20
32          },
33          {
34            "amount": 20
35          }
36        ],
37        "type": "RECURRING",
38        "unit_amount": "null"
39      },
40      "quantity": 1
41    }
42  ],
43  "subscription_id": "sub_hkpdkcmxdgazzq53jbk",
44  "total_amount": 10
45}

Was this section helpful?

Retrieve an InvoiceItem

GET /api/v1/billing/invoices/{id}/items/{item_id}

Copy for LLMView as Markdown

Retrieves the details of an InvoiceItem.

Parameters

idrequiredstring

Unique identifier of the invoice object that this invoice item belongs to.

item_idrequiredstring

Unique identifier of the InvoiceItem object.

Response body - 200 OK

amountnumber

The amount of the invoice item.

currencystring

The currency of the invoice item (in 3-letter ISO-4217 format).

idstring

Unique identifier of the InvoiceItem object.

invoice_idstring

Unique identifier of the Invoice object that this invoice item belongs to.

period_end_atstring

The end of the billing period associated with this invoice item. This value is exclusive.

period_start_atstring

The start of the billing period associated with this invoice item. This value is inclusive.

priceobject

Price subscribed by the customer.

price.activeboolean

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

price.currencystring

Currency of the price (in 3-letter ISO-4217 format).

price.descriptionstring

Price description.

price.flat_amountnumber

The fixed amount to be charged. Applicable for flat pricing model only.

price.idstring

Unique identifier of the Price object.

price.metadataobject

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

price.namestring

Price name.

price.pricing_modelstring

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

flat: a fixed price.
per_unit: a fixed price per unit quantity.
volume: the unit price is taken based on which tier the total quantity falls in.
tiered: the unit price changes as the quantity grows.

price.product_idstring

Unique identifier of the Product object this price is associated with.

price.recurringobject

The billing cycle for recurring charges. Exists when type=RECURRING.

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

price.recurring.period_unitstring

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

price.request_idstring

Unique request identifier specified by the merchant in the last operation.

price.tiersarray

List of quantity-based pricing tiers for this price. Applicable for volume and tiered pricing models.

price.tiers.amountnumber

The per-unit amount to be charged for this tier when the pricing model is volume or tiered.

price.tiers.flat_amountnumber

The fixed amount to be charged for this tier when the pricing model is volume or tiered.

price.tiers.upper_boundnumber

price.typestring

The type of the Price. Use ONE_OFF for one-off purchases and RECURRING for recurring purchases (subscriptions).

price.unit_amountnumber

The amount to be charged per product unit. Applicable for per_unit pricing model only.

quantitynumber

The product quantity.

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/invoices/{id}/items/{item_id}

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

Response (200 OK)

1{
2  "amount": 2,
3  "currency": "USD",
4  "id": "iit_hkpd49cskgblnsnzgm1",
5  "invoice_id": "inv_hkpd49cskgblns6iimw",
6  "period_end_at": "2022-01-05T10:15:30+0000",
7  "period_start_at": "2022-01-01T10:15:30+0000",
8  "price": {
9    "active": true,
10    "currency": "USD",
11    "description": "Standard option: $10 / month.",
12    "flat_amount": "null",
13    "id": "pri_hkpd7fedfgb004apkvs",
14    "metadata": {
15      "foo": "bar"
16    },
17    "name": "Standard option",
18    "pricing_model": "tiered",
19    "product_id": "prd_hkpd1x2gbgazzvcd42w",
20    "recurring": {
21      "period": 1,
22      "period_unit": "MONTH"
23    },
24    "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
25    "tiers": [
26      {
27        "amount": 10,
28        "upper_bound": 20
29      },
30      {
31        "amount": 20
32      }
33    ],
34    "type": "RECURRING",
35    "unit_amount": "null"
36  },
37  "quantity": 1
38}

Was this section helpful?

Get list of InvoiceItems

GET /api/v1/billing/invoices/{id}/items

Copy for LLMView as Markdown

Retrieves a list of InvoiceItems based on the query parameters.

Parameters

idrequiredstring

Unique identifier of the Invoice object that the invoice items belong to.

page_numinteger

Page number starting from 0. Defaults to 0.

page_sizeinteger

Number of invoiceItems per page. Defaults to 20.

Response body - 200 OK

has_moreboolean

A flag which identifies whether there are more results.

itemsarray

Paged results.

items.amountnumber

The amount of the invoice item.

items.currencystring

The currency of the invoice item (in 3-letter ISO-4217 format).

items.idstring

Unique identifier of the InvoiceItem object.

items.invoice_idstring

Unique identifier of the Invoice object that this invoice item belongs to.

items.period_end_atstring

The end of the billing period associated with this invoice item. This value is exclusive.

items.period_start_atstring

The start of the billing period associated with this invoice item. This value is inclusive.

items.priceobject

Price subscribed by the customer.

items.price.activeboolean

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

items.price.currencystring

Currency of the price (in 3-letter ISO-4217 format).

items.price.descriptionstring

Price description.

items.price.flat_amountnumber

The fixed amount to be charged. Applicable for flat pricing model only.

items.price.idstring

Unique identifier of the Price object.

items.price.metadataobject

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

items.price.namestring

Price name.

items.price.pricing_modelstring

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

flat: a fixed price.
per_unit: a fixed price per unit quantity.
volume: the unit price is taken based on which tier the total quantity falls in.
tiered: the unit price changes as the quantity grows.

items.price.product_idstring

Unique identifier of the Product object this price is associated with.

items.price.recurringobject

The billing cycle for recurring charges. Exists when type=RECURRING.

items.price.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.price.recurring.period_unitstring

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

items.price.request_idstring

Unique request identifier specified by the merchant in the last operation.

items.price.tiersarray

List of quantity-based pricing tiers for this price. Applicable for volume and tiered pricing models.

items.price.tiers.amountnumber

The per-unit amount to be charged for this tier when the pricing model is volume or tiered.

items.price.tiers.flat_amountnumber

The fixed amount to be charged for this tier when the pricing model is volume or tiered.

items.price.tiers.upper_boundnumber

items.price.typestring

The type of the Price. Use ONE_OFF for one-off purchases and RECURRING for recurring purchases (subscriptions).

items.price.unit_amountnumber

The amount to be charged per product unit. Applicable for per_unit pricing model only.

items.quantitynumber

The product quantity.

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/invoices/{id}/items

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

Response (200 OK)

1{
2  "has_more": false,
3  "items": [
4    {
5      "amount": 2,
6      "currency": "USD",
7      "id": "iit_hkpd49cskgblnsnzgm1",
8      "invoice_id": "inv_hkpd49cskgblns6iimw",
9      "period_end_at": "2022-01-05T10:15:30+0000",
10      "period_start_at": "2022-01-01T10:15:30+0000",
11      "price": {
12        "active": true,
13        "currency": "USD",
14        "description": "Standard option: $10 / month.",
15        "flat_amount": "null",
16        "id": "pri_hkpd7fedfgb004apkvs",
17        "metadata": {
18          "foo": "bar"
19        },
20        "name": "Standard option",
21        "pricing_model": "tiered",
22        "product_id": "prd_hkpd1x2gbgazzvcd42w",
23        "recurring": {
24          "period": 1,
25          "period_unit": "MONTH"
26        },
27        "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
28        "tiers": [
29          {
30            "amount": 10,
31            "upper_bound": 20
32          },
33          {
34            "amount": 20
35          }
36        ],
37        "type": "RECURRING",
38        "unit_amount": "null"
39      },
40      "quantity": 1
41    }
42  ]
43}

Was this section helpful?