Customers
Customers of the store with their contacts, marketing consent and address book. All of it is personal data under the customers:read scope.
Customers
Objects
Customer
idintegerrequiredID of the record, unique among records of its kind in the store.
external_idstring or nullrequiredExternal ID of the customer, its ID in your system; null when not set. After two customers are merged, the ID of the merged one also finds the surviving customer; the response shows the main ID.
versionintegerrequiredVersion of the record: it grows with every change. Send it as the ETag in If-Match to change the record.
namestring or nullrequiredName of the customer; null when unknown.
phonestring or nullrequiredMain phone of the customer in E.164 format, such as +5491123456789; null when unknown.
emailstring or nullrequiredEmail of the customer; null when unknown.
languagestringrequiredLanguage the store writes to the customer in: ru, en or es.
- Values:
ruenes
is_blockedbooleanrequiredThe store has blocked the customer: they cannot sign in to the storefront.
marketing_consentsarray of objectrequiredMarketing consent per channel (email, telegram, whatsapp, instagram): a row for each channel where the customer explicitly agreed (subscribed) or refused (unsubscribed), with the moment of the latest explicit consent. A missing channel means implied consent: a store with marketing_consent_mode opt_out writes to that channel, one with opt_in does not. WhatsApp requires subscribed.
Fields · 3
channelstringrequiredMarketing channel: email, telegram, whatsapp or instagram.
- Values:
emailtelegramwhatsappinstagram
statusstringrequiredsubscribed — the customer explicitly agreed to marketing on the channel; unsubscribed — they refused it.
- Values:
subscribedunsubscribed
consented_atstring (date-time) or nullrequiredWhen the customer last explicitly agreed to marketing on the channel; a refusal keeps this time. null when they have not.
accepts_marketingbooleanrequiredDeprecated, see marketing_consents: the customer has not unsubscribed from email marketing.
marketing_consent_atstring (date-time) or nullrequiredDeprecated, see marketing_consents: when the customer explicitly agreed to email marketing; null when they have not.
balanceintegerrequiredBalance of the customer in the store: orders can be paid with it. In minor units of the currency of the store.
addressesarray of objectrequiredAddress book of the customer; its size is limited by the store. A deleted address is simply missing from the list.
Fields · 15
idintegerrequiredID of the address.
customer_idintegerrequiredID of the customer the address belongs to.
labelstring or nullrequiredName of the address, such as Home or Work; null when not given.
streetstringrequiredStreet.
housestring or nullrequiredHouse number.
apartmentstring or nullrequiredApartment or office.
floorstring or nullrequiredFloor.
entrancestring or nullrequiredEntrance.
districtstring or nullrequiredDistrict or neighborhood.
postal_codestring or nullrequiredPostal code.
commentstring or nullrequiredComment for the courier, such as how to get in; null when not given.
locationobject or nullrequiredPoint of the address on the map; null when the address came from another system and has not been located yet.
Fields · 2
latnumberrequiredLatitude in degrees.
lngnumberrequiredLongitude in degrees.
is_defaultbooleanrequiredThe main address of the customer. When the main address is deleted, the newest address becomes the main one.
created_atstring (date-time)requiredWhen the record was created.
updated_atstring (date-time)requiredWhen the record last changed.
group_idsarray of integerrequiredThe customer's groups by ascending ID. Membership is written by the group commands: a change moves the customer in the feed and sends customer.updated, but changes neither version nor updated_at.
wholesale_price_list_idinteger or nullrequiredWholesale price list of the business customer: their wholesale sales are priced by it. null — wholesale at base prices. The list itself is visible only with costs:read.
merged_into_customer_idinteger or nullrequiredThe customer this one was merged into: that customer got its contacts, addresses and orders. null when not merged.
created_atstring (date-time)requiredWhen the record was created.
updated_atstring (date-time)requiredWhen the record last changed.
deleted_atstring (date-time) or nullrequiredWhen the record was archived; null for a live record.
Endpoints
List customers changed since a given time: contacts, marketing consent, addresses and groups; look up by phone, email and group
get/customers
Scope: customers: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.
phonestringOnly customers with this phone, in E.164 format.
- Max length:
- 32
emailstringOnly customers with this email.
- Max length:
- 254
group_idintegerOnly customers in this group: its current members.
- Minimum:
- 1
wholesale_price_list_idintegerOnly customers assigned this wholesale price list.
- 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/customers" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"data": [
{
"id": 0,
"external_id": "string",
"version": 0,
"name": "string",
"phone": "string",
"email": "string",
"language": "ru",
"is_blocked": true,
"marketing_consents": [
{
"channel": "email",
"status": "subscribed",
"consented_at": "2026-01-15T12:00:00Z"
}
],
"accepts_marketing": true,
"marketing_consent_at": "2026-01-15T12:00:00Z",
"balance": 0,
"addresses": [
{
"id": 0,
"customer_id": 0,
"label": "string",
"street": "string",
"house": "string",
"apartment": "string",
"floor": "string",
"entrance": "string",
"district": "string",
"postal_code": "string",
"comment": "string",
"location": {
"lat": 0,
"lng": 0
},
"is_default": true,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}
],
"group_ids": [
0
],
"wholesale_price_list_id": 0,
"merged_into_customer_id": 0,
"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 customer: a name and at least one contact
post/customers
Scope: customers:write
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
namestringrequiredName of the customer; null when unknown.
- Max length:
- 120
- Pattern:
\S
languagestringLanguage the store writes to the customer in: ru, en or es.
- Values:
ruenes
phonestringMain phone of the customer in E.164 format, such as +5491123456789; null when unknown.
- Max length:
- 32
emailstringEmail of the customer; null when unknown.
- Max length:
- 254
external_idstring or nullExternal ID of the customer, its ID in your system; null when not set. After two customers are merged, the ID of the merged one also finds the surviving customer; the response shows the main ID.
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 Customer
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
customer_contact_in_useThe contact already belongs to a store customer - 409
external_id_in_useThe external ID is taken - 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/customers" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"name": "string",
"language": "ru",
"phone": "string",
"email": "string",
"external_id": "string"
}{
"id": 0,
"external_id": "string",
"version": 0,
"name": "string",
"phone": "string",
"email": "string",
"language": "ru",
"is_blocked": true,
"marketing_consents": [
{
"channel": "email",
"status": "subscribed",
"consented_at": "2026-01-15T12:00:00Z"
}
],
"accepts_marketing": true,
"marketing_consent_at": "2026-01-15T12:00:00Z",
"balance": 0,
"addresses": [
{
"id": 0,
"customer_id": 0,
"label": "string",
"street": "string",
"house": "string",
"apartment": "string",
"floor": "string",
"entrance": "string",
"district": "string",
"postal_code": "string",
"comment": "string",
"location": {
"lat": 0,
"lng": 0
},
"is_default": true,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}
],
"group_ids": [
0
],
"wholesale_price_list_id": 0,
"merged_into_customer_id": 0,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}Get a customer
get/customers/{customer}
Scope: customers:read
Parameters
Path
customerintegerrequiredID of the customer.
Responses
200Success
Headers
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
application/json
Returns Customer
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/customers/{customer}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"external_id": "string",
"version": 0,
"name": "string",
"phone": "string",
"email": "string",
"language": "ru",
"is_blocked": true,
"marketing_consents": [
{
"channel": "email",
"status": "subscribed",
"consented_at": "2026-01-15T12:00:00Z"
}
],
"accepts_marketing": true,
"marketing_consent_at": "2026-01-15T12:00:00Z",
"balance": 0,
"addresses": [
{
"id": 0,
"customer_id": 0,
"label": "string",
"street": "string",
"house": "string",
"apartment": "string",
"floor": "string",
"entrance": "string",
"district": "string",
"postal_code": "string",
"comment": "string",
"location": {
"lat": 0,
"lng": 0
},
"is_default": true,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}
],
"group_ids": [
0
],
"wholesale_price_list_id": 0,
"merged_into_customer_id": 0,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}Update a customer's name, language and external ID
patch/customers/{customer}
Scope: customers:write
Parameters
Path
customerintegerrequiredID of the customer.
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
namestringName of the customer; null when unknown.
- Max length:
- 120
- Pattern:
\S
languagestringLanguage the store writes to the customer in: ru, en or es.
- Values:
ruenes
external_idstring or nullExternal ID of the customer, its ID in your system; null when not set. After two customers are merged, the ID of the merged one also finds the surviving customer; the response shows the main ID.
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 Customer
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
customer_contact_in_useThe contact already belongs to a store customer - 409
external_id_in_useThe external ID is taken - 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/customers/{customer}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"' \
-H "Content-Type: application/json" \
-d @body.json{
"name": "string",
"language": "ru",
"external_id": "string"
}{
"id": 0,
"external_id": "string",
"version": 0,
"name": "string",
"phone": "string",
"email": "string",
"language": "ru",
"is_blocked": true,
"marketing_consents": [
{
"channel": "email",
"status": "subscribed",
"consented_at": "2026-01-15T12:00:00Z"
}
],
"accepts_marketing": true,
"marketing_consent_at": "2026-01-15T12:00:00Z",
"balance": 0,
"addresses": [
{
"id": 0,
"customer_id": 0,
"label": "string",
"street": "string",
"house": "string",
"apartment": "string",
"floor": "string",
"entrance": "string",
"district": "string",
"postal_code": "string",
"comment": "string",
"location": {
"lat": 0,
"lng": 0
},
"is_default": true,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}
],
"group_ids": [
0
],
"wholesale_price_list_id": 0,
"merged_into_customer_id": 0,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}Get a customer by its external ID
get/customers/by-external-id/{external_id}
Scope: customers:read
Parameters
Path
external_idstringrequiredExternal ID: the ID of the record in your system.
Responses
200Success
Headers
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
application/json
Returns Customer
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/customers/by-external-id/{external_id}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"external_id": "string",
"version": 0,
"name": "string",
"phone": "string",
"email": "string",
"language": "ru",
"is_blocked": true,
"marketing_consents": [
{
"channel": "email",
"status": "subscribed",
"consented_at": "2026-01-15T12:00:00Z"
}
],
"accepts_marketing": true,
"marketing_consent_at": "2026-01-15T12:00:00Z",
"balance": 0,
"addresses": [
{
"id": 0,
"customer_id": 0,
"label": "string",
"street": "string",
"house": "string",
"apartment": "string",
"floor": "string",
"entrance": "string",
"district": "string",
"postal_code": "string",
"comment": "string",
"location": {
"lat": 0,
"lng": 0
},
"is_default": true,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}
],
"group_ids": [
0
],
"wholesale_price_list_id": 0,
"merged_into_customer_id": 0,
"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 customer by its external ID
patch/customers/by-external-id/{external_id}
Scope: customers:write
Parameters
Path
external_idstringrequiredExternal ID: the ID of the record in your system.
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-MatchstringETag 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
namestringName of the customer; null when unknown.
- Max length:
- 120
- Pattern:
\S
languagestringLanguage the store writes to the customer in: ru, en or es.
- Values:
ruenes
phonestringMain phone of the customer in E.164 format, such as +5491123456789; null when unknown.
- Max length:
- 32
emailstringEmail of the customer; null when unknown.
- Max length:
- 254
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 Customer
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 Customer
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
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
customer_contact_in_useThe contact already belongs to a store customer - 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/customers/by-external-id/{external_id}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"name": "string",
"language": "ru",
"phone": "string",
"email": "string"
}{
"id": 0,
"external_id": "string",
"version": 0,
"name": "string",
"phone": "string",
"email": "string",
"language": "ru",
"is_blocked": true,
"marketing_consents": [
{
"channel": "email",
"status": "subscribed",
"consented_at": "2026-01-15T12:00:00Z"
}
],
"accepts_marketing": true,
"marketing_consent_at": "2026-01-15T12:00:00Z",
"balance": 0,
"addresses": [
{
"id": 0,
"customer_id": 0,
"label": "string",
"street": "string",
"house": "string",
"apartment": "string",
"floor": "string",
"entrance": "string",
"district": "string",
"postal_code": "string",
"comment": "string",
"location": {
"lat": 0,
"lng": 0
},
"is_default": true,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}
],
"group_ids": [
0
],
"wholesale_price_list_id": 0,
"merged_into_customer_id": 0,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}Assign a wholesale price list to a customer or remove it
post/customers/{customer}/wholesale-price-list
Scope: customers:writeorders:wholesale
Parameters
Path
customerintegerrequiredID of the customer.
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
price_list_idinteger or nullrequiredThe customer's wholesale price list; null removes the assignment — wholesale sales to the customer go at base prices.
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 Customer
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/customers/{customer}/wholesale-price-list" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"' \
-H "Content-Type: application/json" \
-d @body.json{
"price_list_id": 0
}{
"id": 0,
"external_id": "string",
"version": 0,
"name": "string",
"phone": "string",
"email": "string",
"language": "ru",
"is_blocked": true,
"marketing_consents": [
{
"channel": "email",
"status": "subscribed",
"consented_at": "2026-01-15T12:00:00Z"
}
],
"accepts_marketing": true,
"marketing_consent_at": "2026-01-15T12:00:00Z",
"balance": 0,
"addresses": [
{
"id": 0,
"customer_id": 0,
"label": "string",
"street": "string",
"house": "string",
"apartment": "string",
"floor": "string",
"entrance": "string",
"district": "string",
"postal_code": "string",
"comment": "string",
"location": {
"lat": 0,
"lng": 0
},
"is_default": true,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}
],
"group_ids": [
0
],
"wholesale_price_list_id": 0,
"merged_into_customer_id": 0,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}