Skip to content

Customers

Read and update the signed-in customer's profile, profile picture and addresses, and attach a guest cart to their account.

The account area of a storefront shows who is signed in, lets the customer edit their details, keeps the addresses they ship to, and carries the cart they built as a guest into their account. The endpoints of this page serve that area. The order history and the downloads of an account are on the Orders guide.

Every endpoint of this page needs the bearer token of a signed-in customer, the one Logging in and Registering a customer return. The token identifies the customer, so no URL carries a customer ID: /customers/me always means the owner of the token. The Customers page covers the customer model behind these endpoints.

Endpoints

These routes sit in the authenticated route group. A request without a token, with an expired or revoked token, or with a token that was not issued for the store answers 401.

Request bodies are flat JSON objects, such as {"opt_in": true}. The profile picture is the only multipart upload.

A missing or rejected token answers 401 with the unauthenticated code:

Response 401
{
    "errors": [
        {
            "status": "401",
            "code": "unauthenticated",
            "title": "Unauthorized",
            "detail": "Unauthenticated."
        }
    ]
}

The storefront then drops the stored token and sends the customer to the sign-in form.

Reading the Profile

The storefront reads the profile to greet the customer, fill the account form and show the profile picture. It is also the cheapest way to check that a stored token still works when the storefront starts.

GET/store/customers/me
Auth
Customer bearer token
Rate limit
shopper-api

Query parameters

  • fields[customers]stringoptional

    Comma-separated attributes to return, such as first_name,last_name. See Sparse fieldsets.

This request reads the profile of the customer the token belongs to:

Request
curl http://localhost:8000/store/customers/me \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Bearer 1|customer-token"

The API answers 200 OK with a customers resource:

Response 200
{
    "data": {
        "id": "01JD9B2K7X4N8R3T6V1Y5Z0QWE",
        "type": "customers",
        "attributes": {
            "first_name": "Camille",
            "last_name": "Martin",
            "email": "camille.martin@example.com",
            "avatar": "http://localhost:8000/storage/avatars/u8jzPde0IgxLd6GncfBAepfJBd0Kh8oOOL8dKLzd.jpg",
            "avatar_type": "storage",
            "phone_number": "+33 6 12 34 56 78",
            "gender": "female",
            "birth_date": "1992-04-18",
            "opt_in": true,
            "email_verified": true,
            "created_at": "2026-09-03T14:20:11+00:00"
        }
    }
}
Errors
StatusCodeWhen
401unauthenticatedThe request has no valid customer token

The meaning of every code is in Error Codes.

customers attributes

  • first_namestring, null

    First name.

  • last_namestring

    Last name.

  • emailstring

    Email the customer signs in with.

  • avatarstring

    URL of the profile picture: the uploaded file, or a generated picture when there is none.

  • avatar_typestring

    storage when the customer uploaded a picture, avatar_ui for the generated one.

  • phone_numberstring, null

    Phone number, as the customer typed it.

  • genderstring, null

    female or male.

  • birth_datestring, null

    Date of birth, YYYY-MM-DD.

  • opt_inboolean

    Whether the customer accepts marketing emails.

  • email_verifiedboolean

    Whether the customer confirmed their email address.

  • created_atstring

    When the account was created, ISO 8601.

The customer id is a ULID, like the IDs of carts, orders and addresses.

Updating the Profile

The account form saves the fields the customer changed. Send only those fields: a field left out of the body keeps its value.

PATCH/store/customers/me
Auth
Customer bearer token
Rate limit
shopper-api

Query parameters

  • fields[customers]stringoptional

    Comma-separated attributes to return, such as first_name,last_name. See Sparse fieldsets.

Body

  • first_namestring, nulloptional

    First name, up to 255 characters. null clears it.

  • last_namestringoptional

    Last name, up to 255 characters. It cannot be cleared.

  • phone_numberstring, nulloptional

    Phone number, up to 255 characters. null clears it.

  • birth_datestring, nulloptional

    A date before today, such as 1992-04-18. null clears it.

  • genderstring, nulloptional

    female or male. null clears it.

  • opt_inbooleanoptional

    Whether the customer accepts marketing emails.

