Arguments, results, errors, and access, confirmation, and retry policy for each Products tool in FloPay MCP, from the reviewed API contract.

Products tools

Generated from the FloPay MCP contract version 1, revision 764b41d5c7205d6df7eeaeac832fafe882247f5526b1d4d6bc6f98e3eaca7784.

Collection_create

Create Collection

Creates a collection optionally containing a set of products.

Policy	Value
Operation	`POST /v1/collections`
Class	`mutating`
Risk	`medium`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`mutation`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`code`	body	string	Yes	Minimum length: 1. Maximum length: 255.
`description`	body	string	No	Minimum length: 0. Maximum length: 1000.
`name`	body	string	Yes	Minimum length: 1. Maximum length: 255.
`productIds`	body	array of string (uuid)	No	Product ids in this collection.

Result

Returns 201 with a JSON body.

Field	Type	Required	Description
`code`	string	Yes
`createdAt`	string (date-time)	Yes
`description`	string or null	Yes
`id`	string	Yes
`name`	string	Yes
`products`	array of object	Yes
`products[].ageGroup`	string or null	Yes
`products[].attributes`	object or null	Yes
`products[].availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`products[].brand`	object or null	Yes
`products[].brand.code`	string	Yes
`products[].brand.createdAt`	string (date-time)	Yes
`products[].brand.description`	string or null	Yes
`products[].brand.id`	string	Yes
`products[].brand.name`	string	Yes
`products[].brand.updatedAt`	string (date-time)	Yes
`products[].category`	object or null	Yes
`products[].category.code`	string	Yes
`products[].category.createdAt`	string (date-time)	Yes
`products[].category.description`	string or null	Yes
`products[].category.id`	string	Yes
`products[].category.name`	string	Yes
`products[].category.parentId`	string (uuid) or null	Yes
`products[].category.updatedAt`	string (date-time)	Yes
`products[].code`	string	Yes
`products[].createdAt`	string (date-time)	Yes
`products[].description`	string or null	Yes
`products[].gender`	string or null	Yes
`products[].gtin`	string or null	Yes
`products[].heightMm`	number or null	Yes
`products[].id`	string	Yes
`products[].knowledgeBaseUrl`	string or null	Yes
`products[].lengthMm`	number or null	Yes
`products[].longDescription`	string or null	Yes
`products[].media`	array of object	Yes
`products[].media[].altText`	string or null	Yes
`products[].media[].createdAt`	string (date-time)	Yes
`products[].media[].id`	string	Yes
`products[].media[].isPrimary`	boolean	Yes
`products[].media[].position`	number	Yes
`products[].media[].type`	string	Yes	Allowed values: `image`, `video`, `model_3d`, `document`.
`products[].media[].updatedAt`	string (date-time)	Yes
`products[].media[].url`	string	Yes
`products[].media[].variantId`	string (uuid) or null	Yes
`products[].metadata`	object or null	Yes
`products[].name`	string	Yes
`products[].prices`	array of object	Yes
`products[].prices[].amount`	number	Yes	Base price in major units.
`products[].prices[].createdAt`	string (date-time)	Yes
`products[].prices[].currency`	string	Yes	ISO-4217 currency code.
`products[].prices[].effectiveAmount`	number	Yes	Sale price when the current time is in the sale window, otherwise the base amount.
`products[].prices[].id`	string	Yes
`products[].prices[].rebillAtSaleAmount`	boolean	Yes	When false an active sale applies to the first subscription charge only (rebills revert to the full amount); when true the sale price is retained for the subscription lifetime.
`products[].prices[].saleAmount`	number or null	Yes	Sale price; populated only when sale window is set.
`products[].prices[].saleEndsAt`	string (date-time) or null	Yes
`products[].prices[].saleStartsAt`	string (date-time) or null	Yes
`products[].prices[].status`	string	Yes	Inactive prices remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`products[].prices[].updatedAt`	string (date-time)	Yes
`products[].prices[].variantId`	string (uuid) or null	Yes
`products[].recurringInterval`	string or null	Yes	Allowed values: `day`, `week`, `month`, `year`.
`products[].recurringIntervalCount`	number or null	Yes
`products[].recurringTrialPeriodDays`	number or null	Yes
`products[].recurringTrialPeriodDaysFree`	boolean	Yes	Whether the trial period is free. When `false` the trial period is charged the effective sale price before rebilling at the recurring price.
`products[].status`	string	Yes	Catalog lifecycle state. Inactive products retain identity and history but cannot be sold. Allowed values: `active`, `inactive`.
`products[].stockQuantity`	number or null	Yes
`products[].tags`	array of string or null	Yes
`products[].tangibility`	string or null	Yes	Allowed values: `digital`, `physical`.
`products[].taxCode`	string or null	Yes
`products[].type`	string	Yes	Allowed values: `subscription`, `item`.
`products[].updatedAt`	string (date-time)	Yes
`products[].variants`	array of object	Yes
`products[].variants[].attributes`	object or null	Yes
`products[].variants[].availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`products[].variants[].createdAt`	string (date-time)	Yes
`products[].variants[].heightMm`	number or null	Yes
`products[].variants[].id`	string	Yes
`products[].variants[].lengthMm`	number or null	Yes
`products[].variants[].name`	string or null	Yes
`products[].variants[].sku`	string	Yes
`products[].variants[].status`	string	Yes	Inactive variants remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`products[].variants[].stockQuantity`	number or null	Yes
`products[].variants[].updatedAt`	string (date-time)	Yes
`products[].variants[].weightGrams`	number or null	Yes
`products[].variants[].widthMm`	number or null	Yes
`products[].weightGrams`	number or null	Yes
`products[].widthMm`	number or null	Yes
`updatedAt`	string (date-time)	Yes

Errors

Status	Description
`400`	The supplied request body or list query is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Collection mutations require an owner or admin membership.

Collection_findOne

Get Collection

Returns a single collection with its products.

Policy	Value
Operation	`GET /v1/collections/{uuid}`
Class	`read-only`
Risk	`low`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`read`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`uuid`	path	string	Yes

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`code`	string	Yes
`createdAt`	string (date-time)	Yes
`description`	string or null	Yes
`id`	string	Yes
`name`	string	Yes
`products`	array of object	Yes
`products[].ageGroup`	string or null	Yes
`products[].attributes`	object or null	Yes
`products[].availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`products[].brand`	object or null	Yes
`products[].brand.code`	string	Yes
`products[].brand.createdAt`	string (date-time)	Yes
`products[].brand.description`	string or null	Yes
`products[].brand.id`	string	Yes
`products[].brand.name`	string	Yes
`products[].brand.updatedAt`	string (date-time)	Yes
`products[].category`	object or null	Yes
`products[].category.code`	string	Yes
`products[].category.createdAt`	string (date-time)	Yes
`products[].category.description`	string or null	Yes
`products[].category.id`	string	Yes
`products[].category.name`	string	Yes
`products[].category.parentId`	string (uuid) or null	Yes
`products[].category.updatedAt`	string (date-time)	Yes
`products[].code`	string	Yes
`products[].createdAt`	string (date-time)	Yes
`products[].description`	string or null	Yes
`products[].gender`	string or null	Yes
`products[].gtin`	string or null	Yes
`products[].heightMm`	number or null	Yes
`products[].id`	string	Yes
`products[].knowledgeBaseUrl`	string or null	Yes
`products[].lengthMm`	number or null	Yes
`products[].longDescription`	string or null	Yes
`products[].media`	array of object	Yes
`products[].media[].altText`	string or null	Yes
`products[].media[].createdAt`	string (date-time)	Yes
`products[].media[].id`	string	Yes
`products[].media[].isPrimary`	boolean	Yes
`products[].media[].position`	number	Yes
`products[].media[].type`	string	Yes	Allowed values: `image`, `video`, `model_3d`, `document`.
`products[].media[].updatedAt`	string (date-time)	Yes
`products[].media[].url`	string	Yes
`products[].media[].variantId`	string (uuid) or null	Yes
`products[].metadata`	object or null	Yes
`products[].name`	string	Yes
`products[].prices`	array of object	Yes
`products[].prices[].amount`	number	Yes	Base price in major units.
`products[].prices[].createdAt`	string (date-time)	Yes
`products[].prices[].currency`	string	Yes	ISO-4217 currency code.
`products[].prices[].effectiveAmount`	number	Yes	Sale price when the current time is in the sale window, otherwise the base amount.
`products[].prices[].id`	string	Yes
`products[].prices[].rebillAtSaleAmount`	boolean	Yes	When false an active sale applies to the first subscription charge only (rebills revert to the full amount); when true the sale price is retained for the subscription lifetime.
`products[].prices[].saleAmount`	number or null	Yes	Sale price; populated only when sale window is set.
`products[].prices[].saleEndsAt`	string (date-time) or null	Yes
`products[].prices[].saleStartsAt`	string (date-time) or null	Yes
`products[].prices[].status`	string	Yes	Inactive prices remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`products[].prices[].updatedAt`	string (date-time)	Yes
`products[].prices[].variantId`	string (uuid) or null	Yes
`products[].recurringInterval`	string or null	Yes	Allowed values: `day`, `week`, `month`, `year`.
`products[].recurringIntervalCount`	number or null	Yes
`products[].recurringTrialPeriodDays`	number or null	Yes
`products[].recurringTrialPeriodDaysFree`	boolean	Yes	Whether the trial period is free. When `false` the trial period is charged the effective sale price before rebilling at the recurring price.
`products[].status`	string	Yes	Catalog lifecycle state. Inactive products retain identity and history but cannot be sold. Allowed values: `active`, `inactive`.
`products[].stockQuantity`	number or null	Yes
`products[].tags`	array of string or null	Yes
`products[].tangibility`	string or null	Yes	Allowed values: `digital`, `physical`.
`products[].taxCode`	string or null	Yes
`products[].type`	string	Yes	Allowed values: `subscription`, `item`.
`products[].updatedAt`	string (date-time)	Yes
`products[].variants`	array of object	Yes
`products[].variants[].attributes`	object or null	Yes
`products[].variants[].availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`products[].variants[].createdAt`	string (date-time)	Yes
`products[].variants[].heightMm`	number or null	Yes
`products[].variants[].id`	string	Yes
`products[].variants[].lengthMm`	number or null	Yes
`products[].variants[].name`	string or null	Yes
`products[].variants[].sku`	string	Yes
`products[].variants[].status`	string	Yes	Inactive variants remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`products[].variants[].stockQuantity`	number or null	Yes
`products[].variants[].updatedAt`	string (date-time)	Yes
`products[].variants[].weightGrams`	number or null	Yes
`products[].variants[].widthMm`	number or null	Yes
`products[].weightGrams`	number or null	Yes
`products[].widthMm`	number or null	Yes
`updatedAt`	string (date-time)	Yes

Errors

Status	Description
`400`	The supplied request body or list query is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Collection mutations require an owner or admin membership.
`404`	No collection with the requested id exists for this client.

Collection_list

List Collections

Returns paginated collections for the authenticated client. Supports page, limit, sort[asc|desc], and whitelisted filters for id, code, name, createdAt, and updatedAt.

