Products
Catalogue products. Each product belongs to a product group and carries one or more prices.
List products
Credential: a company's API key or OAuth token.
Retrieves a paginated list of your company's products, each including its
prices. Each price carries its billingPeriodType, so a product with a
one_time price can be told apart from a recurring-only one without
fetching each product. Recurring and usage prices are listed only for a
company with the Subscriptions module. Each product carries its full
metadata map; entitlements are returned by the single-product endpoint.
Pass ?search= to prefix-match on product name or number, or
?productGroupId= to narrow the list to one product group.
Pass metadata[key]=value query parameters to return only the products
whose metadata carries every given key with exactly the given value (AND
semantics, exact match, at most 10 pairs). The filter composes with
search and productGroupId, and total counts the filtered set. A
request with more than 10 pairs returns 400 with error code
METADATA_TOO_MANY_FILTERS.
Pagination
Pass each response's nextCursor back as cursor, with the same filters
and sort, until hasMore is false. Paging by page is deprecated, and
page cannot be sent with cursor (400 PAGINATION_CURSOR_WITH_PAGE). A
cursor replayed with other filters or another sort is refused with
400 PAGINATION_INVALID_CURSOR.
Required Scope
products-read
query Parameters
cursorOpaque cursor from the previous response's nextCursor. Returns the rows after it, in the same order. Send the same filters and sort as the request that produced it, and do not send page. The preferred way to page through a list.
pageDeprecated: page with cursor instead. Page number (1-indexed). From 2026-12-31, a page past the first of a list with more than 10,000 matching rows is refused.
limitMaximum number of items per page
searchPrefix search on name or number
productGroupIdFilter by product group ID
sortByField to sort by
sortOrderSort direction
Exact-match metadata filters in the form metadata[key]=value. Multiple pairs combine with AND semantics — a record matches only if it carries every given key with exactly the given value. At most 10 pairs per request.
List products › Responses
Paginated list of products for the company matching the given filters (each includes its prices)
Page of products, each with its prices (GET one product for its entitlements)
totalTotal number of matching products
limitItems per page
nextCursorCursor for the next page; pass it as cursor. null on the last page, and on every page of a sort that cannot page by cursor — hasMore then says whether another page follows by page number.
hasMoreWhether more rows follow this page.
pageDeprecated: page with nextCursor instead. Current page number.
totalPagesDeprecated: page with nextCursor instead. Total number of pages.
Create a product
Credential: a company's API key or OAuth token.
Creates a product.
An optional initial price can be supplied inline — it is created, activated, and set as the product's default price in the same transaction.
An optional metadata map (string keys to string values, at most 50 entries,
keys up to 128 characters, values up to 500 characters) is stored with the
product and echoed on the response. An invalid map is rejected before the
product is created, with error code METADATA_KEY_REQUIRED,
METADATA_KEY_TOO_LONG, METADATA_VALUE_TOO_LONG,
METADATA_DUPLICATE_KEY or METADATA_TOO_MANY_ENTRIES.
Required Scope
products-write
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Create a product › Request Body
productNumberUnique product number within the company
nameName of the product
unitUnit of measurement
productGroupIdProduct group this product belongs to (must exist)
descriptionOptional description
isActiveWhether the product is active
productTypeProduct type (goods or services)
allowFreePriceWhether a price of 0 on this product is a deliberate free price. Off, a price of 0 cannot be saved.
Optional initial price. If provided it is created, activated and set as default in one transaction.
entitlementIdsExternally managed entitlement IDs to bind (max 100)
Key-value metadata to attach to the product. At most 50 entries; keys up to 128 characters, string values up to 500 characters.
Create a product › Responses
Product created successfully
idThe unique identifier of the product
productNumberUnique product number within the company
nameName of the product
unitUnit of measurement
productGroupIdProduct group this product belongs to
productTypeProduct type (goods or services) for EU VAT
isActiveWhether the product is active
isArchivedWhether the product is archived
isLockedWhether the product is locked (in use, cannot be deleted)
allowFreePriceWhether a price of 0 on this product is a deliberate free price. Off, a price of 0 cannot be saved and a stored 0 reads as no price set.
createdAtWhen the product was created
updatedAtWhen the product was last updated
descriptionOptional description
Prices configured for this product
Entitlements granted by this product
Key-value metadata attached to the product
Get a product
Credential: a company's API key or OAuth token.
Returns a single product, including its prices.
Required Scope
products-read
path Parameters
productIdProduct ID
Get a product › Responses
Product details, including its prices
idThe unique identifier of the product
productNumberUnique product number within the company
nameName of the product
unitUnit of measurement
productGroupIdProduct group this product belongs to
productTypeProduct type (goods or services) for EU VAT
isActiveWhether the product is active
isArchivedWhether the product is archived
isLockedWhether the product is locked (in use, cannot be deleted)
allowFreePriceWhether a price of 0 on this product is a deliberate free price. Off, a price of 0 cannot be saved and a stored 0 reads as no price set.
createdAtWhen the product was created
updatedAtWhen the product was last updated
descriptionOptional description
Prices configured for this product
Entitlements granted by this product
Key-value metadata attached to the product
Delete a product
Credential: a company's API key or OAuth token.
Deletes a product. A product that is locked (in use) cannot be deleted.
A product that a quote, an order confirmation or another record uses is refused
with 409 and the code PRODUCT_IN_USE; details.documents names up to ten of
those quotes and order confirmations and details.documentCount counts them all.
Archive such a product instead.
Deleting a product also deletes its metadata.
Required Scope
products-write
path Parameters
productIdProduct ID
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Delete a product › Responses
Product deleted successfully
Update a product
Credential: a company's API key or OAuth token.
Updates a product. Only the fields provided in the request are changed.
When metadata is provided it replaces the product's metadata wholesale:
send the complete desired map, and send an empty object ({}) to clear
every entry. Omit the field to leave the metadata unchanged. The response
carries the resulting map.
Required Scope
products-write
path Parameters
productIdProduct ID
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Update a product › Request Body
productNumberUnique product number within the company
nameName of the product
descriptionOptional description
unitUnit of measurement
productGroupIdProduct group this product belongs to
isActiveWhether the product is active
productTypeProduct type (goods or services)
allowFreePriceWhether a price of 0 on this product is a deliberate free price. Omit to leave unchanged. Turning it off leaves stored prices as they are.
entitlementIdsExternally managed entitlement IDs to bind (max 100)
Key-value metadata. When provided, REPLACES the product metadata wholesale — send the complete desired map; an empty object clears all entries. Omit the field to leave metadata unchanged. At most 50 entries; keys up to 128 characters, string values up to 500 characters.
Update a product › Responses
Product updated successfully
idThe unique identifier of the product
productNumberUnique product number within the company
nameName of the product
unitUnit of measurement
productGroupIdProduct group this product belongs to
productTypeProduct type (goods or services) for EU VAT
isActiveWhether the product is active
isArchivedWhether the product is archived
isLockedWhether the product is locked (in use, cannot be deleted)
allowFreePriceWhether a price of 0 on this product is a deliberate free price. Off, a price of 0 cannot be saved and a stored 0 reads as no price set.
createdAtWhen the product was created
updatedAtWhen the product was last updated
descriptionOptional description
Prices configured for this product
Entitlements granted by this product
Key-value metadata attached to the product
Archive a product
Credential: a company's API key or OAuth token.
Archives a product and every price on it. Nothing new can be sold against an
archived product, while the subscriptions and documents already referencing it
keep resolving — which is why this, not DELETE, is what a product in use
gets. There is no unarchive.
Archiving keeps the product's metadata; the response carries it unchanged.
Required Scope
products-write
path Parameters
productIdProduct ID
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Archive a product › Responses
Product archived successfully
idThe unique identifier of the product
productNumberUnique product number within the company
nameName of the product
unitUnit of measurement
productGroupIdProduct group this product belongs to
productTypeProduct type (goods or services) for EU VAT
isActiveWhether the product is active
isArchivedWhether the product is archived
isLockedWhether the product is locked (in use, cannot be deleted)
allowFreePriceWhether a price of 0 on this product is a deliberate free price. Off, a price of 0 cannot be saved and a stored 0 reads as no price set.
createdAtWhen the product was created
updatedAtWhen the product was last updated
descriptionOptional description
Prices configured for this product
Entitlements granted by this product
Key-value metadata attached to the product