Products
Product cards: names, descriptions, categories, options and photos. Variants have their own endpoints; a product is created and written together with them.
Products
Objects
Product
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 record: it grows with every change. Send it as the ETag in If-Match to change the record.
typestringrequiredKind of product: goods — goods for sale; dish — a dish cooked to order; ingredient — raw material for recipes; prep — a semi-finished item made in-house; manufactured — made by the own production of the store; meal_program — a meal subscription; bundle — a set of other products; gift_card — a gift card; service — a service booked in advance.
- Values:
goodsdishingredientprepmanufacturedmeal_programbundlegift_cardserviceservice_package
stock_unitobject or nullrequiredStock unit of an item with stock by measure (ingredient, prep, manufactured): stock, recipes and yield are kept in it. null for goods and dishes — their unit is the selling axis of the variant.
Fields · 3
unitstringrequiredBase unit: g — grams, ml — milliliters, pcs — pieces. Quantities of the variants of the product are decimal strings in this unit.
- Values:
gmlpcs
purchase_unitstring or nullrequiredName of the purchase package, such as kg or box; null — the item is bought in its base unit.
purchase_quantitystringrequiredHow many base units are in one purchase package, a decimal string, such as 1000 for a kilogram of an item kept in grams.
namemap of stringrequiredName by language: an object of the filled languages, for example {"es": "Café", "en": "Coffee"}.
short_descriptionmap of stringrequiredShort description by language, plain text for product lists.
descriptionmap of stringrequiredDescription by language in Markdown (GitHub Flavored): an object of the filled languages.
slugstringrequiredAddress of the product on the storefront, unique in the store.
brand_idinteger or nullrequiredID of the brand of the product; null when not set.
tax_class_idinteger or nullrequiredID of the tax class of the product (/v1/tax-classes); null — the default class of the store. A sale keeps the rate of its item: a change of class affects future sales only.
category_idsarray of integerrequiredIDs of the categories the product is in, ascending.
primary_category_idinteger or nullrequiredThe main category among category_ids; null when the product has no main category.
optionsarray of objectrequiredOptions the variants differ by, such as size or color, in order.
Fields · 5
idintegerrequiredID of the option.
keystringrequiredMachine key of the option, unique within the product, such as size.
namemap of stringrequiredName of the option by language.
positionintegerrequiredPosition of the option: lower comes first.
valuesarray of objectrequiredValues of the option in order.
Fields · 4
idintegerrequiredID of the value. Variants refer to it in option_values.
valuemap of stringrequiredThe value by language, such as {"es": "Rojo", "en": "Red"}.
swatch_colorstring or nullrequiredColor of the swatch, a hex code such as #C0392B; null when the value has no swatch.
positionintegerrequiredPosition of the value: lower comes first.
modifier_groupsarray of objectrequiredThe product modifier groups in display order with the selection rule on this product. Option surcharges by variant — GET /v1/products/{product}/modifier-groups; PUT on the same path replaces the groups.
Fields · 2
group_idintegerrequiredID of the modifier group (/v1/modifier-groups).
selection_ruleobject or nullrequiredSelection rule on this product instead of the group rule; null — the group rule.
Fields · 2
min_selectintegerrequiredHow many options must be chosen on this product.
max_selectinteger or nullrequiredHow many options can be chosen on this product; null — no limit.
mediaarray of objectrequiredPhotos and videos of the gallery in order: the same objects as in /v1/products/{product}/media.
Fields · 7
idintegerrequiredID of the file in the media library. A file is in the gallery of a product at most once.
kindstringrequiredimage or video.
- Values:
imagevideo
urlstringrequiredPublic address of the file.
mimestringrequiredMIME type of the file, such as image/webp.
altmap of stringrequiredAlternative text by language, for screen readers and search engines.
positionintegerrequiredPlace in the gallery, starting from zero.
is_primarybooleanrequiredThe main photo: the storefront shows it first.
is_activebooleanrequiredfalse takes the product off sale and hides it from the storefront.
published_atstring (date-time) or nullrequiredWhen the product appears on the storefront; null — right away.
unpublished_atstring (date-time) or nullrequiredWhen the product leaves the storefront; null — it stays.
sale_schedulearray of object or nullrequiredWhen the item can be ordered — week windows in the store time zone; null means always. Outside a window the product stays visible and can go to the cart, and checkout checks the schedule against the order fulfilment time.
Fields · 3
daysarray of integerrequiredWindow days, ISO: 1 is Monday, 7 is Sunday.
fromstringrequiredWindow start, “HH:MM” on the store clock.
tostringrequiredWindow end, “HH:MM”, exclusive; “24:00” means until the end of the day. An end earlier than the start makes the window run past midnight; it belongs to its start day.
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 product was archived with its variants; null for a live product.
Endpoints
List products: categories, options and media, without variants
get/products
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.
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/products" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"data": [
{
"id": 0,
"external_id": "string",
"version": 0,
"type": "goods",
"stock_unit": {
"unit": "g",
"purchase_unit": "string",
"purchase_quantity": "string"
},
"name": {
"key": "string"
},
"short_description": {
"key": "string"
},
"description": {
"key": "string"
},
"slug": "string",
"brand_id": 0,
"tax_class_id": 0,
"category_ids": [
0
],
"primary_category_id": 0,
"options": [
{
"id": 0,
"key": "string",
"name": {
"key": "string"
},
"position": 0,
"values": [
{
"id": 0,
"value": {
"key": "string"
},
"swatch_color": "string",
"position": 0
}
]
}
],
"modifier_groups": [
{
"group_id": 0,
"selection_rule": {
"min_select": 0,
"max_select": 0
}
}
],
"media": [
{
"id": 0,
"kind": "image",
"url": "string",
"mime": "string",
"alt": {
"key": "string"
},
"position": 0,
"is_primary": true
}
],
"is_active": true,
"published_at": "2026-01-15T12:00:00Z",
"unpublished_at": "2026-01-15T12:00:00Z",
"sale_schedule": [
{
"days": [
0
],
"from": "string",
"to": "string"
}
],
"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"
}Create a product with its variants
post/products
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
namemap of string or nullrequiredName by language: an object of the filled languages, for example {"es": "Café", "en": "Coffee"}.
- Max length:
- 255
short_descriptionmap of string or null or nullShort description by language, plain text for product lists.
- Max length:
- 500
descriptionmap of string or null or nullDescription by language in Markdown (GitHub Flavored): an object of the filled languages.
- Max length:
- 50000
slugstringAddress of the product on the storefront, unique in the store.
- Max length:
- 160
brand_idinteger or nullID of the brand of the product; null when not set.
tax_class_idinteger or nullID of the tax class of the product (/v1/tax-classes); null — the default class of the store. A sale keeps the rate of its item: a change of class affects future sales only.
category_idsarray of integerIDs of the categories the product is in, ascending.
primary_category_idinteger or nullThe main category among category_ids; null when the product has no main category.
is_activebooleanfalse takes the product off sale and hides it from the storefront.
published_atstring (date-time) or nullWhen the product appears on the storefront; null — right away.
unpublished_atstring (date-time) or nullWhen the product leaves the storefront; null — it stays.
sale_schedulearray of object or nullWhen the item can be ordered — week windows in the store time zone; null means always. Outside a window the product stays visible and can go to the cart, and checkout checks the schedule against the order fulfilment time.
- Max items:
- 14
Fields · 3
daysarray of integerrequiredWindow days, ISO: 1 is Monday, 7 is Sunday.
- Min items:
- 1
- Max items:
- 7
- Minimum:
- 1
- Maximum:
- 7
fromstringrequiredWindow start, “HH:MM” on the store clock.
- Pattern:
^(?:[01]\d|2[0-3]):[0-5]\d$|^24:00$
tostringrequiredWindow end, “HH:MM”, exclusive; “24:00” means until the end of the day. An end earlier than the start makes the window run past midnight; it belongs to its start day.
- Pattern:
^(?:[01]\d|2[0-3]):[0-5]\d$|^24:00$
typestringKind of product: goods — goods for sale; dish — a dish cooked to order; ingredient — raw material for recipes; prep — a semi-finished item made in-house; manufactured — made by the own production of the store; meal_program — a meal subscription; bundle — a set of other products; gift_card — a gift card; service — a service booked in advance.
- Values:
goodsdishingredientprep
stock_unitobject or nullStock unit of an item with stock by measure (ingredient, prep, manufactured): stock, recipes and yield are kept in it. null for goods and dishes — their unit is the selling axis of the variant.
Fields · 3
unitstringBase unit: g — grams, ml — milliliters, pcs — pieces. Quantities of the variants of the product are decimal strings in this unit.
- Values:
gmlpcs
purchase_unitstring or nullName of the purchase package, such as kg or box; null — the item is bought in its base unit.
- Max length:
- 16
purchase_quantitystring or nullHow many base units are in one purchase package, a decimal string, such as 1000 for a kilogram of an item kept in grams.
- Max length:
- 32
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.
variantsarray of objectrequiredVariant rows written together with the card. A row is found by its external_id: a variant of the product with this ID is changed by the sent fields, without one a variant is created; variants not mentioned stay as they are. Creating a product needs at least one row with a price.
- Min items:
- 1
- Max items:
- 200
Fields · 23
external_idstring or nullExternal ID of the variant, its ID in your system: the key the row is matched by.
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.
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 Product
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 - 409
plan_limit_reachedThe plan limit is reached - 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/products" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"name": {
"key": "string"
},
"short_description": {
"key": "string"
},
"description": {
"key": "string"
},
"slug": "string",
"brand_id": 0,
"tax_class_id": 0,
"category_ids": [
0
],
"primary_category_id": 0,
"is_active": true,
"published_at": "2026-01-15T12:00:00Z",
"unpublished_at": "2026-01-15T12:00:00Z",
"sale_schedule": [
{
"days": [
1
],
"from": "string",
"to": "string"
}
],
"type": "goods",
"stock_unit": {
"unit": "g",
"purchase_unit": "string",
"purchase_quantity": "string"
},
"external_id": "string",
"variants": [
{
"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
}
]
}
]
}{
"id": 0,
"external_id": "string",
"version": 0,
"type": "goods",
"stock_unit": {
"unit": "g",
"purchase_unit": "string",
"purchase_quantity": "string"
},
"name": {
"key": "string"
},
"short_description": {
"key": "string"
},
"description": {
"key": "string"
},
"slug": "string",
"brand_id": 0,
"tax_class_id": 0,
"category_ids": [
0
],
"primary_category_id": 0,
"options": [
{
"id": 0,
"key": "string",
"name": {
"key": "string"
},
"position": 0,
"values": [
{
"id": 0,
"value": {
"key": "string"
},
"swatch_color": "string",
"position": 0
}
]
}
],
"modifier_groups": [
{
"group_id": 0,
"selection_rule": {
"min_select": 0,
"max_select": 0
}
}
],
"media": [
{
"id": 0,
"kind": "image",
"url": "string",
"mime": "string",
"alt": {
"key": "string"
},
"position": 0,
"is_primary": true
}
],
"is_active": true,
"published_at": "2026-01-15T12:00:00Z",
"unpublished_at": "2026-01-15T12:00:00Z",
"sale_schedule": [
{
"days": [
0
],
"from": "string",
"to": "string"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}Get a product
get/products/{product}
Scope: catalog:read
Parameters
Path
productintegerrequiredID of the product.
Responses
200Success
Headers
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
application/json
Returns Product
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/products/{product}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"external_id": "string",
"version": 0,
"type": "goods",
"stock_unit": {
"unit": "g",
"purchase_unit": "string",
"purchase_quantity": "string"
},
"name": {
"key": "string"
},
"short_description": {
"key": "string"
},
"description": {
"key": "string"
},
"slug": "string",
"brand_id": 0,
"tax_class_id": 0,
"category_ids": [
0
],
"primary_category_id": 0,
"options": [
{
"id": 0,
"key": "string",
"name": {
"key": "string"
},
"position": 0,
"values": [
{
"id": 0,
"value": {
"key": "string"
},
"swatch_color": "string",
"position": 0
}
]
}
],
"modifier_groups": [
{
"group_id": 0,
"selection_rule": {
"min_select": 0,
"max_select": 0
}
}
],
"media": [
{
"id": 0,
"kind": "image",
"url": "string",
"mime": "string",
"alt": {
"key": "string"
},
"position": 0,
"is_primary": true
}
],
"is_active": true,
"published_at": "2026-01-15T12:00:00Z",
"unpublished_at": "2026-01-15T12:00:00Z",
"sale_schedule": [
{
"days": [
0
],
"from": "string",
"to": "string"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}Change a product card: fields, categories, external ID
patch/products/{product}
Scope: catalog:write
Parameters
Path
productintegerrequiredID of the product.
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
namemap of string or nullName by language: an object of the filled languages, for example {"es": "Café", "en": "Coffee"}.
- Max length:
- 255
short_descriptionmap of string or null or nullShort description by language, plain text for product lists.
- Max length:
- 500
descriptionmap of string or null or nullDescription by language in Markdown (GitHub Flavored): an object of the filled languages.
- Max length:
- 50000
slugstringAddress of the product on the storefront, unique in the store.
- Max length:
- 160
brand_idinteger or nullID of the brand of the product; null when not set.
tax_class_idinteger or nullID of the tax class of the product (/v1/tax-classes); null — the default class of the store. A sale keeps the rate of its item: a change of class affects future sales only.
category_idsarray of integerIDs of the categories the product is in, ascending.
primary_category_idinteger or nullThe main category among category_ids; null when the product has no main category.
is_activebooleanfalse takes the product off sale and hides it from the storefront.
published_atstring (date-time) or nullWhen the product appears on the storefront; null — right away.
unpublished_atstring (date-time) or nullWhen the product leaves the storefront; null — it stays.
sale_schedulearray of object or nullWhen the item can be ordered — week windows in the store time zone; null means always. Outside a window the product stays visible and can go to the cart, and checkout checks the schedule against the order fulfilment time.
- Max items:
- 14
Fields · 3
daysarray of integerrequiredWindow days, ISO: 1 is Monday, 7 is Sunday.
- Min items:
- 1
- Max items:
- 7
- Minimum:
- 1
- Maximum:
- 7
fromstringrequiredWindow start, “HH:MM” on the store clock.
- Pattern:
^(?:[01]\d|2[0-3]):[0-5]\d$|^24:00$
tostringrequiredWindow end, “HH:MM”, exclusive; “24:00” means until the end of the day. An end earlier than the start makes the window run past midnight; it belongs to its start day.
- Pattern:
^(?:[01]\d|2[0-3]):[0-5]\d$|^24:00$
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.
variantsarray of objectVariant rows written together with the card. A row is found by its external_id: a variant of the product with this ID is changed by the sent fields, without one a variant is created; variants not mentioned stay as they are. Creating a product needs at least one row with a price.
- Min items:
- 1
- Max items:
- 200
Fields · 24
external_idstring or nullExternal ID of the variant, its ID in your system: the key the row is matched by.
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.
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 Product
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/products/{product}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"' \
-H "Content-Type: application/json" \
-d @body.json{
"name": {
"key": "string"
},
"short_description": {
"key": "string"
},
"description": {
"key": "string"
},
"slug": "string",
"brand_id": 0,
"tax_class_id": 0,
"category_ids": [
0
],
"primary_category_id": 0,
"is_active": true,
"published_at": "2026-01-15T12:00:00Z",
"unpublished_at": "2026-01-15T12:00:00Z",
"sale_schedule": [
{
"days": [
1
],
"from": "string",
"to": "string"
}
],
"external_id": "string",
"variants": [
{
"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
}
]
}
]
}{
"id": 0,
"external_id": "string",
"version": 0,
"type": "goods",
"stock_unit": {
"unit": "g",
"purchase_unit": "string",
"purchase_quantity": "string"
},
"name": {
"key": "string"
},
"short_description": {
"key": "string"
},
"description": {
"key": "string"
},
"slug": "string",
"brand_id": 0,
"tax_class_id": 0,
"category_ids": [
0
],
"primary_category_id": 0,
"options": [
{
"id": 0,
"key": "string",
"name": {
"key": "string"
},
"position": 0,
"values": [
{
"id": 0,
"value": {
"key": "string"
},
"swatch_color": "string",
"position": 0
}
]
}
],
"modifier_groups": [
{
"group_id": 0,
"selection_rule": {
"min_select": 0,
"max_select": 0
}
}
],
"media": [
{
"id": 0,
"kind": "image",
"url": "string",
"mime": "string",
"alt": {
"key": "string"
},
"position": 0,
"is_primary": true
}
],
"is_active": true,
"published_at": "2026-01-15T12:00:00Z",
"unpublished_at": "2026-01-15T12:00:00Z",
"sale_schedule": [
{
"days": [
0
],
"from": "string",
"to": "string"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}Archive a product with its variants
delete/products/{product}
Scope: catalog:write
Parameters
Path
productintegerrequiredID of the product.
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
live_subscriptionsstringThe program with live subscriptions is taken off sale.
- 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 - 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/products/{product}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"'Get a product by its external ID
get/products/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 Product
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/products/by-external-id/{external_id}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"external_id": "string",
"version": 0,
"type": "goods",
"stock_unit": {
"unit": "g",
"purchase_unit": "string",
"purchase_quantity": "string"
},
"name": {
"key": "string"
},
"short_description": {
"key": "string"
},
"description": {
"key": "string"
},
"slug": "string",
"brand_id": 0,
"tax_class_id": 0,
"category_ids": [
0
],
"primary_category_id": 0,
"options": [
{
"id": 0,
"key": "string",
"name": {
"key": "string"
},
"position": 0,
"values": [
{
"id": 0,
"value": {
"key": "string"
},
"swatch_color": "string",
"position": 0
}
]
}
],
"modifier_groups": [
{
"group_id": 0,
"selection_rule": {
"min_select": 0,
"max_select": 0
}
}
],
"media": [
{
"id": 0,
"kind": "image",
"url": "string",
"mime": "string",
"alt": {
"key": "string"
},
"position": 0,
"is_primary": true
}
],
"is_active": true,
"published_at": "2026-01-15T12:00:00Z",
"unpublished_at": "2026-01-15T12:00:00Z",
"sale_schedule": [
{
"days": [
0
],
"from": "string",
"to": "string"
}
],
"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 product with its variants by its external ID
patch/products/by-external-id/{external_id}
Scope: catalog:write
Parameters
Path
external_idstringrequiredExternal ID: the ID of the record in your system.
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
namemap of string or nullName by language: an object of the filled languages, for example {"es": "Café", "en": "Coffee"}.
- Max length:
- 255
short_descriptionmap of string or null or nullShort description by language, plain text for product lists.
- Max length:
- 500
descriptionmap of string or null or nullDescription by language in Markdown (GitHub Flavored): an object of the filled languages.
- Max length:
- 50000
slugstringAddress of the product on the storefront, unique in the store.
- Max length:
- 160
brand_idinteger or nullID of the brand of the product; null when not set.
tax_class_idinteger or nullID of the tax class of the product (/v1/tax-classes); null — the default class of the store. A sale keeps the rate of its item: a change of class affects future sales only.
category_idsarray of integerIDs of the categories the product is in, ascending.
primary_category_idinteger or nullThe main category among category_ids; null when the product has no main category.
is_activebooleanfalse takes the product off sale and hides it from the storefront.
published_atstring (date-time) or nullWhen the product appears on the storefront; null — right away.
unpublished_atstring (date-time) or nullWhen the product leaves the storefront; null — it stays.
sale_schedulearray of object or nullWhen the item can be ordered — week windows in the store time zone; null means always. Outside a window the product stays visible and can go to the cart, and checkout checks the schedule against the order fulfilment time.
- Max items:
- 14
Fields · 3
daysarray of integerrequiredWindow days, ISO: 1 is Monday, 7 is Sunday.
- Min items:
- 1
- Max items:
- 7
- Minimum:
- 1
- Maximum:
- 7
fromstringrequiredWindow start, “HH:MM” on the store clock.
- Pattern:
^(?:[01]\d|2[0-3]):[0-5]\d$|^24:00$
tostringrequiredWindow end, “HH:MM”, exclusive; “24:00” means until the end of the day. An end earlier than the start makes the window run past midnight; it belongs to its start day.
- Pattern:
^(?:[01]\d|2[0-3]):[0-5]\d$|^24:00$
typestringKind of product: goods — goods for sale; dish — a dish cooked to order; ingredient — raw material for recipes; prep — a semi-finished item made in-house; manufactured — made by the own production of the store; meal_program — a meal subscription; bundle — a set of other products; gift_card — a gift card; service — a service booked in advance.
- Values:
goodsdishingredientprep
stock_unitobject or nullStock unit of an item with stock by measure (ingredient, prep, manufactured): stock, recipes and yield are kept in it. null for goods and dishes — their unit is the selling axis of the variant.
Fields · 3
unitstringBase unit: g — grams, ml — milliliters, pcs — pieces. Quantities of the variants of the product are decimal strings in this unit.
- Values:
gmlpcs
purchase_unitstring or nullName of the purchase package, such as kg or box; null — the item is bought in its base unit.
- Max length:
- 16
purchase_quantitystring or nullHow many base units are in one purchase package, a decimal string, such as 1000 for a kilogram of an item kept in grams.
- Max length:
- 32
variantsarray of objectVariant rows written together with the card. A row is found by its external_id: a variant of the product with this ID is changed by the sent fields, without one a variant is created; variants not mentioned stay as they are. Creating a product needs at least one row with a price.
- Min items:
- 1
- Max items:
- 200
Fields · 24
external_idstring or nullExternal ID of the variant, its ID in your system: the key the row is matched by.
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.
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 Product
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 Product
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
external_id_in_useThe external ID is taken - 409
idempotency_key_in_useA request with this key is in progress - 409
plan_limit_reachedThe plan limit is reached - 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/products/by-external-id/{external_id}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"name": {
"key": "string"
},
"short_description": {
"key": "string"
},
"description": {
"key": "string"
},
"slug": "string",
"brand_id": 0,
"tax_class_id": 0,
"category_ids": [
0
],
"primary_category_id": 0,
"is_active": true,
"published_at": "2026-01-15T12:00:00Z",
"unpublished_at": "2026-01-15T12:00:00Z",
"sale_schedule": [
{
"days": [
1
],
"from": "string",
"to": "string"
}
],
"type": "goods",
"stock_unit": {
"unit": "g",
"purchase_unit": "string",
"purchase_quantity": "string"
},
"variants": [
{
"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
}
]
}
]
}{
"id": 0,
"external_id": "string",
"version": 0,
"type": "goods",
"stock_unit": {
"unit": "g",
"purchase_unit": "string",
"purchase_quantity": "string"
},
"name": {
"key": "string"
},
"short_description": {
"key": "string"
},
"description": {
"key": "string"
},
"slug": "string",
"brand_id": 0,
"tax_class_id": 0,
"category_ids": [
0
],
"primary_category_id": 0,
"options": [
{
"id": 0,
"key": "string",
"name": {
"key": "string"
},
"position": 0,
"values": [
{
"id": 0,
"value": {
"key": "string"
},
"swatch_color": "string",
"position": 0
}
]
}
],
"modifier_groups": [
{
"group_id": 0,
"selection_rule": {
"min_select": 0,
"max_select": 0
}
}
],
"media": [
{
"id": 0,
"kind": "image",
"url": "string",
"mime": "string",
"alt": {
"key": "string"
},
"position": 0,
"is_primary": true
}
],
"is_active": true,
"published_at": "2026-01-15T12:00:00Z",
"unpublished_at": "2026-01-15T12:00:00Z",
"sale_schedule": [
{
"days": [
0
],
"from": "string",
"to": "string"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}Replace the product options and lay out its variants
put/products/{product}/options
Scope: catalog:write
Parameters
Path
productintegerrequiredID of the product.
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 · 1
variant_axesstringVariants with the same combination are merged, and the variants named for the archive are archived together with their dependencies.
- 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
optionsarray of objectrequiredOptions the variants differ by, such as size or color, in order.
- Max items:
- 10
Fields · 4
keystringrequiredMachine key of the option, unique within the product, such as size.
- Max length:
- 32
- Pattern:
^[a-z][a-z0-9_]*$
namemap of string or nullrequiredName of the option by language.
- Max length:
- 120
valuesarray of objectrequiredValues of the option in order.
- Min items:
- 1
- Max items:
- 50
Fields · 3
valuemap of string or nullrequiredThe value by language, such as {"es": "Rojo", "en": "Red"}.
- Max length:
- 120
swatch_colorstring or nullColor of the swatch, a hex code such as #C0392B; null when the value has no swatch.
- Max length:
- 16
- Pattern:
^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
idinteger or nullID of the value. Variants refer to it in option_values.
idinteger or nullID of the option.
variantsarray of objectrequiredLayout of every live variant of the product: a combination of values or the archive. A variant missing from the layout is rejected: it may have been added after you read the product.
- Max items:
- 200
Fields · 3
idintegerrequiredID of the variant.
archivebooleantrue — archive the variant instead of giving it values.
value_indexesarray of integerValues of the variant: for every option, the index of the value in options[i].values of this request, so new values without an id can be named.
- Max items:
- 10
- Minimum:
- 0
- Maximum:
- 49
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 Product
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 - 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/products/{product}/options" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"' \
-H "Content-Type: application/json" \
-d @body.json{
"options": [
{
"key": "string",
"name": {
"key": "string"
},
"values": [
{
"value": {
"key": "string"
},
"swatch_color": "string",
"id": 0
}
],
"id": 0
}
],
"variants": [
{
"id": 0,
"archive": true,
"value_indexes": [
0
]
}
]
}{
"id": 0,
"external_id": "string",
"version": 0,
"type": "goods",
"stock_unit": {
"unit": "g",
"purchase_unit": "string",
"purchase_quantity": "string"
},
"name": {
"key": "string"
},
"short_description": {
"key": "string"
},
"description": {
"key": "string"
},
"slug": "string",
"brand_id": 0,
"tax_class_id": 0,
"category_ids": [
0
],
"primary_category_id": 0,
"options": [
{
"id": 0,
"key": "string",
"name": {
"key": "string"
},
"position": 0,
"values": [
{
"id": 0,
"value": {
"key": "string"
},
"swatch_color": "string",
"position": 0
}
]
}
],
"modifier_groups": [
{
"group_id": 0,
"selection_rule": {
"min_select": 0,
"max_select": 0
}
}
],
"media": [
{
"id": 0,
"kind": "image",
"url": "string",
"mime": "string",
"alt": {
"key": "string"
},
"position": 0,
"is_primary": true
}
],
"is_active": true,
"published_at": "2026-01-15T12:00:00Z",
"unpublished_at": "2026-01-15T12:00:00Z",
"sale_schedule": [
{
"days": [
0
],
"from": "string",
"to": "string"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}