Policy	Value
Operation	`GET /v1/collections`
Class	`read-only`
Risk	`low`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`read`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`page`	query	integer	No	1-based page number for paginated list endpoints. Default: `1`. Minimum: 1.
`limit`	query	integer	No	Maximum number of records to return per page. Default: `20`. Minimum: 1. Maximum: 100.
`sort`	query	string	No	Sort by one allowed field. Use exactly one of `sort[asc]` or `sort[desc]`. Allowed fields: `code`, `createdAt`, `name`, `updatedAt`. Default: `createdAt` DESC. Allowed values: `code`, `createdAt`, `name`, `updatedAt`.
`relation`	query	string	No	This endpoint does not support relation aliases. Supplying relation returns 400.
`code`	query	string	No	Client-defined collection code. Equality filter. Pass without operator for exact match or pass any of the following operators: `[search]`. `[search]` is case-insensitive text contains matching.
`createdAt`	query	string (date-time)	No	Collection creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`id`	query	string	No	Collection id. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`name`	query	string	No	Collection name. Equality filter. Pass without operator for exact match or pass any of the following operators: `[search]`. `[search]` is case-insensitive text contains matching.
`updatedAt`	query	string (date-time)	No	Collection update timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`data`	array of object	Yes
`data[].code`	string	Yes
`data[].createdAt`	string (date-time)	Yes
`data[].description`	string or null	Yes
`data[].id`	string	Yes
`data[].name`	string	Yes
`data[].products`	array of object	Yes
`data[].products[].ageGroup`	string or null	Yes
`data[].products[].attributes`	object or null	Yes
`data[].products[].availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`data[].products[].brand`	object or null	Yes
`data[].products[].brand.code`	string	Yes
`data[].products[].brand.createdAt`	string (date-time)	Yes
`data[].products[].brand.description`	string or null	Yes
`data[].products[].brand.id`	string	Yes
`data[].products[].brand.name`	string	Yes
`data[].products[].brand.updatedAt`	string (date-time)	Yes
`data[].products[].category`	object or null	Yes
`data[].products[].category.code`	string	Yes
`data[].products[].category.createdAt`	string (date-time)	Yes
`data[].products[].category.description`	string or null	Yes
`data[].products[].category.id`	string	Yes
`data[].products[].category.name`	string	Yes
`data[].products[].category.parentId`	string (uuid) or null	Yes
`data[].products[].category.updatedAt`	string (date-time)	Yes
`data[].products[].code`	string	Yes
`data[].products[].createdAt`	string (date-time)	Yes
`data[].products[].description`	string or null	Yes
`data[].products[].gender`	string or null	Yes
`data[].products[].gtin`	string or null	Yes
`data[].products[].heightMm`	number or null	Yes
`data[].products[].id`	string	Yes
`data[].products[].knowledgeBaseUrl`	string or null	Yes
`data[].products[].lengthMm`	number or null	Yes
`data[].products[].longDescription`	string or null	Yes
`data[].products[].media`	array of object	Yes
`data[].products[].media[].altText`	string or null	Yes
`data[].products[].media[].createdAt`	string (date-time)	Yes
`data[].products[].media[].id`	string	Yes
`data[].products[].media[].isPrimary`	boolean	Yes
`data[].products[].media[].position`	number	Yes
`data[].products[].media[].type`	string	Yes	Allowed values: `image`, `video`, `model_3d`, `document`.
`data[].products[].media[].updatedAt`	string (date-time)	Yes
`data[].products[].media[].url`	string	Yes
`data[].products[].media[].variantId`	string (uuid) or null	Yes
`data[].products[].metadata`	object or null	Yes
`data[].products[].name`	string	Yes
`data[].products[].prices`	array of object	Yes
`data[].products[].prices[].amount`	number	Yes	Base price in major units.
`data[].products[].prices[].createdAt`	string (date-time)	Yes
`data[].products[].prices[].currency`	string	Yes	ISO-4217 currency code.
`data[].products[].prices[].effectiveAmount`	number	Yes	Sale price when the current time is in the sale window, otherwise the base amount.
`data[].products[].prices[].id`	string	Yes
`data[].products[].prices[].rebillAtSaleAmount`	boolean	Yes	When false an active sale applies to the first subscription charge only (rebills revert to the full amount); when true the sale price is retained for the subscription lifetime.
`data[].products[].prices[].saleAmount`	number or null	Yes	Sale price; populated only when sale window is set.
`data[].products[].prices[].saleEndsAt`	string (date-time) or null	Yes
`data[].products[].prices[].saleStartsAt`	string (date-time) or null	Yes
`data[].products[].prices[].status`	string	Yes	Inactive prices remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`data[].products[].prices[].updatedAt`	string (date-time)	Yes
`data[].products[].prices[].variantId`	string (uuid) or null	Yes
`data[].products[].recurringInterval`	string or null	Yes	Allowed values: `day`, `week`, `month`, `year`.
`data[].products[].recurringIntervalCount`	number or null	Yes
`data[].products[].recurringTrialPeriodDays`	number or null	Yes
`data[].products[].recurringTrialPeriodDaysFree`	boolean	Yes	Whether the trial period is free. When `false` the trial period is charged the effective sale price before rebilling at the recurring price.
`data[].products[].status`	string	Yes	Catalog lifecycle state. Inactive products retain identity and history but cannot be sold. Allowed values: `active`, `inactive`.
`data[].products[].stockQuantity`	number or null	Yes
`data[].products[].tags`	array of string or null	Yes
`data[].products[].tangibility`	string or null	Yes	Allowed values: `digital`, `physical`.
`data[].products[].taxCode`	string or null	Yes
`data[].products[].type`	string	Yes	Allowed values: `subscription`, `item`.
`data[].products[].updatedAt`	string (date-time)	Yes
`data[].products[].variants`	array of object	Yes
`data[].products[].variants[].attributes`	object or null	Yes
`data[].products[].variants[].availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`data[].products[].variants[].createdAt`	string (date-time)	Yes
`data[].products[].variants[].heightMm`	number or null	Yes
`data[].products[].variants[].id`	string	Yes
`data[].products[].variants[].lengthMm`	number or null	Yes
`data[].products[].variants[].name`	string or null	Yes
`data[].products[].variants[].sku`	string	Yes
`data[].products[].variants[].status`	string	Yes	Inactive variants remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`data[].products[].variants[].stockQuantity`	number or null	Yes
`data[].products[].variants[].updatedAt`	string (date-time)	Yes
`data[].products[].variants[].weightGrams`	number or null	Yes
`data[].products[].variants[].widthMm`	number or null	Yes
`data[].products[].weightGrams`	number or null	Yes
`data[].products[].widthMm`	number or null	Yes
`data[].updatedAt`	string (date-time)	Yes
`limit`	number	Yes
`page`	number	Yes
`pages`	number	Yes
`total`	number	Yes

Errors

Status	Description
`400`	The supplied request body or list query is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Collection mutations require an owner or admin membership.

Collection_update

Update Collection

Updates a collection. Products are replaced when productIds is supplied.

Policy	Value
Operation	`PATCH /v1/collections/{uuid}`
Class	`mutating`
Risk	`medium`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`mutation`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`uuid`	path	string	Yes
`code`	body	string	No	Minimum length: 1. Maximum length: 255.
`description`	body	string	No	Minimum length: 0. Maximum length: 1000.
`name`	body	string	No	Minimum length: 1. Maximum length: 255.
`productIds`	body	array of string (uuid)	No	Product ids in this collection.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`code`	string	Yes
`createdAt`	string (date-time)	Yes
`description`	string or null	Yes
`id`	string	Yes
`name`	string	Yes
`products`	array of object	Yes
`products[].ageGroup`	string or null	Yes
`products[].attributes`	object or null	Yes
`products[].availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`products[].brand`	object or null	Yes
`products[].brand.code`	string	Yes
`products[].brand.createdAt`	string (date-time)	Yes
`products[].brand.description`	string or null	Yes
`products[].brand.id`	string	Yes
`products[].brand.name`	string	Yes
`products[].brand.updatedAt`	string (date-time)	Yes
`products[].category`	object or null	Yes
`products[].category.code`	string	Yes
`products[].category.createdAt`	string (date-time)	Yes
`products[].category.description`	string or null	Yes
`products[].category.id`	string	Yes
`products[].category.name`	string	Yes
`products[].category.parentId`	string (uuid) or null	Yes
`products[].category.updatedAt`	string (date-time)	Yes
`products[].code`	string	Yes
`products[].createdAt`	string (date-time)	Yes
`products[].description`	string or null	Yes
`products[].gender`	string or null	Yes
`products[].gtin`	string or null	Yes
`products[].heightMm`	number or null	Yes
`products[].id`	string	Yes
`products[].knowledgeBaseUrl`	string or null	Yes
`products[].lengthMm`	number or null	Yes
`products[].longDescription`	string or null	Yes
`products[].media`	array of object	Yes
`products[].media[].altText`	string or null	Yes
`products[].media[].createdAt`	string (date-time)	Yes
`products[].media[].id`	string	Yes
`products[].media[].isPrimary`	boolean	Yes
`products[].media[].position`	number	Yes
`products[].media[].type`	string	Yes	Allowed values: `image`, `video`, `model_3d`, `document`.
`products[].media[].updatedAt`	string (date-time)	Yes
`products[].media[].url`	string	Yes
`products[].media[].variantId`	string (uuid) or null	Yes
`products[].metadata`	object or null	Yes
`products[].name`	string	Yes
`products[].prices`	array of object	Yes
`products[].prices[].amount`	number	Yes	Base price in major units.
`products[].prices[].createdAt`	string (date-time)	Yes
`products[].prices[].currency`	string	Yes	ISO-4217 currency code.
`products[].prices[].effectiveAmount`	number	Yes	Sale price when the current time is in the sale window, otherwise the base amount.
`products[].prices[].id`	string	Yes
`products[].prices[].rebillAtSaleAmount`	boolean	Yes	When false an active sale applies to the first subscription charge only (rebills revert to the full amount); when true the sale price is retained for the subscription lifetime.
`products[].prices[].saleAmount`	number or null	Yes	Sale price; populated only when sale window is set.
`products[].prices[].saleEndsAt`	string (date-time) or null	Yes
`products[].prices[].saleStartsAt`	string (date-time) or null	Yes
`products[].prices[].status`	string	Yes	Inactive prices remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`products[].prices[].updatedAt`	string (date-time)	Yes
`products[].prices[].variantId`	string (uuid) or null	Yes
`products[].recurringInterval`	string or null	Yes	Allowed values: `day`, `week`, `month`, `year`.
`products[].recurringIntervalCount`	number or null	Yes
`products[].recurringTrialPeriodDays`	number or null	Yes
`products[].recurringTrialPeriodDaysFree`	boolean	Yes	Whether the trial period is free. When `false` the trial period is charged the effective sale price before rebilling at the recurring price.
`products[].status`	string	Yes	Catalog lifecycle state. Inactive products retain identity and history but cannot be sold. Allowed values: `active`, `inactive`.
`products[].stockQuantity`	number or null	Yes
`products[].tags`	array of string or null	Yes
`products[].tangibility`	string or null	Yes	Allowed values: `digital`, `physical`.
`products[].taxCode`	string or null	Yes
`products[].type`	string	Yes	Allowed values: `subscription`, `item`.
`products[].updatedAt`	string (date-time)	Yes
`products[].variants`	array of object	Yes
`products[].variants[].attributes`	object or null	Yes
`products[].variants[].availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`products[].variants[].createdAt`	string (date-time)	Yes
`products[].variants[].heightMm`	number or null	Yes
`products[].variants[].id`	string	Yes
`products[].variants[].lengthMm`	number or null	Yes
`products[].variants[].name`	string or null	Yes
`products[].variants[].sku`	string	Yes
`products[].variants[].status`	string	Yes	Inactive variants remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`products[].variants[].stockQuantity`	number or null	Yes
`products[].variants[].updatedAt`	string (date-time)	Yes
`products[].variants[].weightGrams`	number or null	Yes
`products[].variants[].widthMm`	number or null	Yes
`products[].weightGrams`	number or null	Yes
`products[].widthMm`	number or null	Yes
`updatedAt`	string (date-time)	Yes

Errors

Status	Description
`400`	The supplied request body or list query is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Collection mutations require an owner or admin membership.
`404`	No collection with the requested id exists for this client.

Coupon_create

Create Coupon

Creates a coupon optionally scoped to a list of products.

Policy	Value
Operation	`POST /v1/coupons`
Class	`mutating`
Risk	`medium`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`mutation`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`code`	body	string	Yes	Minimum length: 1. Maximum length: 255.
`description`	body	string	No	Minimum length: 0. Maximum length: 1000.
`duration`	body	string	Yes	Allowed values: `forever`, `once`, `repeating`.
`metadata`	body	object	No
`name`	body	string	Yes	Minimum length: 1. Maximum length: 255.
`percentageOff`	body	number	No	Percent discount in major units, e.g. 10 for 10%. Required when type is percentage. Must be omitted when type is amount. Minimum: 0.01. Maximum: 100.
`prices`	body	array of object	No	Required when type is amount. Must be omitted when type is percentage. Minimum items: 1.
`prices[].amount`	body	number	Yes	Discount amount in major units. Up to 2 decimal places. Minimum: 0. Maximum: 99999999.99.
`prices[].currency`	body	string	Yes	Minimum length: 3. Maximum length: 3.
`productIds`	body	array of string (uuid)	No	Product ids this coupon applies to. Empty or omitted means the coupon applies to every product.
`repeatingIntervalCount`	body	number	No	Number of intervals the coupon repeats for (only used when duration is repeating). Minimum: 1.
`stackable`	body	boolean	No	Whether this coupon may be combined with other coupons in the same checkout session. Defaults to false; when false, the coupon cannot appear alongside any other coupon code in a multi-coupon request. Default: `false`.
`type`	body	string	Yes	Allowed values: `percentage`, `amount`.

Result

Returns 201 with a JSON body.

Field	Type	Required	Description
`code`	string	Yes
`createdAt`	string (date-time)	Yes
`description`	string or null	Yes
`duration`	string	Yes	Allowed values: `forever`, `once`, `repeating`.
`id`	string	Yes
`metadata`	object or null	Yes
`name`	string	Yes
`percentageOff`	number or null	Yes	Percent discount in major units. Populated when type is percentage; null otherwise.
`prices`	array of object	Yes
`prices[].amount`	number	Yes	Discount amount in major units.
`prices[].createdAt`	string (date-time)	Yes
`prices[].currency`	string	Yes	ISO-4217 currency code.
`prices[].id`	string	Yes
`prices[].updatedAt`	string (date-time)	Yes
`products`	array of object	Yes	Empty array means the coupon applies to every product.
`products[].ageGroup`	string or null	Yes
`products[].attributes`	object or null	Yes
`products[].availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`products[].brand`	object or null	Yes
`products[].brand.code`	string	Yes
`products[].brand.createdAt`	string (date-time)	Yes
`products[].brand.description`	string or null	Yes
`products[].brand.id`	string	Yes
`products[].brand.name`	string	Yes
`products[].brand.updatedAt`	string (date-time)	Yes
`products[].category`	object or null	Yes
`products[].category.code`	string	Yes
`products[].category.createdAt`	string (date-time)	Yes
`products[].category.description`	string or null	Yes
`products[].category.id`	string	Yes
`products[].category.name`	string	Yes
`products[].category.parentId`	string (uuid) or null	Yes
`products[].category.updatedAt`	string (date-time)	Yes
`products[].code`	string	Yes
`products[].createdAt`	string (date-time)	Yes
`products[].description`	string or null	Yes
`products[].gender`	string or null	Yes
`products[].gtin`	string or null	Yes
`products[].heightMm`	number or null	Yes
`products[].id`	string	Yes
`products[].knowledgeBaseUrl`	string or null	Yes
`products[].lengthMm`	number or null	Yes
`products[].longDescription`	string or null	Yes
`products[].media`	array of object	Yes
`products[].media[].altText`	string or null	Yes
`products[].media[].createdAt`	string (date-time)	Yes
`products[].media[].id`	string	Yes
`products[].media[].isPrimary`	boolean	Yes
`products[].media[].position`	number	Yes
`products[].media[].type`	string	Yes	Allowed values: `image`, `video`, `model_3d`, `document`.
`products[].media[].updatedAt`	string (date-time)	Yes
`products[].media[].url`	string	Yes
`products[].media[].variantId`	string (uuid) or null	Yes
`products[].metadata`	object or null	Yes
`products[].name`	string	Yes
`products[].prices`	array of object	Yes
`products[].prices[].amount`	number	Yes	Base price in major units.
`products[].prices[].createdAt`	string (date-time)	Yes
`products[].prices[].currency`	string	Yes	ISO-4217 currency code.
`products[].prices[].effectiveAmount`	number	Yes	Sale price when the current time is in the sale window, otherwise the base amount.
`products[].prices[].id`	string	Yes
`products[].prices[].rebillAtSaleAmount`	boolean	Yes	When false an active sale applies to the first subscription charge only (rebills revert to the full amount); when true the sale price is retained for the subscription lifetime.
`products[].prices[].saleAmount`	number or null	Yes	Sale price; populated only when sale window is set.
`products[].prices[].saleEndsAt`	string (date-time) or null	Yes
`products[].prices[].saleStartsAt`	string (date-time) or null	Yes
`products[].prices[].status`	string	Yes	Inactive prices remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`products[].prices[].updatedAt`	string (date-time)	Yes
`products[].prices[].variantId`	string (uuid) or null	Yes
`products[].recurringInterval`	string or null	Yes	Allowed values: `day`, `week`, `month`, `year`.
`products[].recurringIntervalCount`	number or null	Yes
`products[].recurringTrialPeriodDays`	number or null	Yes
`products[].recurringTrialPeriodDaysFree`	boolean	Yes	Whether the trial period is free. When `false` the trial period is charged the effective sale price before rebilling at the recurring price.
`products[].status`	string	Yes	Catalog lifecycle state. Inactive products retain identity and history but cannot be sold. Allowed values: `active`, `inactive`.
`products[].stockQuantity`	number or null	Yes
`products[].tags`	array of string or null	Yes
`products[].tangibility`	string or null	Yes	Allowed values: `digital`, `physical`.
`products[].taxCode`	string or null	Yes
`products[].type`	string	Yes	Allowed values: `subscription`, `item`.
`products[].updatedAt`	string (date-time)	Yes
`products[].variants`	array of object	Yes
`products[].variants[].attributes`	object or null	Yes
`products[].variants[].availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`products[].variants[].createdAt`	string (date-time)	Yes
`products[].variants[].heightMm`	number or null	Yes
`products[].variants[].id`	string	Yes
`products[].variants[].lengthMm`	number or null	Yes
`products[].variants[].name`	string or null	Yes
`products[].variants[].sku`	string	Yes
`products[].variants[].status`	string	Yes	Inactive variants remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`products[].variants[].stockQuantity`	number or null	Yes
`products[].variants[].updatedAt`	string (date-time)	Yes
`products[].variants[].weightGrams`	number or null	Yes
`products[].variants[].widthMm`	number or null	Yes
`products[].weightGrams`	number or null	Yes
`products[].widthMm`	number or null	Yes
`repeatingIntervalCount`	number or null	Yes
`stackable`	boolean	Yes	Whether this coupon may be combined with other coupons in the same checkout session. When false, the coupon cannot appear alongside any other coupon code in a multi-coupon request.
`status`	string	Yes	Inactive coupons retain their code and history but cannot be applied to new checkouts. Allowed values: `active`, `inactive`.
`type`	string	Yes	Allowed values: `percentage`, `amount`.
`updatedAt`	string (date-time)	Yes

