Set Checkout Address

Save the billing and shipping addresses onto the cart. This is the first step of checkout — shipping rates and payment methods are unavailable until it succeeds.

Endpoint

POST /api/shop/checkout-addresses

One endpoint saves both addresses. There is no separate billing and shipping call, and no way to reference a saved address by ID — the fields are always sent in full.

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

Request Body

Billing fields

Field	Type	Required	Description
billingFirstName	string	Yes	First name on the billing address.
billingLastName	string	Yes	Last name.
billingEmail	string	Yes	Email the order confirmation goes to.
billingAddress	string	Yes	Street address.
billingCity	string	Yes	City.
billingState	string	Yes	State or region code.
billingCountry	string	Yes	Two-letter country code.
billingPostcode	string	Yes	Postal code.
billingPhoneNumber	string	Yes	Contact number.
billingCompanyName	string	No	Company, for business orders.

Shipping fields

Field	Type	Required	Description
useForShipping	boolean	No	true copies the billing address to the shipping address. Send false and the shipping* fields to ship elsewhere.
shippingFirstName, shippingLastName, shippingEmail, shippingAddress, shippingCity, shippingState, shippingCountry, shippingPostcode, shippingPhoneNumber	string	When useForShipping is false	The delivery address, mirroring the billing fields.
shippingCompanyName	string	No	Company at the delivery address.

Fields accepted but belonging to later steps

The same input also accepts shippingMethod, paymentMethod, paymentSuccessUrl, paymentFailureUrl, and paymentCancelUrl. Setting them here is optional — the dedicated Set Shipping Method and Set Payment Method endpoints are the normal route.

Response

The saved address block, returned as a bare object. When useForShipping is true the shipping* fields echo the billing values.

Use Cases

• Guest checkout — collect the address in a form and post it with the cart token; no account is needed.
• Ship to a different address — send useForShipping: false with the full shipping block.
• Signed-in checkout — send the customer's Bearer token instead of the cart token. The fields are still sent in full; read the customer's saved addresses with Get Customer Addresses and prefill the form from one.

Best Practices

1. Send every billing field — a missing one fails the whole call with Billing address is required, not a field-level validation error
2. Do not send addressId — the endpoint has no saved-address shortcut, and an ID-only body fails
3. Use ISO codes for billingCountry and billingState — US and NY, not full names
4. Re-read shipping methods after any address change — available rates and their prices depend on the destination
5. Post the address before reading rates or payment methods — both return an empty array until it exists

Related Resources

• Get Addresses — read back the addresses saved on the cart
• Get Shipping Methods — the rates available for the saved address
• Set Shipping Method — save the chosen rate on the cart
• Place Order — turn the prepared cart into an order