Backend API: Manage customer addresses

This document describes how to manage the addresses of a customer using the Backend API. Addresses are a sub-resource of a customer, so every endpoint is addressed through the reference of the customer that owns the address.

Addresses are addressed by uuid. The internal database identifier is never exposed. The uuid is derived deterministically from the address, so it is stable for the lifetime of the record.

Installation

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

Retrieve customer addresses

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

GET /customers/{{customer_reference}}/addresses

Request

Without a sort parameter, the collection is ordered by address ID in ascending order, the same default the Back Office address table uses. 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.

Response

{
    "data": [
        {
            "type": "addresses",
            "id": "5caa05f5-41f5-5e6c-a254-07d7887fb4e9",
            "attributes": {
                "uuid": "5caa05f5-41f5-5e6c-a254-07d7887fb4e9",
                "customerReference": "DE--1",
                "salutation": "Mr",
                "firstName": "Spencor",
                "lastName": "Hopkin",
                "address1": "Julie-Wolfthorn-Straße",
                "address2": "1",
                "address3": "Floor 3",
                "company": "Spryker Systems GmbH",
                "city": "Berlin",
                "zipCode": "10115",
                "iso2Code": "DE",
                "country": "Germany",
                "region": "",
                "phone": "+49 30 234567890",
                "comment": "Please ring the doorbell twice.",
                "isDefaultBilling": true,
                "isDefaultShipping": true,
                "createdAt": "2026-08-31 10:06:00.000000",
                "updatedAt": "2026-08-31 12:30:00.000000"
            },
            "links": {
                "self": "https://glue-backend.mysprykershop.com/customers/DE--1/addresses/5caa05f5-41f5-5e6c-a254-07d7887fb4e9"
            }
        }
    ],
    "meta": {
        "pagination": {
            "numFound": 2,
            "currentPage": 1,
            "maxPage": 1,
            "currentItemsPerPage": 10
        }
    },
    "links": {
        "self": "https://glue-backend.mysprykershop.com/customers/DE--1/addresses",
        "first": "https://glue-backend.mysprykershop.com/customers/DE--1/addresses?page[limit]=10&page[offset]=0",
        "last": "https://glue-backend.mysprykershop.com/customers/DE--1/addresses?page[limit]=10&page[offset]=0"
    }
}

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

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 address

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

GET /customers/{{customer_reference}}/addresses/{{address_uuid}}

Request

Request sample: GET https://glue-backend.mysprykershop.com/customers/DE--1/addresses/5caa05f5-41f5-5e6c-a254-07d7887fb4e9

Response

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

Add a customer address

To create an address for a customer, send the request:

POST /customers/{{customer_reference}}/addresses

Request

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

{
    "data": {
        "type": "addresses",
        "attributes": {
            "salutation": "Mr",
            "firstName": "Spencor",
            "lastName": "Hopkin",
            "address1": "Julie-Wolfthorn-Straße",
            "address2": "1",
            "city": "Berlin",
            "zipCode": "10115",
            "iso2Code": "DE"
        }
    }
}

country is read-only. To set the country of an address, send iso2Code.

Response

Response sample:

{
    "data": {
        "type": "addresses",
        "id": "5caa05f5-41f5-5e6c-a254-07d7887fb4e9",
        "attributes": {
            "uuid": "5caa05f5-41f5-5e6c-a254-07d7887fb4e9",
            "customerReference": "DE--1",
            "salutation": "Mr",
            "firstName": "Spencor",
            "lastName": "Hopkin",
            "address1": "Julie-Wolfthorn-Straße",
            "address2": "1",
            "city": "Berlin",
            "zipCode": "10115",
            "iso2Code": "DE",
            "country": "Germany",
            "isDefaultBilling": true,
            "isDefaultShipping": true,
            "createdAt": "2026-09-04 10:06:00.000000",
            "updatedAt": "2026-09-04 10:06:00.000000"
        },
        "links": {
            "self": "https://glue-backend.mysprykershop.com/customers/DE--1/addresses/5caa05f5-41f5-5e6c-a254-07d7887fb4e9"
        }
    }
}

Edit a customer address

To update an address of a customer, send the request:

PATCH /customers/{{customer_reference}}/addresses/{{address_uuid}}

Request

Request sample: PATCH https://glue-backend.mysprykershop.com/customers/DE--1/addresses/5caa05f5-41f5-5e6c-a254-07d7887fb4e9

{
    "data": {
        "type": "addresses",
        "id": "5caa05f5-41f5-5e6c-a254-07d7887fb4e9",
        "attributes": {
            "city": "Hamburg",
            "zipCode": "20095"
        }
    }
}

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

Response

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

Delete a customer address

To delete an address of a customer, send the request:

DELETE /customers/{{customer_reference}}/addresses/{{address_uuid}}

Request

Request sample: DELETE https://glue-backend.mysprykershop.com/customers/DE--1/addresses/5caa05f5-41f5-5e6c-a254-07d7887fb4e9

Response

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

If the deleted address was a default billing or shipping address, the customer is left without that default. Deleting an address does not promote another address in its place.

Other management options

• Backend API: Manage customers
• Backend API: Manage customer notes
• Backend API: Manage company users

Possible errors

To view generic errors, see API errors and troubleshooting.