Use invoice and payment APIs
The invoice and payment APIs let you create invoices for products, memberships, and gift cards, retrieve invoice details, process payments, and close invoices. These APIs are central to the payment collection step in all sale workflows.
For complete endpoint documentation including request/response schemas and code examples, see the individual API reference articles linked below.
On this page
- Before you begin
- Create invoices
- Retrieve and manage invoices
- Process payments
- Group invoices
- Related articles
Before you begin
- You need a valid API key or access token. See Set up API authentication.
- A payment processor must be active for the center.
Permission: Manage API Keys (under Administrator) -- Required to access Zenoti APIs.
Create invoices
Create an invoice for products
POST /v1/invoices/products
Generates an invoice for retail product sales.
| Parameter | Type | Required | Description |
|---|---|---|---|
| center_id | guid | Yes | Center identifier |
| guest_id | guid | Yes | Guest identifier |
| product_id | guid | Yes | Product identifier |
| quantity | integer | Yes | Number of units |
| sale_by_employee_id | guid | Yes | Employee processing the sale |
Response: invoice_id.
Create an invoice for memberships
POST /api/Catalog/Memberships/CreateInvoice
Creates an invoice for membership sales.
| Parameter | Type | Required | Description |
|---|---|---|---|
| center_id | guid | Yes | Center identifier |
| user_id | guid | Yes | Guest identifier |
| membership_version_ids | string | Yes | Membership version IDs |
Response: Invoice with Id, InvoiceNumber, Status, Price (Sales, Tax, Final, Discount), SaleDate, InvoiceMemberships, Payments, PaymentOptions.
Create an invoice for gift cards
POST /v1/invoices/gift_cards
Creates an invoice for gift card sales.
| Parameter | Type | Required | Description |
|---|---|---|---|
| gift_cards.type | enum | No | 0=CustomAmount, 1=Service, 2=PreDefined |
| gift_cards.code | string | Yes | Unique gift card identifier |
| gift_cards.custom_amount | object | Yes | price (purchase price) and value (face value) |
| gift_cards.expiry | object | Yes | days or date for expiration |
| gift_cards.is_onetime_use | boolean | No | Single-use restriction |
Response: invoice_id.
Add a product to an existing invoice
PUT /v1/invoices/{invoice_id}/products
Adds a product to an existing open invoice.
Retrieve and manage invoices
Retrieve invoice details
GET /v1/invoices/{invoice_id}
Retrieves full invoice details with optional data expansion.
| Parameter | Type | Required | Description |
|---|---|---|---|
| invoice_id | string | Yes | Invoice identifier |
| expand | string | No | InvoiceItems, Appointments, Transactions, gst_parameters, dues_and_fees |
Response: id, invoice_number, receipt_number, invoice_date, center_id, is_closed, is_refund, lock, total_price (net_price, tax, rounding_adjustment, sum_total), invoice_dues (total, paid, balance), guest details, and expanded data (invoice items, appointments, transactions).
Close an invoice
POST /v1/invoices/{invoice_id}/close
Closes an invoice after full payment has been received.
| Parameter | Type | Required | Description |
|---|---|---|---|
| invoice_id | guid | Yes | Invoice identifier |
Response: is_invoice_closed, closed_by_id, status.
Note: Closing fails if there is an outstanding balance, unassigned tips, or future-dated appointments. Resolve these before closing.
Cancel an invoice
PUT /v1/invoices/{invoice_id}/cancel
Cancels an invoice and removes all associated appointments and purchases. Payments must be removed before cancellation.
Process payments
Collect payment with a saved card
POST /v1/invoices/{invoice_id}/online_payments
Processes payment using a guest's saved credit or debit card. Supports 3D Secure authentication.
| Parameter | Type | Required | Description |
|---|---|---|---|
| invoice_id | string | Yes | Invoice identifier |
| center_id | uuid | Yes | Center identifier |
| account_id | uuid | Conditional | Saved card identifier (required for saved card payments) |
| amount | decimal | No | Payment amount (system calculates if omitted) |
| tip_amount | decimal | No | Tip amount |
| source | integer | No | Payment origin (1=WebStore, 5=Mobile) |
| paying_guest_id | uuid | No | Alternative payer for group invoices |
| redirect_uri | string | No | Required for 3D Secure authentication flow |
Response: success, invoice_transaction_id, token_id, hosted_payment_uri (if 3D Secure is required).
Insert a custom payment
POST /v1/invoices/{invoice_id}/payment/custom
Records a payment collected through a third-party payment processor into Zenoti for reporting and analytics.
| Parameter | Type | Required | Description |
|---|---|---|---|
| invoice_id | guid | Yes | Invoice identifier |
| amount | decimal | Yes | Total payment amount including tip |
| tip_amount | decimal | No | Tip portion |
| cash_register_id | guid | No | Register identifier |
| custom_payment_id | guid | No | External payment identifier |
| collected_by_id | guid | No | Employee who collected payment |
Response: transaction with payment_option, total_amount_paid, amount_paid, tip_amount, transaction_id, payment_date.
Group invoices
Create a group invoice
POST /v1/group_invoices
Combines multiple invoices into a single billable entity for group checkout.
| Parameter | Type | Required | Description |
|---|---|---|---|
| group_name | string | Yes | Name for the group invoice |
| invoice_ids | array | Yes | Invoice IDs to combine |
Response: is_invoice_created, group_invoice (with Id, name, host_id, Invoices, Payments, Price).
Retrieve a group invoice
GET /v1/group_invoices/{group_invoice_id}
Retrieves details of a group invoice.
Tips
- Use the
expandparameter on retrieve invoice details to get exactly the data you need. Expanding all fields when you only need the total price adds unnecessary response size. - Tips are included as part of the payment endpoints (
tip_amountfield), not as a separate API call. - Close the invoice only after all payments are applied and the balance is zero. The API returns specific error codes for common close failures (outstanding balance, future appointments, unassigned tips).