Billing Customers

A Billing Customer is an individual or business who purchases or subscribes to your products or services.

Endpoints

POST /api/v1/billing/billing_customers/create
GET /api/v1/billing/billing_customers/{id}
GET /api/v1/billing/billing_customers/{id}/bank_transfer_instructions
GET /api/v1/billing/billing_customers
POST /api/v1/billing/billing_customers/{id}/update

Create a Billing Customer

POST /api/v1/billing/billing_customers/create

Copy for LLMView as Markdown

Creates a Billing Customer.

Request body

request_idrequiredstring

Unique request ID specified by the merchant.

addressobject

Address of the billing customer.

address.country_coderequiredstring

The two-letter country code in ISO 3166-1 alpha-2 format.

address.citystring

City of the address.

address.postcodestring

PostCode of the address.

address.statestring

State or province of the address.

address.streetstring

Street of the address.

default_billing_currencystring

Default currency to use when billing this customer in 3-letter ISO-4217 format.

default_legal_entity_idstring

ID of the default legal entity to use when billing this customer. You can get this ID from the legal_entity_id in the response of the Retrieve account details API.

descriptionstring

Additional description about the billing customer.

emailstring

Email address of the billing customer.

metadataobject

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

namestring

Name of the billing customer.

nicknamestring

Internal nickname for the billing customer.

phone_numberstring

Phone number of the billing customer.

tax_identification_numberstring

Tax identification number of the billing customer.

typestring

Type of the billing customer. Defaults to BUSINESS if tax_identification_number exists. Otherwise defaults to INDIVIDUAL.

BUSINESS

INDIVIDUAL

Response body - 201 Created

addressobject

Address of the billing customer.

address.country_codestring

The two-letter country code in ISO 3166-1 alpha-2 format.

address.citystring

City of the address.

address.postcodestring

PostCode of the address.

address.statestring

State or province of the address.

address.streetstring

Street of the address.

automatic_tax_eligibilitystring

Indicates whether automatic tax can be applied for this customer based on the customer's current address data and the seller’s tax registration for that jurisdiction.

ELIGIBLE

Customer is in a jurisdiction where the seller is registered, and automatic tax can be applied.

LOCATION_NOT_SUPPORTED

The customer's jurisdiction can be determined from the current address data, but automatic tax calculation isn't supported there.

ADDRESS_INCOMPLETE

The customer's jurisdiction can't be determined from the provided address data.

created_atstring

Time when the billing customer was created.

default_billing_currencystring

Default currency to use when billing this customer in 3-letter ISO-4217 format.

default_legal_entity_idstring

ID of the default legal entity to use when billing this customer.

descriptionstring

Additional description about the billing customer.

emailstring

Email address of the billing customer.

idstring

ID of the billing customer object.

metadataobject

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

namestring

Name of the billing customer.

nicknamestring

Internal nickname for the billing customer.

phone_numberstring

Phone number of the billing customer.

tax_identification_numberstring

Tax identification number of the billing customer.

typestring

Type of the billing customer

BUSINESS

INDIVIDUAL

updated_atstring

