About the Invoices API

The Invoices API allows you to create, manage, and track business invoices. It supports detailed line items, customer information, payment terms, and automated calculations for taxes and totals.

With the Invoices API, you can:

• Create and manage standalone invoices with custom or catalog line items.
• Publish invoices, assign invoice numbers, and send them to customers.
• Track invoice payments, including partial payments and deposits.
• Calculate taxes, totals, and shipping options before creating an invoice.
• Generate and download PDF documents for invoices.
• Organize invoices using tags, archiving, and filtering.
• Perform bulk operations for creating, updating, deleting, and tagging invoices.
• Create invoices with automatic charges that generate and charge subsequent invoices on a recurring billing cycle.

Invoice types

Invoices are created with a reference type that determines their behavior. You can create STANDALONE and AUTO_CHARGE invoices through this API. After creation, the type can't be changed:

• STANDALONE: An invoice you create independently, as opposed to order invoices created automatically by Wix eCommerce. When the first payment is made, a Wix eCommerce order is created automatically to process the transaction. You can set limitActions to true to prevent other apps from modifying the invoice.
• AUTO_CHARGE: An invoice with automatic charges. After the invoice is paid, Wix automatically generates and charges subsequent invoices on the configured billing cycle. Subscription settings are managed in Wix eCommerce automations.
• ORDER: An invoice created for an existing Wix eCommerce order. Its lifecycle is bound to that order. Only Wix eCommerce can create order invoices.

Invoice lifecycle and status management

Invoices progress through a unified lifecycle from DRAFT through PUBLISHED to PAID or VOIDED. Available actions are determined by the invoice's current status. Status qualifiers such as SENT, VIEWED, and OVERDUE provide additional context and are system-managed. For full details, see Invoice Lifecycle and Status Qualifiers.

For AUTO_CHARGE invoices, voiding an individual invoice does not cancel the subscription — subsequent invoices continue to be generated and charged. To stop the billing cycle, cancel the subscription through Wix eCommerce automations.

Financial calculations

Invoices support deposit payments and pre-creation calculations. When a deposit is configured, the checkout presents the deposit amount as the initial payment—subsequent payments cover the remaining balance. Call Calculate Invoice to preview totals, taxes, and available shipping options before creating or updating an invoice. For details on deposits and total fields, see Invoice Calculations.

Tracking invoice activity

The invoice's activityInfo field tracks when the invoice was last sent, who it was sent to, and when it was last viewed. Send Invoice updates this automatically. For invoices sent or displayed outside of Wix, see Track invoice activity outside of Wix.

Before you begin

It's important to note the following points before starting to code:

• The Invoices V2 API isn't currently available to all Wix users and is being rolled out gradually.
• Wix users can configure their site to automatically create invoices whenever an online order is paid.
• When the first payment is made on a standalone invoice, a Wix eCommerce order is created automatically to process the transaction. The order ID is stored in reference.standaloneReference.orderId and is used for all subsequent payments.
• Invoices can only be deleted when in DRAFT status. Afterward, they can be archived.
• Invoice numbers are assigned automatically when an invoice is published. The numbering schema (prefix, sequential number, and suffix) is configured in the Invoices Settings API.
• Business details such as company name, address, email, phone, and logo are automatically populated from the Site Properties API at creation if not explicitly provided. They aren't synced after creation and become permanently fixed at PARTIALLY_PAID, PAID, or VOIDED.
• Invoices require a contactId from the Contacts API.
• The currency is set at creation, defaulting to the site's currency, and can't be changed.
• Tax calculations depend on regional settings which can be configured in the Site Properties API.
• Sending an invoice defaults to the customer contact if no contactIds are specified. An invoice can be sent to a maximum of 5 distinct contacts.
• Only one subscription line item is supported per invoice.

Use cases

• Preview invoice totals
• Create and send a standalone invoice
• Track invoice activity outside of Wix
• Initiate online payment for a standalone invoice
• Generate and download a PDF document
• Implement bulk invoice processing for recurring billing
• Create an invoice with automatic charges

Terminology

• Invoice: A document that records goods or services provided to a customer, including itemized amounts and payment details.
• Standalone invoice: An invoice you create independently, as opposed to order invoices created automatically by Wix eCommerce for existing orders. When the first payment is made, a Wix eCommerce order is created automatically to process the transaction.
• Order invoice: An invoice created for an existing Wix eCommerce order. Its lifecycle is bound to that order.
• Invoice preset: A collection of invoice configurations that define the invoice's appearance, behavior, and custom fields. Presets can be used for different business scenarios, for example, multiple locations or domains in the same business.
• Invoice settings: Site-level configurations that control the invoice numbering schema.
• Deposit: A partial upfront payment amount configured on the invoice. Defines the initial payment amount presented at checkout.
• Status qualifier: A flag applied alongside an invoice's primary status to provide additional context.
• Shipping info: The invoice's shipping destination, including the recipient's contact details and address. Independent of any shipment; an invoice can have a shipping address without a shipment.
• Shipment info: Delivery and shipping cost details (carrier, method, price, tax) tied to the Wix eCommerce integration. It uses the invoice's shipping address as the delivery destination unless a pickup address is specified.