Errors

Status	Description
`400`	The supplied request body or list query is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Coupon mutations require an owner or admin membership.

Coupon_findOne

Get Coupon

Returns a single coupon with nested prices and products.

Policy	Value
Operation	`GET /v1/coupons/{uuid}`
Class	`read-only`
Risk	`low`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`read`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`uuid`	path	string	Yes

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`code`	string	Yes
`createdAt`	string (date-time)	Yes
`description`	string or null	Yes
`duration`	string	Yes	Allowed values: `forever`, `once`, `repeating`.
`id`	string	Yes
`metadata`	object or null	Yes
`name`	string	Yes
`percentageOff`	number or null	Yes	Percent discount in major units. Populated when type is percentage; null otherwise.
`prices`	array of object	Yes
`prices[].amount`	number	Yes	Discount amount in major units.
`prices[].createdAt`	string (date-time)	Yes
`prices[].currency`	string	Yes	ISO-4217 currency code.
`prices[].id`	string	Yes
`prices[].updatedAt`	string (date-time)	Yes
`products`	array of object	Yes	Empty array means the coupon applies to every product.
`products[].ageGroup`	string or null	Yes
`products[].attributes`	object or null	Yes
`products[].availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`products[].brand`	object or null	Yes
`products[].brand.code`	string	Yes
`products[].brand.createdAt`	string (date-time)	Yes
`products[].brand.description`	string or null	Yes
`products[].brand.id`	string	Yes
`products[].brand.name`	string	Yes
`products[].brand.updatedAt`	string (date-time)	Yes
`products[].category`	object or null	Yes
`products[].category.code`	string	Yes
`products[].category.createdAt`	string (date-time)	Yes
`products[].category.description`	string or null	Yes
`products[].category.id`	string	Yes
`products[].category.name`	string	Yes
`products[].category.parentId`	string (uuid) or null	Yes
`products[].category.updatedAt`	string (date-time)	Yes
`products[].code`	string	Yes
`products[].createdAt`	string (date-time)	Yes
`products[].description`	string or null	Yes
`products[].gender`	string or null	Yes
`products[].gtin`	string or null	Yes
`products[].heightMm`	number or null	Yes
`products[].id`	string	Yes
`products[].knowledgeBaseUrl`	string or null	Yes
`products[].lengthMm`	number or null	Yes
`products[].longDescription`	string or null	Yes
`products[].media`	array of object	Yes
`products[].media[].altText`	string or null	Yes
`products[].media[].createdAt`	string (date-time)	Yes
`products[].media[].id`	string	Yes
`products[].media[].isPrimary`	boolean	Yes
`products[].media[].position`	number	Yes
`products[].media[].type`	string	Yes	Allowed values: `image`, `video`, `model_3d`, `document`.
`products[].media[].updatedAt`	string (date-time)	Yes
`products[].media[].url`	string	Yes
`products[].media[].variantId`	string (uuid) or null	Yes
`products[].metadata`	object or null	Yes
`products[].name`	string	Yes
`products[].prices`	array of object	Yes
`products[].prices[].amount`	number	Yes	Base price in major units.
`products[].prices[].createdAt`	string (date-time)	Yes
`products[].prices[].currency`	string	Yes	ISO-4217 currency code.
`products[].prices[].effectiveAmount`	number	Yes	Sale price when the current time is in the sale window, otherwise the base amount.
`products[].prices[].id`	string	Yes
`products[].prices[].rebillAtSaleAmount`	boolean	Yes	When false an active sale applies to the first subscription charge only (rebills revert to the full amount); when true the sale price is retained for the subscription lifetime.
`products[].prices[].saleAmount`	number or null	Yes	Sale price; populated only when sale window is set.
`products[].prices[].saleEndsAt`	string (date-time) or null	Yes
`products[].prices[].saleStartsAt`	string (date-time) or null	Yes
`products[].prices[].status`	string	Yes	Inactive prices remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`products[].prices[].updatedAt`	string (date-time)	Yes
`products[].prices[].variantId`	string (uuid) or null	Yes
`products[].recurringInterval`	string or null	Yes	Allowed values: `day`, `week`, `month`, `year`.
`products[].recurringIntervalCount`	number or null	Yes
`products[].recurringTrialPeriodDays`	number or null	Yes
`products[].recurringTrialPeriodDaysFree`	boolean	Yes	Whether the trial period is free. When `false` the trial period is charged the effective sale price before rebilling at the recurring price.
`products[].status`	string	Yes	Catalog lifecycle state. Inactive products retain identity and history but cannot be sold. Allowed values: `active`, `inactive`.
`products[].stockQuantity`	number or null	Yes
`products[].tags`	array of string or null	Yes
`products[].tangibility`	string or null	Yes	Allowed values: `digital`, `physical`.
`products[].taxCode`	string or null	Yes
`products[].type`	string	Yes	Allowed values: `subscription`, `item`.
`products[].updatedAt`	string (date-time)	Yes
`products[].variants`	array of object	Yes
`products[].variants[].attributes`	object or null	Yes
`products[].variants[].availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`products[].variants[].createdAt`	string (date-time)	Yes
`products[].variants[].heightMm`	number or null	Yes
`products[].variants[].id`	string	Yes
`products[].variants[].lengthMm`	number or null	Yes
`products[].variants[].name`	string or null	Yes
`products[].variants[].sku`	string	Yes
`products[].variants[].status`	string	Yes	Inactive variants remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`products[].variants[].stockQuantity`	number or null	Yes
`products[].variants[].updatedAt`	string (date-time)	Yes
`products[].variants[].weightGrams`	number or null	Yes
`products[].variants[].widthMm`	number or null	Yes
`products[].weightGrams`	number or null	Yes
`products[].widthMm`	number or null	Yes
`repeatingIntervalCount`	number or null	Yes
`stackable`	boolean	Yes	Whether this coupon may be combined with other coupons in the same checkout session. When false, the coupon cannot appear alongside any other coupon code in a multi-coupon request.
`status`	string	Yes	Inactive coupons retain their code and history but cannot be applied to new checkouts. Allowed values: `active`, `inactive`.
`type`	string	Yes	Allowed values: `percentage`, `amount`.
`updatedAt`	string (date-time)	Yes

Errors

Status	Description
`400`	The supplied request body or list query is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Coupon mutations require an owner or admin membership.
`404`	No coupon with the requested id exists for this client.

Coupon_list

List Coupons

Returns paginated coupons. Dashboard bearer callers see active and inactive coupons by default and may filter by status; legacy Basic callers retain active-only defaults.

Policy	Value
Operation	`GET /v1/coupons`
Class	`read-only`
Risk	`low`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`read`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`page`	query	integer	No	1-based page number for paginated list endpoints. Default: `1`. Minimum: 1.
`limit`	query	integer	No	Maximum number of records to return per page. Default: `20`. Minimum: 1. Maximum: 100.
`sort`	query	string	No	Sort by one allowed field. Use exactly one of `sort[asc]` or `sort[desc]`. Allowed fields: `code`, `createdAt`, `duration`, `name`, `type`, `updatedAt`. Default: `createdAt` DESC. Allowed values: `code`, `createdAt`, `duration`, `name`, `type`, `updatedAt`.
`relation`	query	string	No	This endpoint does not support relation aliases. Supplying relation returns 400.
`code`	query	string	No	Client-defined coupon code. Equality filter. Pass without operator for exact match or pass any of the following operators: `[search]`. `[search]` is case-insensitive text contains matching.
`createdAt`	query	string (date-time)	No	Coupon creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`duration`	query	string	No	Coupon duration. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `forever`, `once`, `repeating`.
`id`	query	string	No	Coupon id. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`name`	query	string	No	Coupon name. Equality filter. Pass without operator for exact match or pass any of the following operators: `[search]`. `[search]` is case-insensitive text contains matching.
`status`	query	string	No	Catalog lifecycle state. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `active`, `inactive`.
`type`	query	string	No	Coupon type. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `percentage`, `amount`.
`updatedAt`	query	string (date-time)	No	Coupon update timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`data`	array of object	Yes
`data[].code`	string	Yes
`data[].createdAt`	string (date-time)	Yes
`data[].description`	string or null	Yes
`data[].duration`	string	Yes	Allowed values: `forever`, `once`, `repeating`.
`data[].id`	string	Yes
`data[].metadata`	object or null	Yes
`data[].name`	string	Yes
`data[].percentageOff`	number or null	Yes	Percent discount in major units. Populated when type is percentage; null otherwise.
`data[].prices`	array of object	Yes
`data[].prices[].amount`	number	Yes	Discount amount in major units.
`data[].prices[].createdAt`	string (date-time)	Yes
`data[].prices[].currency`	string	Yes	ISO-4217 currency code.
`data[].prices[].id`	string	Yes
`data[].prices[].updatedAt`	string (date-time)	Yes
`data[].products`	array of object	Yes	Empty array means the coupon applies to every product.
`data[].products[].ageGroup`	string or null	Yes
`data[].products[].attributes`	object or null	Yes
`data[].products[].availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`data[].products[].brand`	object or null	Yes
`data[].products[].brand.code`	string	Yes
`data[].products[].brand.createdAt`	string (date-time)	Yes
`data[].products[].brand.description`	string or null	Yes
`data[].products[].brand.id`	string	Yes
`data[].products[].brand.name`	string	Yes
`data[].products[].brand.updatedAt`	string (date-time)	Yes
`data[].products[].category`	object or null	Yes
`data[].products[].category.code`	string	Yes
`data[].products[].category.createdAt`	string (date-time)	Yes
`data[].products[].category.description`	string or null	Yes
`data[].products[].category.id`	string	Yes
`data[].products[].category.name`	string	Yes
`data[].products[].category.parentId`	string (uuid) or null	Yes
`data[].products[].category.updatedAt`	string (date-time)	Yes
`data[].products[].code`	string	Yes
`data[].products[].createdAt`	string (date-time)	Yes
`data[].products[].description`	string or null	Yes
`data[].products[].gender`	string or null	Yes
`data[].products[].gtin`	string or null	Yes
`data[].products[].heightMm`	number or null	Yes
`data[].products[].id`	string	Yes
`data[].products[].knowledgeBaseUrl`	string or null	Yes
`data[].products[].lengthMm`	number or null	Yes
`data[].products[].longDescription`	string or null	Yes
`data[].products[].media`	array of object	Yes
`data[].products[].media[].altText`	string or null	Yes
`data[].products[].media[].createdAt`	string (date-time)	Yes
`data[].products[].media[].id`	string	Yes
`data[].products[].media[].isPrimary`	boolean	Yes
`data[].products[].media[].position`	number	Yes
`data[].products[].media[].type`	string	Yes	Allowed values: `image`, `video`, `model_3d`, `document`.
`data[].products[].media[].updatedAt`	string (date-time)	Yes
`data[].products[].media[].url`	string	Yes
`data[].products[].media[].variantId`	string (uuid) or null	Yes
`data[].products[].metadata`	object or null	Yes
`data[].products[].name`	string	Yes
`data[].products[].prices`	array of object	Yes
`data[].products[].prices[].amount`	number	Yes	Base price in major units.
`data[].products[].prices[].createdAt`	string (date-time)	Yes
`data[].products[].prices[].currency`	string	Yes	ISO-4217 currency code.
`data[].products[].prices[].effectiveAmount`	number	Yes	Sale price when the current time is in the sale window, otherwise the base amount.
`data[].products[].prices[].id`	string	Yes
`data[].products[].prices[].rebillAtSaleAmount`	boolean	Yes	When false an active sale applies to the first subscription charge only (rebills revert to the full amount); when true the sale price is retained for the subscription lifetime.
`data[].products[].prices[].saleAmount`	number or null	Yes	Sale price; populated only when sale window is set.
`data[].products[].prices[].saleEndsAt`	string (date-time) or null	Yes
`data[].products[].prices[].saleStartsAt`	string (date-time) or null	Yes
`data[].products[].prices[].status`	string	Yes	Inactive prices remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`data[].products[].prices[].updatedAt`	string (date-time)	Yes
`data[].products[].prices[].variantId`	string (uuid) or null	Yes
`data[].products[].recurringInterval`	string or null	Yes	Allowed values: `day`, `week`, `month`, `year`.
`data[].products[].recurringIntervalCount`	number or null	Yes
`data[].products[].recurringTrialPeriodDays`	number or null	Yes
`data[].products[].recurringTrialPeriodDaysFree`	boolean	Yes	Whether the trial period is free. When `false` the trial period is charged the effective sale price before rebilling at the recurring price.
`data[].products[].status`	string	Yes	Catalog lifecycle state. Inactive products retain identity and history but cannot be sold. Allowed values: `active`, `inactive`.
`data[].products[].stockQuantity`	number or null	Yes
`data[].products[].tags`	array of string or null	Yes
`data[].products[].tangibility`	string or null	Yes	Allowed values: `digital`, `physical`.
`data[].products[].taxCode`	string or null	Yes
`data[].products[].type`	string	Yes	Allowed values: `subscription`, `item`.
`data[].products[].updatedAt`	string (date-time)	Yes
`data[].products[].variants`	array of object	Yes
`data[].products[].variants[].attributes`	object or null	Yes
`data[].products[].variants[].availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`data[].products[].variants[].createdAt`	string (date-time)	Yes
`data[].products[].variants[].heightMm`	number or null	Yes
`data[].products[].variants[].id`	string	Yes
`data[].products[].variants[].lengthMm`	number or null	Yes
`data[].products[].variants[].name`	string or null	Yes
`data[].products[].variants[].sku`	string	Yes
`data[].products[].variants[].status`	string	Yes	Inactive variants remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`data[].products[].variants[].stockQuantity`	number or null	Yes
`data[].products[].variants[].updatedAt`	string (date-time)	Yes
`data[].products[].variants[].weightGrams`	number or null	Yes
`data[].products[].variants[].widthMm`	number or null	Yes
`data[].products[].weightGrams`	number or null	Yes
`data[].products[].widthMm`	number or null	Yes
`data[].repeatingIntervalCount`	number or null	Yes
`data[].stackable`	boolean	Yes	Whether this coupon may be combined with other coupons in the same checkout session. When false, the coupon cannot appear alongside any other coupon code in a multi-coupon request.
`data[].status`	string	Yes	Inactive coupons retain their code and history but cannot be applied to new checkouts. Allowed values: `active`, `inactive`.
`data[].type`	string	Yes	Allowed values: `percentage`, `amount`.
`data[].updatedAt`	string (date-time)	Yes
`limit`	number	Yes
`page`	number	Yes
`pages`	number	Yes
`total`	number	Yes

