Search...
APIJSLog inGet started in sandbox
Airwallex logo
Home
Platform APIs
Connected Accounts
Accounts
Payments
Billing
Transactional FX
Payouts
Issuing
Back to home
OverviewHow Airwallex Billing worksGet started with billingChoose your billing solutionConfigure your billing settingsSupported currencies
Invoicing
Get started with invoicingInvoices via API
Test and go live

Invoices via API

This tutorial will guide you through the steps to create and manage invoices with Billing APIs.

Before you begin

Invoice objects

Use the following API resources to build and manage invoices.

ResourceDefinition
Billing Customer APIAn 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 APIRepresents 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 APIRepresents the pricing information for a Product such as amount, currency, and billing frequency.
Invoices APIRepresents 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 or OUT_OF_BAND. For more information on these methods, see Invoice payment collection methods.
    • If CHARGE_ON_CHECKOUT you must specify linked_payment_account_id field.
Shell

After creating an invoice, you can:

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. Specify FLAT for a fixed price and PER_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.

Shell

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

Was this page helpful?
On this page
Was this page helpful?