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.

Loading the search index…

Variants

Objects

Variant

  • idintegerrequired

    ID of the record, unique among records of its kind in the store.

  • external_idstring or nullrequired

    External ID: the ID of the record in your system; null when the app has not set one. Every app sees only its own IDs.

  • versionintegerrequired

    Version 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_idintegerrequired

    ID of the product.

  • skustring or nullrequired

    Stock keeping unit (SKU); null when not set.

  • namemap of stringrequired

    Name of the variant by language, such as {"es": "Grande"}.

  • positionintegerrequired

    Position among the variants of the product: lower comes first.

  • is_activebooleanrequired

    false takes the variant off sale.

  • barcodesarray of objectrequired

    Barcodes of the variant.

    Fields · 3
    • valuestringrequired

      The barcode.

    • typestringrequired

      Symbology: ean13, ean8, upca, upce, code128, code39, gtin, itf, qr, datamatrix or other.

    • is_primarybooleanrequired

      The main barcode of the variant: labels and receipts show it.

  • option_valuesarray of objectrequired

    Option values of the variant: one value of every option of the product.

    Fields · 2
    • option_idintegerrequired

      ID of the option in options of the product.

    • value_idintegerrequired

      ID of the value in values of that option.

  • sold_bystringrequired

    How the variant is sold: each — by the piece; weight — by weight; volume — by volume.

    Values:
    eachweightvolume
  • unitstringrequired

    Unit of every quantity of the variant: pcs — pieces; g — grams; ml — milliliters.

    Values:
    pcsgml
  • quantity_decimalsintegerrequired

    Decimals of the quantities of the variant: 0 for pieces, 3 for weight and volume.

    Values:
    03
  • priceintegerrequired

    Price for price_per_quantity units, an integer in minor units of currency.

  • compare_at_priceinteger or nullrequired

    Price before the discount, shown crossed out; null when there is no discount.

  • list_priceinteger or nullrequired

    Price 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 nullrequired

    Currency 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.

  • currencystringrequired

    Currency of the prices, an ISO 4217 code: the currency of the store.

  • price_per_quantitystring or nullrequired

    How 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 nullrequired

    Step 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 nullrequired

    Smallest quantity in a line of a variant sold by weight or volume; null when not set.

  • max_measure_qtystring or nullrequired

    Largest quantity in a line of a variant sold by weight or volume; null when not set.

  • net_contentobject or nullrequired

    Net 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
    • quantitystringrequired

      Measure as a decimal string in unit: "500", "0.5".

    • unitstringrequired

      Unit of the measure: g — grams; ml — millilitres.

      Values:
      gml
  • sale_starts_atstring (date-time) or nullrequired

    When the sale starts: compare_at_price is shown from this moment; null — no start limit.

  • sale_ends_atstring (date-time) or nullrequired

    When the sale ends; null — no end limit.

  • cost_price_microinteger or null

    Cost 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_quantitystring

    How many units the cost is for, a decimal string: the purchase unit, such as 1000 g. Only with the costs:read scope.

  • track_inventorybooleanrequired

    The store counts the stock of the variant; false — it is sold without counting stock.

  • stock_source_variant_idinteger or nullrequired

    For 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 nullrequired

    How 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 nullrequired

    Shipping weight in grams; null when not set.

  • length_mminteger or nullrequired

    Length of the package in millimeters; null when not set.

  • width_mminteger or nullrequired

    Width of the package in millimeters; null when not set.

  • height_mminteger or nullrequired

    Height of the package in millimeters; null when not set.

  • created_atstring (date-time)required

    When the record was created.

  • updated_atstring (date-time)required

    When the record last changed.

  • deleted_atstring (date-time) or nullrequired

    When the record was archived; null for a live record.

