Invoicing overview

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


  1. Create a product and a price.
  2. Create a customer and receive a customer ID.
  3. 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.
  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.

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.

CategoryDescription
Product custom_price references a product_id . The product must already exist, be active, and be one-time.
AmountSet unit_amount and currency on the custom price. The line total is unit_amount multiplied by quantity . The currency must match the invoice currency.
NameOptionally, set a name for the line item, shown on the invoice and the PDF. If omitted, the product name is used.
TaxTax 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.
DiscountsA 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.
ScopeCustom-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.

Invoice statuses
StatusDescription
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.

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.

Discounts

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

Pass a coupon_code or coupon_id in the create invoice API v2 or update invoice API v2 request to apply a discount. To remove an applied discount, send an empty discounts value in the update request.
  • 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.

Looking for help? Contact us
Stay informed with Changelog