Price lists
Location and wholesale price lists: a percentage over the base price or over cost, with rounding. Fixed prices and surcharges have their own feeds.
Price lists
Objects
PriceList
idintegerrequiredID of the record, unique among records of its kind in the store.
versionintegerrequiredVersion of the record: it grows with every change. Send it as the ETag in If-Match to change the record.
kindstringrequiredList kind: location — selling prices at the list locations over the base price, wholesale — wholesale prices of a business customer from cost. Never changes.
- Values:
locationwholesale
namestringrequiredThe list's label in the store dashboard; for a location list, the name of the location it was created for.
adjustment_bpintegerrequiredRule adjustment in basis points: +20% is 2000, −10% is -1000. For a location list it applies to the variant base price (-9000 to 50000), for a wholesale list it is a markup over unit cost (0 to 50000).
roundingobjectrequiredRounding of the price set by the list rule. Fixed prices and prices of items sold by weight or volume are not rounded.
Fields · 2
modestringrequiredRounding direction: nearest, up or down.
- Values:
nearestupdown
precisionintegerrequiredRounding digit in major-unit decimals: 2 — to cents, 0 — to whole units, -2 — to hundreds.
created_atstring (date-time)requiredWhen the record was created.
updated_atstring (date-time)requiredWhen the record last changed.
Endpoints
List the store's price lists: location and wholesale lists with their rule and rounding
get/price-lists
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.
kindstringOnly lists of this kind: location — location lists, wholesale — wholesale lists.
- Values:
locationwholesale
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-lists" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"data": [
{
"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"
}
],
"deleted": [
{
"id": 0,
"deleted_at": "2026-01-15T12:00:00Z"
}
],
"next_cursor": "string",
"has_more": true,
"sync_cursor": "string"
}Create a wholesale price list
post/price-lists
Scope: orders:wholesale
Parameters
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
Request body application/json
kindstringrequiredList kind: only wholesale. A location list is created by its location in the dashboard.
- Values:
wholesale
namestringrequiredName of the wholesale list, up to 120 characters: the dashboard shows it on the customer profile.
- Max length:
- 120
adjustment_bpintegerrequiredMarkup over cost in basis points (1% = 100), from 0 to 50000: 0 — at cost; a wholesale list never sells below cost.
- Minimum:
- 0
- Maximum:
- 50000
roundingobjectRounding of the unit price — mode and precision together. Omitted — the list takes the store price rounding.
Fields · 2
modestringHow to round: nearest, up or down.
- Values:
nearestupdown
precisionintegerRounding step in minor units of the store currency; the step of the minor unit itself means no rounding.
- Values:
10-1-2-3-4-5-62
Responses
201Created
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"
Locationstring (uri)requiredAddress of the created record; for an accepted request (202), the address to follow its outcome.
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
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
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
- 409
idempotency_key_in_useA request with this key is in progress - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
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" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"kind": "wholesale",
"name": "string",
"adjustment_bp": 0,
"rounding": {
"mode": "nearest",
"precision": "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"
}Get a price list
get/price-lists/{price_list}
Scope: catalog:read
Parameters
Path
price_listintegerrequiredPrice list ID.
Responses
200Success
Headers
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
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-lists/{price_list}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"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"
}Update a price list: adjustment and rounding, and the name of a wholesale list; a location list's rule changes prices at all its locations
patch/price-lists/{price_list}
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
namestringNew name of a wholesale list, up to 120 characters. A location list is named by its location — the field is rejected.
- Max length:
- 120
adjustment_bpintegerNew adjustment in basis points (1% = 100): over the base price for a location list, from −9000 to 50000; over cost for a wholesale list, from 0. Omitted — unchanged.
- Minimum:
- 0
- Maximum:
- 50000
roundingobjectNew rounding of the list's prices — mode and precision together; omitted — unchanged. Fixed prices and prices of items sold by weight or volume are not rounded.
Fields · 2
modestringRounding direction: nearest, up or down.
- Values:
nearestupdown
precisionintegerRounding position in digits of major units: 2 — to cents, 0 — to whole units, -2 — to hundreds. Allowed: the positions from the store's price settings and the currency's minor unit position — no rounding.
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 PATCH "https://api.saleya.app/v1/price-lists/{price_list}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"' \
-H "Content-Type: application/json" \
-d @body.json{
"name": "string",
"adjustment_bp": 0,
"rounding": {
"mode": "nearest",
"precision": 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"
}Delete a wholesale price list; its assignment to customers is removed with consent
delete/price-lists/{price_list}
Scope: orders:wholesale
Parameters
Path
price_liststringrequiredPrice list ID.
Query
consentobjectConsents 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
wholesale_price_list_buyersstringThe wholesale list is assigned to customers: deleting it removes the assignment, and their wholesale sales go at base prices. buyers — how many customers it affects.
- Min length:
- 64
- Max length:
- 64
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"
Responses
204Success
Headers
Idempotent-Replayedstringtrue 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-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
consent_requiredConsent to the consequences is required - 409
idempotency_key_in_useA request with this key is in progress - 409
in_use_conflictRecord in use - 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 DELETE "https://api.saleya.app/v1/price-lists/{price_list}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"'