Products

Product cards: names, descriptions, categories, options and photos. Variants have their own endpoints; a product is created and written together with them.

Loading the search index…

Products

Objects

Product

  • 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 record: it grows with every change. Send it as the ETag in If-Match to change the record.

  • typestringrequired

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

    Stock 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
    • unitstringrequired

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

      Name of the purchase package, such as kg or box; null — the item is bought in its base unit.

    • purchase_quantitystringrequired

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

    Name by language: an object of the filled languages, for example {"es": "Café", "en": "Coffee"}.

  • short_descriptionmap of stringrequired

    Short description by language, plain text for product lists.

  • descriptionmap of stringrequired

    Description by language in Markdown (GitHub Flavored): an object of the filled languages.

  • slugstringrequired

    Address of the product on the storefront, unique in the store.

  • brand_idinteger or nullrequired

    ID of the brand of the product; null when not set.

  • tax_class_idinteger or nullrequired

    ID 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 integerrequired

    IDs of the categories the product is in, ascending.

  • primary_category_idinteger or nullrequired

    The main category among category_ids; null when the product has no main category.

  • optionsarray of objectrequired

    Options the variants differ by, such as size or color, in order.

    Fields · 5
    • idintegerrequired

      ID of the option.

    • keystringrequired

      Machine key of the option, unique within the product, such as size.

    • namemap of stringrequired

      Name of the option by language.

    • positionintegerrequired

      Position of the option: lower comes first.

    • valuesarray of objectrequired

      Values of the option in order.

      Fields · 4
      • idintegerrequired

        ID of the value. Variants refer to it in option_values.

      • valuemap of stringrequired

        The value by language, such as {"es": "Rojo", "en": "Red"}.

      • swatch_colorstring or nullrequired

        Color of the swatch, a hex code such as #C0392B; null when the value has no swatch.

      • positionintegerrequired

        Position of the value: lower comes first.

  • modifier_groupsarray of objectrequired

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

      ID of the modifier group (/v1/modifier-groups).

    • selection_ruleobject or nullrequired

      Selection rule on this product instead of the group rule; null — the group rule.

      Fields · 2
      • min_selectintegerrequired

        How many options must be chosen on this product.

      • max_selectinteger or nullrequired

        How many options can be chosen on this product; null — no limit.

  • mediaarray of objectrequired

    Photos and videos of the gallery in order: the same objects as in /v1/products/{product}/media.

    Fields · 7
    • idintegerrequired

      ID of the file in the media library. A file is in the gallery of a product at most once.

    • kindstringrequired

      image or video.

      Values:
      imagevideo
    • urlstringrequired

      Public address of the file.

    • mimestringrequired

      MIME type of the file, such as image/webp.

    • altmap of stringrequired

      Alternative text by language, for screen readers and search engines.

    • positionintegerrequired

      Place in the gallery, starting from zero.

    • is_primarybooleanrequired

      The main photo: the storefront shows it first.

  • is_activebooleanrequired

    false takes the product off sale and hides it from the storefront.

  • published_atstring (date-time) or nullrequired

    When the product appears on the storefront; null — right away.

  • unpublished_atstring (date-time) or nullrequired

    When the product leaves the storefront; null — it stays.

  • sale_schedulearray of object or nullrequired

    When 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 integerrequired

      Window days, ISO: 1 is Monday, 7 is Sunday.

    • fromstringrequired

      Window start, “HH:MM” on the store clock.

    • tostringrequired

      Window 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)required

    When the record was created.

  • updated_atstring (date-time)required

    When the record last changed.

  • deleted_atstring (date-time) or nullrequired

    When 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

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

Responses

200Success

