Customers

Read the customers that were created or matched through your API client.

Get a customer

GET /customers/{externalId}

Scope: customers.read

Returns all data of the customer linked to your customer ID, including the address book. Login data such as passwords and security codes is never included.

Only customers that were created or matched through your API client can be read. Any other customer, an unknown ID and a deleted customer all answer 404, so the response never reveals whether a customer exists.

Path parameters

Parameter	Type	Required	Description
`externalId`	string	required	Your customer ID, as sent in `customer.external_id`. Case-sensitive. URL-encode special characters. max length 191

Example request

curl "https://shop.example.com/api/v1/customers/u-55871" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json"

Responses

200 OK The customer.

{
  "data": {
    "id": 9021,
    "customer_id": 9021,
    "external_id": "u-55871",
    "email": "alex.sample@example.com",
    "salutation": "Mr",
    "title": null,
    "first_name": "Alex",
    "last_name": "Sample",
    "company_name": null,
    "street": "Sample Street",
    "house_number": "5",
    "additional": "2nd floor",
    "postcode": "10115",
    "city": "Berlin",
    "country_id": 276,
    "country": "DE",
    "telephone": "+49 30 0000000",
    "shop_id": 1,
    "customer_class_id": 1,
    "is_guest": 0,
    "status": 0,
    "created_at": "2026-10-13T12:05:03.000000Z",
    "updated_at": "2026-10-13T12:05:03.000000Z",
    "billing": {
      "salutation": "Mr",
      "title": null,
      "first_name": "Alex",
      "last_name": "Sample",
      "company": null,
      "street": "Sample Street",
      "house": "5",
      "additional": "2nd floor",
      "postcode": "10115",
      "city": "Berlin",
      "country": "DE"
    },
    "addresses": [
      {
        "id": 1,
        "customer_id": 9021,
        "first_name": "Alex",
        "last_name": "Sample",
        "company_name": null,
        "street": "Packstation",
        "house_number": "123",
        "postcode": "10117",
        "city": "Berlin",
        "country_id": 276,
        "country": "DE",
        "packstation": 1,
        "packstation_name": "123",
        "postnumber": "12345678",
        "is_default": 0,
        "is_default_billing": 0,
        "is_default_shipping": false
      }
    ]
  }
}

Response fields

Field	Type	Required	Description
`data`	object	required	All data of the customer. The fields listed here are the most important ones; further fields of the customer record are included as well and may be added over time. Login data (passwords, security codes, reset tokens) is never included.
`id`	integer	optional	Our customer number (same as `customer_id`).
`customer_id`	integer	required	Our customer number.
`external_id`	string	required	Your customer ID, as used in the path.
`email`	string \| null	optional
`salutation`	string \| null	optional
`title`	string \| null	optional
`first_name`	string \| null	optional
`last_name`	string \| null	optional
`company_name`	string \| null	optional
`street`	string \| null	optional
`house_number`	string \| null	optional
`additional`	string \| null	optional
`postcode`	string \| null	optional
`city`	string \| null	optional
`country_id`	integer \| null	optional	Our internal country ID.
`country`	string \| null	required	Country code according to ISO 3166-1 alpha-2.
`telephone`	string \| null	optional
`shop_id`	integer \| null	optional
`customer_class_id`	integer \| null	optional	Assigned customer class (see `listCustomerClasses`).
`is_guest`	integer \| null	optional	`1` for a guest customer without an account.
`status`	integer \| null	optional	`0` = active, any other value = blocked.
`created_at`	string (date-time) \| null	optional
`updated_at`	string (date-time) \| null	optional
`billing`	object	required	Billing address of the customer in the format of `customer.billing` of an order.
`salutation`	string \| null	optional
`title`	string \| null	optional
`first_name`	string \| null	optional
`last_name`	string \| null	optional
`company`	string \| null	optional
`street`	string \| null	optional
`house`	string \| null	optional
`additional`	string \| null	optional
`postcode`	string \| null	optional
`city`	string \| null	optional
`country`	string \| null	optional
`addresses[]`	array of object	required	Address book of the customer, without deleted addresses.
`id`	integer	required	ID of the address, used in the path of `updateCustomerAddress` and `deleteCustomerAddress`.
`customer_id`	integer	required	Our customer number.
`salutation`	string \| null	optional
`title`	string \| null	optional
`first_name`	string \| null	optional
`last_name`	string \| null	optional
`company_name`	string \| null	optional
`street`	string \| null	optional
`house_number`	string \| null	optional
`additional`	string \| null	optional
`postcode`	string \| null	optional
`city`	string \| null	optional
`country_id`	integer \| null	optional	Our internal country ID.
`country`	string \| null	required	Country code according to ISO 3166-1 alpha-2.
`telephone`	string \| null	optional
`mobile`	string \| null	optional
`email`	string \| null	optional
`packstation`	integer \| null	optional	`1` for a parcel locker address.
`packstation_name`	string \| null	optional	Number of the parcel locker.
`postnumber`	string \| null	optional	Parcel locker customer number.
`is_default`	integer \| null	optional	`1` if this is the default delivery address (same as `is_default_shipping`).
`is_default_billing`	integer \| null	optional	`1` if this is the default billing address.
`is_default_shipping`	boolean	required	`true` if this is the default delivery address.
`created_at`	string (date-time) \| null	optional
`updated_at`	string (date-time) \| null	optional

Error responses

401 Unauthorized The API key is missing, malformed, wrong, paused, expired or revoked. The body is always the same and never names the reason.

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key.",
    "details": []
  }
}

403 Forbidden The API key is valid but lacks a scope this endpoint needs. details.required lists the scopes the endpoint requires, details.missing the ones your key lacks. Ask the shop operator to add the scope.

{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key is missing a required scope.",
    "details": {
      "required": [
        "orders.write"
      ],
      "missing": [
        "orders.write"
      ]
    }
  }
}

404 Not Found The path does not exist, the API is not enabled on this system, the order does not belong to the shop of your API client, or the customer, address or label value is not known to your API client.

{
  "error": {
    "code": "not_found",
    "message": "The requested resource does not exist.",
    "details": []
  }
}

429 Too Many Requests Too many requests. Either your API client used up its requests per minute (message Too many requests., with all rate limit headers), or too many failed authentications came in a short time (message Too many authentication attempts., only Retry-After). Both carry the code rate_limited.

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests.",
    "details": []
  }
}

500 Internal Server Error An unexpected error occurred on our side. Retry later.

{
  "error": {
    "code": "server_error",
    "message": "An unexpected error occurred.",
    "details": []
  }
}

All error codes: error code reference.