Customers

Customers of the store with their contacts, marketing consent and address book. All of it is personal data under the customers:read scope.

Loading the search index…

Customers

Objects

Customer

  • idintegerrequired

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

  • external_idstring or nullrequired

    External 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.

  • versionintegerrequired

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

  • namestring or nullrequired

    Name of the customer; null when unknown.

  • phonestring or nullrequired

    Main phone of the customer in E.164 format, such as +5491123456789; null when unknown.

  • emailstring or nullrequired

    Email of the customer; null when unknown.

  • languagestringrequired

    Language the store writes to the customer in: ru, en or es.

    Values:
    ruenes
  • is_blockedbooleanrequired

    The store has blocked the customer: they cannot sign in to the storefront.

  • marketing_consentsarray of objectrequired

    Marketing 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
    • channelstringrequired

      Marketing channel: email, telegram, whatsapp or instagram.

      Values:
      emailtelegramwhatsappinstagram
    • statusstringrequired

      subscribed — the customer explicitly agreed to marketing on the channel; unsubscribed — they refused it.

      Values:
      subscribedunsubscribed
    • consented_atstring (date-time) or nullrequired

      When the customer last explicitly agreed to marketing on the channel; a refusal keeps this time. null when they have not.

  • accepts_marketingbooleanrequired

    Deprecated, see marketing_consents: the customer has not unsubscribed from email marketing.

  • balanceintegerrequired

    Balance of the customer in the store: orders can be paid with it. In minor units of the currency of the store.

  • addressesarray of objectrequired

    Address book of the customer; its size is limited by the store. A deleted address is simply missing from the list.

    Fields · 15
    • idintegerrequired

      ID of the address.

    • customer_idintegerrequired

      ID of the customer the address belongs to.

    • labelstring or nullrequired

      Name of the address, such as Home or Work; null when not given.

    • streetstringrequired

      Street.

    • housestring or nullrequired

      House number.

    • apartmentstring or nullrequired

      Apartment or office.

    • floorstring or nullrequired

      Floor.

    • entrancestring or nullrequired

      Entrance.

    • districtstring or nullrequired

      District or neighborhood.

    • postal_codestring or nullrequired

      Postal code.

    • commentstring or nullrequired

      Comment for the courier, such as how to get in; null when not given.

    • locationobject or nullrequired

      Point of the address on the map; null when the address came from another system and has not been located yet.

      Fields · 2
      • latnumberrequired

        Latitude in degrees.

      • lngnumberrequired

        Longitude in degrees.

    • is_defaultbooleanrequired

      The main address of the customer. When the main address is deleted, the newest address becomes the main one.

    • created_atstring (date-time)required

      When the record was created.

    • updated_atstring (date-time)required

      When the record last changed.

  • group_idsarray of integerrequired

    The 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 nullrequired

    Wholesale 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 nullrequired

    The customer this one was merged into: that customer got its contacts, addresses and orders. null when not merged.

  • created_atstring (date-time)required

    When the record was created.

  • updated_atstring (date-time)required

    When the record last changed.

  • deleted_atstring (date-time) or nullrequired

    When 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

  • 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.

  • phonestring

    Only customers with this phone, in E.164 format.

    Max length:
    32
  • emailstring

    Only customers with this email.

    Max length:
    254
  • group_idinteger

    Only customers in this group: its current members.

    Minimum:
    1
  • wholesale_price_list_idinteger

    Only customers assigned this wholesale price list.

    Minimum:
    1

Responses

200Success

application/json

  • dataarray of Customerrequired

    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/customers" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "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-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

Request body application/json

  • namestringrequired

    Name of the customer; null when unknown.

    Max length:
    120
    Pattern:
    \S
  • languagestring

    Language the store writes to the customer in: ru, en or es.

    Values:
    ruenes
  • phonestring

    Main phone of the customer in E.164 format, such as +5491123456789; null when unknown.

    Max length:
    32
  • emailstring

    Email of the customer; null when unknown.

    Max length:
    254
  • external_idstring or null

    External 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-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"
  • Locationstring (uri)required

    Address 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-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

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

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 -X POST "https://api.saleya.app/v1/customers" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
Request body — body.json
{
  "name": "string",
  "language": "ru",
  "phone": "string",
  "email": "string",
  "external_id": "string"
}
Example response · 201
{
  "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

  • customerintegerrequired

    ID of the customer.

Responses

200Success

Headers

  • ETagstringrequired

    Version 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-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/customers/{customer}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "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

  • customerintegerrequired

    ID of the customer.

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

  • namestring

    Name of the customer; null when unknown.

    Max length:
    120
    Pattern:
    \S
  • languagestring

    Language the store writes to the customer in: ru, en or es.

    Values:
    ruenes
  • external_idstring or null

    External 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-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 Customer

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 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
Request body — body.json
{
  "name": "string",
  "language": "ru",
  "external_id": "string"
}
Example response · 200
{
  "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_idstringrequired

    External ID: the ID of the record in your system.

Responses

200Success

Headers

  • ETagstringrequired

    Version 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-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/customers/by-external-id/{external_id}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "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_idstringrequired

    External ID: the ID of the record in your system.

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-Matchstring

    ETag 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

  • namestring

    Name of the customer; null when unknown.

    Max length:
    120
    Pattern:
    \S
  • languagestring

    Language the store writes to the customer in: ru, en or es.

    Values:
    ruenes
  • phonestring

    Main phone of the customer in E.164 format, such as +5491123456789; null when unknown.

    Max length:
    32
  • emailstring

    Email of the customer; null when unknown.

    Max length:
    254

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 Customer

201Created

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"
  • Locationstring (uri)required

    Address 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-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

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 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
Request body — body.json
{
  "name": "string",
  "language": "ru",
  "phone": "string",
  "email": "string"
}
Example response · 200
{
  "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

  • customerintegerrequired

    ID of the customer.

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

  • price_list_idinteger or nullrequired

    The customer's wholesale price list; null removes the assignment — wholesale sales to the customer go at base prices.

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 Customer

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/customers/{customer}/wholesale-price-list" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"' \
  -H "Content-Type: application/json" \
  -d @body.json
Request body — body.json
{
  "price_list_id": 0
}
Example response · 200
{
  "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"
}