The email address is not part of this endpoint. A body that carries email gets no error, and the email stays the same.

Request
curl -X PATCH http://localhost:8000/store/customers/me \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Bearer 1|customer-token" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+33 7 98 76 54 32", "opt_in": false}'

The API answers 200 OK with the whole profile, in the shape of Reading the profile, so the storefront re-renders the form from the response.

A value that fails validation answers 422, with one error per field. The code is the name of the rule that failed, and the pointer names the field:

Response 422
{
    "errors": [
        {
            "status": "422",
            "code": "before",
            "title": "Unprocessable Content",
            "detail": "The birth date field must be a date before today.",
            "source": {
                "pointer": "/data/attributes/birth_date"
            }
        }
    ]
}

The Errors guide lists every error code.

Errors
StatusCodeWhen
401unauthenticatedThe request has no valid customer token
422Rule name, such as beforeA field fails validation, the pointer names it

The meaning of every code is in Error Codes.

Profile Picture

A customer who uploads a picture sees it in the account area. Without one, avatar points to a generated picture, so the storefront always has an image to show.

POST/store/customers/me/avatar
Auth
Customer bearer token
Rate limit
shopper-api

Query parameters

  • fields[customers]stringoptional

    Comma-separated attributes to return, such as first_name,last_name. See Sparse fieldsets.

Body

  • avatarfile

    The image, sent as multipart/form-data, 1,024 KB at most.

The upload is a multipart request with the image in the avatar field. The file must be an image of 1,024 KB at most.

Request
curl -X POST http://localhost:8000/store/customers/me/avatar \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Bearer 1|customer-token" \
  -F "avatar=@camille.jpg"

The API answers 200 OK with the profile. avatar_type is now storage, and avatar is the URL of the stored file:

Response 200
{
    "data": {
        "id": "01JD9B2K7X4N8R3T6V1Y5Z0QWE",
        "type": "customers",
        "attributes": {
            "first_name": "Camille",
            "last_name": "Martin",
            "email": "camille.martin@example.com",
            "avatar": "http://localhost:8000/storage/avatars/kD3f9QmZ7xWb2LpR8sTn4VhY6cJe1AuG0oNi5MrK.jpg",
            "avatar_type": "storage",
            "phone_number": "+33 7 98 76 54 32",
            "gender": "female",
            "birth_date": "1992-04-18",
            "opt_in": false,
            "email_verified": true,
            "created_at": "2026-09-03T14:20:11+00:00"
        }
    }
}

The file goes to the avatars folder of the media disk, the shopper.media.storage.disk_name setting described in Media. A new upload replaces the previous picture and deletes its file. A file that is not an image or is larger than 1,024 KB answers 422 with a pointer on /data/attributes/avatar.

Errors
StatusCodeWhen
401unauthenticatedThe request has no valid customer token
422requiredThe request has no file in avatar
422image_fileThe file is not an image or is larger than 1,024 KB

The meaning of every code is in Error Codes.

DELETE/store/customers/me/avatar
Auth
Customer bearer token
Rate limit
shopper-api

Query parameters

  • fields[customers]stringoptional

    Comma-separated attributes to return, such as first_name,last_name. See Sparse fieldsets.

To go back to the generated picture, delete the upload:

Request
curl -X DELETE http://localhost:8000/store/customers/me/avatar \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Bearer 1|customer-token"

The API answers 200 OK with the profile, where avatar_type is avatar_ui and avatar is the generated URL again.

Errors
StatusCodeWhen
401unauthenticatedThe request has no valid customer token

The meaning of every code is in Error Codes.

Addresses

Saved addresses spare a returning customer from typing their address at every checkout. The account area lists them, and the checkout offers them as choices. Each address is either a shipping or a billing address, and the customer can mark one address as the default for each.

Every address request is scoped to the owner of the token. An address ID that belongs to another customer answers 404 not_found, the same answer as an ID that does not exist.

Listing Addresses

The list returns every address of the customer, newest first, in one response. It is not paginated.

GET/store/customers/me/addresses
Auth
Customer bearer token
Rate limit
shopper-api

