Solidgate Docs
Sign in

Invoicing overview

Understand how invoices work in Solidgate Billing, including invoice structure, statuses, the payment flow, and available invoice actions

An invoice is the billing record for a one-time purchase. It connects a customer to a charge. Each invoice contains one or more line items, with quantity, price, tax, and any applied discounts. Create invoices through the API or the SolidgateHub.

How invoices work

An invoice links a customer to a product charge. Before creating an invoice, you need a customer record. A customer stores identity, address, and tax information and is either an individual (B2C) or a business (B2B).

When you create an invoice, you use an existing customer and one or more products. Each invoice also requires a merchant_reference value that must be unique within a channel. The invoice starts in draft status, where you can modify it. Once finalized, it moves to open and is ready for payment. Payment transitions the invoice to paid status. An invoice in dunning also moves to paid if a retry or manual payment succeeds.

Invoice flow

A typical invoice purchase follows this sequence:


  1. Create a product and a price.
  2. Create a customer and receive a customer ID.
  3. Create an invoice in draft status with one or more product prices, quantities, and a unique merchant reference.
  4. Update the invoice if needed.
  5. Finalize the invoice to move it to open status.
  6. Pay the invoice using a saved payment instrument, a Payment Page, or a Payment Link.
  7. Receive confirmation through a webhook when the invoice moves to paid status.

Invoice statuses

Every invoice progresses through a defined set of statuses.

StatusDescription
DRAFTOpen for changes. You can edit line items, discounts, and customer details.
OPENFinalized and waiting for payment. No further changes are possible.
DUNNINGInvoice payment failed and automatic recovery is in progress. Solidgate retries the charge based on your dunning settings.
UNPAIDAll recovery attempts are exhausted and the amount is still owed. Solidgate does not retry the charge automatically.
PAIDPayment authorized successfully.
VOIDEDCanceled by the merchant or automatically voided after the due date.
Status details
Draft

A draft is the working state of an invoice. Line items, discounts, customer details, due date, and notes are all editable, and it carries no payment obligation yet. Once the details are correct, finalize the draft to commit it and move it to OPEN status. A draft you no longer need can be deleted, which is irreversible.

Open

Once finalized, the invoice is locked. Its line items and amounts can no longer be changed. From here you either collect payment through the Payment Form or a saved payment instrument, or cancel the invoice by voiding it. A finalized invoice cannot be deleted. An open invoice that reaches its due date without payment is voided automatically.

Dunning

An invoice enters dunning when a payment attempt on an open recurring invoice fails. Solidgate starts automatic recovery and retries the invoice on a schedule based on your smart retry settings. The invoice stays locked. Its line items and amounts cannot be changed. From here the invoice moves to PAID if a retry or a manual payment succeeds, or to UNPAID or VOIDED once recovery is exhausted, depending on the invoice status setting you set up in the Hub. While in dunning, you can still collect payment manually or void the invoice to cancel it.

The INVOICE_DUNNING_STARTED webhook fires when the invoice enters this state.

Unpaid

An invoice reaches unpaid when all automatic recovery attempts are exhausted and the invoice status setting in the Hub is configured to mark failed invoices as unpaid. The amount is still owed, but Solidgate does not retry the charge automatically. You can still collect payment manually, for example, after the customer updates their payment method, by sending a request to the pay invoiceAPI v2 endpoint, or void the invoice to cancel the payment. If the invoice is linked to a subscription, the subscription also moves to unpaid, meaning no further invoices are auto-charged until the customer pays.

The INVOICE_UNPAID webhook fires when the invoice enters this state.

Paid

PAID status is reached when payment is authorized successfully. It is final. The invoice does not transition further.

Successful payment triggers the INVOICE_PAID webhook, which is the signal to release goods or unlock the purchase. To pay an invoice through the API, send a request to the pay invoiceAPI v2 endpoint.

Voided

Voiding cancels the invoice but preserves it in your records, so it stays searchable for reference and reconciliation. A voided invoice cannot be paid, and the status is final. Voiding is available while the invoice is in DRAFT, OPEN, or DUNNING status.

Choose whether to void invoices automatically when all recovery attempts fail or mark them unpaid. Void invoices if you do not plan to recover the subscription as it cancels the subscription immediately. Mark them unpaid instead if you plan to contact customers and collect payment. Configure this with the invoice status setting in the Hub.

To configure the invoice status setting



  1. Go to Billing > Billing 2.0 > Settings.
  2. Find Invoice status.
  3. Select Unpaid or Voided as the status to apply after all invoice retries fail.

Tax calculation

Tax is calculated automatically based on the customer’s address. When an invoice includes address information, Solidgate recalculates the tax and returns updated totals.

Taxes

Discounts

You can apply one coupon per invoice. The discount is reflected in the invoice price breakdown after it is applied.

Looking for help? Contact us
Stay informed with Changelog