Errors

Status	Description
`400`	The supplied request body or list query is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Coupon mutations require an owner or admin membership.

Coupon_reactivate

Reactivate Coupon

Reactivates a historically used coupon.

Policy	Value
Operation	`POST /v1/coupons/{uuid}/reactivate`
Class	`mutating`
Risk	`medium`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`mutation`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`uuid`	path	string	Yes

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`code`	string	Yes
`createdAt`	string (date-time)	Yes
`description`	string or null	Yes
`duration`	string	Yes	Allowed values: `forever`, `once`, `repeating`.
`id`	string	Yes
`metadata`	object or null	Yes
`name`	string	Yes
`percentageOff`	number or null	Yes	Percent discount in major units. Populated when type is percentage; null otherwise.
`prices`	array of object	Yes
`prices[].amount`	number	Yes	Discount amount in major units.
`prices[].createdAt`	string (date-time)	Yes
`prices[].currency`	string	Yes	ISO-4217 currency code.
`prices[].id`	string	Yes
`prices[].updatedAt`	string (date-time)	Yes
`products`	array of object	Yes	Empty array means the coupon applies to every product.
`products[].ageGroup`	string or null	Yes
`products[].attributes`	object or null	Yes
`products[].availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`products[].brand`	object or null	Yes
`products[].brand.code`	string	Yes
`products[].brand.createdAt`	string (date-time)	Yes
`products[].brand.description`	string or null	Yes
`products[].brand.id`	string	Yes
`products[].brand.name`	string	Yes
`products[].brand.updatedAt`	string (date-time)	Yes
`products[].category`	object or null	Yes
`products[].category.code`	string	Yes
`products[].category.createdAt`	string (date-time)	Yes
`products[].category.description`	string or null	Yes
`products[].category.id`	string	Yes
`products[].category.name`	string	Yes
`products[].category.parentId`	string (uuid) or null	Yes
`products[].category.updatedAt`	string (date-time)	Yes
`products[].code`	string	Yes
`products[].createdAt`	string (date-time)	Yes
`products[].description`	string or null	Yes
`products[].gender`	string or null	Yes
`products[].gtin`	string or null	Yes
`products[].heightMm`	number or null	Yes
`products[].id`	string	Yes
`products[].knowledgeBaseUrl`	string or null	Yes
`products[].lengthMm`	number or null	Yes
`products[].longDescription`	string or null	Yes
`products[].media`	array of object	Yes
`products[].media[].altText`	string or null	Yes
`products[].media[].createdAt`	string (date-time)	Yes
`products[].media[].id`	string	Yes
`products[].media[].isPrimary`	boolean	Yes
`products[].media[].position`	number	Yes
`products[].media[].type`	string	Yes	Allowed values: `image`, `video`, `model_3d`, `document`.
`products[].media[].updatedAt`	string (date-time)	Yes
`products[].media[].url`	string	Yes
`products[].media[].variantId`	string (uuid) or null	Yes
`products[].metadata`	object or null	Yes
`products[].name`	string	Yes
`products[].prices`	array of object	Yes
`products[].prices[].amount`	number	Yes	Base price in major units.
`products[].prices[].createdAt`	string (date-time)	Yes
`products[].prices[].currency`	string	Yes	ISO-4217 currency code.
`products[].prices[].effectiveAmount`	number	Yes	Sale price when the current time is in the sale window, otherwise the base amount.
`products[].prices[].id`	string	Yes
`products[].prices[].rebillAtSaleAmount`	boolean	Yes	When false an active sale applies to the first subscription charge only (rebills revert to the full amount); when true the sale price is retained for the subscription lifetime.
`products[].prices[].saleAmount`	number or null	Yes	Sale price; populated only when sale window is set.
`products[].prices[].saleEndsAt`	string (date-time) or null	Yes
`products[].prices[].saleStartsAt`	string (date-time) or null	Yes
`products[].prices[].status`	string	Yes	Inactive prices remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`products[].prices[].updatedAt`	string (date-time)	Yes
`products[].prices[].variantId`	string (uuid) or null	Yes
`products[].recurringInterval`	string or null	Yes	Allowed values: `day`, `week`, `month`, `year`.
`products[].recurringIntervalCount`	number or null	Yes
`products[].recurringTrialPeriodDays`	number or null	Yes
`products[].recurringTrialPeriodDaysFree`	boolean	Yes	Whether the trial period is free. When `false` the trial period is charged the effective sale price before rebilling at the recurring price.
`products[].status`	string	Yes	Catalog lifecycle state. Inactive products retain identity and history but cannot be sold. Allowed values: `active`, `inactive`.
`products[].stockQuantity`	number or null	Yes
`products[].tags`	array of string or null	Yes
`products[].tangibility`	string or null	Yes	Allowed values: `digital`, `physical`.
`products[].taxCode`	string or null	Yes
`products[].type`	string	Yes	Allowed values: `subscription`, `item`.
`products[].updatedAt`	string (date-time)	Yes
`products[].variants`	array of object	Yes
`products[].variants[].attributes`	object or null	Yes
`products[].variants[].availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`products[].variants[].createdAt`	string (date-time)	Yes
`products[].variants[].heightMm`	number or null	Yes
`products[].variants[].id`	string	Yes
`products[].variants[].lengthMm`	number or null	Yes
`products[].variants[].name`	string or null	Yes
`products[].variants[].sku`	string	Yes
`products[].variants[].status`	string	Yes	Inactive variants remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`products[].variants[].stockQuantity`	number or null	Yes
`products[].variants[].updatedAt`	string (date-time)	Yes
`products[].variants[].weightGrams`	number or null	Yes
`products[].variants[].widthMm`	number or null	Yes
`products[].weightGrams`	number or null	Yes
`products[].widthMm`	number or null	Yes
`repeatingIntervalCount`	number or null	Yes
`stackable`	boolean	Yes	Whether this coupon may be combined with other coupons in the same checkout session. When false, the coupon cannot appear alongside any other coupon code in a multi-coupon request.
`status`	string	Yes	Inactive coupons retain their code and history but cannot be applied to new checkouts. Allowed values: `active`, `inactive`.
`type`	string	Yes	Allowed values: `percentage`, `amount`.
`updatedAt`	string (date-time)	Yes

Errors

Status	Description
`400`	The supplied request body or list query is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Coupon mutations require an owner or admin membership.

Coupon_update

Update Coupon

Updates a coupon. Prices and products are replaced when supplied.

Policy	Value
Operation	`PATCH /v1/coupons/{uuid}`
Class	`mutating`
Risk	`medium`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`mutation`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`uuid`	path	string	Yes
`code`	body	string	No	Minimum length: 1. Maximum length: 255.
`description`	body	string	No	Minimum length: 0. Maximum length: 1000.
`duration`	body	string	No	Allowed values: `forever`, `once`, `repeating`.
`metadata`	body	object	No
`name`	body	string	No	Minimum length: 1. Maximum length: 255.
`percentageOff`	body	number	No	Percent discount in major units, e.g. 10 for 10%. Required when type is percentage. Must be omitted when type is amount. Minimum: 0.01. Maximum: 100.
`prices`	body	array of object	No	Required when type is amount. Must be omitted when type is percentage. Minimum items: 1.
`prices[].amount`	body	number	Yes	Discount amount in major units. Up to 2 decimal places. Minimum: 0. Maximum: 99999999.99.
`prices[].currency`	body	string	Yes	Minimum length: 3. Maximum length: 3.
`productIds`	body	array of string (uuid)	No	Product ids this coupon applies to. Empty or omitted means the coupon applies to every product.
`repeatingIntervalCount`	body	number	No	Number of intervals the coupon repeats for (only used when duration is repeating). Minimum: 1.
`stackable`	body	boolean	No	Whether this coupon may be combined with other coupons in the same checkout session. Defaults to false; when false, the coupon cannot appear alongside any other coupon code in a multi-coupon request. Default: `false`.
`type`	body	string	No	Allowed values: `percentage`, `amount`.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`code`	string	Yes
`createdAt`	string (date-time)	Yes
`description`	string or null	Yes
`duration`	string	Yes	Allowed values: `forever`, `once`, `repeating`.
`id`	string	Yes
`metadata`	object or null	Yes
`name`	string	Yes
`percentageOff`	number or null	Yes	Percent discount in major units. Populated when type is percentage; null otherwise.
`prices`	array of object	Yes
`prices[].amount`	number	Yes	Discount amount in major units.
`prices[].createdAt`	string (date-time)	Yes
`prices[].currency`	string	Yes	ISO-4217 currency code.
`prices[].id`	string	Yes
`prices[].updatedAt`	string (date-time)	Yes
`products`	array of object	Yes	Empty array means the coupon applies to every product.
`products[].ageGroup`	string or null	Yes
`products[].attributes`	object or null	Yes
`products[].availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`products[].brand`	object or null	Yes
`products[].brand.code`	string	Yes
`products[].brand.createdAt`	string (date-time)	Yes
`products[].brand.description`	string or null	Yes
`products[].brand.id`	string	Yes
`products[].brand.name`	string	Yes
`products[].brand.updatedAt`	string (date-time)	Yes
`products[].category`	object or null	Yes
`products[].category.code`	string	Yes
`products[].category.createdAt`	string (date-time)	Yes
`products[].category.description`	string or null	Yes
`products[].category.id`	string	Yes
`products[].category.name`	string	Yes
`products[].category.parentId`	string (uuid) or null	Yes
`products[].category.updatedAt`	string (date-time)	Yes
`products[].code`	string	Yes
`products[].createdAt`	string (date-time)	Yes
`products[].description`	string or null	Yes
`products[].gender`	string or null	Yes
`products[].gtin`	string or null	Yes
`products[].heightMm`	number or null	Yes
`products[].id`	string	Yes
`products[].knowledgeBaseUrl`	string or null	Yes
`products[].lengthMm`	number or null	Yes
`products[].longDescription`	string or null	Yes
`products[].media`	array of object	Yes
`products[].media[].altText`	string or null	Yes
`products[].media[].createdAt`	string (date-time)	Yes
`products[].media[].id`	string	Yes
`products[].media[].isPrimary`	boolean	Yes
`products[].media[].position`	number	Yes
`products[].media[].type`	string	Yes	Allowed values: `image`, `video`, `model_3d`, `document`.
`products[].media[].updatedAt`	string (date-time)	Yes
`products[].media[].url`	string	Yes
`products[].media[].variantId`	string (uuid) or null	Yes
`products[].metadata`	object or null	Yes
`products[].name`	string	Yes
`products[].prices`	array of object	Yes
`products[].prices[].amount`	number	Yes	Base price in major units.
`products[].prices[].createdAt`	string (date-time)	Yes
`products[].prices[].currency`	string	Yes	ISO-4217 currency code.
`products[].prices[].effectiveAmount`	number	Yes	Sale price when the current time is in the sale window, otherwise the base amount.
`products[].prices[].id`	string	Yes
`products[].prices[].rebillAtSaleAmount`	boolean	Yes	When false an active sale applies to the first subscription charge only (rebills revert to the full amount); when true the sale price is retained for the subscription lifetime.
`products[].prices[].saleAmount`	number or null	Yes	Sale price; populated only when sale window is set.
`products[].prices[].saleEndsAt`	string (date-time) or null	Yes
`products[].prices[].saleStartsAt`	string (date-time) or null	Yes
`products[].prices[].status`	string	Yes	Inactive prices remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`products[].prices[].updatedAt`	string (date-time)	Yes
`products[].prices[].variantId`	string (uuid) or null	Yes
`products[].recurringInterval`	string or null	Yes	Allowed values: `day`, `week`, `month`, `year`.
`products[].recurringIntervalCount`	number or null	Yes
`products[].recurringTrialPeriodDays`	number or null	Yes
`products[].recurringTrialPeriodDaysFree`	boolean	Yes	Whether the trial period is free. When `false` the trial period is charged the effective sale price before rebilling at the recurring price.
`products[].status`	string	Yes	Catalog lifecycle state. Inactive products retain identity and history but cannot be sold. Allowed values: `active`, `inactive`.
`products[].stockQuantity`	number or null	Yes
`products[].tags`	array of string or null	Yes
`products[].tangibility`	string or null	Yes	Allowed values: `digital`, `physical`.
`products[].taxCode`	string or null	Yes
`products[].type`	string	Yes	Allowed values: `subscription`, `item`.
`products[].updatedAt`	string (date-time)	Yes
`products[].variants`	array of object	Yes
`products[].variants[].attributes`	object or null	Yes
`products[].variants[].availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`products[].variants[].createdAt`	string (date-time)	Yes
`products[].variants[].heightMm`	number or null	Yes
`products[].variants[].id`	string	Yes
`products[].variants[].lengthMm`	number or null	Yes
`products[].variants[].name`	string or null	Yes
`products[].variants[].sku`	string	Yes
`products[].variants[].status`	string	Yes	Inactive variants remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`products[].variants[].stockQuantity`	number or null	Yes
`products[].variants[].updatedAt`	string (date-time)	Yes
`products[].variants[].weightGrams`	number or null	Yes
`products[].variants[].widthMm`	number or null	Yes
`products[].weightGrams`	number or null	Yes
`products[].widthMm`	number or null	Yes
`repeatingIntervalCount`	number or null	Yes
`stackable`	boolean	Yes	Whether this coupon may be combined with other coupons in the same checkout session. When false, the coupon cannot appear alongside any other coupon code in a multi-coupon request.
`status`	string	Yes	Inactive coupons retain their code and history but cannot be applied to new checkouts. Allowed values: `active`, `inactive`.
`type`	string	Yes	Allowed values: `percentage`, `amount`.
`updatedAt`	string (date-time)	Yes

