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.
Price list fixed prices
Objects
PriceListItem
idintegerrequiredID of the record, unique among records of its kind in the store.
price_list_idintegerrequiredPrice list ID.
variant_idintegerrequiredID of the variant with a fixed price in the list; the variant may be archived.
priceintegerrequiredPrice in minor units of currency: the assigned price in store money.
compare_at_priceinteger or nullrequiredPrice before the discount, shown struck through; null when there is no discount. Always null in a wholesale list.
list_priceinteger or nullrequiredPrice 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 nullrequiredPrice before the discount in list_price_currency; null — no discount, or the price was set in store money.
list_price_currencystring or nullrequiredCurrency of the assigned price (a price list in another currency); null — the price is in the store currency.
currencystringrequiredCurrency of the amounts, an ISO 4217 code: the currency of the store.
tare_quantitystring or nullrequiredPackage 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)requiredWhen the record was created.
updated_atstring (date-time)requiredWhen 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
limitintegerPage size: up to 250 records; 50 by default.
- Minimum:
- 1
- Maximum:
- 250
cursorstringOpaque cursor: next_cursor of the previous page, or sync_cursor of the last page saved by the previous sync. The list goes in commit order, so the sync cursor later returns only what changed after it.
- Max length:
- 4096
updated_sincestring (date-time)Only records changed after this moment, ISO 8601 with a time zone. A filter for the first sync; continue with the cursor.
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$
include_deletedbooleantrue — also return deleted records: archived ones with deleted_at set, and records erased from the database as tombstones {id, deleted_at} in the continuation by the sync cursor. Turn it on for a sync.
price_list_idintegerOnly prices of this price list.
- Minimum:
- 1
variant_idintegerOnly prices of this variant across all lists.
- Minimum:
- 1
Responses
200Success
application/json
Records of the page.
deletedarray of objectrequiredRecords erased from the database since the cursor, as tombstones: only with include_deleted=true in the continuation by the sync cursor.
Fields · 2
idintegerrequiredID of the erased record.
deleted_atstring (date-time)requiredWhen the record was erased.
next_cursorstring or nullrequiredCursor of the next page; null on the last page.
has_morebooleanrequiredtrue when there is a next page.
sync_cursorstring or nullrequiredOn the last page — the cursor to continue from later: it returns only what changed after this page. null on other pages.
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
410The sync cursor is older than the deletion retention period or was issued before the database was restored
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/price-list-items" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"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_itemintegerrequiredPrice list fixed price ID.
Responses
200Success
application/json
Returns PriceListItem
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/price-list-items/{price_list_item}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"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_liststringrequiredPrice list ID.
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
If-MatchstringrequiredETag of the record from the last read, for example "7". The change applies only if nobody changed the record since then; otherwise 412. Without it — 428.
- Example:
"7"
Request body application/json
itemsarray of objectrequiredFixed 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_idintegerrequiredVariant ID (/v1/variants). Gift cards and meal plans have no location price.
priceinteger or nullPrice 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 nullCompare-at price in the store currency, above price; null or omitted — none. Wholesale lists have none.
- Minimum:
- 1
- Maximum:
- 10000000000
list_priceinteger or nullPrice 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 nullCompare-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-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
application/json
Returns PriceList
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
412The record changed after it was read: the version in If-Match is not current
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
428The request needs If-Match with the ETag of the record
application/problem+json
Returns Problem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
idempotency_key_in_useA request with this key is in progress - 412
precondition_failedThe record has changed - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid - 428
precondition_requiredIf-Match is required
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X 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{
"items": [
{
"variant_id": 0,
"price": 1,
"compare_at_price": 1,
"list_price": 1,
"list_compare_at_price": 1
}
]
}{
"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_liststringrequiredPrice list ID.
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
If-MatchstringrequiredETag of the record from the last read, for example "7". The change applies only if nobody changed the record since then; otherwise 412. Without it — 428.
- Example:
"7"
Request body application/json
variant_idsarray of integerrequiredIDs 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-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
application/json
Returns PriceList
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
412The record changed after it was read: the version in If-Match is not current
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
428The request needs If-Match with the ETag of the record
application/problem+json
Returns Problem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
idempotency_key_in_useA request with this key is in progress - 412
precondition_failedThe record has changed - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid - 428
precondition_requiredIf-Match is required
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X 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{
"variant_ids": [
0
]
}{
"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"
}