Query parameters

  • includestringoptional

    country adds the country of each address, a countries resource described in Countries.

  • fields[addresses]stringoptional

    Comma-separated attributes to return, such as street_address,city,postal_code. See Sparse fieldsets.

This request lists the addresses of the customer:

Request
curl http://localhost:8000/store/customers/me/addresses \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Bearer 1|customer-token"

The API answers 200 OK with an array of addresses resources:

Response 200
{
    "data": [
        {
            "id": "01JZ8KA2B3C4D5E6F7G8H9JKMN",
            "type": "addresses",
            "attributes": {
                "first_name": "Camille",
                "last_name": "Martin",
                "company_name": null,
                "street_address": "18 Rue de la Roquette",
                "street_address_plus": "Apartment 4B",
                "postal_code": "75011",
                "city": "Paris",
                "state": null,
                "country_code": "FR",
                "type": "shipping",
                "phone_number": "+33 6 12 34 56 78",
                "shipping_default": true,
                "billing_default": false,
                "created_at": "2026-11-02T18:05:43+00:00",
                "updated_at": "2026-11-02T18:05:43+00:00"
            }
        }
    ]
}

country_code is the two-letter ISO code of the country, and type is shipping or billing.

Errors
StatusCodeWhen
401unauthenticatedThe request has no valid customer token

The meaning of every code is in Error Codes.

Saving an Address

The storefront saves an address from the account area, or after a checkout when the customer ticks a "save this address" box.

POST/store/customers/me/addresses
Auth
Customer bearer token
Rate limit
shopper-api

Query parameters

  • includestringoptional

    country adds the country of the address, a countries resource described in Countries.

  • fields[addresses]stringoptional

    Comma-separated attributes to return, such as street_address,city,postal_code. See Sparse fieldsets.

Body

  • first_namestring

    First name, up to 255 characters.

  • last_namestring

    Last name, up to 255 characters.

  • street_addressstring

    Street and number, up to 255 characters.

  • postal_codestring

    Postal code, up to 255 characters.

  • citystring

    City, up to 255 characters.

  • country_codestring

    Two-letter ISO code of the country, such as FR or US. Upper-cased before validation.

  • typestring

    shipping or billing.

  • company_namestring, nulloptional

    Company, up to 255 characters.

  • street_address_plusstring, nulloptional

    Second address line, such as an apartment or a floor, up to 255 characters.

  • statestring, nulloptional

    State or region, such as NY, up to 255 characters.

  • phone_numberstring, nulloptional

    Phone number, up to 255 characters.

  • shipping_defaultbooleanoptional

    true makes this address the default shipping address of the customer.

  • billing_defaultbooleanoptional

    true makes this address the default billing address of the customer.

This request saves an address in Paris and makes it the default shipping address of the customer:

Request
curl -X POST http://localhost:8000/store/customers/me/addresses \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Bearer 1|customer-token" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Camille",
    "last_name": "Martin",
    "street_address": "18 Rue de la Roquette",
    "street_address_plus": "Apartment 4B",
    "postal_code": "75011",
    "city": "Paris",
    "country_code": "fr",
    "type": "shipping",
    "phone_number": "+33 6 12 34 56 78",
    "shipping_default": true,
    "billing_default": false
  }'

The API answers 201 Created with the new address, in the shape of the list above. A flag left out of the body is stored as false, but the 201 response shows it as null; the list and the update return false.

An unknown country code answers 422 with the exists code on /data/attributes/country_code.

Errors
StatusCodeWhen
401unauthenticatedThe request has no valid customer token
422existscountry_code is not a known country
422Rule name, such as requiredAnother field fails validation

The meaning of every code is in Error Codes.

Default Addresses

A customer has at most one default shipping address and one default billing address. Setting shipping_default or billing_default to true on an address, when saving or updating it, removes that flag from the other addresses of the customer, so the checkout can pick the default without asking.

The values 1 and "1" count as true and move the default the same way.

Updating and Deleting an Address

PATCH/store/customers/me/addresses/{addressId}
Auth
Customer bearer token
Rate limit
shopper-api

Path parameters

  • addressIdstring

    The id of the addresses resource.