Errors

Status	Description
`400`	The supplied request body or list query is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Coupon mutations require an owner or admin membership.
`404`	No coupon with the requested id exists for this client.

Product_create

Create Product

Creates an active product immediately. Nested prices are the initial full price set; use the stable price routes for later single-price changes.

Policy	Value
Operation	`POST /v1/products`
Class	`mutating`
Risk	`medium`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`mutation`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`ageGroup`	body	string	No	Minimum length: 0. Maximum length: 32.
`attributes`	body	object	No	Free-form technical attributes (e.g. dimensions, ingredients, energy rating).
`availabilityStatus`	body	string	No	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`brandId`	body	string (uuid)	No	Brand id this product belongs to.
`categoryId`	body	string (uuid)	No	Category id this product belongs to.
`code`	body	string	Yes	Unique product code for this client. Minimum length: 1. Maximum length: 255.
`collectionIds`	body	array of string (uuid)	No	Collection ids this product belongs to. Replaces the full set on update; pass an empty array to remove from all collections.
`description`	body	string	No	Minimum length: 0. Maximum length: 1000.
`gender`	body	string	No	Minimum length: 0. Maximum length: 32.
`gtin`	body	string	No	GTIN / UPC / EAN / ISBN. Must be 8, 12, 13, or 14 digits.
`heightMm`	body	number	No	Minimum: 0.
`knowledgeBaseUrl`	body	string (uri)	No	Minimum length: 0. Maximum length: 2048.
`lengthMm`	body	number	No	Minimum: 0.
`longDescription`	body	string	No	Long-form product description, suitable for marketing content or LLM input. Minimum length: 0. Maximum length: 100000.
`metadata`	body	object	No
`name`	body	string	Yes	Minimum length: 1. Maximum length: 255.
`prices`	body	array of object	Yes	Minimum items: 1.
`prices[].amount`	body	number	Yes	Price in major units. Up to 2 decimal places. Minimum: 0. Maximum: 99999999.99.
`prices[].currency`	body	string	Yes	ISO-4217 currency code. Minimum length: 3. Maximum length: 3.
`prices[].rebillAtSaleAmount`	body	boolean	No	When false (default) an active sale applies to the first subscription charge only and rebills revert to the full amount. When true the sale price is kept for the lifetime of the subscription. No-op when no sale is active. Default: `false`.
`prices[].saleAmount`	body	number	No	Optional sale price; takes effect inside the sale window. Minimum: 0. Maximum: 99999999.99.
`prices[].saleEndsAt`	body	string (date-time)	No	Sale end timestamp (inclusive).
`prices[].saleStartsAt`	body	string (date-time)	No	Sale start timestamp (inclusive).
`prices[].variantId`	body	string (uuid)	No	Optional variant id to scope this price to a specific variant.
`recurringInterval`	body	string	No	Allowed values: `day`, `week`, `month`, `year`.
`recurringIntervalCount`	body	number	No	Minimum: 1.
`recurringTrialPeriodDays`	body	number	No	Minimum: 0.
`recurringTrialPeriodDaysFree`	body	boolean	No	Whether the `recurringTrialPeriodDays` trial is free. When `true` (default) the trial period is $0 for the configured days, then the subscription rebills. When `false` the trial period is charged the effective sale price (sale amount if a sale is active, otherwise the amount) before rebilling at the recurring price. Requires `recurringTrialPeriodDays > 0`. Default: `true`.
`stockQuantity`	body	number	No	Hint for stock on hand. Flo does not act as the inventory ledger. Minimum: 0.
`tags`	body	array of string	No
`tangibility`	body	string	No	Allowed values: `digital`, `physical`.
`taxCode`	body	string	No	Provider-neutral tax code. Minimum length: 0. Maximum length: 64.
`type`	body	string	Yes	Allowed values: `subscription`, `item`.
`weightGrams`	body	number	No	Minimum: 0.
`widthMm`	body	number	No	Minimum: 0.

Result

Returns 201 with a JSON body.

Field	Type	Required	Description
`ageGroup`	string or null	Yes
`attributes`	object or null	Yes
`availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`brand`	object or null	Yes
`brand.code`	string	Yes
`brand.createdAt`	string (date-time)	Yes
`brand.description`	string or null	Yes
`brand.id`	string	Yes
`brand.name`	string	Yes
`brand.updatedAt`	string (date-time)	Yes
`category`	object or null	Yes
`category.code`	string	Yes
`category.createdAt`	string (date-time)	Yes
`category.description`	string or null	Yes
`category.id`	string	Yes
`category.name`	string	Yes
`category.parentId`	string (uuid) or null	Yes
`category.updatedAt`	string (date-time)	Yes
`code`	string	Yes
`createdAt`	string (date-time)	Yes
`description`	string or null	Yes
`gender`	string or null	Yes
`gtin`	string or null	Yes
`heightMm`	number or null	Yes
`id`	string	Yes
`knowledgeBaseUrl`	string or null	Yes
`lengthMm`	number or null	Yes
`longDescription`	string or null	Yes
`media`	array of object	Yes
`media[].altText`	string or null	Yes
`media[].createdAt`	string (date-time)	Yes
`media[].id`	string	Yes
`media[].isPrimary`	boolean	Yes
`media[].position`	number	Yes
`media[].type`	string	Yes	Allowed values: `image`, `video`, `model_3d`, `document`.
`media[].updatedAt`	string (date-time)	Yes
`media[].url`	string	Yes
`media[].variantId`	string (uuid) or null	Yes
`metadata`	object or null	Yes
`name`	string	Yes
`prices`	array of object	Yes
`prices[].amount`	number	Yes	Base price in major units.
`prices[].createdAt`	string (date-time)	Yes
`prices[].currency`	string	Yes	ISO-4217 currency code.
`prices[].effectiveAmount`	number	Yes	Sale price when the current time is in the sale window, otherwise the base amount.
`prices[].id`	string	Yes
`prices[].rebillAtSaleAmount`	boolean	Yes	When false an active sale applies to the first subscription charge only (rebills revert to the full amount); when true the sale price is retained for the subscription lifetime.
`prices[].saleAmount`	number or null	Yes	Sale price; populated only when sale window is set.
`prices[].saleEndsAt`	string (date-time) or null	Yes
`prices[].saleStartsAt`	string (date-time) or null	Yes
`prices[].status`	string	Yes	Inactive prices remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`prices[].updatedAt`	string (date-time)	Yes
`prices[].variantId`	string (uuid) or null	Yes
`recurringInterval`	string or null	Yes	Allowed values: `day`, `week`, `month`, `year`.
`recurringIntervalCount`	number or null	Yes
`recurringTrialPeriodDays`	number or null	Yes
`recurringTrialPeriodDaysFree`	boolean	Yes	Whether the trial period is free. When `false` the trial period is charged the effective sale price before rebilling at the recurring price.
`status`	string	Yes	Catalog lifecycle state. Inactive products retain identity and history but cannot be sold. Allowed values: `active`, `inactive`.
`stockQuantity`	number or null	Yes
`tags`	array of string or null	Yes
`tangibility`	string or null	Yes	Allowed values: `digital`, `physical`.
`taxCode`	string or null	Yes
`type`	string	Yes	Allowed values: `subscription`, `item`.
`updatedAt`	string (date-time)	Yes
`variants`	array of object	Yes
`variants[].attributes`	object or null	Yes
`variants[].availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`variants[].createdAt`	string (date-time)	Yes
`variants[].heightMm`	number or null	Yes
`variants[].id`	string	Yes
`variants[].lengthMm`	number or null	Yes
`variants[].name`	string or null	Yes
`variants[].sku`	string	Yes
`variants[].status`	string	Yes	Inactive variants remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`variants[].stockQuantity`	number or null	Yes
`variants[].updatedAt`	string (date-time)	Yes
`variants[].weightGrams`	number or null	Yes
`variants[].widthMm`	number or null	Yes
`weightGrams`	number or null	Yes
`widthMm`	number or null	Yes

Errors

Status	Description
`400`	The supplied request body or list query is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Product mutations require an owner or admin membership.

Product_findOne

Get Product

Returns a single product with its nested prices.

Policy	Value
Operation	`GET /v1/products/{uuid}`
Class	`read-only`
Risk	`low`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`read`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`uuid`	path	string	Yes

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`ageGroup`	string or null	Yes
`attributes`	object or null	Yes
`availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`brand`	object or null	Yes
`brand.code`	string	Yes
`brand.createdAt`	string (date-time)	Yes
`brand.description`	string or null	Yes
`brand.id`	string	Yes
`brand.name`	string	Yes
`brand.updatedAt`	string (date-time)	Yes
`category`	object or null	Yes
`category.code`	string	Yes
`category.createdAt`	string (date-time)	Yes
`category.description`	string or null	Yes
`category.id`	string	Yes
`category.name`	string	Yes
`category.parentId`	string (uuid) or null	Yes
`category.updatedAt`	string (date-time)	Yes
`code`	string	Yes
`createdAt`	string (date-time)	Yes
`description`	string or null	Yes
`gender`	string or null	Yes
`gtin`	string or null	Yes
`heightMm`	number or null	Yes
`id`	string	Yes
`knowledgeBaseUrl`	string or null	Yes
`lengthMm`	number or null	Yes
`longDescription`	string or null	Yes
`media`	array of object	Yes
`media[].altText`	string or null	Yes
`media[].createdAt`	string (date-time)	Yes
`media[].id`	string	Yes
`media[].isPrimary`	boolean	Yes
`media[].position`	number	Yes
`media[].type`	string	Yes	Allowed values: `image`, `video`, `model_3d`, `document`.
`media[].updatedAt`	string (date-time)	Yes
`media[].url`	string	Yes
`media[].variantId`	string (uuid) or null	Yes
`metadata`	object or null	Yes
`name`	string	Yes
`prices`	array of object	Yes
`prices[].amount`	number	Yes	Base price in major units.
`prices[].createdAt`	string (date-time)	Yes
`prices[].currency`	string	Yes	ISO-4217 currency code.
`prices[].effectiveAmount`	number	Yes	Sale price when the current time is in the sale window, otherwise the base amount.
`prices[].id`	string	Yes
`prices[].rebillAtSaleAmount`	boolean	Yes	When false an active sale applies to the first subscription charge only (rebills revert to the full amount); when true the sale price is retained for the subscription lifetime.
`prices[].saleAmount`	number or null	Yes	Sale price; populated only when sale window is set.
`prices[].saleEndsAt`	string (date-time) or null	Yes
`prices[].saleStartsAt`	string (date-time) or null	Yes
`prices[].status`	string	Yes	Inactive prices remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`prices[].updatedAt`	string (date-time)	Yes
`prices[].variantId`	string (uuid) or null	Yes
`recurringInterval`	string or null	Yes	Allowed values: `day`, `week`, `month`, `year`.
`recurringIntervalCount`	number or null	Yes
`recurringTrialPeriodDays`	number or null	Yes
`recurringTrialPeriodDaysFree`	boolean	Yes	Whether the trial period is free. When `false` the trial period is charged the effective sale price before rebilling at the recurring price.
`status`	string	Yes	Catalog lifecycle state. Inactive products retain identity and history but cannot be sold. Allowed values: `active`, `inactive`.
`stockQuantity`	number or null	Yes
`tags`	array of string or null	Yes
`tangibility`	string or null	Yes	Allowed values: `digital`, `physical`.
`taxCode`	string or null	Yes
`type`	string	Yes	Allowed values: `subscription`, `item`.
`updatedAt`	string (date-time)	Yes
`variants`	array of object	Yes
`variants[].attributes`	object or null	Yes
`variants[].availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`variants[].createdAt`	string (date-time)	Yes
`variants[].heightMm`	number or null	Yes
`variants[].id`	string	Yes
`variants[].lengthMm`	number or null	Yes
`variants[].name`	string or null	Yes
`variants[].sku`	string	Yes
`variants[].status`	string	Yes	Inactive variants remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`variants[].stockQuantity`	number or null	Yes
`variants[].updatedAt`	string (date-time)	Yes
`variants[].weightGrams`	number or null	Yes
`variants[].widthMm`	number or null	Yes
`weightGrams`	number or null	Yes
`widthMm`	number or null	Yes