VariantRecipe

  • variant_idintegerrequired

    ID of the variant the recipe belongs to: a dish, a prep or another item made of components.

  • product_idintegerrequired

    ID of the product of the variant. The recipe is versioned on its card: ETag and If-Match carry the product version.

  • versionintegerrequired

    Version of the product card: the counter that If-Match checks. A recipe change moves it; the same recipe sent again does not.

  • componentsarray of objectrequired

    Components 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_idintegerrequired

      ID of the component variant: an ingredient or a prep of the store.

    • quantitystring or nullrequired

      Amount 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_modestringrequired

      How 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 nullrequired

    Output 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 objectrequired

    Amounts 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_idintegerrequired

      ID of a per-dish option from the product modifier groups.

    • componentsarray of objectrequired

      What the option consumes when taken with this variant: ingredients and preps with their amount.

      Fields · 2
      • variant_idintegerrequired

        ID of the product variant.

      • quantitystring or nullrequired

        Component 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

  • limitinteger

    Page size: up to 250 records; 50 by default.

    Minimum:
    1
    Maximum:
    250
  • cursorstring

    Opaque 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_deletedboolean

    true — 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_idinteger

    Only records of this product.

    Minimum:
    1
  • skustring

    Only the variant with this SKU.

    Max length:
    64
  • barcodestring

    Only variants with this barcode.

    Max length:
    512

Responses

200Success

application/json

  • dataarray of Variantrequired

    Records of the page.

  • deletedarray of objectrequired

    Records erased from the database since the cursor, as tombstones: only with include_deleted=true in the continuation by the sync cursor.

    Fields · 2
    • idintegerrequired

      ID of the erased record.

    • deleted_atstring (date-time)required

      When the record was erased.

  • next_cursorstring or nullrequired

    Cursor of the next page; null on the last page.

  • has_morebooleanrequired

    true when there is a next page.

  • sync_cursorstring or nullrequired

    On 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
curl "https://api.saleya.app/v1/variants" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "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-Keystring

    Unique 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_idintegerrequired

    ID of the product.

  • external_idstring or null

    External 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 null

    Stock keeping unit (SKU); null when not set.

    Max length:
    64
  • namemap of string or null or null

    Name of the variant by language, such as {"es": "Grande"}.

    Max length:
    255
  • priceintegerrequired

    Price for price_per_quantity units, an integer in minor units of currency.

    Minimum:
    0
    Maximum:
    10000000000
  • track_inventoryboolean

    The store counts the stock of the variant; false — it is sold without counting stock.

  • is_activeboolean

    false takes the variant off sale.

  • positioninteger

    Position among the variants of the product: lower comes first.

    Minimum:
    0
    Maximum:
    2147483647
  • list_priceinteger

    Price 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 null

    Currency 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 null

    Price before the discount, shown crossed out; null when there is no discount.

    Maximum:
    10000000000
  • weight_gramsinteger or null

    Shipping weight in grams; null when not set.

    Minimum:
    0
    Maximum:
    2147483647
  • length_mminteger or null

    Length of the package in millimeters; null when not set.

    Minimum:
    0
    Maximum:
    2147483647
  • width_mminteger or null

    Width of the package in millimeters; null when not set.

    Minimum:
    0
    Maximum:
    2147483647
  • height_mminteger or null

    Height of the package in millimeters; null when not set.

    Minimum:
    0
    Maximum:
    2147483647
  • sale_starts_atstring (date-time) or null

    When the sale starts: compare_at_price is shown from this moment; null — no start limit.

  • sale_ends_atstring (date-time) or null

    When the sale ends; null — no end limit.

  • sold_bystring

    How the variant is sold: each — by the piece; weight — by weight; volume — by volume.

    Values:
    eachweightvolume
  • price_per_quantitystring or null

    How 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 null

    Step 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 null

    Smallest quantity in a line of a variant sold by weight or volume; null when not set.

    Max length:
    32
  • max_measure_qtystring or null

    Largest quantity in a line of a variant sold by weight or volume; null when not set.

    Max length:
    32
  • net_contentobject

    Net 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
    • quantitystring

      Measure as a decimal string in unit: "500", "0.5".

      Max length:
      32
    • unitstring

      Unit of the measure: g — grams; ml — millilitres.

      Values:
      gml
  • barcodesarray of object or null

    Barcodes of the variant.

    Max items:
    20
    Fields · 3
    • typestringrequired

      Symbology: ean13, ean8, upca, upce, code128, code39, gtin, itf, qr, datamatrix or other.

      Values:
      ean13ean8upcaupcecode128code39gtinitfqrdatamatrixother
    • valuestringrequired

      The barcode.

    • is_primaryboolean or null

      The main barcode of the variant: labels and receipts show it.

  • option_valuesarray of object

    Option values of the variant: one value of every option of the product.

    Max items:
    10
    Fields · 2
    • option_idintegerrequired

      ID of the option in options of the product.

    • value_idintegerrequired

      ID of the value in values of that option.

  • stock_source_variant_idinteger or null

    For 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 null

    How 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 null

    Name 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-Replayedstring

    true when this is the saved response of an earlier request with the same Idempotency-Key.

    Values:
    true
  • ETagstringrequired

    Version of the record. Send it in If-Match to change the record.

    Example:
    "7"
  • Locationstring (uri)required

    Address 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterinteger

    Seconds 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
