Addresses

The signed-in shopper's address book, the same one checkout offers them.

Reach it through $shopper->customer->addresses. It needs a client with the shopper's access token (see sign-in).

List addresses

$shopper->customer->addresses->list(): array

The address book, the default first. Not paginated.

Returns

A list of CustomerAddress arrays, each:

Field	Type	Description
`[].id`	integer
`[].label`	string or null
`[].name`	string
`[].phone`	string
`[].countryCode`	string
`[].state`	string or null
`[].stateId`	integer or null
`[].city`	string or null
`[].cityId`	integer or null
`[].neighbourhood`	string or null
`[].neighbourhoodId`	integer or null
`[].addressLine1`	string
`[].addressLine2`	string or null
`[].postalCode`	string or null
`[].isDefault`	boolean

Errors

Status	When
`401`	`invalid_api_key`, or `invalid_customer_token`: the shopper's token is missing or not valid for this shop.
`402`	The shop is suspended (message only).
`403`	`origin_not_allowed` (publishable key from an unlisted site), `secret_key_in_browser`, or the shop is not live (message only).
`404`	Not found, or the shop's plan has no Integration API.
`429`	Rate limited.

Example

$addresses = $shopper->customer->addresses->list();

Add an address

$shopper->customer->addresses->create(array $input, string|false|null $idempotencyKey = null): array

A new address. The first address, or one sent with isDefault, becomes the default. Limited like cart writes.

Parameters

Parameter	Type
`$input`	`array`	The address's fields, below.
`$idempotencyKey`	`string\|false\|null`	Your own `Idempotency-Key`, or `false` for none. One is made for you when null.

Request fields

Field	Type	Description
`label`	string or null	At most 50 characters.
`name` required	string	At most 255 characters.
`phone` required	string	At most 50 characters.
`countryCode` required	string	ISO 3166-1 alpha-3, one the shop ships to. At most 3 characters.
`city` required	string	At most 100 characters.
`state`	string or null	At most 100 characters.
`addressLine1` required	string	At most 500 characters.
`addressLine2`	string or null	At most 500 characters.
`postalCode`	string or null	At most 20 characters.
`isDefault`	boolean
`shippingStateId`	integer or null
`shippingCityId`	integer or null
`shippingNeighbourhoodId`	integer or null
`shippingLocationUnlisted`	boolean or null

Returns

The new CustomerAddress array:

Field	Type	Description
`id`	integer
`label`	string or null
`name`	string
`phone`	string
`countryCode`	string
`state`	string or null
`stateId`	integer or null
`city`	string or null
`cityId`	integer or null
`neighbourhood`	string or null
`neighbourhoodId`	integer or null
`addressLine1`	string
`addressLine2`	string or null
`postalCode`	string or null
`isDefault`	boolean

Errors

Status	When
`401`	`invalid_api_key`, or `invalid_customer_token`: the shopper's token is missing or not valid for this shop.
`402`	The shop is suspended (message only).
`403`	`origin_not_allowed` (publishable key from an unlisted site), `secret_key_in_browser`, or the shop is not live (message only).
`404`	Not found, or the shop's plan has no Integration API.
`409`	`idempotency_in_progress`: a request with this `Idempotency-Key` is still running. Retry with the same key after `Retry-After` seconds; the first answer is then replayed.
`422`	Validation errors (`{ message, errors }`), or an idempotency refusal(`idempotency_key_reused`, `idempotency_key_invalid`).
`429`	Rate limited.

Example

$address = $shopper->customer->addresses->create([
    'name' => 'Sara Ali',
    'phone' => '+966500000000',
    'countryCode' => 'SAU',
    'city' => 'Riyadh',
    'addressLine1' => '12 King Fahd Road',
    'isDefault' => true,
]);

Edit an address

$shopper->customer->addresses->update(int $id, array $changes, string|false|null $idempotencyKey = null): array

Changes one of the shopper's addresses. It is validated with the same rules as a new address, so send every required field.

Parameters

Parameter	Type
`$id`	`int`	The address's id.
`$changes`	`array`	The address's fields, below.
`$idempotencyKey`	`string\|false\|null`	Your own `Idempotency-Key`, or `false` for none.

Request fields