application/json

  • dataarray of Productrequired

    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/products" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "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-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

  • namemap of string or nullrequired

    Name by language: an object of the filled languages, for example {"es": "Café", "en": "Coffee"}.

    Max length:
    255
  • short_descriptionmap of string or null or null

    Short description by language, plain text for product lists.

    Max length:
    500
  • descriptionmap of string or null or null

    Description by language in Markdown (GitHub Flavored): an object of the filled languages.

    Max length:
    50000
  • slugstring

    Address of the product on the storefront, unique in the store.

    Max length:
    160
  • brand_idinteger or null

    ID of the brand of the product; null when not set.

  • tax_class_idinteger or null

    ID 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 integer

    IDs of the categories the product is in, ascending.

  • primary_category_idinteger or null

    The main category among category_ids; null when the product has no main category.

  • is_activeboolean

    false takes the product off sale and hides it from the storefront.

  • published_atstring (date-time) or null

    When the product appears on the storefront; null — right away.

  • unpublished_atstring (date-time) or null

    When the product leaves the storefront; null — it stays.

  • sale_schedulearray of object or null

    When 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 integerrequired

      Window days, ISO: 1 is Monday, 7 is Sunday.

      Min items:
      1
      Max items:
      7
      Minimum:
      1
      Maximum:
      7
    • fromstringrequired

      Window start, “HH:MM” on the store clock.

      Pattern:
      ^(?:[01]\d|2[0-3]):[0-5]\d$|^24:00$
    • tostringrequired

      Window 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$
  • typestring

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

    Stock 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
    • unitstring

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

      Name of the purchase package, such as kg or box; null — the item is bought in its base unit.

      Max length:
      16
    • purchase_quantitystring or null

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

  • variantsarray of objectrequired

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

      External ID of the variant, its ID in your system: the key the row is matched by.

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

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 Product

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/products" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
Request body — 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
        }
      ]
    }
  ]
}
Example response · 201
{
  "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

  • productintegerrequired

    ID of the product.

Responses

200Success

Headers

  • ETagstringrequired

    Version 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-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/products/{product}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "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

  • productintegerrequired

    ID of the product.

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

  • namemap of string or null

    Name by language: an object of the filled languages, for example {"es": "Café", "en": "Coffee"}.

    Max length:
    255
  • short_descriptionmap of string or null or null

    Short description by language, plain text for product lists.

    Max length:
    500
  • descriptionmap of string or null or null

    Description by language in Markdown (GitHub Flavored): an object of the filled languages.

    Max length:
    50000
  • slugstring

    Address of the product on the storefront, unique in the store.

    Max length:
    160
  • brand_idinteger or null

    ID of the brand of the product; null when not set.

  • tax_class_idinteger or null

    ID 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 integer

    IDs of the categories the product is in, ascending.

  • primary_category_idinteger or null

    The main category among category_ids; null when the product has no main category.

  • is_activeboolean

    false takes the product off sale and hides it from the storefront.

  • published_atstring (date-time) or null

    When the product appears on the storefront; null — right away.

  • unpublished_atstring (date-time) or null

    When the product leaves the storefront; null — it stays.

  • sale_schedulearray of object or null

    When 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 integerrequired

      Window days, ISO: 1 is Monday, 7 is Sunday.

      Min items:
      1
      Max items:
      7
      Minimum:
      1
      Maximum:
      7
    • fromstringrequired

      Window start, “HH:MM” on the store clock.

      Pattern:
      ^(?:[01]\d|2[0-3]):[0-5]\d$|^24:00$
    • tostringrequired

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

  • variantsarray of object

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

      External ID of the variant, its ID in your system: the key the row is matched by.

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

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 Product

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/products/{product}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"' \
  -H "Content-Type: application/json" \
  -d @body.json
Request body — 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
        }
      ]
    }
  ]
}
Example response · 200
{
  "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

  • productintegerrequired

    ID of the product.

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
    • live_subscriptionsstring

      The program with live subscriptions is taken off sale.

      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/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_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 Product

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/products/by-external-id/{external_id}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "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_idstringrequired

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

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

  • namemap of string or null

    Name by language: an object of the filled languages, for example {"es": "Café", "en": "Coffee"}.

    Max length:
    255
  • short_descriptionmap of string or null or null

    Short description by language, plain text for product lists.

    Max length:
    500
  • descriptionmap of string or null or null

    Description by language in Markdown (GitHub Flavored): an object of the filled languages.

    Max length:
    50000
  • slugstring

    Address of the product on the storefront, unique in the store.

    Max length:
    160
  • brand_idinteger or null

    ID of the brand of the product; null when not set.

  • tax_class_idinteger or null

    ID 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 integer

    IDs of the categories the product is in, ascending.

  • primary_category_idinteger or null

    The main category among category_ids; null when the product has no main category.

  • is_activeboolean

    false takes the product off sale and hides it from the storefront.

  • published_atstring (date-time) or null

    When the product appears on the storefront; null — right away.

  • unpublished_atstring (date-time) or null

    When the product leaves the storefront; null — it stays.

  • sale_schedulearray of object or null

    When 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 integerrequired

      Window days, ISO: 1 is Monday, 7 is Sunday.

      Min items:
      1
      Max items:
      7
      Minimum:
      1
      Maximum:
      7
    • fromstringrequired

      Window start, “HH:MM” on the store clock.

      Pattern:
      ^(?:[01]\d|2[0-3]):[0-5]\d$|^24:00$
    • tostringrequired

      Window 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$
  • typestring

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

    Stock 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
    • unitstring

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

      Name of the purchase package, such as kg or box; null — the item is bought in its base unit.

      Max length:
      16
    • purchase_quantitystring or null

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

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

      External ID of the variant, its ID in your system: the key the row is matched by.

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

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 Product

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 Product

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/products/by-external-id/{external_id}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
Request body — 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
        }
      ]
    }
  ]
}
Example response · 200
{
  "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

  • productintegerrequired

    ID of the product.

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 · 1
    • variant_axesstring

      Variants 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-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

  • optionsarray of objectrequired

    Options the variants differ by, such as size or color, in order.

    Max items:
    10
    Fields · 4
    • keystringrequired

      Machine key of the option, unique within the product, such as size.

      Max length:
      32
      Pattern:
      ^[a-z][a-z0-9_]*$
    • namemap of string or nullrequired

      Name of the option by language.

      Max length:
      120
    • valuesarray of objectrequired

      Values of the option in order.

      Min items:
      1
      Max items:
      50
      Fields · 3
      • valuemap of string or nullrequired

        The value by language, such as {"es": "Rojo", "en": "Red"}.

        Max length:
        120
      • swatch_colorstring or null

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

        ID of the value. Variants refer to it in option_values.

    • idinteger or null

      ID of the option.

  • variantsarray of objectrequired

    Layout 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
    • idintegerrequired

      ID of the variant.

    • archiveboolean

      true — archive the variant instead of giving it values.

    • value_indexesarray of integer

      Values 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-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 Product

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/products/{product}/options" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"' \
  -H "Content-Type: application/json" \
  -d @body.json
Request body — 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
      ]
    }
  ]
}
Example response · 200
{
  "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"
}