Errors

Status	Description
`400`	The supplied request body or list query is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Product mutations require an owner or admin membership.
`404`	No product with the requested id exists for this client.

Returns paginated products for the authenticated client. Dashboard bearer callers see active and inactive records by default and may filter by status; legacy Basic callers retain active-only defaults.

Policy	Value
Operation	`GET /v1/products`
Class	`read-only`
Risk	`low`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`read`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`page`	query	integer	No	1-based page number for paginated list endpoints. Default: `1`. Minimum: 1.
`limit`	query	integer	No	Maximum number of records to return per page. Default: `20`. Minimum: 1. Maximum: 100.
`sort`	query	string	No	Sort by one allowed field. Use exactly one of `sort[asc]` or `sort[desc]`. Allowed fields: `code`, `createdAt`, `name`, `type`, `updatedAt`. Default: `createdAt` DESC. Allowed values: `code`, `createdAt`, `name`, `type`, `updatedAt`.
`relation`	query	string	No	This endpoint does not support relation aliases. Supplying relation returns 400.
`availabilityStatus`	query	string	No	Product availability status. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`brandId`	query	string	No	Brand id this product belongs to. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`categoryId`	query	string	No	Category id this product belongs to. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`code`	query	string	No	Client-defined product code. Equality filter. Pass without operator for exact match or pass any of the following operators: `[search]`. `[search]` is case-insensitive text contains matching.
`createdAt`	query	string (date-time)	No	Product creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`id`	query	string	No	Product id. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`name`	query	string	No	Human-readable product name. Equality filter. Pass without operator for exact match or pass any of the following operators: `[search]`. `[search]` is case-insensitive text contains matching.
`status`	query	string	No	Catalog lifecycle state. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `active`, `inactive`.
`tangibility`	query	string	No	Whether the product is digital or physical. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `digital`, `physical`.
`type`	query	string	No	Product type. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `subscription`, `item`.
`updatedAt`	query	string (date-time)	No	Product update timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`data`	array of object	Yes
`data[].availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`data[].brandId`	string (uuid) or null	Yes
`data[].categoryId`	string (uuid) or null	Yes
`data[].code`	string	Yes
`data[].createdAt`	string (date-time)	Yes
`data[].description`	string or null	Yes
`data[].id`	string	Yes
`data[].name`	string	Yes
`data[].prices`	array of object	Yes
`data[].prices[].amount`	number	Yes	Base price in major units.
`data[].prices[].createdAt`	string (date-time)	Yes
`data[].prices[].currency`	string	Yes	ISO-4217 currency code.
`data[].prices[].effectiveAmount`	number	Yes	Sale price when the current time is in the sale window, otherwise the base amount.
`data[].prices[].id`	string	Yes
`data[].prices[].rebillAtSaleAmount`	boolean	Yes	When false an active sale applies to the first subscription charge only (rebills revert to the full amount); when true the sale price is retained for the subscription lifetime.
`data[].prices[].saleAmount`	number or null	Yes	Sale price; populated only when sale window is set.
`data[].prices[].saleEndsAt`	string (date-time) or null	Yes
`data[].prices[].saleStartsAt`	string (date-time) or null	Yes
`data[].prices[].status`	string	Yes	Inactive prices remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`data[].prices[].updatedAt`	string (date-time)	Yes
`data[].prices[].variantId`	string (uuid) or null	Yes
`data[].recurringInterval`	string or null	Yes	Allowed values: `day`, `week`, `month`, `year`.
`data[].recurringIntervalCount`	number or null	Yes
`data[].status`	string	Yes	Allowed values: `active`, `inactive`.
`data[].tags`	array of string or null	Yes
`data[].tangibility`	string or null	Yes	Allowed values: `digital`, `physical`.
`data[].type`	string	Yes	Allowed values: `subscription`, `item`.
`data[].updatedAt`	string (date-time)	Yes
`limit`	number	Yes
`page`	number	Yes
`pages`	number	Yes
`total`	number	Yes

Errors

Status	Description
`400`	The supplied request body or list query is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Product mutations require an owner or admin membership.

Product_reactivate

Reactivate Product

Re-runs current catalog validation and reactivates an inactive historical product.

Policy	Value
Operation	`POST /v1/products/{uuid}/reactivate`
Class	`mutating`
Risk	`medium`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`mutation`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`uuid`	path	string	Yes

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`ageGroup`	string or null	Yes
`attributes`	object or null	Yes
`availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`brand`	object or null	Yes
`brand.code`	string	Yes
`brand.createdAt`	string (date-time)	Yes
`brand.description`	string or null	Yes
`brand.id`	string	Yes
`brand.name`	string	Yes
`brand.updatedAt`	string (date-time)	Yes
`category`	object or null	Yes
`category.code`	string	Yes
`category.createdAt`	string (date-time)	Yes
`category.description`	string or null	Yes
`category.id`	string	Yes
`category.name`	string	Yes
`category.parentId`	string (uuid) or null	Yes
`category.updatedAt`	string (date-time)	Yes
`code`	string	Yes
`createdAt`	string (date-time)	Yes
`description`	string or null	Yes
`gender`	string or null	Yes
`gtin`	string or null	Yes
`heightMm`	number or null	Yes
`id`	string	Yes
`knowledgeBaseUrl`	string or null	Yes
`lengthMm`	number or null	Yes
`longDescription`	string or null	Yes
`media`	array of object	Yes
`media[].altText`	string or null	Yes
`media[].createdAt`	string (date-time)	Yes
`media[].id`	string	Yes
`media[].isPrimary`	boolean	Yes
`media[].position`	number	Yes
`media[].type`	string	Yes	Allowed values: `image`, `video`, `model_3d`, `document`.
`media[].updatedAt`	string (date-time)	Yes
`media[].url`	string	Yes
`media[].variantId`	string (uuid) or null	Yes
`metadata`	object or null	Yes
`name`	string	Yes
`prices`	array of object	Yes
`prices[].amount`	number	Yes	Base price in major units.
`prices[].createdAt`	string (date-time)	Yes
`prices[].currency`	string	Yes	ISO-4217 currency code.
`prices[].effectiveAmount`	number	Yes	Sale price when the current time is in the sale window, otherwise the base amount.
`prices[].id`	string	Yes
`prices[].rebillAtSaleAmount`	boolean	Yes	When false an active sale applies to the first subscription charge only (rebills revert to the full amount); when true the sale price is retained for the subscription lifetime.
`prices[].saleAmount`	number or null	Yes	Sale price; populated only when sale window is set.
`prices[].saleEndsAt`	string (date-time) or null	Yes
`prices[].saleStartsAt`	string (date-time) or null	Yes
`prices[].status`	string	Yes	Inactive prices remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`prices[].updatedAt`	string (date-time)	Yes
`prices[].variantId`	string (uuid) or null	Yes
`recurringInterval`	string or null	Yes	Allowed values: `day`, `week`, `month`, `year`.
`recurringIntervalCount`	number or null	Yes
`recurringTrialPeriodDays`	number or null	Yes
`recurringTrialPeriodDaysFree`	boolean	Yes	Whether the trial period is free. When `false` the trial period is charged the effective sale price before rebilling at the recurring price.
`status`	string	Yes	Catalog lifecycle state. Inactive products retain identity and history but cannot be sold. Allowed values: `active`, `inactive`.
`stockQuantity`	number or null	Yes
`tags`	array of string or null	Yes
`tangibility`	string or null	Yes	Allowed values: `digital`, `physical`.
`taxCode`	string or null	Yes
`type`	string	Yes	Allowed values: `subscription`, `item`.
`updatedAt`	string (date-time)	Yes
`variants`	array of object	Yes
`variants[].attributes`	object or null	Yes
`variants[].availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`variants[].createdAt`	string (date-time)	Yes
`variants[].heightMm`	number or null	Yes
`variants[].id`	string	Yes
`variants[].lengthMm`	number or null	Yes
`variants[].name`	string or null	Yes
`variants[].sku`	string	Yes
`variants[].status`	string	Yes	Inactive variants remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`variants[].stockQuantity`	number or null	Yes
`variants[].updatedAt`	string (date-time)	Yes
`variants[].weightGrams`	number or null	Yes
`variants[].widthMm`	number or null	Yes
`weightGrams`	number or null	Yes
`widthMm`	number or null	Yes

Errors

Status	Description
`400`	The supplied request body or list query is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Product mutations require an owner or admin membership.

Product_update

Update Product

Updates a product. The backward-compatible nested prices payload remains full-set replacement; use the dedicated price routes when stable price IDs are required.

Policy	Value
Operation	`PATCH /v1/products/{uuid}`
Class	`mutating`
Risk	`medium`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`mutation`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`uuid`	path	string	Yes
`ageGroup`	body	string	No	Minimum length: 0. Maximum length: 32.
`attributes`	body	object	No	Free-form technical attributes (e.g. dimensions, ingredients, energy rating).
`availabilityStatus`	body	string	No	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`brandId`	body	string (uuid)	No	Brand id this product belongs to.
`categoryId`	body	string (uuid)	No	Category id this product belongs to.
`code`	body	string	No	Unique product code for this client. Minimum length: 1. Maximum length: 255.
`collectionIds`	body	array of string (uuid)	No	Collection ids this product belongs to. Replaces the full set on update; pass an empty array to remove from all collections.
`description`	body	string	No	Minimum length: 0. Maximum length: 1000.
`gender`	body	string	No	Minimum length: 0. Maximum length: 32.
`gtin`	body	string	No	GTIN / UPC / EAN / ISBN. Must be 8, 12, 13, or 14 digits.
`heightMm`	body	number	No	Minimum: 0.
`knowledgeBaseUrl`	body	string (uri)	No	Minimum length: 0. Maximum length: 2048.
`lengthMm`	body	number	No	Minimum: 0.
`longDescription`	body	string	No	Long-form product description, suitable for marketing content or LLM input. Minimum length: 0. Maximum length: 100000.
`metadata`	body	object	No
`name`	body	string	No	Minimum length: 1. Maximum length: 255.
`prices`	body	array of object	No	Minimum items: 1.
`prices[].amount`	body	number	Yes	Price in major units. Up to 2 decimal places. Minimum: 0. Maximum: 99999999.99.
`prices[].currency`	body	string	Yes	ISO-4217 currency code. Minimum length: 3. Maximum length: 3.
`prices[].rebillAtSaleAmount`	body	boolean	No	When false (default) an active sale applies to the first subscription charge only and rebills revert to the full amount. When true the sale price is kept for the lifetime of the subscription. No-op when no sale is active. Default: `false`.
`prices[].saleAmount`	body	number	No	Optional sale price; takes effect inside the sale window. Minimum: 0. Maximum: 99999999.99.
`prices[].saleEndsAt`	body	string (date-time)	No	Sale end timestamp (inclusive).
`prices[].saleStartsAt`	body	string (date-time)	No	Sale start timestamp (inclusive).
`prices[].variantId`	body	string (uuid)	No	Optional variant id to scope this price to a specific variant.
`recurringInterval`	body	string	No	Allowed values: `day`, `week`, `month`, `year`.
`recurringIntervalCount`	body	number	No	Minimum: 1.
`recurringTrialPeriodDays`	body	number	No	Minimum: 0.
`recurringTrialPeriodDaysFree`	body	boolean	No	Whether the `recurringTrialPeriodDays` trial is free. When `true` (default) the trial period is $0 for the configured days, then the subscription rebills. When `false` the trial period is charged the effective sale price (sale amount if a sale is active, otherwise the amount) before rebilling at the recurring price. Requires `recurringTrialPeriodDays > 0`. Default: `true`.
`stockQuantity`	body	number	No	Hint for stock on hand. Flo does not act as the inventory ledger. Minimum: 0.
`tags`	body	array of string	No
`tangibility`	body	string	No	Allowed values: `digital`, `physical`.
`taxCode`	body	string	No	Provider-neutral tax code. Minimum length: 0. Maximum length: 64.
`type`	body	string	No	Allowed values: `subscription`, `item`.
`weightGrams`	body	number	No	Minimum: 0.
`widthMm`	body	number	No	Minimum: 0.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`ageGroup`	string or null	Yes
`attributes`	object or null	Yes
`availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`brand`	object or null	Yes
`brand.code`	string	Yes
`brand.createdAt`	string (date-time)	Yes
`brand.description`	string or null	Yes
`brand.id`	string	Yes
`brand.name`	string	Yes
`brand.updatedAt`	string (date-time)	Yes
`category`	object or null	Yes
`category.code`	string	Yes
`category.createdAt`	string (date-time)	Yes
`category.description`	string or null	Yes
`category.id`	string	Yes
`category.name`	string	Yes
`category.parentId`	string (uuid) or null	Yes
`category.updatedAt`	string (date-time)	Yes
`code`	string	Yes
`createdAt`	string (date-time)	Yes
`description`	string or null	Yes
`gender`	string or null	Yes
`gtin`	string or null	Yes
`heightMm`	number or null	Yes
`id`	string	Yes
`knowledgeBaseUrl`	string or null	Yes
`lengthMm`	number or null	Yes
`longDescription`	string or null	Yes
`media`	array of object	Yes
`media[].altText`	string or null	Yes
`media[].createdAt`	string (date-time)	Yes
`media[].id`	string	Yes
`media[].isPrimary`	boolean	Yes
`media[].position`	number	Yes
`media[].type`	string	Yes	Allowed values: `image`, `video`, `model_3d`, `document`.
`media[].updatedAt`	string (date-time)	Yes
`media[].url`	string	Yes
`media[].variantId`	string (uuid) or null	Yes
`metadata`	object or null	Yes
`name`	string	Yes
`prices`	array of object	Yes
`prices[].amount`	number	Yes	Base price in major units.
`prices[].createdAt`	string (date-time)	Yes
`prices[].currency`	string	Yes	ISO-4217 currency code.
`prices[].effectiveAmount`	number	Yes	Sale price when the current time is in the sale window, otherwise the base amount.
`prices[].id`	string	Yes
`prices[].rebillAtSaleAmount`	boolean	Yes	When false an active sale applies to the first subscription charge only (rebills revert to the full amount); when true the sale price is retained for the subscription lifetime.
`prices[].saleAmount`	number or null	Yes	Sale price; populated only when sale window is set.
`prices[].saleEndsAt`	string (date-time) or null	Yes
`prices[].saleStartsAt`	string (date-time) or null	Yes
`prices[].status`	string	Yes	Inactive prices remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`prices[].updatedAt`	string (date-time)	Yes
`prices[].variantId`	string (uuid) or null	Yes
`recurringInterval`	string or null	Yes	Allowed values: `day`, `week`, `month`, `year`.
`recurringIntervalCount`	number or null	Yes
`recurringTrialPeriodDays`	number or null	Yes
`recurringTrialPeriodDaysFree`	boolean	Yes	Whether the trial period is free. When `false` the trial period is charged the effective sale price before rebilling at the recurring price.
`status`	string	Yes	Catalog lifecycle state. Inactive products retain identity and history but cannot be sold. Allowed values: `active`, `inactive`.
`stockQuantity`	number or null	Yes
`tags`	array of string or null	Yes
`tangibility`	string or null	Yes	Allowed values: `digital`, `physical`.
`taxCode`	string or null	Yes
`type`	string	Yes	Allowed values: `subscription`, `item`.
`updatedAt`	string (date-time)	Yes
`variants`	array of object	Yes
`variants[].attributes`	object or null	Yes
`variants[].availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`variants[].createdAt`	string (date-time)	Yes
`variants[].heightMm`	number or null	Yes
`variants[].id`	string	Yes
`variants[].lengthMm`	number or null	Yes
`variants[].name`	string or null	Yes
`variants[].sku`	string	Yes
`variants[].status`	string	Yes	Inactive variants remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`variants[].stockQuantity`	number or null	Yes
`variants[].updatedAt`	string (date-time)	Yes
`variants[].weightGrams`	number or null	Yes
`variants[].widthMm`	number or null	Yes
`weightGrams`	number or null	Yes
`widthMm`	number or null	Yes

Errors

Status	Description
`400`	The supplied request body or list query is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Product mutations require an owner or admin membership.
`404`	No product with the requested id exists for this client.

ProductBrand_create

Create Brand

Creates a product brand for the authenticated client.

Policy	Value
Operation	`POST /v1/products/brands`
Class	`mutating`
Risk	`low`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`mutation`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`code`	body	string	Yes	Unique brand code for this client. Minimum length: 1. Maximum length: 255.
`description`	body	string	No	Minimum length: 0. Maximum length: 1000.
`name`	body	string	Yes	Minimum length: 1. Maximum length: 255.

Result

Returns 201 with a JSON body.

Field	Type	Required
`code`	string	Yes
`createdAt`	string (date-time)	Yes
`description`	string or null	Yes
`id`	string	Yes
`name`	string	Yes
`updatedAt`	string (date-time)	Yes

Errors

Status	Description
`400`	The supplied request body or list query is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Brand mutations require an owner or admin membership.

ProductBrand_findOne

Get Brand

Returns a single brand.

Policy	Value
Operation	`GET /v1/products/brands/{uuid}`
Class	`read-only`
Risk	`low`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`read`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`uuid`	path	string	Yes

Result

Returns 200 with a JSON body.

Field	Type	Required
`code`	string	Yes
`createdAt`	string (date-time)	Yes
`description`	string or null	Yes
`id`	string	Yes
`name`	string	Yes
`updatedAt`	string (date-time)	Yes

Errors

Status	Description
`400`	The supplied request body or list query is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Brand mutations require an owner or admin membership.
`404`	No brand with the requested id exists for this client.

ProductBrand_list

List Brands

Returns paginated product brands for the client.

Policy	Value
Operation	`GET /v1/products/brands`
Class	`read-only`
Risk	`low`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`read`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`page`	query	integer	No	1-based page number for paginated list endpoints. Default: `1`. Minimum: 1.
`limit`	query	integer	No	Maximum number of records to return per page. Default: `20`. Minimum: 1. Maximum: 100.
`sort`	query	string	No	Sort by one allowed field. Use exactly one of `sort[asc]` or `sort[desc]`. Allowed fields: `code`, `createdAt`, `name`, `updatedAt`. Default: `createdAt` DESC. Allowed values: `code`, `createdAt`, `name`, `updatedAt`.
`relation`	query	string	No	This endpoint does not support relation aliases. Supplying relation returns 400.
`code`	query	string	No	Brand code. Equality filter. Pass without operator for exact match or pass any of the following operators: `[search]`. `[search]` is case-insensitive text contains matching.
`createdAt`	query	string (date-time)	No	Brand creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`id`	query	string	No	Brand id. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`name`	query	string	No	Brand name. Equality filter. Pass without operator for exact match or pass any of the following operators: `[search]`. `[search]` is case-insensitive text contains matching.
`updatedAt`	query	string (date-time)	No	Brand update timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.

Result

Returns 200 with a JSON body.

Field	Type	Required
`data`	array of object	Yes
`data[].code`	string	Yes
`data[].createdAt`	string (date-time)	Yes
`data[].description`	string or null	Yes
`data[].id`	string	Yes
`data[].name`	string	Yes
`data[].updatedAt`	string (date-time)	Yes
`limit`	number	Yes
`page`	number	Yes
`pages`	number	Yes
`total`	number	Yes

Errors

Status	Description
`400`	The supplied request body or list query is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Brand mutations require an owner or admin membership.

ProductBrand_update

Update Brand

Updates a brand.

Policy	Value
Operation	`PATCH /v1/products/brands/{uuid}`
Class	`mutating`
Risk	`low`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`mutation`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`uuid`	path	string	Yes
`code`	body	string	No	Unique brand code for this client. Minimum length: 1. Maximum length: 255.
`description`	body	string	No	Minimum length: 0. Maximum length: 1000.
`name`	body	string	No	Minimum length: 1. Maximum length: 255.

Result

Returns 200 with a JSON body.

Field	Type	Required
`code`	string	Yes
`createdAt`	string (date-time)	Yes
`description`	string or null	Yes
`id`	string	Yes
`name`	string	Yes
`updatedAt`	string (date-time)	Yes

Errors

Status	Description
`400`	The supplied request body or list query is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Brand mutations require an owner or admin membership.
`404`	No brand with the requested id exists for this client.

ProductCategory_create

Create Category

Creates a product category, optionally nested under a parent category.

Policy	Value
Operation	`POST /v1/products/categories`
Class	`mutating`
Risk	`low`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`mutation`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`code`	body	string	Yes	Minimum length: 1. Maximum length: 255.
`description`	body	string	No	Minimum length: 0. Maximum length: 1000.
`name`	body	string	Yes	Minimum length: 1. Maximum length: 255.
`parentId`	body	string (uuid)	No	Parent category id for nested taxonomies.

Result

Returns 201 with a JSON body.

Field	Type	Required
`code`	string	Yes
`createdAt`	string (date-time)	Yes
`description`	string or null	Yes
`id`	string	Yes
`name`	string	Yes
`parentId`	string (uuid) or null	Yes
`updatedAt`	string (date-time)	Yes

Errors

Status	Description
`400`	The supplied request body or list query is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Category mutations require an owner or admin membership.

ProductCategory_findOne

Get Category

Returns a single category.

Policy	Value
Operation	`GET /v1/products/categories/{uuid}`
Class	`read-only`
Risk	`low`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`read`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`uuid`	path	string	Yes

Result

Returns 200 with a JSON body.

Field	Type	Required
`code`	string	Yes
`createdAt`	string (date-time)	Yes
`description`	string or null	Yes
`id`	string	Yes
`name`	string	Yes
`parentId`	string (uuid) or null	Yes
`updatedAt`	string (date-time)	Yes

Errors

Status	Description
`400`	The supplied request body or list query is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Category mutations require an owner or admin membership.
`404`	No category with the requested id exists for this client.

ProductCategory_list

List Categories

Returns paginated product categories for the client.

Policy	Value
Operation	`GET /v1/products/categories`
Class	`read-only`
Risk	`low`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`read`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`page`	query	integer	No	1-based page number for paginated list endpoints. Default: `1`. Minimum: 1.
`limit`	query	integer	No	Maximum number of records to return per page. Default: `20`. Minimum: 1. Maximum: 100.
`sort`	query	string	No	Sort by one allowed field. Use exactly one of `sort[asc]` or `sort[desc]`. Allowed fields: `code`, `createdAt`, `name`, `updatedAt`. Default: `createdAt` DESC. Allowed values: `code`, `createdAt`, `name`, `updatedAt`.
`relation`	query	string	No	This endpoint does not support relation aliases. Supplying relation returns 400.
`code`	query	string	No	Category code. Equality filter. Pass without operator for exact match or pass any of the following operators: `[search]`. `[search]` is case-insensitive text contains matching.
`createdAt`	query	string (date-time)	No	Category creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`id`	query	string	No	Category id. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`name`	query	string	No	Category name. Equality filter. Pass without operator for exact match or pass any of the following operators: `[search]`. `[search]` is case-insensitive text contains matching.
`parentId`	query	string	No	Category parent id. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`updatedAt`	query	string (date-time)	No	Category update timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.

Result

Returns 200 with a JSON body.

Field	Type	Required
`data`	array of object	Yes
`data[].code`	string	Yes
`data[].createdAt`	string (date-time)	Yes
`data[].description`	string or null	Yes
`data[].id`	string	Yes
`data[].name`	string	Yes
`data[].parentId`	string (uuid) or null	Yes
`data[].updatedAt`	string (date-time)	Yes
`limit`	number	Yes
`page`	number	Yes
`pages`	number	Yes
`total`	number	Yes

Errors

Status	Description
`400`	The supplied request body or list query is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Category mutations require an owner or admin membership.

ProductCategory_update

Update Category

Updates a category.

Policy	Value
Operation	`PATCH /v1/products/categories/{uuid}`
Class	`mutating`
Risk	`low`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`mutation`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`uuid`	path	string	Yes
`code`	body	string	No	Minimum length: 1. Maximum length: 255.
`description`	body	string	No	Minimum length: 0. Maximum length: 1000.
`name`	body	string	No	Minimum length: 1. Maximum length: 255.
`parentId`	body	string (uuid)	No	Parent category id for nested taxonomies.

Result

Returns 200 with a JSON body.

Field	Type	Required
`code`	string	Yes
`createdAt`	string (date-time)	Yes
`description`	string or null	Yes
`id`	string	Yes
`name`	string	Yes
`parentId`	string (uuid) or null	Yes
`updatedAt`	string (date-time)	Yes

Errors

Status	Description
`400`	The supplied request body or list query is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Category mutations require an owner or admin membership.
`404`	No category with the requested id exists for this client.

ProductMedia_create

Create Media

Creates a media item under the specified product.

Policy	Value
Operation	`POST /v1/products/{productUuid}/media`
Class	`mutating`
Risk	`low`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`mutation`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`productUuid`	path	string	Yes
`altText`	body	string	No	Minimum length: 0. Maximum length: 500.
`isPrimary`	body	boolean	No	Marks this asset as the primary media item.
`position`	body	number	No	Sort position; lower values render first. Minimum: 0.
`type`	body	string	Yes	Allowed values: `image`, `video`, `model_3d`, `document`.
`url`	body	string (uri)	Yes	Minimum length: 1. Maximum length: 2048.
`variantId`	body	string (uuid)	No	Variant id to associate this media item with.

Result

Returns 201 with a JSON body.

Field	Type	Required	Description
`altText`	string or null	Yes
`createdAt`	string (date-time)	Yes
`id`	string	Yes
`isPrimary`	boolean	Yes
`position`	number	Yes
`type`	string	Yes	Allowed values: `image`, `video`, `model_3d`, `document`.
`updatedAt`	string (date-time)	Yes
`url`	string	Yes
`variantId`	string (uuid) or null	Yes

Errors

Status	Description
`400`	The supplied request body is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Media mutations require an owner or admin membership.

ProductMedia_findOne

Get Media

Returns a single media item.

Policy	Value
Operation	`GET /v1/products/{productUuid}/media/{uuid}`
Class	`read-only`
Risk	`low`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`read`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`productUuid`	path	string	Yes
`uuid`	path	string	Yes

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`altText`	string or null	Yes
`createdAt`	string (date-time)	Yes
`id`	string	Yes
`isPrimary`	boolean	Yes
`position`	number	Yes
`type`	string	Yes	Allowed values: `image`, `video`, `model_3d`, `document`.
`updatedAt`	string (date-time)	Yes
`url`	string	Yes
`variantId`	string (uuid) or null	Yes

Errors

Status	Description
`400`	The supplied request body is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Media mutations require an owner or admin membership.
`404`	No media with the requested id exists for this product.

ProductMedia_update

Update Media

Updates a media item.

Policy	Value
Operation	`PATCH /v1/products/{productUuid}/media/{uuid}`
Class	`mutating`
Risk	`low`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`mutation`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`productUuid`	path	string	Yes
`uuid`	path	string	Yes
`altText`	body	string	No	Minimum length: 0. Maximum length: 500.
`isPrimary`	body	boolean	No	Marks this asset as the primary media item.
`position`	body	number	No	Sort position; lower values render first. Minimum: 0.
`type`	body	string	No	Allowed values: `image`, `video`, `model_3d`, `document`.
`url`	body	string (uri)	No	Minimum length: 1. Maximum length: 2048.
`variantId`	body	string (uuid)	No	Variant id to associate this media item with.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`altText`	string or null	Yes
`createdAt`	string (date-time)	Yes
`id`	string	Yes
`isPrimary`	boolean	Yes
`position`	number	Yes
`type`	string	Yes	Allowed values: `image`, `video`, `model_3d`, `document`.
`updatedAt`	string (date-time)	Yes
`url`	string	Yes
`variantId`	string (uuid) or null	Yes

Errors

Status	Description
`400`	The supplied request body is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Media mutations require an owner or admin membership.
`404`	No media with the requested id exists for this product.

ProductPrice_create

Create stable Product Price

Policy	Value
Operation	`POST /v1/products/{productUuid}/prices`
Class	`mutating`
Risk	`medium`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`mutation`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`productUuid`	path	string	Yes
`amount`	body	number	Yes	Price in major units. Up to 2 decimal places. Minimum: 0. Maximum: 99999999.99.
`currency`	body	string	Yes	ISO-4217 currency code. Minimum length: 3. Maximum length: 3.
`rebillAtSaleAmount`	body	boolean	No	When false (default) an active sale applies to the first subscription charge only and rebills revert to the full amount. When true the sale price is kept for the lifetime of the subscription. No-op when no sale is active. Default: `false`.
`saleAmount`	body	number	No	Optional sale price; takes effect inside the sale window. Minimum: 0. Maximum: 99999999.99.
`saleEndsAt`	body	string (date-time)	No	Sale end timestamp (inclusive).
`saleStartsAt`	body	string (date-time)	No	Sale start timestamp (inclusive).
`variantId`	body	string (uuid)	No	Optional variant id to scope this price to a specific variant.

Result

Returns 201 with a JSON body.

Field	Type	Required	Description
`amount`	number	Yes	Base price in major units.
`createdAt`	string (date-time)	Yes
`currency`	string	Yes	ISO-4217 currency code.
`effectiveAmount`	number	Yes	Sale price when the current time is in the sale window, otherwise the base amount.
`id`	string	Yes
`rebillAtSaleAmount`	boolean	Yes	When false an active sale applies to the first subscription charge only (rebills revert to the full amount); when true the sale price is retained for the subscription lifetime.
`saleAmount`	number or null	Yes	Sale price; populated only when sale window is set.
`saleEndsAt`	string (date-time) or null	Yes
`saleStartsAt`	string (date-time) or null	Yes
`status`	string	Yes	Inactive prices remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`updatedAt`	string (date-time)	Yes
`variantId`	string (uuid) or null	Yes

Errors

Status	Description
`400`	The supplied price or lifecycle request is invalid.
`401`	A valid Basic auth API key or OAuth2 bearer token is required.
`403`	OAuth client members have read-only catalog access. Stable price mutations require an owner or admin membership.

ProductPrice_findOne

Get Product Price

Policy	Value
Operation	`GET /v1/products/{productUuid}/prices/{uuid}`
Class	`read-only`
Risk	`low`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`read`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`productUuid`	path	string	Yes
`uuid`	path	string	Yes

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`amount`	number	Yes	Base price in major units.
`createdAt`	string (date-time)	Yes
`currency`	string	Yes	ISO-4217 currency code.
`effectiveAmount`	number	Yes	Sale price when the current time is in the sale window, otherwise the base amount.
`id`	string	Yes
`rebillAtSaleAmount`	boolean	Yes	When false an active sale applies to the first subscription charge only (rebills revert to the full amount); when true the sale price is retained for the subscription lifetime.
`saleAmount`	number or null	Yes	Sale price; populated only when sale window is set.
`saleEndsAt`	string (date-time) or null	Yes
`saleStartsAt`	string (date-time) or null	Yes
`status`	string	Yes	Inactive prices remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`updatedAt`	string (date-time)	Yes
`variantId`	string (uuid) or null	Yes

Errors

Status	Description
`400`	The supplied price or lifecycle request is invalid.
`401`	A valid Basic auth API key or OAuth2 bearer token is required.
`403`	OAuth client members have read-only catalog access. Stable price mutations require an owner or admin membership.
`404`	No price with the requested id exists for this product.

ProductPrice_reactivate

Reactivate Product Price

Policy	Value
Operation	`POST /v1/products/{productUuid}/prices/{uuid}/reactivate`
Class	`mutating`
Risk	`medium`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`mutation`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`productUuid`	path	string	Yes
`uuid`	path	string	Yes

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`amount`	number	Yes	Base price in major units.
`createdAt`	string (date-time)	Yes
`currency`	string	Yes	ISO-4217 currency code.
`effectiveAmount`	number	Yes	Sale price when the current time is in the sale window, otherwise the base amount.
`id`	string	Yes
`rebillAtSaleAmount`	boolean	Yes	When false an active sale applies to the first subscription charge only (rebills revert to the full amount); when true the sale price is retained for the subscription lifetime.
`saleAmount`	number or null	Yes	Sale price; populated only when sale window is set.
`saleEndsAt`	string (date-time) or null	Yes
`saleStartsAt`	string (date-time) or null	Yes
`status`	string	Yes	Inactive prices remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`updatedAt`	string (date-time)	Yes
`variantId`	string (uuid) or null	Yes

Errors

Status	Description
`400`	The supplied price or lifecycle request is invalid.
`401`	A valid Basic auth API key or OAuth2 bearer token is required.
`403`	OAuth client members have read-only catalog access. Stable price mutations require an owner or admin membership.

ProductPrice_update

Update stable Product Price

Updates one price in place without replacing unrelated prices or changing its id.

Policy	Value
Operation	`PATCH /v1/products/{productUuid}/prices/{uuid}`
Class	`mutating`
Risk	`medium`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`mutation`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`productUuid`	path	string	Yes
`uuid`	path	string	Yes
`amount`	body	number	No	Price in major units. Up to 2 decimal places. Minimum: 0. Maximum: 99999999.99.
`currency`	body	string	No	ISO-4217 currency code. Minimum length: 3. Maximum length: 3.
`rebillAtSaleAmount`	body	boolean	No	When false (default) an active sale applies to the first subscription charge only and rebills revert to the full amount. When true the sale price is kept for the lifetime of the subscription. No-op when no sale is active. Default: `false`.
`saleAmount`	body	number	No	Optional sale price; takes effect inside the sale window. Minimum: 0. Maximum: 99999999.99.
`saleEndsAt`	body	string (date-time)	No	Sale end timestamp (inclusive).
`saleStartsAt`	body	string (date-time)	No	Sale start timestamp (inclusive).
`variantId`	body	string (uuid)	No	Optional variant id to scope this price to a specific variant.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`amount`	number	Yes	Base price in major units.
`createdAt`	string (date-time)	Yes
`currency`	string	Yes	ISO-4217 currency code.
`effectiveAmount`	number	Yes	Sale price when the current time is in the sale window, otherwise the base amount.
`id`	string	Yes
`rebillAtSaleAmount`	boolean	Yes	When false an active sale applies to the first subscription charge only (rebills revert to the full amount); when true the sale price is retained for the subscription lifetime.
`saleAmount`	number or null	Yes	Sale price; populated only when sale window is set.
`saleEndsAt`	string (date-time) or null	Yes
`saleStartsAt`	string (date-time) or null	Yes
`status`	string	Yes	Inactive prices remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`updatedAt`	string (date-time)	Yes
`variantId`	string (uuid) or null	Yes

Errors

Status	Description
`400`	The supplied price or lifecycle request is invalid.
`401`	A valid Basic auth API key or OAuth2 bearer token is required.
`403`	OAuth client members have read-only catalog access. Stable price mutations require an owner or admin membership.

ProductVariant_create

Create Variant

Creates a variant under the specified product.

Policy	Value
Operation	`POST /v1/products/{productUuid}/variants`
Class	`mutating`
Risk	`medium`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`mutation`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`productUuid`	path	string	Yes
`attributes`	body	object	No	Free-form variant attributes (e.g. color, size, material).
`availabilityStatus`	body	string	No	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`heightMm`	body	number	No	Minimum: 0.
`lengthMm`	body	number	No	Minimum: 0.
`name`	body	string	No	Minimum length: 1. Maximum length: 255.
`sku`	body	string	Yes	Variant SKU unique per product. Minimum length: 1. Maximum length: 255.
`stockQuantity`	body	number	No	Minimum: 0.
`weightGrams`	body	number	No	Minimum: 0.
`widthMm`	body	number	No	Minimum: 0.

Result

Returns 201 with a JSON body.

Field	Type	Required	Description
`attributes`	object or null	Yes
`availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`createdAt`	string (date-time)	Yes
`heightMm`	number or null	Yes
`id`	string	Yes
`lengthMm`	number or null	Yes
`name`	string or null	Yes
`sku`	string	Yes
`status`	string	Yes	Inactive variants remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`stockQuantity`	number or null	Yes
`updatedAt`	string (date-time)	Yes
`weightGrams`	number or null	Yes
`widthMm`	number or null	Yes