Field	Type	Description
`label`	string or null	At most 50 characters.
`name` required	string	At most 255 characters.
`phone` required	string	At most 50 characters.
`countryCode` required	string	ISO 3166-1 alpha-3, one the shop ships to. At most 3 characters.
`city` required	string	At most 100 characters.
`state`	string or null	At most 100 characters.
`addressLine1` required	string	At most 500 characters.
`addressLine2`	string or null	At most 500 characters.
`postalCode`	string or null	At most 20 characters.
`isDefault`	boolean
`shippingStateId`	integer or null
`shippingCityId`	integer or null
`shippingNeighbourhoodId`	integer or null
`shippingLocationUnlisted`	boolean or null

Returns

The changed CustomerAddress array:

Field	Type	Description
`id`	integer
`label`	string or null
`name`	string
`phone`	string
`countryCode`	string
`state`	string or null
`stateId`	integer or null
`city`	string or null
`cityId`	integer or null
`neighbourhood`	string or null
`neighbourhoodId`	integer or null
`addressLine1`	string
`addressLine2`	string or null
`postalCode`	string or null
`isDefault`	boolean

Errors

Status	When
`401`	`invalid_api_key`, or `invalid_customer_token`: the shopper's token is missing or not valid for this shop.
`402`	The shop is suspended (message only).
`403`	`origin_not_allowed` (publishable key from an unlisted site), `secret_key_in_browser`, or the shop is not live (message only).
`404`	`address_not_found`, or the plan has no Integration API.
`409`	`idempotency_in_progress`: a request with this `Idempotency-Key` is still running. Retry with the same key after `Retry-After` seconds; the first answer is then replayed.
`422`	Validation errors (`{ message, errors }`), or an idempotency refusal(`idempotency_key_reused`, `idempotency_key_invalid`).
`429`	Rate limited.

Example

$shopper->customer->addresses->update(7, [
    'name' => 'Sara Ali',
    'phone' => '+966500000000',
    'countryCode' => 'SAU',
    'city' => 'Jeddah',
    'addressLine1' => '4 Tahlia Street',
]);

Delete an address

$shopper->customer->addresses->delete(int $id): void

Deletes one of the shopper's addresses. Deleting the default makes the next address the default.

Parameters

Parameter	Type
`$id`	`int`	The address's id.

Returns

Nothing.

Errors

Status	When
`401`	`invalid_api_key`, or `invalid_customer_token`: the shopper's token is missing or not valid for this shop.
`402`	The shop is suspended (message only).
`403`	`origin_not_allowed` (publishable key from an unlisted site), `secret_key_in_browser`, or the shop is not live (message only).
`404`	`address_not_found`, or the plan has no Integration API.
`409`	`idempotency_in_progress`: a request with this `Idempotency-Key` is still running. Retry with the same key after `Retry-After` seconds; the first answer is then replayed.
`422`	Validation errors (`{ message, errors }`), or an idempotency refusal(`idempotency_key_reused`, `idempotency_key_invalid`).
`429`	Rate limited.

Make an address the default

$shopper->customer->addresses->makeDefault(int $id): array

Makes one of the shopper's addresses their default.

Parameters

Parameter	Type
`$id`	`int`	The address's id.

Returns

The CustomerAddress array:

Field	Type	Description
`id`	integer
`label`	string or null
`name`	string
`phone`	string
`countryCode`	string
`state`	string or null
`stateId`	integer or null
`city`	string or null
`cityId`	integer or null
`neighbourhood`	string or null
`neighbourhoodId`	integer or null
`addressLine1`	string
`addressLine2`	string or null
`postalCode`	string or null
`isDefault`	boolean

Errors

Status	When
`401`	`invalid_api_key`, or `invalid_customer_token`: the shopper's token is missing or not valid for this shop.
`402`	The shop is suspended (message only).
`403`	`origin_not_allowed` (publishable key from an unlisted site), `secret_key_in_browser`, or the shop is not live (message only).
`404`	`address_not_found`, or the plan has no Integration API.
`409`	`idempotency_in_progress`: a request with this `Idempotency-Key` is still running. Retry with the same key after `Retry-After` seconds; the first answer is then replayed.
`422`	Validation errors (`{ message, errors }`), or an idempotency refusal(`idempotency_key_reused`, `idempotency_key_invalid`).
`429`	Rate limited.

Example

$shopper->customer->addresses->makeDefault(7);