Customer addresses
The address book of a customer: add, change, make the main one, delete.
Customer addresses
Objects
CustomerAddress
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.
Endpoints
Get an address from a customer's address book
get/customers/{customer}/addresses/{address}
Scope: customers:read
Parameters
Path
customerintegerrequiredID of the customer.
addressintegerrequiredID of the address in the address book of the customer.
Responses
200Success
Headers
ETagstringrequiredVersion 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-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}/addresses/{address}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"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
customerintegerrequiredID of the customer.
addressintegerrequiredID of the address in the address book 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
labelstring or nullName of the address, such as Home or Work; null when not given.
- Max length:
- 64
streetstringStreet.
- Max length:
- 255
housestring or nullHouse number.
- Max length:
- 32
apartmentstring or nullApartment or office.
- Max length:
- 32
floorstring or nullFloor.
- Max length:
- 16
entrancestring or nullEntrance.
- Max length:
- 16
districtstring or nullDistrict or neighborhood.
- Max length:
- 64
postal_codestring or nullPostal code.
- Max length:
- 16
commentstring or nullComment for the courier, such as how to get in; null when not given.
- Max length:
- 500
locationobjectPoint of the address on the map; null when the address came from another system and has not been located yet.
Fields · 2
latnumberLatitude in degrees.
- Minimum:
- -90
- Maximum:
- 90
lngnumberLongitude in degrees.
- Minimum:
- -180
- Maximum:
- 180
is_defaultbooleanThe main address of the customer. When the main address is deleted, the newest address becomes the main one.
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 CustomerAddress
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/customers/{customer}/addresses/{address}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"' \
-H "Content-Type: application/json" \
-d @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
}{
"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
customerintegerrequiredID of the customer.
addressintegerrequiredID of the address in the address book 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"
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
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/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
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
Request body application/json
labelstring or nullName of the address, such as Home or Work; null when not given.
- Max length:
- 64
streetstringrequiredStreet.
- Max length:
- 255
housestring or nullHouse number.
- Max length:
- 32
apartmentstring or nullApartment or office.
- Max length:
- 32
floorstring or nullFloor.
- Max length:
- 16
entrancestring or nullEntrance.
- Max length:
- 16
districtstring or nullDistrict or neighborhood.
- Max length:
- 64
postal_codestring or nullPostal code.
- Max length:
- 16
commentstring or nullComment for the courier, such as how to get in; null when not given.
- Max length:
- 500
locationobjectrequiredPoint 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.
- Minimum:
- -90
- Maximum:
- 90
lngnumberrequiredLongitude in degrees.
- Minimum:
- -180
- Maximum:
- 180
is_defaultbooleanThe main address of the customer. When the main address is deleted, the newest address becomes the main one.
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 CustomerAddress
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
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
address_book_fullThe customer's address book is full - 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/{customer}/addresses" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @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
}{
"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"
}