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 Solidgate Hub .
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:
- Create a product and a price.
- Create a customer and receive a customer ID.
- Create an invoice in draft status with a unique merchant reference and one or more line items.
Each line item is set to a product price or a custom price with a quantity. - Update the invoice if needed.
- Finalize the invoice to move it to open status.
- Pay the invoice using a saved payment instrument, a Payment Page, or a Payment Link.
- Receive confirmation through a webhook when the invoice moves to paid status.
Custom-price line items
A line item normally references an existing product price ( product_price_id ) in your catalog. Use a custom price for a one-off charge, such as a negotiated discount or a one-time service fee. Set it ( custom_price ) directly on the line item instead of a catalog product price. This skips creating a product price for it.
A line item accepts either a product price or a custom price, never both. Omitting both or including both returns an error.
| Category | Description |
|---|---|
| Product | custom_price references a product_id . The product must already exist, be active, and be one-time. |
| Amount | Set unit_amount and currency on the custom price. The line total is unit_amount multiplied by quantity . The currency must match the invoice currency. |
| Name | Optionally, set a name for the line item, shown on the invoice and the PDF. If omitted, the product name is used. |
| Tax | Tax category and behavior come from the referenced product, the same as for a catalog-price line item. If the product has no tax category, the account's default tax category applies. If neither is set, the line remains untaxed. |
| Discounts | A coupon applied to the invoice discounts a custom-price line item the same way as a catalog-price line item. Coupons apply by amount, not by product or price. |
| Scope | Custom-price lines are available only on standalone invoices. Invoices linked to a subscription use only catalog product prices. |
Invoice statuses
Every invoice progresses through a defined set of statuses.
| Status | Description |
|---|---|
| DRAFT | Open for changes. You can edit line items, discounts, and customer details. |
| OPEN | Finalized and waiting for payment. No further changes are possible. |
| DUNNING | Invoice payment failed and automatic recovery is in progress. Solidgate retries the charge based on your dunning settings. |
| UNPAID | All recovery attempts are exhausted and the amount is still owed. Solidgate does not retry the charge automatically. |
| PAID | Payment authorized successfully. |
| VOIDED | Canceled by the merchant or automatically voided after the due date. |
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.
- Go to Billing > Billing 2.0 > Settings.
- Find Invoice status.
- 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.
Discounts
You can apply one coupon per invoice. The discount is reflected in the invoice price breakdown after it is applied.
- To apply a coupon when creating an invoice, select the existing one in the Coupon dropdown.
- To change or remove a coupon on a draft invoice, open the invoice details page and select Edit next to Items.