Customer addresses

The address book of a customer: add, change, make the main one, delete.

Loading the search index…

Customer addresses

Objects

CustomerAddress

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

Endpoints

Get an address from a customer's address book

get/customers/{customer}/addresses/{address}

Scope: customers:read

Parameters

Path

  • customerintegerrequired

    ID of the customer.

  • addressintegerrequired

    ID of the address in the address book 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 CustomerAddress

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

Update a customer's address

patch/customers/{customer}/addresses/{address}

Scope: customers:write

Parameters

Path

  • customerintegerrequired

    ID of the customer.

  • addressintegerrequired

    ID of the address in the address book 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

  • labelstring or null

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

    Max length:
    64
  • streetstring

    Street.

    Max length:
    255
  • housestring or null

    House number.

    Max length:
    32
  • apartmentstring or null

    Apartment or office.

    Max length:
    32
  • floorstring or null

    Floor.

    Max length:
    16
  • entrancestring or null

    Entrance.

    Max length:
    16
  • districtstring or null

    District or neighborhood.

    Max length:
    64
  • postal_codestring or null

    Postal code.

    Max length:
    16
  • commentstring or null

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

    Max length:
    500
  • locationobject

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

    Fields · 2
    • latnumber

      Latitude in degrees.

      Minimum:
      -90
      Maximum:
      90
    • lngnumber

      Longitude in degrees.

      Minimum:
      -180
      Maximum:
      180
  • is_defaultboolean

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

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 CustomerAddress

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

Delete an address from a customer's address book

delete/customers/{customer}/addresses/{address}

Scope: customers:write

Parameters

Path

  • customerintegerrequired

    ID of the customer.

  • addressintegerrequired

    ID of the address in the address book 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"

Responses

204Success

Headers

  • Idempotent-Replayedstring

    true 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-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 DELETE "https://api.saleya.app/v1/customers/{customer}/addresses/{address}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"'

Add an address to a customer's address book

post/customers/{customer}/addresses

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

Request body application/json

  • labelstring or null

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

    Max length:
    64
  • streetstringrequired

    Street.

    Max length:
    255
  • housestring or null

    House number.

    Max length:
    32
  • apartmentstring or null

    Apartment or office.

    Max length:
    32
  • floorstring or null

    Floor.

    Max length:
    16
  • entrancestring or null

    Entrance.

    Max length:
    16
  • districtstring or null

    District or neighborhood.

    Max length:
    64
  • postal_codestring or null

    Postal code.

    Max length:
    16
  • commentstring or null

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

    Max length:
    500
  • locationobjectrequired

    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.

      Minimum:
      -90
      Maximum:
      90
    • lngnumberrequired

      Longitude in degrees.

      Minimum:
      -180
      Maximum:
      180
  • is_defaultboolean

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

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 CustomerAddress

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

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/{customer}/addresses" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
Request body — body.json
{
  "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
}
Example response · 201
{
  "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"
}