Errors

Status	Description
`400`	The supplied request body is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Variant mutations require an owner or admin membership.

ProductVariant_findOne

Get Variant

Returns a single variant under the specified product.

Policy	Value
Operation	`GET /v1/products/{productUuid}/variants/{uuid}`
Class	`read-only`
Risk	`low`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`read`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`productUuid`	path	string	Yes
`uuid`	path	string	Yes

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`attributes`	object or null	Yes
`availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`createdAt`	string (date-time)	Yes
`heightMm`	number or null	Yes
`id`	string	Yes
`lengthMm`	number or null	Yes
`name`	string or null	Yes
`sku`	string	Yes
`status`	string	Yes	Inactive variants remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`stockQuantity`	number or null	Yes
`updatedAt`	string (date-time)	Yes
`weightGrams`	number or null	Yes
`widthMm`	number or null	Yes

Errors

Status	Description
`400`	The supplied request body is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Variant mutations require an owner or admin membership.
`404`	No variant with the requested id exists for this product.

ProductVariant_reactivate

Reactivate Variant

Reactivates an inactive historical variant.

Policy	Value
Operation	`POST /v1/products/{productUuid}/variants/{uuid}/reactivate`
Class	`mutating`
Risk	`medium`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`mutation`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`productUuid`	path	string	Yes
`uuid`	path	string	Yes

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`attributes`	object or null	Yes
`availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`createdAt`	string (date-time)	Yes
`heightMm`	number or null	Yes
`id`	string	Yes
`lengthMm`	number or null	Yes
`name`	string or null	Yes
`sku`	string	Yes
`status`	string	Yes	Inactive variants remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`stockQuantity`	number or null	Yes
`updatedAt`	string (date-time)	Yes
`weightGrams`	number or null	Yes
`widthMm`	number or null	Yes