Query parameters

  • includestringoptional

    country adds the country of the address, a countries resource described in Countries.

  • fields[addresses]stringoptional

    Comma-separated attributes to return, such as street_address,city,postal_code. See Sparse fieldsets.

Body

  • first_namestringoptional

    First name, up to 255 characters.

  • last_namestringoptional

    Last name, up to 255 characters.

  • company_namestring, nulloptional

    Company, up to 255 characters.

  • street_addressstringoptional

    Street and number, up to 255 characters.

  • street_address_plusstring, nulloptional

    Second address line, such as an apartment or a floor, up to 255 characters.

  • postal_codestringoptional

    Postal code, up to 255 characters.

  • citystringoptional

    City, up to 255 characters.

  • statestring, nulloptional

    State or region, such as NY, up to 255 characters.

  • country_codestringoptional

    Two-letter ISO code of the country, such as FR or US. Upper-cased before validation.

  • typestringoptional

    shipping or billing.

  • phone_numberstring, nulloptional

    Phone number, up to 255 characters.

  • shipping_defaultbooleanoptional

    true makes this address the default shipping address of the customer.

  • billing_defaultbooleanoptional

    true makes this address the default billing address of the customer.

An update takes the same fields as Saving an address, all optional. Send only what changed:

Request
curl -X PATCH http://localhost:8000/store/customers/me/addresses/01JZ8KB7C8D9E0F1G2H3J4K5M6 \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Bearer 1|customer-token" \
  -H "Content-Type: application/json" \
  -d '{"billing_default": true}'

The API answers 200 OK with the updated address.

Errors
StatusCodeWhen
401unauthenticatedThe request has no valid customer token
404not_foundThe customer has no address with this ID
422existscountry_code is not a known country
422Rule name, such as booleanAnother field fails validation

The meaning of every code is in Error Codes.

DELETE/store/customers/me/addresses/{addressId}
Auth
Customer bearer token
Rate limit
shopper-api

Path parameters

  • addressIdstring

    The id of the addresses resource.

A delete removes the address for good:

Request
curl -X DELETE http://localhost:8000/store/customers/me/addresses/01JZ8KB7C8D9E0F1G2H3J4K5M6 \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Bearer 1|customer-token"

The API answers 204 No Content, with no body. Deleting a default address leaves the customer without a default of that kind until another address gets the flag.

Errors
StatusCodeWhen
401unauthenticatedThe request has no valid customer token
404not_foundThe customer has no address with this ID

The meaning of every code is in Error Codes.

Using a Saved Address at Checkout

The cart does not take an address ID: the Cart guide sets addresses on a cart as objects. To ship to a saved address, copy its fields into the cart address. Most names are the same; these differ:

Saved addressCart address
company_namecompany
street_addressaddress_1
street_address_plusaddress_2
phone_numberphone

first_name, last_name, city, state, postal_code and country_code keep their names.

Transferring a Guest Cart

Most visitors fill a cart before they sign in. When they sign in at checkout, the cart they built must follow them into their account, and join the cart they may have left open on another device. The transfer does that: it attaches a guest cart to the signed-in customer and returns the cart the storefront uses from then on.

The login and registration requests accept the guest cart ID as cart_id and run this same transfer, returning the resulting cart ID in meta.cart_id, as Logging in shows. The transfer endpoint is for a customer who is already signed in when the guest cart appears, such as a second tab or a token restored from storage.

POST/store/carts/{cartId}/transfer
Auth
Customer bearer token

Path parameters

  • cartIdstring

    The ID of the guest cart.

Query parameters

  • includestringoptional

    Related resources to return with the cart, listed in Reading a Cart.

  • fields[carts]stringoptional

    Comma-separated attributes to return, such as lines_count,total. See Sparse fieldsets.

This request attaches a guest cart to the customer the token belongs to:

Request
curl -X POST http://localhost:8000/store/carts/01JZ9A1B2C3D4E5F6G7H8J9K0M/transfer \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Bearer 1|customer-token"
Errors
StatusCodeWhen
401unauthenticatedThe request has no valid customer token
403forbiddenThe cart belongs to another customer
404not_foundNo cart has this ID
409cart_completedThe cart is already an order
409payment_session_collectedThe guest cart is already paid at the payment provider
409payment_session_in_progressAnother request is opening a payment session on the cart, retry after Retry-After
503payment_provider_unavailableThe payment provider did not answer while the transfer released the payment session, retry after Retry-After
400bad_requestAn include path outside the cart list

