Invoice
Invoices represent orders completed by customers. Invoices contain line items, discounts, and payments.
The invoice model
The invoice model contains identifying information about the invoice.
Properties
- Name
id- Type
- string
- Description
Unique identifier for the invoice.
- Name
customer_id- Type
- string
- Description
Identifier for the customer the invoice belongs to.
- Name
store_id- Type
- string
- Description
Identifier for the store where the invoice was processed.
- Name
cashier_id- Type
- string
- Description
Identifier for the cashier who processed the invoice.
- Name
number- Type
- string
- Description
A unique identifier for the invoice, typically created by the POS system.
- Name
subtotal- Type
- float
- Description
Subtotal of the invoice, including all modifiers and discounts.
- Name
date_ordered- Type
- string
- Description
Timestamp of when the invoice was first created in local time of the POS system.
- Name
date_created- Type
- string
- Description
Timestamp of when the invoice was first created.
- Name
date_updated- Type
- string
- Description
Timestamp of when the invoice was last updated.
- Name
status- Type
- string
- Description
A string enum for indicating the current status of the invoice.
Retrieve a list of invoices
This endpoint allows you to retrieve a paginated list of your invoices. By default, this will include the 25 most recent objects, starting with the most recent.
Query parameters
- Name
limit- Type
- integer
- Description
The maximum number of entries to include in the response.
- Name
page- Type
- integer
- Description
An offset to determine which groups of results to return.
- Name
query- Type
- string
- Description
A search string which can be used to filter results by various criteria (see below).
Filter parameters
These attributes can be used to filter the result set returned by the API. They are included as a space-delimited string of key:value pairs.
- Name
cu- Type
- string
- Description
ID of the customer.
- Name
st- Type
- string
- Description
ID of the store.
- Name
c- Type
- string
- Description
ID of the cashier.
- Name
s- Type
- string
- Description
Status of the invoice.
Request
curl -G https://api.spoonity.com/invoices \
-H "Authorization: Bearer {token}"
Response
{
"items": [
{
"id": "invo_17b0187c18577b36",
"customer_id": "cust_uhfhf63juwe7j84h",
"store_id": "stor_uri84ydhdt3453tw",
"cashier_id": "cash_74yeurgdtwyeh651",
"number": "INV-001",
"subtotal": 21.99,
"date_ordered": "2026-02-02T13:48:05.683Z",
"date_created": "2026-02-02T13:48:05.683Z",
"date_updated": "2026-02-02T13:48:05.683Z",
"status": "COMPLETE",
},
{
"id": "invo_835et56dy328sf93",
"customer_id": "cust_uhfhf63juwe7j84h",
"store_id": "stor_uri84ydhdt3453tw",
"cashier_id": "cash_74yeurgdtwyeh651",
"number": "INV-002",
"subtotal": 13.49,
"date_ordered": "2026-02-01T13:48:05.683Z",
"date_created": "2026-02-01T13:48:05.683Z",
"date_updated": "2026-02-01T13:48:05.683Z",
"status": "COMPLETE",
}
],
"paging": {
"next": "https://api.spoonity.com/invoices?limit=25&page=2",
"prev": null
}
}
Retrieve a particular invoice
This endpoint allows you to retrieve a specific invoice by ID.
Path parameters
- Name
id- Type
- string
- Description
The invoice ID.
Request
curl -G https://api.spoonity.com/invoices/:id \
-H "Authorization: Bearer {token}"
Response
{
"id": "invo_835et56dy328sf93",
"customer_id": "cust_uhfhf63juwe7j84h",
"store_id": "stor_uri84ydhdt3453tw",
"cashier_id": "cash_74yeurgdtwyeh651",
"number": "INV-002",
"subtotal": 13.49,
"date_ordered": "2026-02-01T13:48:05.683Z",
"date_created": "2026-02-01T13:48:05.683Z",
"date_updated": "2026-02-01T13:48:05.683Z",
"status": "COMPLETE",
}
Create an invoice
This endpoint allows you to add a new invoice. Invoices can be created atomically, or in parts through the use of the line items, payments, and discounts endpoints.
Required attributes
- Name
customer_id- Type
- string
- Description
ID of the customer the invoice belongs to.
- Name
store_id- Type
- string
- Description
ID of the store where the invoice was processed.
- Name
cashier_id- Type
- string
- Description
ID of the cashier who processed the invoice.
- Name
number- Type
- string
- Description
Unique identifier for the invoice, typically created by the POS system.
- Name
subtotal- Type
- string
- Description
Subtotal of the invoice, excluding discounts.
- Name
date_ordered- Type
- string
- Description
POS order date.
Request
curl -G https://api.spoonity.com/invoices \
-H "Authorization: Bearer {token}" \
-d name="Points"
Response
{
"id": "invo_835et56dy328sf93",
"customer_id": "cust_uhfhf63juwe7j84h",
"store_id": "stor_uri84ydhdt3453tw",
"cashier_id": "cash_74yeurgdtwyeh651",
"number": "INV-002",
"subtotal": 13.49,
"date_ordered": "2026-02-01T13:48:05.683Z",
"date_created": "2026-02-01T13:48:05.683Z",
"date_updated": "2026-02-01T13:48:05.683Z",
"status": "COMPLETE",
}
Update an invoice
This endpoint allows you to update an invoice. Only ACTIVE invoices can be updated.
Path parameters
- Name
id- Type
- string
- Description
The invoice ID.
Optional attributes
- Name
subtotal- Type
- string
- Description
Subtotal of the invoice, excluding discounts.
- Name
date_ordered- Type
- string
- Description
POS order date.
Request
curl -G https://api.spoonity.com/invoices/:id \
--request PUT \
-H "Authorization: Bearer {token}" \
-d subtotal=10.99
Response
{
"id": "invo_835et56dy328sf93",
"customer_id": "cust_uhfhf63juwe7j84h",
"store_id": "stor_uri84ydhdt3453tw",
"cashier_id": "cash_74yeurgdtwyeh651",
"number": "INV-002",
"subtotal": 10.99,
"date_ordered": "2026-02-01T13:48:05.683Z",
"date_created": "2026-02-01T13:48:05.683Z",
"date_updated": "2026-02-01T13:48:05.683Z",
"status": "ACTIVE",
}
Void or delete an invoice
This endpoint allows you to void or delete an invoice. Open invoices are deleted, and voided invoices are cancelled.
Path parameters
- Name
id- Type
- string
- Description
The invoice ID.
Request
curl -G https://api.spoonity.com/invoices/:id \
--request DELETE \
-H "Authorization: Bearer {token}"
Response
{}