curl -X POST "https://api.saleya.app/v1/variants" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
Request body — 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"
  }
}
Example response · 201
{
  "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

  • variantintegerrequired

    ID of the variant.

Responses

200Success

Headers

  • ETagstringrequired

    Version 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
curl "https://api.saleya.app/v1/variants/{variant}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "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

  • variantintegerrequired

    ID of the variant.

Query

  • consentobject

    Consents 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_changestring

      The 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_offstring

      The packs of the variant are archived when it stops being sold in packs.

      Min length:
      64
      Max length:
      64
    • stock_sourcestring

      The 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_menustring

      The dish leaves the menus of meal subscription programs.

      Min length:
      64
      Max length:
      64

Header

  • Idempotency-Keystring

    Unique 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-Matchstringrequired

    ETag 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 null

    External 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 null

    Stock keeping unit (SKU); null when not set.

    Max length:
    64
  • namemap of string or null or null

    Name of the variant by language, such as {"es": "Grande"}.

    Max length:
    255
  • priceinteger

    Price for price_per_quantity units, an integer in minor units of currency.

    Minimum:
    0
    Maximum:
    10000000000
  • track_inventoryboolean

    The store counts the stock of the variant; false — it is sold without counting stock.

  • is_activeboolean

    false takes the variant off sale.

  • positioninteger

    Position among the variants of the product: lower comes first.

    Minimum:
    0
    Maximum:
    2147483647
  • list_priceinteger

    Price 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 null

    Currency 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 null

    Price before the discount, shown crossed out; null when there is no discount.

    Maximum:
    10000000000
  • weight_gramsinteger or null

    Shipping weight in grams; null when not set.

    Minimum:
    0
    Maximum:
    2147483647
  • length_mminteger or null

    Length of the package in millimeters; null when not set.

    Minimum:
    0
    Maximum:
    2147483647
  • width_mminteger or null

    Width of the package in millimeters; null when not set.

    Minimum:
    0
    Maximum:
    2147483647
  • height_mminteger or null

    Height of the package in millimeters; null when not set.

    Minimum:
    0
    Maximum:
    2147483647
  • sale_starts_atstring (date-time) or null

    When the sale starts: compare_at_price is shown from this moment; null — no start limit.

  • sale_ends_atstring (date-time) or null

    When the sale ends; null — no end limit.

  • sold_bystring

    How the variant is sold: each — by the piece; weight — by weight; volume — by volume.

    Values:
    eachweightvolume
  • price_per_quantitystring or null

    How 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 null

    Step 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 null

    Smallest quantity in a line of a variant sold by weight or volume; null when not set.

    Max length:
    32
  • max_measure_qtystring or null

    Largest quantity in a line of a variant sold by weight or volume; null when not set.

    Max length:
    32
  • net_contentobject

    Net 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
    • quantitystring

      Measure as a decimal string in unit: "500", "0.5".

      Max length:
      32
    • unitstring

      Unit of the measure: g — grams; ml — millilitres.

      Values:
      gml
  • barcodesarray of object or null

    Barcodes of the variant.

    Max items:
    20
    Fields · 3
    • typestringrequired

      Symbology: ean13, ean8, upca, upce, code128, code39, gtin, itf, qr, datamatrix or other.

      Values:
      ean13ean8upcaupcecode128code39gtinitfqrdatamatrixother
    • valuestringrequired

      The barcode.

    • is_primaryboolean or null

      The main barcode of the variant: labels and receipts show it.

  • option_valuesarray of object

    Option values of the variant: one value of every option of the product.

    Max items:
    10
    Fields · 2
    • option_idintegerrequired

      ID of the option in options of the product.

    • value_idintegerrequired

      ID of the value in values of that option.

  • stock_source_variant_idinteger or null

    For 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 null

    How 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-Replayedstring

    true when this is the saved response of an earlier request with the same Idempotency-Key.

    Values:
    true
  • ETagstringrequired

    Version 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterinteger

    Seconds 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
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
Request body — 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"
}
Example response · 200
{
  "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

  • variantintegerrequired

    ID of the variant.

Query

  • consentobject

    Consents 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_ingredientstring

      The item is an ingredient of live recipes and leaves them.

      Min length:
      64
      Max length:
      64
    • production_draftstring

      Draft production acts with the item are cancelled.

      Min length:
      64
      Max length:
      64
    • program_menustring

      The dish leaves the menus of meal subscription programs.

      Min length:
      64
      Max length:
      64
    • stock_dependentsstring

      Packs drawing from the stock of this variant become ordinary variants with zero stock.

      Min length:
      64
      Max length:
      64

Header

  • Idempotency-Keystring

    Unique 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-Matchstringrequired

    ETag 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-Replayedstring

    true 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterinteger

    Seconds 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
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_idstringrequired

    External ID: the ID of the record in your system.

Responses

200Success

Headers

  • ETagstringrequired

    Version 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
curl "https://api.saleya.app/v1/variants/by-external-id/{external_id}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "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_idstringrequired

    External ID: the ID of the record in your system.

Query

  • consentobject

    Consents 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_changestring

      The 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_offstring

      The packs of the variant are archived when it stops being sold in packs.

      Min length:
      64
      Max length:
      64
    • stock_sourcestring

      The 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_menustring

      The dish leaves the menus of meal subscription programs.

      Min length:
      64
      Max length:
      64

Header

  • Idempotency-Keystring

    Unique 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-Matchstring

    ETag 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_idinteger

    ID of the product.

  • skustring or null

    Stock keeping unit (SKU); null when not set.

    Max length:
    64
  • namemap of string or null or null

    Name of the variant by language, such as {"es": "Grande"}.

    Max length:
    255
  • priceinteger

    Price for price_per_quantity units, an integer in minor units of currency.

    Minimum:
    0
    Maximum:
    10000000000
  • track_inventoryboolean

    The store counts the stock of the variant; false — it is sold without counting stock.

  • is_activeboolean

    false takes the variant off sale.

  • positioninteger

    Position among the variants of the product: lower comes first.

    Minimum:
    0
    Maximum:
    2147483647
  • list_priceinteger

    Price 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 null

    Currency 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 null

    Price before the discount, shown crossed out; null when there is no discount.

    Maximum:
    10000000000
  • weight_gramsinteger or null

    Shipping weight in grams; null when not set.

    Minimum:
    0
    Maximum:
    2147483647
  • length_mminteger or null

    Length of the package in millimeters; null when not set.

    Minimum:
    0
    Maximum:
    2147483647
  • width_mminteger or null

    Width of the package in millimeters; null when not set.

    Minimum:
    0
    Maximum:
    2147483647
  • height_mminteger or null

    Height of the package in millimeters; null when not set.

    Minimum:
    0
    Maximum:
    2147483647
  • sale_starts_atstring (date-time) or null

    When the sale starts: compare_at_price is shown from this moment; null — no start limit.

  • sale_ends_atstring (date-time) or null

    When the sale ends; null — no end limit.

  • sold_bystring

    How the variant is sold: each — by the piece; weight — by weight; volume — by volume.

    Values:
    eachweightvolume
  • price_per_quantitystring or null

    How 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 null

    Step 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 null

    Smallest quantity in a line of a variant sold by weight or volume; null when not set.

    Max length:
    32
  • max_measure_qtystring or null

    Largest quantity in a line of a variant sold by weight or volume; null when not set.

    Max length:
    32
  • net_contentobject

    Net 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
    • quantitystring

      Measure as a decimal string in unit: "500", "0.5".

      Max length:
      32
    • unitstring

      Unit of the measure: g — grams; ml — millilitres.

      Values:
      gml
  • barcodesarray of object or null

    Barcodes of the variant.

    Max items:
    20
    Fields · 3
    • typestringrequired

      Symbology: ean13, ean8, upca, upce, code128, code39, gtin, itf, qr, datamatrix or other.

      Values:
      ean13ean8upcaupcecode128code39gtinitfqrdatamatrixother
    • valuestringrequired

      The barcode.

    • is_primaryboolean or null

      The main barcode of the variant: labels and receipts show it.

  • option_valuesarray of object

    Option values of the variant: one value of every option of the product.

    Max items:
    10
    Fields · 2
    • option_idintegerrequired

      ID of the option in options of the product.

    • value_idintegerrequired

      ID of the value in values of that option.

  • stock_source_variant_idinteger or null

    For 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 null

    How 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 null

    Name 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-Replayedstring

    true when this is the saved response of an earlier request with the same Idempotency-Key.

    Values:
    true
  • ETagstringrequired

    Version of the record. Send it in If-Match to change the record.

    Example:
    "7"

application/json

Returns Variant

201Created

Headers

  • Idempotent-Replayedstring

    true when this is the saved response of an earlier request with the same Idempotency-Key.

    Values:
    true
  • ETagstringrequired

    Version of the record. Send it in If-Match to change the record.

    Example:
    "7"
  • Locationstring (uri)required

    Address 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterinteger

    Seconds 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
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
Request body — 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"
  }
}
Example response · 200
{
  "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

  • variantintegerrequired

    ID of the variant.

Responses

200Success

Headers

  • ETagstringrequired

    Version 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
curl "https://api.saleya.app/v1/variants/{variant}/recipe" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "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

  • variantintegerrequired

    ID of the variant.

Header

  • Idempotency-Keystring

    Unique 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-Matchstringrequired

    ETag 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 objectrequired

    Components 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_idintegerrequired

      ID of the component variant: an ingredient or a prep of the store.

    • quantitystring or nullrequired

      Amount 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_modestring

      How 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 null

    Output 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 object

    Amounts 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_idintegerrequired

      ID of a per-dish option from the product modifier groups.

    • componentsarray of objectrequired

      What the option consumes when taken with this variant: ingredients and preps with their amount.

      Max items:
      100
      Fields · 2
      • variant_idintegerrequired

        ID of the product variant.

      • quantitystring or nullrequired

        Component 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-Replayedstring

    true when this is the saved response of an earlier request with the same Idempotency-Key.

    Values:
    true
  • ETagstringrequired

    Version 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterinteger

    Seconds 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
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
Request body — 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"
        }
      ]
    }
  ]
}
Example response · 200
{
  "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"
        }
      ]
    }
  ]
}