Price list fixed prices

Fixed variant prices in price lists that override the list rule: the price in the price list currency and in store money.

Loading the search index…

Price list fixed prices

Objects

PriceListItem

  • idintegerrequired

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

  • price_list_idintegerrequired

    Price list ID.

  • variant_idintegerrequired

    ID of the variant with a fixed price in the list; the variant may be archived.

  • priceintegerrequired

    Price in minor units of currency: the assigned price in store money.

  • compare_at_priceinteger or nullrequired

    Price before the discount, shown struck through; null when there is no discount. Always null in a wholesale list.

  • list_priceinteger or nullrequired

    Price as the owner set it, in minor units of list_price_currency; null — the price was set in store money (price).

  • list_compare_at_priceinteger or nullrequired

    Price before the discount in list_price_currency; null — no discount, or the price was set in store money.

  • list_price_currencystring or nullrequired

    Currency of the assigned price (a price list in another currency); null — the price is in the store currency.

  • currencystringrequired

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

  • tare_quantitystring or nullrequired

    Package the wholesale price of a raw material or prepared ingredient is set for, in the variant unit — as of when it was set; null — the price is per the variant price_per_quantity.

  • created_atstring (date-time)required

    When the record was created.

  • updated_atstring (date-time)required

    When the record last changed.

Endpoints

List fixed variant prices in price lists changed since a given moment

get/price-list-items

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.

  • price_list_idinteger

    Only prices of this price list.

    Minimum:
    1
  • variant_idinteger

    Only prices of this variant across all lists.

    Minimum:
    1

Responses

200Success

application/json

  • dataarray of PriceListItemrequired

    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/price-list-items" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "data": [
    {
      "id": 0,
      "price_list_id": 0,
      "variant_id": 0,
      "price": 0,
      "compare_at_price": 0,
      "list_price": 0,
      "list_compare_at_price": 0,
      "list_price_currency": "string",
      "currency": "string",
      "tare_quantity": "string",
      "created_at": "2026-01-15T12:00:00Z",
      "updated_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"
}

Get a fixed variant price in a price list

get/price-list-items/{price_list_item}

Scope: catalog:read

Parameters

Path

  • price_list_itemintegerrequired

    Price list fixed price ID.

Responses

200Success

application/json

Returns PriceListItem

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/price-list-items/{price_list_item}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "id": 0,
  "price_list_id": 0,
  "variant_id": 0,
  "price": 0,
  "compare_at_price": 0,
  "list_price": 0,
  "list_compare_at_price": 0,
  "list_price_currency": "string",
  "currency": "string",
  "tare_quantity": "string",
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}

Set fixed variant prices in a price list in bulk

post/price-lists/{price_list}/items

Scope: catalog:writeororders:wholesale

Parameters

Path

  • price_liststringrequired

    Price list ID.

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

  • itemsarray of objectrequired

    Fixed prices, up to 1000 per request, each variant once. An existing row gets the new price; the batch is written in full or not at all.

    Min items:
    1
    Max items:
    1000
    No repeats
    Fields · 5
    • variant_idintegerrequired

      Variant ID (/v1/variants). Gift cards and meal plans have no location price.

    • priceinteger or null

      Price in minor units of the store currency, above zero — for a row priced in store money: the row's list_price_currency is null, for a new row — the variant's.

      Minimum:
      1
      Maximum:
      10000000000
    • compare_at_priceinteger or null

      Compare-at price in the store currency, above price; null or omitted — none. Wholesale lists have none.

      Minimum:
      1
      Maximum:
      10000000000
    • list_priceinteger or null

      Price in minor units of the price list currency, above zero — for a row priced in that currency (the row's list_price_currency, for a new row — the variant's). The store money price is converted by the system.

      Minimum:
      1
      Maximum:
      10000000000
    • list_compare_at_priceinteger or null

      Compare-at price in the price list currency, above list_price; null or omitted — none. Wholesale lists have none.

      Minimum:
      1
      Maximum:
      10000000000

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 PriceList

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 POST "https://api.saleya.app/v1/price-lists/{price_list}/items" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"' \
  -H "Content-Type: application/json" \
  -d @body.json
Request body — body.json
{
  "items": [
    {
      "variant_id": 0,
      "price": 1,
      "compare_at_price": 1,
      "list_price": 1,
      "list_compare_at_price": 1
    }
  ]
}
Example response · 200
{
  "id": 0,
  "version": 0,
  "kind": "location",
  "name": "string",
  "adjustment_bp": 0,
  "rounding": {
    "mode": "nearest",
    "precision": 0
  },
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}

Remove fixed variant prices from a price list in bulk

post/price-lists/{price_list}/items/remove

Scope: catalog:writeororders:wholesale

Parameters

Path

  • price_liststringrequired

    Price list ID.

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

  • variant_idsarray of integerrequired

    IDs of variants whose fixed prices to remove, without repeats, up to 1000 per request. A variant without a fixed price is skipped.

    Min items:
    1
    Max items:
    1000
    No repeats

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 PriceList

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 POST "https://api.saleya.app/v1/price-lists/{price_list}/items/remove" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"' \
  -H "Content-Type: application/json" \
  -d @body.json
Request body — body.json
{
  "variant_ids": [
    0
  ]
}
Example response · 200
{
  "id": 0,
  "version": 0,
  "kind": "location",
  "name": "string",
  "adjustment_bp": 0,
  "rounding": {
    "mode": "nearest",
    "precision": 0
  },
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}