Set Shipping Address
Save a delivery address that differs from the billing address.
Endpoint
POST /api/shop/checkout-addressesThis is the same endpoint as Set Checkout Address — one call saves both addresses. There is no shipping-only endpoint, so the billing fields are required here too.
How the two addresses relate
useForShipping | What to send | Result |
|---|---|---|
true | Billing fields only | The billing address is copied to the shipping address. |
false | Billing fields and the full shipping block | The two are stored separately. |
Omitting the shipping block while useForShipping is false fails the call — the shipping fields are not optional in that mode.
Request Headers
| Header | Required | Description |
|---|---|---|
Content-Type | Yes | application/json |
Accept | Yes | application/json |
X-STOREFRONT-KEY | Yes | Your storefront API key |
Authorization | Yes | Bearer <cartToken> for a guest, or the customer's Bearer token when signed in |
Shipping Fields
| Field | Type | Required | Description |
|---|---|---|---|
shippingFirstName | string | Yes | First name at the delivery address. |
shippingLastName | string | Yes | Last name. |
shippingEmail | string | Yes | Contact email for the delivery. |
shippingAddress | string | Yes | Street address. |
shippingCity | string | Yes | City. |
shippingState | string | Yes | State or region code. |
shippingCountry | string | Yes | Two-letter country code. |
shippingPostcode | string | Yes | Postal code. |
shippingPhoneNumber | string | Yes | Contact number for the courier. |
shippingCompanyName | string | No | Company at the delivery address. |
The billing fields are listed on Set Checkout Address.
Use Cases
- Gift orders — bill the buyer, deliver to the recipient.
- Business deliveries — invoice a head office while shipping to a branch, using
shippingCompanyName.
Best Practices
- Send both blocks in one call — there is no way to add a shipping address to an already-saved billing address without re-sending it
- Set
useForShippingexplicitly — leaving it out with no shipping block behaves as an incomplete address - Re-read the rates afterwards — shipping cost depends on the destination, so the rate list changes when the shipping address does
- Use ISO codes —
US,NY, not full names
Related Resources
- Set Checkout Address — save both checkout addresses in one call
- Get Addresses — read back the addresses saved on the cart
- Get Shipping Methods — the rates available for the saved address