Backend API: Manage customers

Last updated:
Edit on GitHub
This page describes the API endpoint contract, which is the same regardless of the serving infrastructure. Storefront API endpoints are served by API Platform (recommended) or the legacy Glue infrastructure; Backend API endpoints currently run on the Glue infrastructure.

This document describes how to manage customers using the Backend API. These endpoints expose the same customer lifecycle that the Back Office uses, so you can build Back Office extensions, ERP integrations, and internal tools against one contract.

Customers are addressed by customerReference. The internal database identifier is never exposed.

Installation

These endpoints are provided by API Platform. To install and enable it, see Enable API Platform.

Retrieve customers

To retrieve a paginated collection of customers, send the request:

GET /customers

Request

HEADER KEY HEADER VALUE REQUIRED DESCRIPTION
Authorization string ✓ Alphanumeric string that authorizes the Back Office user to send requests to protected resources. Get it by authenticating as a Back Office user.
Accept application/vnd.api+json Media type of the response. If you omit this header, the endpoint answers with application/vnd.api+json.
QUERY PARAMETER DESCRIPTION POSSIBLE VALUES
page[limit] Maximum number of items to return per page. From 1 to any. Defaults to 10.
page[offset] Number of items to skip before the page begins. From 0 to any. Defaults to 0.
q Free-text search, matched against the email, first name, and last name. Any string.
filter[customers.customerReference] Filters the collection by an exact customer reference. Any customer reference.
filter[customers.email] Filters the collection by an exact email address. Any email address.
filter[customers.firstName] Filters the collection by a partial first name. Any string.
filter[customers.lastName] Filters the collection by a partial last name. Any string.
sort Sorts the collection by the given field. Prefix a field with - to sort in descending order. Separate several fields with a comma. customerReference, createdAt, email, firstName, lastName, registered
include Adds resource relationships to the request. notes
Anonymized customers

The collection always excludes anonymized customers. There is no parameter that brings them back into the result.

Free-text search and name filters

q takes precedence over filter[customers.firstName] and filter[customers.lastName]. If you send q, the endpoint ignores both name filters. Combining q with filter[customers.email] or filter[customers.customerReference] works as expected.

Sorting by a field that is not on the list returns 400 with the error code 1203, and the error message names the supported fields.

REQUEST USAGE
GET https://glue-backend.mysprykershop.com/customers Retrieve the first page of customers.
GET https://glue-backend.mysprykershop.com/customers?page[limit]=50&page[offset]=100 Retrieve 50 customers, skipping the first 100.
GET https://glue-backend.mysprykershop.com/customers?q=hopkin Retrieve customers whose email, first name, or last name matches hopkin.
GET https://glue-backend.mysprykershop.com/customers?filter[customers.email][email protected] Retrieve the customer with the given email address.
GET https://glue-backend.mysprykershop.com/customers?sort=-createdAt Retrieve customers, newest first.

Response

Response sample: retrieve customers 
{
    "data": [
        {
            "type": "customers",
            "id": "DE--1",
            "attributes": {
                "customerReference": "DE--1",
                "email": "[email protected]",
                "salutation": "Mr",
                "firstName": "Spencor",
                "lastName": "Hopkin",
                "gender": "Male",
                "dateOfBirth": "1990-01-15",
                "phone": "+49123456789",
                "company": "Acme Inc.",
                "localeName": "en_US",
                "storeName": "DE",
                "registered": "2026-08-27",
                "createdAt": "2026-08-27 10:06:00.000000",
                "updatedAt": "2026-08-27 12:30:00.000000",
                "anonymizedAt": null
            },
            "links": {
                "self": "https://glue-backend.mysprykershop.com/customers/DE--1"
            }
        },
        {
            "type": "customers",
            "id": "DE--2",
            "attributes": {
                "customerReference": "DE--2",
                "email": "[email protected]",
                "salutation": "Mr",
                "firstName": "Harald",
                "lastName": "Schmidt",
                "gender": null,
                "dateOfBirth": null,
                "phone": null,
                "company": null,
                "localeName": "de_DE",
                "storeName": "DE",
                "registered": null,
                "createdAt": "2026-08-28 09:14:00.000000",
                "updatedAt": "2026-08-28 09:14:00.000000",
                "anonymizedAt": null
            },
            "links": {
                "self": "https://glue-backend.mysprykershop.com/customers/DE--2"
            }
        }
    ],
    "meta": {
        "pagination": {
            "numFound": 42,
            "currentPage": 1,
            "maxPage": 5,
            "currentItemsPerPage": 10
        }
    },
    "links": {
        "self": "https://glue-backend.mysprykershop.com/customers",
        "first": "https://glue-backend.mysprykershop.com/customers?page[limit]=10&page[offset]=0",
        "last": "https://glue-backend.mysprykershop.com/customers?page[limit]=10&page[offset]=40",
        "next": "https://glue-backend.mysprykershop.com/customers?page[limit]=10&page[offset]=10"
    }
}
Response sample: retrieve a customer with notes 
{
    "data": {
        "type": "customers",
        "id": "DE--1",
        "attributes": {
            "customerReference": "DE--1",
            "email": "[email protected]",
            "salutation": "Mr",
            "firstName": "Spencor",
            "lastName": "Hopkin"
        },
        "relationships": {
            "notes": {
                "data": [
                    {
                        "type": "notes",
                        "id": "b1f7c3d2-8a41-5c6e-9d70-2e5b8f0a4c31"
                    }
                ]
            }
        },
        "links": {
            "self": "https://glue-backend.mysprykershop.com/customers/DE--1"
        }
    },
    "included": [
        {
            "type": "notes",
            "id": "b1f7c3d2-8a41-5c6e-9d70-2e5b8f0a4c31",
            "attributes": {
                "customerReference": "DE--1",
                "message": "Called the customer about invoice 4711; they will pay by Friday.",
                "username": "Admin Spryker",
                "createdAt": "2026-08-31 10:06:00.000000",
                "updatedAt": "2026-08-31 10:06:00.000000"
            }
        }
    ]
}
Included notes

