Set Checkout Address

About

The createCheckoutAddress mutation sets the billing and shipping address for the current checkout session. This is a single mutation that handles both addresses based on the useForShipping flag:

• useForShipping: true — Only billing address fields are required. The billing address is automatically copied to the shipping address.
• useForShipping: false — Both billing and shipping address fields must be provided separately. This allows the customer to ship to a different address than their billing address.

Authentication

This mutation supports both authenticated customers and guest users:

• Authenticated customers: Provide a valid customer authentication token in the Authorization header. Obtain this token via the Customer Login API.
• Guest users: Provide the Guest Cart Token cartToken obtained from the Create Cart mutation.

Authorization: Bearer <accessToken>

Arguments

Billing Address (always required)

Name	Type	Required	Description
billingFirstName	String	Yes	Billing first name
billingLastName	String	Yes	Billing last name
billingEmail	String	Yes	Billing email address
billingAddress	String	Yes	Billing street address
billingCity	String	Yes	Billing city
billingCountry	String	Yes	Billing country code (ISO 3166-1 alpha-2)
billingState	String	Yes	Billing state/province code
billingPostcode	String	Yes	Billing postal/zip code
billingPhoneNumber	String	Yes	Billing phone number
useForShipping	Boolean	No	If true, billing address is used as shipping address. If false, separate shipping fields are required. Default: false

Shipping Address (required when useForShipping is false)

Name	Type	Required	Description
shippingFirstName	String	Conditional	Shipping first name
shippingLastName	String	Conditional	Shipping last name
shippingEmail	String	Conditional	Shipping email address
shippingAddress	String	Conditional	Shipping street address
shippingCity	String	Conditional	Shipping city
shippingCountry	String	Conditional	Shipping country code (ISO 3166-1 alpha-2)
shippingState	String	Conditional	Shipping state/province code
shippingPostcode	String	Conditional	Shipping postal/zip code
shippingPhoneNumber	String	Conditional	Shipping phone number

Response

Field	Type	Description
_id	Integer	Internal address identifier
id	String	Address ID
success	Boolean	Success status
message	String	Success or error message
cartToken	String	Cart token for the checkout session
billingFirstName	String	Billing first name
billingLastName	String	Billing last name
billingAddress	String	Billing street address
billingCity	String	Billing city
billingState	String	Billing state/province
billingPostcode	String	Billing postal/zip code
billingPhoneNumber	String	Billing phone number
shippingFirstName	String	Shipping first name
shippingLastName	String	Shipping last name
shippingAddress	String	Shipping street address
shippingCity	String	Shipping city
shippingState	String	Shipping state/province
shippingPostcode	String	Shipping postal/zip code
shippingPhoneNumber	String	Shipping phone number

Validation Rules

• All required billing address fields must be provided
• billingEmail must be a valid email address
• Country codes must be valid ISO 3166-1 alpha-2 codes
• Phone numbers should be in valid format
• When useForShipping is false, all shipping address fields become required

Error Responses

{
  "errors": {
    "billingEmail": ["The billing email must be a valid email address."],
    "billingCountry": ["Invalid country code."],
    "shippingFirstName": ["The shipping first name field is required."]
  }
}

Related Documentation

• Get Checkout Addresses
• Set Shipping Method
• Checkout Flow