Errors

Status	Description
`400`	The supplied request body is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Variant mutations require an owner or admin membership.

ProductVariant_update

Update Variant

Updates a variant.

Policy	Value
Operation	`PATCH /v1/products/{productUuid}/variants/{uuid}`
Class	`mutating`
Risk	`medium`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`mutation`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`productUuid`	path	string	Yes
`uuid`	path	string	Yes
`attributes`	body	object	No	Free-form variant attributes (e.g. color, size, material).
`availabilityStatus`	body	string	No	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`heightMm`	body	number	No	Minimum: 0.
`lengthMm`	body	number	No	Minimum: 0.
`name`	body	string	No	Minimum length: 1. Maximum length: 255.
`sku`	body	string	No	Variant SKU unique per product. Minimum length: 1. Maximum length: 255.
`stockQuantity`	body	number	No	Minimum: 0.
`weightGrams`	body	number	No	Minimum: 0.
`widthMm`	body	number	No	Minimum: 0.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`attributes`	object or null	Yes
`availabilityStatus`	string or null	Yes	Allowed values: `in_stock`, `out_of_stock`, `pre_order`, `backorder`.
`createdAt`	string (date-time)	Yes
`heightMm`	number or null	Yes
`id`	string	Yes
`lengthMm`	number or null	Yes
`name`	string or null	Yes
`sku`	string	Yes
`status`	string	Yes	Inactive variants remain readable but cannot be selected for new purchases. Allowed values: `active`, `inactive`.
`stockQuantity`	number or null	Yes
`updatedAt`	string (date-time)	Yes
`weightGrams`	number or null	Yes
`widthMm`	number or null	Yes

Errors

Status	Description
`400`	The supplied request body is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	OAuth client members have read-only catalog access. Variant mutations require an owner or admin membership.
`404`	No variant with the requested id exists for this product.

Site navigation

Products tools

Products tools

Collection_create

Collection_findOne

Collection_list

Collection_update

Coupon_create

Coupon_findOne

Coupon_list

Coupon_reactivate

Coupon_update

Product_create

Product_findOne

Product_list

Product_reactivate

Product_update

ProductBrand_create

ProductBrand_findOne

ProductBrand_list

ProductBrand_update

ProductCategory_create

ProductCategory_findOne

ProductCategory_list

ProductCategory_update

ProductMedia_create

ProductMedia_findOne

ProductMedia_update

ProductPrice_create

ProductPrice_findOne

ProductPrice_reactivate

ProductPrice_update

ProductVariant_create

ProductVariant_findOne

ProductVariant_reactivate

ProductVariant_update

On this page