When you request notes with include=notes, the endpoint returns the first 10 notes of the customer and ignores the page[limit], page[offset], and sort parameters of the request, because those parameters address the customer collection. To page or sort notes, use Retrieve customer notes.

ATTRIBUTE TYPE DESCRIPTION
customerReference String Public unique customer identifier. Addresses the customer in every operation.
email String Email address of the customer, also used as the Storefront username.
salutation String Salutation of the customer.
firstName String First name of the customer.
lastName String Last name of the customer.
gender String Gender of the customer.
dateOfBirth String Date of birth of the customer, in the YYYY-MM-DD format.
phone String Phone number of the customer.
company String Company label stored on the customer record and shown in the Back Office.
localeName String Locale assigned to the customer.
storeName String Store context used for outgoing mail templates.
registered String Date on which the customer confirmed the registration. null until the customer confirms it.
createdAt String Date and time when the customer was created.
updatedAt String Date and time when the customer was last updated.
anonymizedAt String Date and time when the customer was anonymized. A non-null value means the record is anonymized.

A collection response carries its pagination summary in the top-level meta.pagination object:

ATTRIBUTE TYPE DESCRIPTION
meta.pagination.numFound Integer Total number of items found.
meta.pagination.currentPage Integer Current page number.
meta.pagination.maxPage Integer Total number of pages.
meta.pagination.currentItemsPerPage Integer Number of items per page.

The top-level links object carries the first and last links, plus prev and next when those pages exist. Each link repeats the query parameters of the request and rewrites the window as page[limit] and page[offset], so you can follow it as it is.

Retrieve a customer

To retrieve a single customer, send the request:

GET /customers/{{customer_reference}}

PATH PARAMETER DESCRIPTION
{{customer_reference}} Reference of the customer to retrieve. To get it, retrieve customers.

Request

HEADER KEY HEADER VALUE REQUIRED DESCRIPTION
Authorization string ✓ Alphanumeric string that authorizes the Back Office user to send requests to protected resources. Get it by authenticating as a Back Office user.
QUERY PARAMETER DESCRIPTION POSSIBLE VALUES
include Adds resource relationships to the request. notes
REQUEST USAGE
GET https://glue-backend.mysprykershop.com/customers/DE--1 Retrieve the customer with the reference DE--1.
GET https://glue-backend.mysprykershop.com/customers/DE--1?include=notes Retrieve the customer with the reference DE--1 and their notes.

Response

The response contains the same attributes as Retrieve customers, without the meta.pagination object.

An anonymized customer is no longer retrievable by reference and returns 404 with the error code 1201.

Create a customer

To create a customer, send the request:

POST /customers

Request

HEADER KEY HEADER VALUE REQUIRED DESCRIPTION
Authorization string ✓ Alphanumeric string that authorizes the Back Office user to send requests to protected resources. Get it by authenticating as a Back Office user.
Content-Type application/vnd.api+json ✓ Media type of the request body.

Request sample: POST https://glue-backend.mysprykershop.com/customers

