Invoices via API
This tutorial will guide you through the steps to create and manage invoices with Billing APIs.
Before you begin
- Obtain your access token API by authenticating to Airwallex using your unique Client ID and API key. You will need the access token to make API calls.
- Enable Airwallex Payments if you want to accept payments online.
- Check out Supported currencies for supported regions and currencies.
- Create the required objects. See Invoice objects.
Invoice objects
Use the following API resources to build and manage invoices.
Resource | Definition |
---|---|
Billing Customer API | An individual or business who purchases or subscribes to the merchant's products or services. The object contains customer's contact information and billing preferences. |
Products API | Represents the goods or services you offer to customers (e.g. books, memberships). When associated with Prices, they can be used in Invoice and Subscription APIs. |
Prices API | Represents the pricing information for a Product such as amount, currency, and billing frequency. |
Invoices API | Represents an official request for payment that details products or services purchased, pricing and payment instructions. It can be issued for one-time purchases or recurring payments (subscriptions). |
Create an invoice
Call Create an invoice API with the following required fields:
billing_customer_id
: Provide the ID of the billing customer created using Create a Billing Customer API.currency
: The currency of the amount on the invoice.collection_method
: Specify how the payment for the invoice will be collected,CHARGE_ON_CHECKOUT
orOUT_OF_BAND
. For more information on these methods, see Invoice payment collection methods.- If
CHARGE_ON_CHECKOUT
you must specifylinked_payment_account_id
field.
- If
After creating an invoice, you can:
- Update invoice information by calling Update an invoice API if the invoice is in
DRAFT
status. - You can preview an invoice after it's created by calling Preview an invoice API.
Add line items to an invoice
When adding line items to an invoice, you must specify the product, price and the quantity per line item or link to a Price object. Invoices only support adding prices with the billing frequency (recurring.period_unit
) set to null
for line items, indicating one-time charge. You can add up to 100 line items at a time.
For an invoice with the DRAFT
status, call Create invoice line items and add them to an invoice API with the invoice ID as the parameter and provide the following fields in the request body:
Note: Provide either line_items.price_id
or pricing details in line_items.price.*
.
line_items.price_id
: Provide the ID of the pricing object created using Create a price API. This includes all the product details associated with the invoice.
line_items.price.pricing_model
: Indicates how to calculate billing amount for a product quantity. SpecifyFLAT
for a fixed price andPER_UNIT
for a fixed price per unit quantity.line_items.price.product_id
: ID of the Product API object this price is associated with.
After creating and adding line items, you can choose to update details using Update invoice line items in an invoice API. You can also delete line items by calling Delete invoice line items API if the invoice is in DRAFT
status.
The example code shows how to add line items to an invoice for an existing price with a PER_UNIT
pricing model for 5 units, and also add an adhoc price with a FLAT
amount.
Finalize an invoice
Finalize an invoice in DRAFT
status by calling Finalize an Invoice API, which creates a commercial agreement between the merchant and customer. It is no longer editable and represents a confirmed amount due with payment_status
as UNPAID
.
An invoice object returns payment_status
as PAID
when the amount due has been fully reconciled, either through full payment, or combination of payments, adjustments, or credits.
Manage invoices
After creating an invoice, you can perform the following actions depending the invoice status.
- Retrieve invoice details and status anytime using Retrieve an invoice API.
- Retrieve the list of invoices you've created using Get list of invoices API.
- Delete an invoice API if the invoice is in
DRAFT
status. Note that you cannot undo this action. - Mark an invoice as paid API if the invoice is in
FINALIZED
status and has already been paid out of band. Note that you cannot undo this action. - Void an invoice API if the invoice is in
FINALIZED
status and unpaid. Note that you cannot undo this action.
Retrieve billing transactions
You can retrieve transactions on your invoice such as a payment or refund. Call Retrieve a Billing Transaction API or Get list of Billing Transactions API to retrieve all transactions.