Time when the billing customer was last updated.

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`, `resource_not_found`(invalid `default_billing_entity_id`), `duplicate_request_id`
401	Unauthorized. Possible error codes: `unauthorized`
500	Server Error. Possible error codes: `internal_error`

POST /api/v1/billing/billing_customers/create

$curl --request POST \
>  --url 'https://api.sandbox.airwallex.com/api/v1/billing/billing_customers/create' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "address": {
>    "city": "Shanghai",
>    "country_code": "CN",
>    "postcode": "100000",
>    "state": "Shanghai",
>    "street": "Pudong District"
>  },
>  "default_billing_currency": "USD",
>  "default_legal_entity_id": "le_ib2DZgZJN72T7bObvNuMYQ",
>  "description": "VIP customer",
>  "email": "[email protected]",
>  "metadata": {
>    "customer_segment": "premium"
>  },
>  "name": "John Doe",
>  "nickname": "JohnnyD",
>  "phone_number": "+1234567890",
>  "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
>  "tax_identification_number": "123-45-6789",
>  "type": "INDIVIDUAL"
>}'

Response (201 Created)

1{
2  "address": {
3    "city": "Shanghai",
4    "country_code": "CN",
5    "postcode": "100000",
6    "state": "Shanghai",
7    "street": "Pudong District"
8  },
9  "automatic_tax_eligibility": "ELIGIBLE",
10  "created_at": "2024-06-10T12:34:56+0000",
11  "default_billing_currency": "USD",
12  "default_legal_entity_id": "le_ib2DZgZJN72T7bObvNuMYQ",
13  "description": "VIP customer",
14  "email": "[email protected]",
15  "id": "bcus_hkpd7fedfgb004apkvs",
16  "metadata": {
17    "customer_segment": "premium"
18  },
19  "name": "John Doe",
20  "nickname": "JohnnyD",
21  "phone_number": "+1234567890",
22  "tax_identification_number": "123-45-6789",
23  "type": "INDIVIDUAL",
24  "updated_at": "2024-06-10T12:34:56+0000"
25}

Was this section helpful?

Retrieve a Billing Customer

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

Copy for LLMView as Markdown

Retrieves the details of a Billing Customer.

Path parameters

idrequiredstring

ID of the Billing Customer object.

Response body - 200 OK

addressobject

Address of the billing customer.

address.country_codestring

The two-letter country code in ISO 3166-1 alpha-2 format.

address.citystring

City of the address.

address.postcodestring

PostCode of the address.

address.statestring

State or province of the address.

address.streetstring

Street of the address.

automatic_tax_eligibilitystring

Indicates whether automatic tax can be applied for this customer based on the customer's current address data and the seller’s tax registration for that jurisdiction.

ELIGIBLE

Customer is in a jurisdiction where the seller is registered, and automatic tax can be applied.

LOCATION_NOT_SUPPORTED

The customer's jurisdiction can be determined from the current address data, but automatic tax calculation isn't supported there.

ADDRESS_INCOMPLETE

The customer's jurisdiction can't be determined from the provided address data.

created_atstring

Time when the billing customer was created.

default_billing_currencystring

Default currency to use when billing this customer in 3-letter ISO-4217 format.

default_legal_entity_idstring

ID of the default legal entity to use when billing this customer.

descriptionstring

Additional description about the billing customer.

emailstring

Email address of the billing customer.

idstring

ID of the billing customer object.

metadataobject

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

namestring

Name of the billing customer.

nicknamestring

Internal nickname for the billing customer.

phone_numberstring

Phone number of the billing customer.

tax_identification_numberstring

Tax identification number of the billing customer.

typestring

Type of the billing customer

BUSINESS

INDIVIDUAL

updated_atstring

Time when the billing customer 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/billing_customers/{id}

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

Response (200 OK)

1{
2  "address": {
3    "city": "Shanghai",
4    "country_code": "CN",
5    "postcode": "100000",
6    "state": "Shanghai",
7    "street": "Pudong District"
8  },
9  "automatic_tax_eligibility": "ELIGIBLE",
10  "created_at": "2024-06-10T12:34:56+0000",
11  "default_billing_currency": "USD",
12  "default_legal_entity_id": "le_ib2DZgZJN72T7bObvNuMYQ",
13  "description": "VIP customer",
14  "email": "[email protected]",
15  "id": "bcus_hkpd7fedfgb004apkvs",
16  "metadata": {
17    "customer_segment": "premium"
18  },
19  "name": "John Doe",
20  "nickname": "JohnnyD",
21  "phone_number": "+1234567890",
22  "tax_identification_number": "123-45-6789",
23  "type": "INDIVIDUAL",
24  "updated_at": "2024-06-10T12:34:56+0000"
25}

Was this section helpful?

Retrieve Bank Transfer Instructions of a Billing Customer

GET /api/v1/billing/billing_customers/{id}/bank_transfer_instructions

Copy for LLMView as Markdown

Retrieves the bank transfer instructions of a Billing Customer as a read-only list, with one entry per supported currency. The list is empty until bank transfer instructions have been provisioned.

Path parameters

idrequiredstring

ID of the Billing Customer object.

Response body - 200 OK - Multiple values

account_categorystring

Category of the receiving bank account. One of CHECKING, SAVINGS, or BUSINESS.

CHECKING

SAVINGS

BUSINESS

account_namestring

Name of the account holder receiving the transfer.

account_numberstring

Bank account number.

bank_codestring

Code identifying the bank. Applicable in markets including Singapore and Hong Kong.

bank_namestring

Name of the financial institution in which the receiving account is domiciled.

branch_codestring

Code identifying the bank branch. Used together with bank_code.

bsb_numberstring

Bank State Branch (BSB) number. Applicable only to accounts in Australia.

charge_typestring

Indicates who bears the bank charges on the transfer. Returned only for international (SWIFT) transfers. Omitted for local transfers. Possible value:

OUR: The payer covers all transfer charges so the full amount is received.

OUR

currencystring

Currency of the receiving account (3-letter ISO-4217 code).

ibanstring

IBAN number.

institution_numberstring

Institution number identifying the bank. Applicable only to accounts in Canada.

merchant_addressobject

The recipient's registered business address, used when making an international (SWIFT) transfer. Returned only for SWIFT transfers. Omitted for local transfers.

merchant_address.country_codestring

Two-letter ISO 3166-1 country code of the recipient's address.

merchant_address.postcodestring

Postal or ZIP code of the recipient's address.

merchant_address.statestring

State, province, or region of the recipient's address.

merchant_address.street_addressarray

Street address of the recipient, given as one or more address lines.

merchant_address.suburbstring

Suburb or city of the recipient's address.

routing_numberstring

Bank routing number. Applicable only to accounts in the United States.

sort_codestring

Bank sort code. Applicable only to accounts in the United Kingdom.

swift_codestring

Bank SWIFT or BIC code.

transit_numberstring

Bank transit number. Applicable only to accounts in Canada.

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/billing_customers/{id}/bank_transfer_instructions

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

Response (200 OK)

1[
2  {
3    "currency": "USD",
4    "account_name": "Tromp, Littel and Luettgen",
5    "account_number": "8453687204",
6    "bank_name": "Community Federal Savings Bank",
7    "routing_number": "026073150"
8  }
9]

Was this section helpful?

List all Billing Customers

GET /api/v1/billing/billing_customers

Copy for LLMView as Markdown

Retrieves a list of Billing Customers based on the query parameters.

Query parameters

emailstring

Email address of the billing customer.

from_created_atstring

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

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 billing customer objects per page. Defaults to 20.

to_created_atstring

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

Response body - 200 OK

itemsarray

Paged results.

items.automatic_tax_eligibilitystring

Indicates whether automatic tax can be applied for this customer based on the customer's current address data and the seller’s tax registration for that jurisdiction.

ELIGIBLE

Customer is in a jurisdiction where the seller is registered, and automatic tax can be applied.

LOCATION_NOT_SUPPORTED

The customer's jurisdiction can be determined from the current address data, but automatic tax calculation isn't supported there.

ADDRESS_INCOMPLETE

The customer's jurisdiction can't be determined from the provided address data.

items.created_atstring

Time when the billing customer was created.

items.idstring

ID of the billing customer object.

items.updated_atstring

Time when the billing customer was last updated.

items.addressobject

Address of the billing customer.

items.address.country_codestring

The two-letter country code in ISO 3166-1 alpha-2 format.

items.address.citystring

City of the address.

items.address.postcodestring

PostCode of the address.

items.address.statestring

State or province of the address.

items.address.streetstring

Street of the address.

items.default_billing_currencystring

Default currency to use when billing this customer in 3-letter ISO-4217 format.

items.default_legal_entity_idstring

ID of the default legal entity to use when billing this customer.

items.descriptionstring

Additional description about the billing customer.

items.emailstring

Email address of the billing customer.

items.metadataobject

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

items.namestring

Name of the billing customer.

items.nicknamestring

Internal nickname for the billing customer.

items.phone_numberstring

Phone number of the billing customer.

items.tax_identification_numberstring

Tax identification number of the billing customer.

items.typestring

Type of the billing customer

BUSINESS

INDIVIDUAL

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

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

Response (200 OK)

1{
2  "items": [
3    {
4      "address": {
5        "city": "Shanghai",
6        "country_code": "CN",
7        "postcode": "100000",
8        "state": "Shanghai",
9        "street": "Pudong District"
10      },
11      "automatic_tax_eligibility": "ELIGIBLE",
12      "created_at": "2024-06-10T12:34:56+0000",
13      "default_billing_currency": "USD",
14      "default_legal_entity_id": "le_ib2DZgZJN72T7bObvNuMYQ",
15      "description": "VIP customer",
16      "email": "[email protected]",
17      "id": "bcus_hkpd7fedfgb004apkvs",
18      "metadata": {
19        "customer_segment": "premium"
20      },
21      "name": "John Doe",
22      "nickname": "JohnnyD",
23      "phone_number": "+1234567890",
24      "tax_identification_number": "123-45-6789",
25      "type": "INDIVIDUAL",
26      "updated_at": "2024-06-10T12:34:56+0000"
27    }
28  ],
29  "page_after": "<string>",
30  "page_before": "<string>"
31}

Was this section helpful?

Update a Billing Customer

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

Copy for LLMView as Markdown

Updates a Billing Customer. Only fields provided in the request are updated, while omitted fields remain unchanged. Array fields are fully replaced if included. Set a field to null or an empty string (for strings) to clear its value.

Path parameters

idrequiredstring

ID of the Billing Customer object.

Request body

addressobject

Address of the billing customer.

address.country_coderequiredstring

The two-letter country code in ISO 3166-1 alpha-2 format.

address.citystring

City of the address.

address.postcodestring

PostCode of the address.

address.statestring

State or province of the address.

address.streetstring

Street of the address.

default_billing_currencystring

Default currency to use when billing this customer in 3-letter ISO-4217 format.

default_legal_entity_idstring

ID of the default legal entity to use when billing this customer.

descriptionstring

Additional description about the billing customer.

emailstring

Email address of the billing customer.

metadataobject

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

namestring

Name of the billing customer.

nicknamestring

Internal nickname for the billing customer.

phone_numberstring

Phone number of the billing customer.

tax_identification_numberstring

Tax identification number of the billing customer.

typestring

Type of the billing customer.

BUSINESS

INDIVIDUAL

Response body - 200 OK

addressobject

Address of the billing customer.

address.country_codestring

The two-letter country code in ISO 3166-1 alpha-2 format.

address.citystring

City of the address.

address.postcodestring

PostCode of the address.

address.statestring

State or province of the address.

address.streetstring

Street of the address.

automatic_tax_eligibilitystring

Indicates whether automatic tax can be applied for this customer based on the customer's current address data and the seller’s tax registration for that jurisdiction.

ELIGIBLE

Customer is in a jurisdiction where the seller is registered, and automatic tax can be applied.

LOCATION_NOT_SUPPORTED

The customer's jurisdiction can be determined from the current address data, but automatic tax calculation isn't supported there.

ADDRESS_INCOMPLETE

The customer's jurisdiction can't be determined from the provided address data.

created_atstring

Time when the billing customer was created.

default_billing_currencystring

Default currency to use when billing this customer in 3-letter ISO-4217 format.

default_legal_entity_idstring

ID of the default legal entity to use when billing this customer.

descriptionstring

Additional description about the billing customer.

emailstring

Email address of the billing customer.

idstring

ID of the billing customer object.

metadataobject

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

namestring

Name of the billing customer.

nicknamestring

Internal nickname for the billing customer.

phone_numberstring

Phone number of the billing customer.

tax_identification_numberstring

Tax identification number of the billing customer.

typestring

Type of the billing customer

BUSINESS

INDIVIDUAL

updated_atstring

Time when the billing customer 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/billing_customers/{id}/update

$curl --request POST \
>  --url 'https://api.sandbox.airwallex.com/api/v1/billing/billing_customers/billing_customer_id/update' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "address": {
>    "city": "Melbourne",
>    "country_code": "AU",
>    "postcode": "3000",
>    "state": "VIC",
>    "street": "200 Collins Street"
>  },
>  "default_billing_currency": "EUR",
>  "default_legal_entity_id": "le_ib2DZgZJN72T7bObvNuMYQ",
>  "description": "Updated corporate account",
>  "email": "[email protected]",
>  "metadata": {
>    "customer_segment": "enterprise"
>  },
>  "name": "Acme Corporation",
>  "nickname": "Acme Corp",
>  "phone_number": "+1987654321",
>  "tax_identification_number": "987-65-4321",
>  "type": "BUSINESS"
>}'

Response (200 OK)

1{
2  "address": {
3    "city": "Shanghai",
4    "country_code": "CN",
5    "postcode": "100000",
6    "state": "Shanghai",
7    "street": "Pudong District"
8  },
9  "automatic_tax_eligibility": "ELIGIBLE",
10  "created_at": "2024-06-10T12:34:56+0000",
11  "default_billing_currency": "USD",
12  "default_legal_entity_id": "le_ib2DZgZJN72T7bObvNuMYQ",
13  "description": "VIP customer",
14  "email": "[email protected]",
15  "id": "bcus_hkpd7fedfgb004apkvs",
16  "metadata": {
17    "customer_segment": "premium"
18  },
19  "name": "John Doe",
20  "nickname": "JohnnyD",
21  "phone_number": "+1234567890",
22  "tax_identification_number": "123-45-6789",
23  "type": "INDIVIDUAL",
24  "updated_at": "2024-06-10T12:34:56+0000"
25}

Was this section helpful?