Product modifiers

Which modifier groups a product has, in order, with its selection rule and option surcharges by variant.

Loading the search index…

Product modifiers

Objects

ProductModifierGroups

  • product_idintegerrequired

    ID of the product. The groups are versioned on its card: ETag and If-Match carry the product version.

  • versionintegerrequired

    Version of the record: it grows with every change. Send it as the ETag in If-Match to change the record.

  • groupsarray of objectrequired

    The product modifier groups in display order. On write, the whole set.

    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.

  • option_pricesarray of objectrequired

    Surcharge and availability of options on the product variants instead of the option surcharge. On write, replaces the overrides as a whole; without the field the previous ones stay, except those of removed groups.

    Fields · 4
    • option_idintegerrequired

      ID of an option from the product groups.

    • variant_idintegerrequired

      ID of the product variant.

    • is_availablebooleanrequired

      false — the option is not offered on this variant; such a row has no surcharge.

    • price_deltainteger or nullrequired

      Option surcharge on this variant, an integer in minor units of the store currency; null only for an unavailable option.

Endpoints

Get the product modifier groups and their option surcharges by variant

get/products/{product}/modifier-groups

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 ProductModifierGroups

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}/modifier-groups" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "product_id": 0,
  "version": 0,
  "groups": [
    {
      "group_id": 0,
      "selection_rule": {
        "min_select": 0,
        "max_select": 0
      }
    }
  ],
  "option_prices": [
    {
      "option_id": 0,
      "variant_id": 0,
      "is_available": true,
      "price_delta": 0
    }
  ]
}

Replace the product modifier groups and their option surcharges by variant

put/products/{product}/modifier-groups

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

  • groupsarray of objectrequired

    The product modifier groups in display order. On write, the whole set.

    Max items:
    50
    No repeats
    Fields · 2
    • group_idintegerrequired

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

    • selection_ruleobject or null

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

      Fields · 2
      • min_selectinteger

        How many options must be chosen on this product.

        Minimum:
        0
        Maximum:
        99
      • max_selectinteger or null

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

        Minimum:
        1
        Maximum:
        99
  • option_pricesarray of object

    Surcharge and availability of options on the product variants instead of the option surcharge. On write, replaces the overrides as a whole; without the field the previous ones stay, except those of removed groups.

    Max items:
    2000
    Fields · 4
    • option_idintegerrequired

      ID of an option from the product groups.

    • is_availablebooleanrequired

      false — the option is not offered on this variant; such a row has no surcharge.

    • price_deltainteger or null

      Option surcharge on this variant, an integer in minor units of the store currency; null only for an unavailable option.

      Minimum:
      -100000000
      Maximum:
      100000000
    • variant_idintegerrequired

      ID of the product variant.

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 ProductModifierGroups

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}/modifier-groups" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"' \
  -H "Content-Type: application/json" \
  -d @body.json
Request body — body.json
{
  "groups": [
    {
      "group_id": 0,
      "selection_rule": {
        "min_select": 0,
        "max_select": 1
      }
    }
  ],
  "option_prices": [
    {
      "option_id": 0,
      "is_available": true,
      "price_delta": 0,
      "variant_id": 0
    }
  ]
}
Example response · 200
{
  "product_id": 0,
  "version": 0,
  "groups": [
    {
      "group_id": 0,
      "selection_rule": {
        "min_select": 0,
        "max_select": 0
      }
    }
  ],
  "option_prices": [
    {
      "option_id": 0,
      "variant_id": 0,
      "is_available": true,
      "price_delta": 0
    }
  ]
}