ZenotiHelp

Use invoice and payment APIs

ZTZenoti Docs Team Updated March 7, 2026 4 min readGuide

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

  • 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 expand parameter 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_amount field), 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).

API reference

Was this article helpful?
Your feedback helps us improve our documentation.