The meaning of every code is in Error Codes.

What the Transfer Does

The result depends on the guest cart and on the open carts the customer already has:

SituationResultCart ID to keep
The cart already belongs to this customerNothing changes, so a retry with the returned ID is safe.The same ID
The customer has no open cartThe guest cart becomes a cart of the customer.The guest cart ID
The customer has an open cartThe guest lines move into the customer's latest open cart, and the guest cart is deleted.The customer cart ID
The guest cart or the customer cart has a payment session openNo merge: the guest cart becomes a cart of the customer, next to the other one.The guest cart ID

When the carts merge, a product present in both carts becomes one line whose quantity is the sum of both, and the other guest lines move as they are. Promotion codes of the guest cart are added to the customer cart. The shipping option of the customer cart is cleared, because the parcel changed, and the customer picks one again at checkout. The email and addresses of the guest cart are not carried over: the customer cart keeps its own.

A merge that cannot be done falls back to the claim, and the guest cart becomes a cart of the customer, unchanged. That happens when a line carries a negotiated price that locks its quantity, when the same product carries different metadata in the two carts, or when a product has no price in the currency of the customer cart.

Unless it has a payment session open, the cart that results is priced again from the catalog, and its promotion codes are checked again: a code the customer can no longer use, such as one limited to one use per customer that they already used, is removed. The Cart page covers how prices and promotions apply.

The Response

The API answers 200 OK with the resulting cart, in the shape the Cart guide describes. meta.price_changes lists the lines whose unit price changed in the transfer, with the price before and after, in cents:

Response 200
{
    "data": {
        "id": "01JZ7Q4R5S6T7V8W9X0Y1Z2A3B",
        "type": "carts",
        "attributes": {
            "currency_code": "EUR",
            "email": null,
            "promotions": [],
            "completed_at": null,
            "metadata": null,
            "lines_count": 2,
            "lines_quantity": 3,
            "subtotal": 25700,
            "discount_total": 0,
            "tax_total": 0,
            "shipping_total": 0,
            "total": 25700,
            "tax_inclusive": false,
            "shipping_option_id": null,
            "created_at": "2026-11-10T16:42:08+00:00",
            "updated_at": "2026-11-19T10:21:37+00:00"
        }
    },
    "meta": {
        "price_changes": [
            {
                "line": "01JZ9A2C3D4E5F6G7H8J9K0M1N",
                "from": 12900,
                "to": 11900
            }
        ]
    }
}

Here the guest cart 01JZ9A1B2C3D4E5F6G7H8J9K0M was merged into the customer cart 01JZ7Q4R5S6T7V8W9X0Y1Z2A3B. The pair of Classic Leather Sneakers the customer had left in that cart now costs €119.00 instead of €129.00, and the storefront shows that change before the customer pays. price_changes is empty when no price moved, and it skips lines that changed currency in a merge.

Store the id of the response as the cart ID and forget the guest cart ID: after a merge, the guest cart no longer exists and its ID answers 404.

Errors

The transfer shares the checkout rate limit with the cart endpoints that add things, described in Rate limits.

StatusCodeWhenWhat to do
401unauthenticatedThe request has no valid customer token.Sign the customer in, then transfer.
403forbiddenThe cart belongs to another customer.Drop the stored cart ID and use the customer's own cart.
404not_foundNo cart has this ID.Drop the stored cart ID.
409cart_completedThe cart is already an order.Drop the stored cart ID.
409payment_session_collectedThe guest cart is already paid at the payment provider, so its payment session cannot be released.Complete the checkout of that cart to place the order.
409payment_session_in_progressAnother request is opening a payment session on the cart. The response carries Retry-After: 3.Retry after 3 seconds.
503payment_provider_unavailableThe payment provider did not answer while the transfer released the payment session of the cart.Retry later.

Next Steps

With the customer signed in and their cart attached, the storefront moves on to the checkout, then to the orders of the account.

Last updated on

Edit on GitHub