Backend API: Manage customer notes

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 the notes of a customer using the Backend API. A note is an internal remark that a Back Office user records against a customer, such as the outcome of a phone call. Notes are a sub-resource of a customer, so every endpoint is addressed through the reference of the customer the note belongs to.

Notes are addressed by uuid. The internal database identifier is never exposed.

Notes are append-only

The resource supports reading notes and adding notes. It has no update and no delete operation, so a customer note timeline is a permanent record. PATCH and DELETE requests to a note return 404. For the same reason a note carries createdAt alone: there is no second timestamp to report, and you cannot sort the collection by one.

Installation

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

Retrieve customer notes

To retrieve a paginated collection of the notes of a customer, send the request:

GET /customers/{{customer_reference}}/notes

PATH PARAMETER DESCRIPTION
{{customer_reference}} Reference of the customer whose notes you want 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.
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.
sort Sorts the collection by the given field. Prefix a field with - to sort in descending order. Separate several fields with a comma. createdAt, username

Without a sort parameter, the collection returns the newest note first. 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.

The collection does not accept filters.

REQUEST USAGE
GET https://glue-backend.mysprykershop.com/customers/DE--1/notes Retrieve the first page of the notes of the customer DE--1, newest first.
GET https://glue-backend.mysprykershop.com/customers/DE--1/notes?sort=createdAt Retrieve the notes of the customer DE--1, oldest first.
GET https://glue-backend.mysprykershop.com/customers/DE--1/notes?page[limit]=50 Retrieve up to 50 notes of the customer DE--1.

Response

Response sample: retrieve customer notes 
{
    "data": [
        {
            "type": "notes",
            "id": "b1f7c3d2-8a41-5c6e-9d70-2e5b8f0a4c31",
            "attributes": {
                "uuid": "b1f7c3d2-8a41-5c6e-9d70-2e5b8f0a4c31",
                "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"
            },
            "links": {
                "self": "https://glue-backend.mysprykershop.com/customers/DE--1/notes/b1f7c3d2-8a41-5c6e-9d70-2e5b8f0a4c31"
            }
        },
        {
            "type": "notes",
            "id": "c2a8d4e3-9b52-5d7f-8e81-3f6c9a1b5d42",
            "attributes": {
                "uuid": "c2a8d4e3-9b52-5d7f-8e81-3f6c9a1b5d42",
                "customerReference": "DE--1",
                "message": "Customer asked for the invoice to be reissued to the billing department.",
                "username": "Admin Spryker",
                "createdAt": "2026-08-29 14:22:00.000000"
            },
            "links": {
                "self": "https://glue-backend.mysprykershop.com/customers/DE--1/notes/c2a8d4e3-9b52-5d7f-8e81-3f6c9a1b5d42"
            }
        }
    ],
    "meta": {
        "pagination": {
            "numFound": 2,
            "currentPage": 1,
            "maxPage": 1,
            "currentItemsPerPage": 10
        }
    },
    "links": {
        "self": "https://glue-backend.mysprykershop.com/customers/DE--1/notes",
        "first": "https://glue-backend.mysprykershop.com/customers/DE--1/notes?page[limit]=10&page[offset]=0",
        "last": "https://glue-backend.mysprykershop.com/customers/DE--1/notes?page[limit]=10&page[offset]=0"
    }
}
ATTRIBUTE TYPE DESCRIPTION
uuid String Public unique note identifier. Addresses the note in every operation.
customerReference String Reference of the customer this note belongs to.
message String Text of the note.
username String Display name of the Back Office user who wrote the note.
createdAt String Date and time when the note was written. A note is never modified after it is written, so this is the only timestamp the resource carries.

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.

You can also retrieve the notes of a customer together with the customer. For more information, see Retrieve a customer.

Retrieve a customer note

To retrieve a single note of a customer, send the request:

GET /customers/{{customer_reference}}/notes/{{note_uuid}}

PATH PARAMETER DESCRIPTION
{{customer_reference}} Reference of the customer the note belongs to.
{{note_uuid}} Uuid of the note to retrieve. To get it, retrieve customer notes.

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: GET https://glue-backend.mysprykershop.com/customers/DE--1/notes/b1f7c3d2-8a41-5c6e-9d70-2e5b8f0a4c31

Response

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

Notes of another customer

A note is reachable only through the customer it belongs to. Requesting a note through a different customer reference returns 404 with the error code 1206, exactly as an unknown uuid does, so the response never reveals that the note exists.

Add a customer note

To add a note to a customer, send the request:

POST /customers/{{customer_reference}}/notes

PATH PARAMETER DESCRIPTION
{{customer_reference}} Reference of the customer to add the note to.

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/DE--1/notes

{
    "data": {
        "type": "notes",
        "attributes": {
            "message": "Called the customer about invoice 4711; they will pay by Friday."
        }
    }
}
ATTRIBUTE TYPE REQUIRED DESCRIPTION
message String ✓ Text of the note. Must not be blank, and must not exceed 65535 characters.
The author comes from the access token

Spryker attributes the note to the Back Office user whose access token you send, and resolves username from that token. You cannot set the author through the API: if you send username in the payload, the endpoint ignores it.

If the acting Back Office user cannot be resolved from the token, the request returns 401 with the error code 1207.

message is the only writable attribute of the resource.

Response

Response sample:

{
    "data": {
        "type": "notes",
        "id": "b1f7c3d2-8a41-5c6e-9d70-2e5b8f0a4c31",
        "attributes": {
            "uuid": "b1f7c3d2-8a41-5c6e-9d70-2e5b8f0a4c31",
            "customerReference": "DE--1",
            "message": "Called the customer about invoice 4711; they will pay by Friday.",
            "username": "Admin Spryker",
            "createdAt": "2026-09-04 10:06:00.000000"
        },
        "links": {
            "self": "https://glue-backend.mysprykershop.com/customers/DE--1/notes/b1f7c3d2-8a41-5c6e-9d70-2e5b8f0a4c31"
        }
    }
}

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.
1203 The sort parameter names a field that the collection does not support.
1206 No note with the given uuid belongs to the given customer.
1207 The Back Office user acting on the request could not be resolved from the access token.

To view generic errors, see API errors and troubleshooting.