Integrate invoicing

Sign in Hub
Get help
Integrate invoicing
Configure API access, create products and customers, issue invoices, process payments, and handle webhook events to integrate Solidgate invoicing

Solidgate invoicing handles one-time charges from creation to settlement in Billing 2.0. Configure products, prices, and customers once, then issue invoices. Set up webhook handling to track every status change.

Step 1. Get API credentials
anchor

To use the Solidgate API, you need API keys. Get your keys before proceeding with the integration:

Step 2. Create product
anchor

A product represents the goods or services you offer. Create a product before issuing an invoice. Products are shared across Billing 1.0 and Billing 2.0. You can create and manage products in the Hub or through the Solidgate API v1 .

Products

Step 3. Create price
anchor

A price defines the cost of a product. Create a price before issuing an invoice. Prices are shared across Billing 1.0 and Billing 2.0. You can create and manage prices in the Hub or through the Solidgate API v1 .

Prices

Step 4. Create customer
anchor

An invoice requires a customer record to identify who is being charged.

A customer can be an existing record or created specifically for the invoice. You can create and manage customers in the Hub or through the Solidgate API v2 .

Customers

Step 5. Create invoice
anchor

Create an invoice in draft status, update it with checkout data, then finalize it to prepare for payment.

Send a request to the create invoice API v2 endpoint with a customer ID and at least one line item. Pass the customer_id and one line_items entry with a product_price_id and quantity . Optionally, include a channel_id , discounts to apply a coupon, and notes for internal reference. The response returns the full invoice object, including the calculated price breakdown with subtotal, discount, tax, and total amounts. To retrieve invoice details later, use the get invoice API v2 endpoint.
The customer, product, and product price must already exist in the system before creating an invoice. You select them from dropdowns during the creation flow.

To create an invoice

  1. Go to Billing > Billing 2.0 > Invoices.
  2. Click on Create invoice.
  3. Select a Customer from the dropdown.
  4. Set the Due date for invoice payment.
  5. Optionally, select a Coupon to apply a discount.
  6. Select a Channel.
  7. Optionally, add a Note.
  8. Select a Currency value from the dropdown.
  9. In the line item section, select a Product, its Price, and set the Quantity.
  10. Click on Save to add the line item.
  11. Click on Create invoice.
The invoice is created in draft status. You can view it in the invoice list and open the details page to edit, void, or delete it.

Key information
anchor

  • An invoice contains one product line item. Set the quantity to match the number of units purchased.
  • Only one-time products can be added to an invoice.
  • All monetary values are in minor units (cents). For example, 20000 represents $200.00.
  • Tax is zero at creation if no address is present. Tax is calculated when you add an address to the invoice.
  • Only draft invoices can be modified. After finalization, the invoice cannot be edited.

Update invoice
anchor

Update a draft invoice when checkout data changes, such as the customer address, coupon, quantity, or identity fields.

Send a request to the update invoice API v2 endpoint with the invoice ID and the fields to modify. Only the fields you include in the request are updated. You can update line items, discounts, notes, due date, and customer details. When you include a customer address, Solidgate recalculates tax and returns updated totals. When updating the customer object, include only the fields you want to change. Omitted fields are not updated.
To update an invoice in a draft status

  1. Go to Billing > Billing 2.0 > Invoices.
  2. Click on the invoice ID to open the details page.
  3. Use the Edit buttons next to Customer, Billing address, or Items to modify the relevant fields and save changes as you make them.
Changes to the billing address trigger automatic tax recalculation.

Customer details
Customer data is captured at finalization. If you update a customer record after an invoice is created, the change does not affect that invoice. You can update customer data through the invoice update endpoint. This changes only the data on that invoice and does not modify the customer object.

For finalization to succeed, the customer details on the invoice must include email, first name, last name, IP address, and at least a country in the address.

Step 6. Pay invoice
anchor

Before payment, finalize the invoice to move it from DRAFT to OPEN . Send a request to the finalize invoice API v2 endpoint with the invoice ID. Once the invoice is open, send a request to the pay invoice API v2 endpoint with the id of the invoice and the payment_instrument_id . The payment result arrives asynchronously through a webhook event. Listen for the INVOICE_PAID event to confirm the charge.

Payment Form

To collect payment through the Solidgate Payment Form, generate a payment intent and pass the invoice_id to link the charge to the invoice. Pass the invoice in DRAFT status. Do not finalize it first. The Payment Form updates the invoice with the customer's address and finalizes it automatically when the customer proceeds to pay.
Payment Form

Handle post-payment events
anchor

To track the invoice lifecycle and get updates about its status, subscribe to invoice-related webhook events. Solidgate sends an INVOICE_PAID event when payment completes. Listen for this event to trigger fulfillment.

Configure webhook endpoints through the Webhooks API v2 .
To set up a webhook endpoint

  1. Go to Developers > Webhooks.
  2. Create an endpoint pointing to your server.
  3. Copy the signing secret ( wsec_… ) issued for your endpoint.
Billing 2.0 uses a single signing secret per endpoint, not a public and secret key pair as in Billing 1.0 webhooks.

Invoice events
anchor

EventDescription
INVOICE_CREATED An invoice was created.

Invoice created Webhook
INVOICE_UPDATED An invoice was modified.

Invoice updated Webhook
INVOICE_FINALIZED An invoice moved from draft to open.

Invoice finalized Webhook
INVOICE_PAID Payment was captured: the primary signal for activating a purchase.

Invoice paid Webhook
INVOICE_PAYMENT_FAILED A payment attempt was declined.

Invoice payment failed Webhook
INVOICE_PAYMENT_REFUNDED A refund was issued.

Invoice payment refunded Webhook
INVOICE_VOIDED The invoice was canceled or expired.

Invoice voided Webhook
INVOICE_DELETED The invoice was deleted.

Invoice deleted Webhook
INVOICE_FINALIZATION_FAILED Finalization was rejected due to missing required data.

Invoice finalization failed Webhook

To receive events for customers, payment instruments, and payments from Billing 1.0, subscribe to the corresponding event types as well.

Invoice status transitions
anchor

Each action on an invoice triggers a status change and a corresponding webhook event. Your integration receives the outcome through the webhook with the corresponding status.

StatusAPI endpointWebhookResulting status
DRAFT Delete invoice API v2 Invoice deleted Webhook (Deleted)
DRAFT Finalize invoice API v2 Invoice finalization failed Webhook DRAFT
DRAFT Finalize invoice API v2 Invoice finalized Webhook OPEN
OPEN Pay invoice API v2 Invoice payment failed Webhook OPEN
OPEN Pay invoice API v2 Invoice paid Webhook PAID
OPEN Void invoice API v2 Invoice voided Webhook VOIDED
Finalization moves an invoice from draft to open. This transition is permanent.
Looking for help? Contact us
Stay informed with Changelog