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(): Promise<CustomerAddress[]>

The address book, the default first. Not paginated.

Returns

A list of CustomerAddress, 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

const addresses = await shopper.customer.addresses.list();

Add an address

shopper.customer.addresses.create(input: CustomerAddressInput): Promise<CustomerAddress>

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

Parameters

Parameter	Type
`input`	`CustomerAddressInput`	The address's fields, below.

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:

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

const address = await 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(id: number, changes: Partial<CustomerAddressInput>): Promise<CustomerAddress>

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`	`number`	The address's id.
`changes`	`object`	The address's fields, below.

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:

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

await 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(id: number): Promise<void>

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

Parameters

Parameter	Type
`id`	`number`	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(id: number): Promise<CustomerAddress>

Makes one of the shopper's addresses their default.

Parameters

Parameter	Type
`id`	`number`	The address's id.

Returns

The CustomerAddress:

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

await shopper.customer.addresses.makeDefault(7);