{
    "data": {
        "type": "customers",
        "attributes": {
            "email": "[email protected]",
            "salutation": "Mr",
            "firstName": "Spencor",
            "lastName": "Hopkin",
            "storeName": "DE",
            "sendPasswordToken": true
        }
    }
}
ATTRIBUTE TYPE REQUIRED DESCRIPTION
email String ✓ Email address of the customer. Must not exceed 100 characters. Uniqueness is validated case-insensitively.
salutation String ✓ Salutation of the customer. One of Mr, Mrs, Dr, Ms, n/a.
firstName String ✓ First name of the customer. Must not exceed 100 characters or contain :, /, <, or >.
lastName String ✓ Last name of the customer. Must not exceed 100 characters or contain :, /, <, or >.
gender String Gender of the customer. One of Male, Female.
dateOfBirth String Date of birth of the customer, in the YYYY-MM-DD format.
phone String Phone number of the customer. Must not exceed 255 characters.
company String Company label of the customer. Must not exceed 100 characters.
localeName String Locale to assign to the customer. Must not exceed 15 characters. If you omit it, the customer receives the current locale.
storeName String ✓ Store to register the customer for. It is the context of every mail the registration sends, so the confirmation link points at the right storefront. Must name a configured store and must not exceed 255 characters.
sendPasswordToken Boolean Sends a password-restore mail so that the customer sets their own password. Requires storeName.
sendRegistrationToken Boolean Sends the registration-confirmation mail. Defaults to true. Set it to false to suppress the mail. Accepted when you create a customer only.
Setting a password

The resource has no password attribute. Sending sendPasswordToken with storeName is the only way to give a customer a password through this API, which mirrors the Send password token through email checkbox in the Back Office. Creating a customer always requires storeName; when you update one, storeName is optional, so sending sendPasswordToken without it returns 422 with the error code 1204.

sendPasswordToken and sendRegistrationToken are write-only. The response does not echo them back.

Response

Response sample:

{
    "data": {
        "type": "customers",
        "id": "DE--42",
        "attributes": {
            "customerReference": "DE--42",
            "email": "[email protected]",
            "salutation": "Mr",
            "firstName": "Spencor",
            "lastName": "Hopkin",
            "storeName": "DE",
            "registered": null,
            "createdAt": "2026-09-04 10:06:00.000000",
            "updatedAt": "2026-09-04 10:06:00.000000",
            "anonymizedAt": null
        },
        "links": {
            "self": "https://glue-backend.mysprykershop.com/customers/DE--42"
        }
    }
}

The database assigns the customerReference that addresses the customer from now on. registered stays null until the customer confirms the registration.

Edit a customer

To update a customer, send the request:

PATCH /customers/{{customer_reference}}

PATH PARAMETER DESCRIPTION
{{customer_reference}} Reference of the customer to update. To get it, retrieve customers.

Request

HEADER KEY HEADER VALUE REQUIRED DESCRIPTION
Authorization string ✓ Alphanumeric string that authorizes the Back Office user to send requests to protected resources. Get it by authenticating as a Back Office user.
Content-Type application/vnd.api+json ✓ Media type of the request body.

Request sample: PATCH https://glue-backend.mysprykershop.com/customers/DE--1

{
    "data": {
        "type": "customers",
        "id": "DE--1",
        "attributes": {
            "firstName": "Spencer"
        }
    }
}

The request accepts the same writable attributes as Create a customer, except sendRegistrationToken, and all of them are optional. The endpoint applies only the attributes present in the payload; every attribute you omit keeps its stored value.

A registration token is issued only when a customer registers, so sendRegistrationToken is not part of this operation. If you send it, it is ignored.

Response

The response contains the updated customer, with the same attributes as Retrieve a customer.

Anonymize a customer

To anonymize a customer, send the request:

DELETE /customers/{{customer_reference}}

PATH PARAMETER DESCRIPTION
{{customer_reference}} Reference of the customer to anonymize. To get it, retrieve customers.

Request

HEADER KEY HEADER VALUE REQUIRED DESCRIPTION
Authorization string ✓ Alphanumeric string that authorizes the Back Office user to send requests to protected resources. Get it by authenticating as a Back Office user.

Request sample: DELETE https://glue-backend.mysprykershop.com/customers/DE--1

Response

A successful request returns the 204 No Content status code with an empty body.

Anonymization is not deletion

This endpoint anonymizes the customer to satisfy the right to erasure. The record is retained, anonymizedAt is set, and the personal data is scrubbed. The customer is no longer retrievable by reference, and the collection never returns the record again. There is no endpoint that deletes a customer row.

Other management options

Possible errors

CODE REASON
901 The request body failed schema validation. Each error names the rejected attribute in source.pointer.
1201 No customer matches the given reference.
1202 The customer was rejected. For example, the email address is already in use.
1203 The sort parameter names a field that the collection does not support.
1204 sendPasswordToken was sent without storeName.
1208 The given store does not exist. The error message lists the available stores.
1209 The given locale does not exist.

To view generic errors, see API errors and troubleshooting.