Variants
What is actually sold and stocked: SKU, barcodes, prices, the unit and how it is sold. Variants change under the version of their product card.
Variants
Objects
Variant
idintegerrequiredID of the record, unique among records of its kind in the store.
external_idstring or nullrequiredExternal ID: the ID of the record in your system; null when the app has not set one. Every app sees only its own IDs.
versionintegerrequiredVersion of the product card: variants change under the common version of the card, so a change of any variant or of the card moves it.
product_idintegerrequiredID of the product.
skustring or nullrequiredStock keeping unit (SKU); null when not set.
namemap of stringrequiredName of the variant by language, such as {"es": "Grande"}.
positionintegerrequiredPosition among the variants of the product: lower comes first.
is_activebooleanrequiredfalse takes the variant off sale.
barcodesarray of objectrequiredBarcodes of the variant.
Fields · 3
valuestringrequiredThe barcode.
typestringrequiredSymbology: ean13, ean8, upca, upce, code128, code39, gtin, itf, qr, datamatrix or other.
is_primarybooleanrequiredThe main barcode of the variant: labels and receipts show it.
option_valuesarray of objectrequiredOption values of the variant: one value of every option of the product.
Fields · 2
option_idintegerrequiredID of the option in options of the product.
value_idintegerrequiredID of the value in values of that option.
sold_bystringrequiredHow the variant is sold: each — by the piece; weight — by weight; volume — by volume.
- Values:
eachweightvolume
unitstringrequiredUnit of every quantity of the variant: pcs — pieces; g — grams; ml — milliliters.
- Values:
pcsgml
quantity_decimalsintegerrequiredDecimals of the quantities of the variant: 0 for pieces, 3 for weight and volume.
- Values:
03
priceintegerrequiredPrice for price_per_quantity units, an integer in minor units of currency.
compare_at_priceinteger or nullrequiredPrice before the discount, shown crossed out; null when there is no discount.
list_priceinteger or nullrequiredPrice as the owner set it, in minor units of list_price_currency; null — the price is set in store money (price). For such a variant price is derived from the price list rate and is not accepted as input.
list_price_currencystring or nullrequiredCurrency of the set price (store price list in a foreign currency); null — the price is in the store currency currency. As input: the store price list currency or currency.
currencystringrequiredCurrency of the prices, an ISO 4217 code: the currency of the store.
price_per_quantitystring or nullrequiredHow many units the price is for, a decimal string: one piece, or 1000 for a price per kilogram of a variant sold by weight. null when a variant sold by weight or volume has none set.
measure_stepstring or nullrequiredStep of the quantity in a line of a variant sold by weight or volume, in its unit; null when not set.
min_measure_qtystring or nullrequiredSmallest quantity in a line of a variant sold by weight or volume; null when not set.
max_measure_qtystring or nullrequiredLargest quantity in a line of a variant sold by weight or volume; null when not set.
net_contentobject or nullrequiredNet content of one piece: a 500 g pack, a 1000 ml bottle. A pack of several units of another variant takes it from that variant, a prepacked piece from its own measure; it can be written only for a plain variant sold by piece. null for variants sold by weight or volume and for pieces without a net content.
Fields · 2
quantitystringrequiredMeasure as a decimal string in unit: "500", "0.5".
unitstringrequiredUnit of the measure: g — grams; ml — millilitres.
- Values:
gml
sale_starts_atstring (date-time) or nullrequiredWhen the sale starts: compare_at_price is shown from this moment; null — no start limit.
sale_ends_atstring (date-time) or nullrequiredWhen the sale ends; null — no end limit.
cost_price_microinteger or nullCost for cost_per_quantity units in millionths of the minor unit of currency: 1.50 USD = 150000000. Only with the costs:read scope.
cost_per_quantitystringHow many units the cost is for, a decimal string: the purchase unit, such as 1000 g. Only with the costs:read scope.
track_inventorybooleanrequiredThe store counts the stock of the variant; false — it is sold without counting stock.
stock_source_variant_idinteger or nullrequiredFor a pack of several units of another variant: that variant. The pack sells from its stock and has no stock levels of its own. null for an ordinary variant.
stock_source_quantitystring or nullrequiredHow much of the base variant one piece of the pack takes, a decimal string in the unit of the base variant; null for an ordinary variant.
weight_gramsinteger or nullrequiredShipping weight in grams; null when not set.
length_mminteger or nullrequiredLength of the package in millimeters; null when not set.
width_mminteger or nullrequiredWidth of the package in millimeters; null when not set.
height_mminteger or nullrequiredHeight of the package in millimeters; null when not set.
created_atstring (date-time)requiredWhen the record was created.
updated_atstring (date-time)requiredWhen the record last changed.
deleted_atstring (date-time) or nullrequiredWhen the record was archived; null for a live record.
VariantRecipe
variant_idintegerrequiredID of the variant the recipe belongs to: a dish, a prep or another item made of components.
product_idintegerrequiredID of the product of the variant. The recipe is versioned on its card: ETag and If-Match carry the product version.
versionintegerrequiredVersion of the product card: the counter that If-Match checks. A recipe change moves it; the same recipe sent again does not.
componentsarray of objectrequiredComponents of the recipe in order: ingredients and preps with their amounts. The whole list replaces the recipe; an empty list clears it.
Fields · 3
variant_idintegerrequiredID of the component variant: an ingredient or a prep of the store.
quantitystring or nullrequiredAmount of the component per portion of a dish or per batch of a prep, a decimal string in the unit of the component (stock_unit of its product); null — to taste: the component is listed but not written off.
measure_modestringrequiredHow production measures the component: fixed — the planned amount; captured — weighed at production; proportional — scaled to a weighed component. Only production of preps reads it.
- Values:
fixedcapturedproportional
yield_quantitystring or nullrequiredOutput of one batch of a prep, a decimal string in the unit of the prep. Required for a prep; null for a dish. With yield checkpoints in the production steps, the steps set the output.
option_recipesarray of objectrequiredAmounts of per-dish options (recipe_per_variant) in this variant: a block for each such option of the product groups. Empty components — no amount, and the option is not offered on this variant. On write, a block sets the option amount as a whole, empty components remove it; options missing from the list and a body without the field are left as they are.
Fields · 2
option_idintegerrequiredID of a per-dish option from the product modifier groups.
componentsarray of objectrequiredWhat the option consumes when taken with this variant: ingredients and preps with their amount.
Fields · 2
variant_idintegerrequiredID of the product variant.
quantitystring or nullrequiredComponent amount for one use of the option, a decimal string in the unit of the component; null — to taste.
Endpoints
List product variants: SKU, barcodes, prices and units
get/variants
Scope: catalog:read
Parameters
Query
limitintegerPage size: up to 250 records; 50 by default.
- Minimum:
- 1
- Maximum:
- 250
cursorstringOpaque cursor: next_cursor of the previous page, or sync_cursor of the last page saved by the previous sync. The list goes in commit order, so the sync cursor later returns only what changed after it.
- Max length:
- 4096
updated_sincestring (date-time)Only records changed after this moment, ISO 8601 with a time zone. A filter for the first sync; continue with the cursor.
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$
include_deletedbooleantrue — also return deleted records: archived ones with deleted_at set, and records erased from the database as tombstones {id, deleted_at} in the continuation by the sync cursor. Turn it on for a sync.
product_idintegerOnly records of this product.
- Minimum:
- 1
skustringOnly the variant with this SKU.
- Max length:
- 64
barcodestringOnly variants with this barcode.
- Max length:
- 512
Responses
200Success
application/json
Records of the page.
deletedarray of objectrequiredRecords erased from the database since the cursor, as tombstones: only with include_deleted=true in the continuation by the sync cursor.
Fields · 2
idintegerrequiredID of the erased record.
deleted_atstring (date-time)requiredWhen the record was erased.
next_cursorstring or nullrequiredCursor of the next page; null on the last page.
has_morebooleanrequiredtrue when there is a next page.
sync_cursorstring or nullrequiredOn the last page — the cursor to continue from later: it returns only what changed after this page. null on other pages.
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
410The sync cursor is older than the deletion retention period or was issued before the database was restored
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/variants" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"data": [
{
"id": 0,
"external_id": "string",
"version": 0,
"product_id": 0,
"sku": "string",
"name": {
"key": "string"
},
"position": 0,
"is_active": true,
"barcodes": [
{
"value": "string",
"type": "string",
"is_primary": true
}
],
"option_values": [
{
"option_id": 0,
"value_id": 0
}
],
"sold_by": "each",
"unit": "pcs",
"quantity_decimals": 0,
"price": 0,
"compare_at_price": 0,
"list_price": 0,
"list_price_currency": "string",
"currency": "string",
"price_per_quantity": "string",
"measure_step": "string",
"min_measure_qty": "string",
"max_measure_qty": "string",
"net_content": {
"quantity": "string",
"unit": "g"
},
"sale_starts_at": "2026-01-15T12:00:00Z",
"sale_ends_at": "2026-01-15T12:00:00Z",
"cost_price_micro": 0,
"cost_per_quantity": "string",
"track_inventory": true,
"stock_source_variant_id": 0,
"stock_source_quantity": "string",
"weight_grams": 0,
"length_mm": 0,
"width_mm": 0,
"height_mm": 0,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}
],
"deleted": [
{
"id": 0,
"deleted_at": "2026-01-15T12:00:00Z"
}
],
"next_cursor": "string",
"has_more": true,
"sync_cursor": "string"
}Add a variant to a product
post/variants
Scope: catalog:write
Parameters
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
Request body application/json
product_idintegerrequiredID of the product.
external_idstring or nullExternal ID: the ID of the record in your system; null when the app has not set one. Every app sees only its own IDs.
skustring or nullStock keeping unit (SKU); null when not set.
- Max length:
- 64
namemap of string or null or nullName of the variant by language, such as {"es": "Grande"}.
- Max length:
- 255
priceintegerrequiredPrice for price_per_quantity units, an integer in minor units of currency.
- Minimum:
- 0
- Maximum:
- 10000000000
track_inventorybooleanThe store counts the stock of the variant; false — it is sold without counting stock.
is_activebooleanfalse takes the variant off sale.
positionintegerPosition among the variants of the product: lower comes first.
- Minimum:
- 0
- Maximum:
- 2147483647
list_priceintegerPrice as the owner set it, in minor units of list_price_currency; null — the price is set in store money (price). For such a variant price is derived from the price list rate and is not accepted as input.
- Minimum:
- 0
- Maximum:
- 10000000000
list_price_currencystring or nullCurrency of the set price (store price list in a foreign currency); null — the price is in the store currency currency. As input: the store price list currency or currency.
- Values:
ARSUSDBRLCLPCOPMXNPENRUBnull
compare_at_priceinteger or nullPrice before the discount, shown crossed out; null when there is no discount.
- Maximum:
- 10000000000
weight_gramsinteger or nullShipping weight in grams; null when not set.
- Minimum:
- 0
- Maximum:
- 2147483647
length_mminteger or nullLength of the package in millimeters; null when not set.
- Minimum:
- 0
- Maximum:
- 2147483647
width_mminteger or nullWidth of the package in millimeters; null when not set.
- Minimum:
- 0
- Maximum:
- 2147483647
height_mminteger or nullHeight of the package in millimeters; null when not set.
- Minimum:
- 0
- Maximum:
- 2147483647
sale_starts_atstring (date-time) or nullWhen the sale starts: compare_at_price is shown from this moment; null — no start limit.
sale_ends_atstring (date-time) or nullWhen the sale ends; null — no end limit.
sold_bystringHow the variant is sold: each — by the piece; weight — by weight; volume — by volume.
- Values:
eachweightvolume
price_per_quantitystring or nullHow many units the price is for, a decimal string: one piece, or 1000 for a price per kilogram of a variant sold by weight. null when a variant sold by weight or volume has none set.
- Max length:
- 32
measure_stepstring or nullStep of the quantity in a line of a variant sold by weight or volume, in its unit; null when not set.
- Max length:
- 32
min_measure_qtystring or nullSmallest quantity in a line of a variant sold by weight or volume; null when not set.
- Max length:
- 32
max_measure_qtystring or nullLargest quantity in a line of a variant sold by weight or volume; null when not set.
- Max length:
- 32
net_contentobjectNet content of one piece: a 500 g pack, a 1000 ml bottle. A pack of several units of another variant takes it from that variant, a prepacked piece from its own measure; it can be written only for a plain variant sold by piece. null for variants sold by weight or volume and for pieces without a net content.
Fields · 2
quantitystringMeasure as a decimal string in unit: "500", "0.5".
- Max length:
- 32
unitstringUnit of the measure: g — grams; ml — millilitres.
- Values:
gml
barcodesarray of object or nullBarcodes of the variant.
- Max items:
- 20
Fields · 3
typestringrequiredSymbology: ean13, ean8, upca, upce, code128, code39, gtin, itf, qr, datamatrix or other.
- Values:
ean13ean8upcaupcecode128code39gtinitfqrdatamatrixother
valuestringrequiredThe barcode.
is_primaryboolean or nullThe main barcode of the variant: labels and receipts show it.
option_valuesarray of objectOption values of the variant: one value of every option of the product.
- Max items:
- 10
Fields · 2
option_idintegerrequiredID of the option in options of the product.
value_idintegerrequiredID of the value in values of that option.
stock_source_variant_idinteger or nullFor a pack of several units of another variant: that variant. The pack sells from its stock and has no stock levels of its own. null for an ordinary variant.
stock_source_quantitystring or nullHow much of the base variant one piece of the pack takes, a decimal string in the unit of the base variant; null for an ordinary variant.
- Max length:
- 32
sibling_namemap of string or nullName by language of the only variant of the product, which this request makes one of several: the only variant has no name of its own, one of several must have it.
- Max length:
- 255
Responses
201Created
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
Locationstring (uri)requiredAddress of the created record; for an accepted request (202), the address to follow its outcome.
application/json
Returns Variant
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
external_id_archivedThe record with this external ID is archived - 409
external_id_in_useThe external ID is taken - 409
idempotency_key_in_useA request with this key is in progress - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X POST "https://api.saleya.app/v1/variants" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"product_id": 0,
"external_id": "string",
"sku": "string",
"name": {
"key": "string"
},
"price": 0,
"track_inventory": true,
"is_active": true,
"position": 0,
"list_price": 0,
"list_price_currency": "ARS",
"compare_at_price": 0,
"weight_grams": 0,
"length_mm": 0,
"width_mm": 0,
"height_mm": 0,
"sale_starts_at": "2026-01-15T12:00:00Z",
"sale_ends_at": "2026-01-15T12:00:00Z",
"sold_by": "each",
"price_per_quantity": "string",
"measure_step": "string",
"min_measure_qty": "string",
"max_measure_qty": "string",
"net_content": {
"quantity": "string",
"unit": "g"
},
"barcodes": [
{
"type": "ean13",
"value": "string",
"is_primary": true
}
],
"option_values": [
{
"option_id": 0,
"value_id": 0
}
],
"stock_source_variant_id": 0,
"stock_source_quantity": "string",
"sibling_name": {
"key": "string"
}
}{
"id": 0,
"external_id": "string",
"version": 0,
"product_id": 0,
"sku": "string",
"name": {
"key": "string"
},
"position": 0,
"is_active": true,
"barcodes": [
{
"value": "string",
"type": "string",
"is_primary": true
}
],
"option_values": [
{
"option_id": 0,
"value_id": 0
}
],
"sold_by": "each",
"unit": "pcs",
"quantity_decimals": 0,
"price": 0,
"compare_at_price": 0,
"list_price": 0,
"list_price_currency": "string",
"currency": "string",
"price_per_quantity": "string",
"measure_step": "string",
"min_measure_qty": "string",
"max_measure_qty": "string",
"net_content": {
"quantity": "string",
"unit": "g"
},
"sale_starts_at": "2026-01-15T12:00:00Z",
"sale_ends_at": "2026-01-15T12:00:00Z",
"cost_price_micro": 0,
"cost_per_quantity": "string",
"track_inventory": true,
"stock_source_variant_id": 0,
"stock_source_quantity": "string",
"weight_grams": 0,
"length_mm": 0,
"width_mm": 0,
"height_mm": 0,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}Get a product variant
get/variants/{variant}
Scope: catalog:read
Parameters
Path
variantintegerrequiredID of the variant.
Responses
200Success
Headers
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
application/json
Returns Variant
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/variants/{variant}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"external_id": "string",
"version": 0,
"product_id": 0,
"sku": "string",
"name": {
"key": "string"
},
"position": 0,
"is_active": true,
"barcodes": [
{
"value": "string",
"type": "string",
"is_primary": true
}
],
"option_values": [
{
"option_id": 0,
"value_id": 0
}
],
"sold_by": "each",
"unit": "pcs",
"quantity_decimals": 0,
"price": 0,
"compare_at_price": 0,
"list_price": 0,
"list_price_currency": "string",
"currency": "string",
"price_per_quantity": "string",
"measure_step": "string",
"min_measure_qty": "string",
"max_measure_qty": "string",
"net_content": {
"quantity": "string",
"unit": "g"
},
"sale_starts_at": "2026-01-15T12:00:00Z",
"sale_ends_at": "2026-01-15T12:00:00Z",
"cost_price_micro": 0,
"cost_per_quantity": "string",
"track_inventory": true,
"stock_source_variant_id": 0,
"stock_source_quantity": "string",
"weight_grams": 0,
"length_mm": 0,
"width_mm": 0,
"height_mm": 0,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}Update a product variant
patch/variants/{variant}
Scope: catalog:write
Parameters
Path
variantintegerrequiredID of the variant.
Query
consentobjectConsents to the consequences of the change, by kind: consent[<consent_kind>]=<consent_token> from a 409 consent_required response. Keep the consents already given when the next kind is asked.
Fields · 4
measure_changestringThe variant changes how it is sold (by the piece or by measure): its stock, prices and limits are converted.
- Min length:
- 64
- Max length:
- 64
piece_mode_offstringThe packs of the variant are archived when it stops being sold in packs.
- Min length:
- 64
- Max length:
- 64
stock_sourcestringThe own stock of the variant moves to its base variant, and it sells from the base from now on.
- Min length:
- 64
- Max length:
- 64
program_menustringThe dish leaves the menus of meal subscription programs.
- Min length:
- 64
- Max length:
- 64
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
If-MatchstringrequiredETag of the record from the last read, for example "7". The change applies only if nobody changed the record since then; otherwise 412. Without it — 428.
- Example:
"7"
Request body application/json
external_idstring or nullExternal ID: the ID of the record in your system; null when the app has not set one. Every app sees only its own IDs.
skustring or nullStock keeping unit (SKU); null when not set.
- Max length:
- 64
namemap of string or null or nullName of the variant by language, such as {"es": "Grande"}.
- Max length:
- 255
priceintegerPrice for price_per_quantity units, an integer in minor units of currency.
- Minimum:
- 0
- Maximum:
- 10000000000
track_inventorybooleanThe store counts the stock of the variant; false — it is sold without counting stock.
is_activebooleanfalse takes the variant off sale.
positionintegerPosition among the variants of the product: lower comes first.
- Minimum:
- 0
- Maximum:
- 2147483647
list_priceintegerPrice as the owner set it, in minor units of list_price_currency; null — the price is set in store money (price). For such a variant price is derived from the price list rate and is not accepted as input.
- Minimum:
- 0
- Maximum:
- 10000000000
list_price_currencystring or nullCurrency of the set price (store price list in a foreign currency); null — the price is in the store currency currency. As input: the store price list currency or currency.
- Values:
ARSUSDBRLCLPCOPMXNPENRUBnull
compare_at_priceinteger or nullPrice before the discount, shown crossed out; null when there is no discount.
- Maximum:
- 10000000000
weight_gramsinteger or nullShipping weight in grams; null when not set.
- Minimum:
- 0
- Maximum:
- 2147483647
length_mminteger or nullLength of the package in millimeters; null when not set.
- Minimum:
- 0
- Maximum:
- 2147483647
width_mminteger or nullWidth of the package in millimeters; null when not set.
- Minimum:
- 0
- Maximum:
- 2147483647
height_mminteger or nullHeight of the package in millimeters; null when not set.
- Minimum:
- 0
- Maximum:
- 2147483647
sale_starts_atstring (date-time) or nullWhen the sale starts: compare_at_price is shown from this moment; null — no start limit.
sale_ends_atstring (date-time) or nullWhen the sale ends; null — no end limit.
sold_bystringHow the variant is sold: each — by the piece; weight — by weight; volume — by volume.
- Values:
eachweightvolume
price_per_quantitystring or nullHow many units the price is for, a decimal string: one piece, or 1000 for a price per kilogram of a variant sold by weight. null when a variant sold by weight or volume has none set.
- Max length:
- 32
measure_stepstring or nullStep of the quantity in a line of a variant sold by weight or volume, in its unit; null when not set.
- Max length:
- 32
min_measure_qtystring or nullSmallest quantity in a line of a variant sold by weight or volume; null when not set.
- Max length:
- 32
max_measure_qtystring or nullLargest quantity in a line of a variant sold by weight or volume; null when not set.
- Max length:
- 32
net_contentobjectNet content of one piece: a 500 g pack, a 1000 ml bottle. A pack of several units of another variant takes it from that variant, a prepacked piece from its own measure; it can be written only for a plain variant sold by piece. null for variants sold by weight or volume and for pieces without a net content.
Fields · 2
quantitystringMeasure as a decimal string in unit: "500", "0.5".
- Max length:
- 32
unitstringUnit of the measure: g — grams; ml — millilitres.
- Values:
gml
barcodesarray of object or nullBarcodes of the variant.
- Max items:
- 20
Fields · 3
typestringrequiredSymbology: ean13, ean8, upca, upce, code128, code39, gtin, itf, qr, datamatrix or other.
- Values:
ean13ean8upcaupcecode128code39gtinitfqrdatamatrixother
valuestringrequiredThe barcode.
is_primaryboolean or nullThe main barcode of the variant: labels and receipts show it.
option_valuesarray of objectOption values of the variant: one value of every option of the product.
- Max items:
- 10
Fields · 2
option_idintegerrequiredID of the option in options of the product.
value_idintegerrequiredID of the value in values of that option.
stock_source_variant_idinteger or nullFor a pack of several units of another variant: that variant. The pack sells from its stock and has no stock levels of its own. null for an ordinary variant.
stock_source_quantitystring or nullHow much of the base variant one piece of the pack takes, a decimal string in the unit of the base variant; null for an ordinary variant.
- Max length:
- 32
Responses
200Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
application/json
Returns Variant
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
412The record changed after it was read: the version in If-Match is not current
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
428The request needs If-Match with the ETag of the record
application/problem+json
Returns Problem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
consent_requiredConsent to the consequences is required - 409
external_id_archivedThe record with this external ID is archived - 409
external_id_in_useThe external ID is taken - 409
idempotency_key_in_useA request with this key is in progress - 412
precondition_failedThe record has changed - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid - 428
precondition_requiredIf-Match is required
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X PATCH "https://api.saleya.app/v1/variants/{variant}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"' \
-H "Content-Type: application/json" \
-d @body.json{
"external_id": "string",
"sku": "string",
"name": {
"key": "string"
},
"price": 0,
"track_inventory": true,
"is_active": true,
"position": 0,
"list_price": 0,
"list_price_currency": "ARS",
"compare_at_price": 0,
"weight_grams": 0,
"length_mm": 0,
"width_mm": 0,
"height_mm": 0,
"sale_starts_at": "2026-01-15T12:00:00Z",
"sale_ends_at": "2026-01-15T12:00:00Z",
"sold_by": "each",
"price_per_quantity": "string",
"measure_step": "string",
"min_measure_qty": "string",
"max_measure_qty": "string",
"net_content": {
"quantity": "string",
"unit": "g"
},
"barcodes": [
{
"type": "ean13",
"value": "string",
"is_primary": true
}
],
"option_values": [
{
"option_id": 0,
"value_id": 0
}
],
"stock_source_variant_id": 0,
"stock_source_quantity": "string"
}{
"id": 0,
"external_id": "string",
"version": 0,
"product_id": 0,
"sku": "string",
"name": {
"key": "string"
},
"position": 0,
"is_active": true,
"barcodes": [
{
"value": "string",
"type": "string",
"is_primary": true
}
],
"option_values": [
{
"option_id": 0,
"value_id": 0
}
],
"sold_by": "each",
"unit": "pcs",
"quantity_decimals": 0,
"price": 0,
"compare_at_price": 0,
"list_price": 0,
"list_price_currency": "string",
"currency": "string",
"price_per_quantity": "string",
"measure_step": "string",
"min_measure_qty": "string",
"max_measure_qty": "string",
"net_content": {
"quantity": "string",
"unit": "g"
},
"sale_starts_at": "2026-01-15T12:00:00Z",
"sale_ends_at": "2026-01-15T12:00:00Z",
"cost_price_micro": 0,
"cost_per_quantity": "string",
"track_inventory": true,
"stock_source_variant_id": 0,
"stock_source_quantity": "string",
"weight_grams": 0,
"length_mm": 0,
"width_mm": 0,
"height_mm": 0,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}Archive a product variant
delete/variants/{variant}
Scope: catalog:write
Parameters
Path
variantintegerrequiredID of the variant.
Query
consentobjectConsents to the consequences of the change, by kind: consent[<consent_kind>]=<consent_token> from a 409 consent_required response. Keep the consents already given when the next kind is asked.
Fields · 4
recipe_ingredientstringThe item is an ingredient of live recipes and leaves them.
- Min length:
- 64
- Max length:
- 64
production_draftstringDraft production acts with the item are cancelled.
- Min length:
- 64
- Max length:
- 64
program_menustringThe dish leaves the menus of meal subscription programs.
- Min length:
- 64
- Max length:
- 64
stock_dependentsstringPacks drawing from the stock of this variant become ordinary variants with zero stock.
- Min length:
- 64
- Max length:
- 64
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
If-MatchstringrequiredETag of the record from the last read, for example "7". The change applies only if nobody changed the record since then; otherwise 412. Without it — 428.
- Example:
"7"
Responses
204Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
No body
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
412The record changed after it was read: the version in If-Match is not current
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
428The request needs If-Match with the ETag of the record
application/problem+json
Returns Problem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
consent_requiredConsent to the consequences is required - 409
idempotency_key_in_useA request with this key is in progress - 409
in_use_conflictRecord in use - 412
precondition_failedThe record has changed - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid - 422
last_variant_of_productLast variant of the product - 428
precondition_requiredIf-Match is required
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X DELETE "https://api.saleya.app/v1/variants/{variant}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"'Get a product variant by its external ID
get/variants/by-external-id/{external_id}
Scope: catalog:read
Parameters
Path
external_idstringrequiredExternal ID: the ID of the record in your system.
Responses
200Success
Headers
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
application/json
Returns Variant
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/variants/by-external-id/{external_id}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"external_id": "string",
"version": 0,
"product_id": 0,
"sku": "string",
"name": {
"key": "string"
},
"position": 0,
"is_active": true,
"barcodes": [
{
"value": "string",
"type": "string",
"is_primary": true
}
],
"option_values": [
{
"option_id": 0,
"value_id": 0
}
],
"sold_by": "each",
"unit": "pcs",
"quantity_decimals": 0,
"price": 0,
"compare_at_price": 0,
"list_price": 0,
"list_price_currency": "string",
"currency": "string",
"price_per_quantity": "string",
"measure_step": "string",
"min_measure_qty": "string",
"max_measure_qty": "string",
"net_content": {
"quantity": "string",
"unit": "g"
},
"sale_starts_at": "2026-01-15T12:00:00Z",
"sale_ends_at": "2026-01-15T12:00:00Z",
"cost_price_micro": 0,
"cost_per_quantity": "string",
"track_inventory": true,
"stock_source_variant_id": 0,
"stock_source_quantity": "string",
"weight_grams": 0,
"length_mm": 0,
"width_mm": 0,
"height_mm": 0,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}Create or update a variant by its external ID
patch/variants/by-external-id/{external_id}
Scope: catalog:write
Parameters
Path
external_idstringrequiredExternal ID: the ID of the record in your system.
Query
consentobjectConsents to the consequences of the change, by kind: consent[<consent_kind>]=<consent_token> from a 409 consent_required response. Keep the consents already given when the next kind is asked.
Fields · 4
measure_changestringThe variant changes how it is sold (by the piece or by measure): its stock, prices and limits are converted.
- Min length:
- 64
- Max length:
- 64
piece_mode_offstringThe packs of the variant are archived when it stops being sold in packs.
- Min length:
- 64
- Max length:
- 64
stock_sourcestringThe own stock of the variant moves to its base variant, and it sells from the base from now on.
- Min length:
- 64
- Max length:
- 64
program_menustringThe dish leaves the menus of meal subscription programs.
- Min length:
- 64
- Max length:
- 64
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
If-MatchstringETag of the record from the last read. Required when a record with this external ID exists (otherwise 428) and must be absent when it does not.
- Example:
"7"
If-None-Matchstring* — create only: if a record with this external ID already exists, the request gets 412.
- Values:
*
Request body application/json
product_idintegerID of the product.
skustring or nullStock keeping unit (SKU); null when not set.
- Max length:
- 64
namemap of string or null or nullName of the variant by language, such as {"es": "Grande"}.
- Max length:
- 255
priceintegerPrice for price_per_quantity units, an integer in minor units of currency.
- Minimum:
- 0
- Maximum:
- 10000000000
track_inventorybooleanThe store counts the stock of the variant; false — it is sold without counting stock.
is_activebooleanfalse takes the variant off sale.
positionintegerPosition among the variants of the product: lower comes first.
- Minimum:
- 0
- Maximum:
- 2147483647
list_priceintegerPrice as the owner set it, in minor units of list_price_currency; null — the price is set in store money (price). For such a variant price is derived from the price list rate and is not accepted as input.
- Minimum:
- 0
- Maximum:
- 10000000000
list_price_currencystring or nullCurrency of the set price (store price list in a foreign currency); null — the price is in the store currency currency. As input: the store price list currency or currency.
- Values:
ARSUSDBRLCLPCOPMXNPENRUBnull
compare_at_priceinteger or nullPrice before the discount, shown crossed out; null when there is no discount.
- Maximum:
- 10000000000
weight_gramsinteger or nullShipping weight in grams; null when not set.
- Minimum:
- 0
- Maximum:
- 2147483647
length_mminteger or nullLength of the package in millimeters; null when not set.
- Minimum:
- 0
- Maximum:
- 2147483647
width_mminteger or nullWidth of the package in millimeters; null when not set.
- Minimum:
- 0
- Maximum:
- 2147483647
height_mminteger or nullHeight of the package in millimeters; null when not set.
- Minimum:
- 0
- Maximum:
- 2147483647
sale_starts_atstring (date-time) or nullWhen the sale starts: compare_at_price is shown from this moment; null — no start limit.
sale_ends_atstring (date-time) or nullWhen the sale ends; null — no end limit.
sold_bystringHow the variant is sold: each — by the piece; weight — by weight; volume — by volume.
- Values:
eachweightvolume
price_per_quantitystring or nullHow many units the price is for, a decimal string: one piece, or 1000 for a price per kilogram of a variant sold by weight. null when a variant sold by weight or volume has none set.
- Max length:
- 32
measure_stepstring or nullStep of the quantity in a line of a variant sold by weight or volume, in its unit; null when not set.
- Max length:
- 32
min_measure_qtystring or nullSmallest quantity in a line of a variant sold by weight or volume; null when not set.
- Max length:
- 32
max_measure_qtystring or nullLargest quantity in a line of a variant sold by weight or volume; null when not set.
- Max length:
- 32
net_contentobjectNet content of one piece: a 500 g pack, a 1000 ml bottle. A pack of several units of another variant takes it from that variant, a prepacked piece from its own measure; it can be written only for a plain variant sold by piece. null for variants sold by weight or volume and for pieces without a net content.
Fields · 2
quantitystringMeasure as a decimal string in unit: "500", "0.5".
- Max length:
- 32
unitstringUnit of the measure: g — grams; ml — millilitres.
- Values:
gml
barcodesarray of object or nullBarcodes of the variant.
- Max items:
- 20
Fields · 3
typestringrequiredSymbology: ean13, ean8, upca, upce, code128, code39, gtin, itf, qr, datamatrix or other.
- Values:
ean13ean8upcaupcecode128code39gtinitfqrdatamatrixother
valuestringrequiredThe barcode.
is_primaryboolean or nullThe main barcode of the variant: labels and receipts show it.
option_valuesarray of objectOption values of the variant: one value of every option of the product.
- Max items:
- 10
Fields · 2
option_idintegerrequiredID of the option in options of the product.
value_idintegerrequiredID of the value in values of that option.
stock_source_variant_idinteger or nullFor a pack of several units of another variant: that variant. The pack sells from its stock and has no stock levels of its own. null for an ordinary variant.
stock_source_quantitystring or nullHow much of the base variant one piece of the pack takes, a decimal string in the unit of the base variant; null for an ordinary variant.
- Max length:
- 32
sibling_namemap of string or nullName by language of the only variant of the product, which this request makes one of several: the only variant has no name of its own, one of several must have it.
- Max length:
- 255
Responses
200Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
application/json
Returns Variant
201Created
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
Locationstring (uri)requiredAddress of the created record; for an accepted request (202), the address to follow its outcome.
application/json
Returns Variant
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
412The record changed after it was read: the version in If-Match is not current
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
428The request needs If-Match with the ETag of the record
application/problem+json
Returns Problem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
consent_requiredConsent to the consequences is required - 409
external_id_archivedThe record with this external ID is archived - 409
idempotency_key_in_useA request with this key is in progress - 412
precondition_failedThe record has changed - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid - 428
precondition_requiredIf-Match is required
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X PATCH "https://api.saleya.app/v1/variants/by-external-id/{external_id}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"product_id": 0,
"sku": "string",
"name": {
"key": "string"
},
"price": 0,
"track_inventory": true,
"is_active": true,
"position": 0,
"list_price": 0,
"list_price_currency": "ARS",
"compare_at_price": 0,
"weight_grams": 0,
"length_mm": 0,
"width_mm": 0,
"height_mm": 0,
"sale_starts_at": "2026-01-15T12:00:00Z",
"sale_ends_at": "2026-01-15T12:00:00Z",
"sold_by": "each",
"price_per_quantity": "string",
"measure_step": "string",
"min_measure_qty": "string",
"max_measure_qty": "string",
"net_content": {
"quantity": "string",
"unit": "g"
},
"barcodes": [
{
"type": "ean13",
"value": "string",
"is_primary": true
}
],
"option_values": [
{
"option_id": 0,
"value_id": 0
}
],
"stock_source_variant_id": 0,
"stock_source_quantity": "string",
"sibling_name": {
"key": "string"
}
}{
"id": 0,
"external_id": "string",
"version": 0,
"product_id": 0,
"sku": "string",
"name": {
"key": "string"
},
"position": 0,
"is_active": true,
"barcodes": [
{
"value": "string",
"type": "string",
"is_primary": true
}
],
"option_values": [
{
"option_id": 0,
"value_id": 0
}
],
"sold_by": "each",
"unit": "pcs",
"quantity_decimals": 0,
"price": 0,
"compare_at_price": 0,
"list_price": 0,
"list_price_currency": "string",
"currency": "string",
"price_per_quantity": "string",
"measure_step": "string",
"min_measure_qty": "string",
"max_measure_qty": "string",
"net_content": {
"quantity": "string",
"unit": "g"
},
"sale_starts_at": "2026-01-15T12:00:00Z",
"sale_ends_at": "2026-01-15T12:00:00Z",
"cost_price_micro": 0,
"cost_per_quantity": "string",
"track_inventory": true,
"stock_source_variant_id": 0,
"stock_source_quantity": "string",
"weight_grams": 0,
"length_mm": 0,
"width_mm": 0,
"height_mm": 0,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}Get the recipe of a variant: components and the yield of a prep
get/variants/{variant}/recipe
Scope: catalog:read
Parameters
Path
variantintegerrequiredID of the variant.
Responses
200Success
Headers
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
application/json
Returns VariantRecipe
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/variants/{variant}/recipe" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"variant_id": 0,
"product_id": 0,
"version": 0,
"components": [
{
"variant_id": 0,
"quantity": "string",
"measure_mode": "fixed"
}
],
"yield_quantity": "string",
"option_recipes": [
{
"option_id": 0,
"components": [
{
"variant_id": 0,
"quantity": "string"
}
]
}
]
}Replace the recipe of a variant: components and the yield of a prep
put/variants/{variant}/recipe
Scope: catalog:write
Parameters
Path
variantintegerrequiredID of the variant.
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
If-MatchstringrequiredETag of the record from the last read, for example "7". The change applies only if nobody changed the record since then; otherwise 412. Without it — 428.
- Example:
"7"
Request body application/json
componentsarray of objectrequiredComponents of the recipe in order: ingredients and preps with their amounts. The whole list replaces the recipe; an empty list clears it.
- Max items:
- 100
Fields · 3
variant_idintegerrequiredID of the component variant: an ingredient or a prep of the store.
quantitystring or nullrequiredAmount of the component per portion of a dish or per batch of a prep, a decimal string in the unit of the component (stock_unit of its product); null — to taste: the component is listed but not written off.
- Max length:
- 32
measure_modestringHow production measures the component: fixed — the planned amount; captured — weighed at production; proportional — scaled to a weighed component. Only production of preps reads it.
- Values:
fixedcapturedproportionalby_output
yield_quantitystring or nullOutput of one batch of a prep, a decimal string in the unit of the prep. Required for a prep; null for a dish. With yield checkpoints in the production steps, the steps set the output.
- Max length:
- 32
option_recipesarray of objectAmounts of per-dish options (recipe_per_variant) in this variant: a block for each such option of the product groups. Empty components — no amount, and the option is not offered on this variant. On write, a block sets the option amount as a whole, empty components remove it; options missing from the list and a body without the field are left as they are.
- Max items:
- 50
- No repeats
Fields · 2
option_idintegerrequiredID of a per-dish option from the product modifier groups.
componentsarray of objectrequiredWhat the option consumes when taken with this variant: ingredients and preps with their amount.
- Max items:
- 100
Fields · 2
variant_idintegerrequiredID of the product variant.
quantitystring or nullrequiredComponent amount for one use of the option, a decimal string in the unit of the component; null — to taste.
- Max length:
- 32
Responses
200Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
application/json
Returns VariantRecipe
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
412The record changed after it was read: the version in If-Match is not current
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
428The request needs If-Match with the ETag of the record
application/problem+json
Returns Problem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
idempotency_key_in_useA request with this key is in progress - 412
precondition_failedThe record has changed - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid - 428
precondition_requiredIf-Match is required
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X PUT "https://api.saleya.app/v1/variants/{variant}/recipe" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"' \
-H "Content-Type: application/json" \
-d @body.json{
"components": [
{
"variant_id": 0,
"quantity": "string",
"measure_mode": "fixed"
}
],
"yield_quantity": "string",
"option_recipes": [
{
"option_id": 0,
"components": [
{
"variant_id": 0,
"quantity": "string"
}
]
}
]
}{
"variant_id": 0,
"product_id": 0,
"version": 0,
"components": [
{
"variant_id": 0,
"quantity": "string",
"measure_mode": "fixed"
}
],
"yield_quantity": "string",
"option_recipes": [
{
"option_id": 0,
"components": [
{
"variant_id": 0,
"quantity": "string"
}
]
}
]
}