Customers

Customer in Super represents a known individual within your business. Customers act as a central record that other resources such as saved card tokens can be associated with.

📘

Customers and saved cards

Creating a customer is required before you can store a card token against them for saved card payments. See Tokens for more detail.

The Customer Object

Create a Customer

Creates a new customer record in Super. The externalReference and brandId fields are required, and externalReference must be unique per brand.

Endpoint: POST https://api.superpayments.com/2026-04-01/customers

📘

Finding your brandId

Your brandId can be found in the Super Portal under Integrations & Tools → API Keys: business.superpayments.com/dashboard/developers/api-keys

Request example:

{
  "externalReference": "your-internal-customer-id",
  "brandId": "0714ece1-629a-47ef-a01a-c79ae8dc2bab",
  "firstName": "John",
  "lastName": "Smith",
  "emailAddress": "[email protected]",
  "phoneNumber": "07462753542",
  "metadata": {
    "yourKey": "yourValue"
  }
}

Response (201):

{
  "id": "cus_0123456789",
  "externalReference": "your-internal-customer-id",
  "brandId": "your-brand-id",
  "firstName": "John",
  "lastName": "Smith",
  "emailAddress": "[email protected]",
  "phoneNumber": "07462123456",
  "metadata": {
    "yourKey": "yourValue"
  },
  "paymentMethods": [],
  "createdAt": "2048-01-24T15:10:15.425Z",
  "updatedAt": "2048-01-24T15:10:15.425Z"
}

📘

Store the returned ID

Store the returned id against the customer in your own system. You will need it to create tokens, retrieve the customer, and make charges.

Get a Customer

Returns a previously created customer. It requires the Super customer ID that was provided upon successful creation of the customer.

Endpoint: GET https://api.superpayments.com/2026-04-01/customers/{id}

The id parameter must be a Super customer ID in the format cus_*. The response includes any saved card tokens currently linked to the customer in the paymentMethods array:

{
  "id": "cus_01kvx2x3c1espan6cmhdyge717",
  "externalReference": "your-internal-customer-id",
  "brandId": "0714ece1-629a-47ef-a01a-c79ae8dc2bab",
  "firstName": "John",
  "lastName": "Smith",
  "emailAddress": "[email protected]",
  "phoneNumber": "07462753542",
  "metadata": {
    "yourKey": "yourValue"
  },
  "paymentMethods": [
    {
      "id": "pm_01kv7tzzpgf20av09wd3jt3aq6",
      "type": "CARD",
      "usage": "OFF_SESSION",
      "status": "ENABLED",
      "metadata": {
        "Card": "4242"
      },
      "createdAt": "2026-06-16T09:07:58.288Z",
      "updatedAt": "2026-06-16T09:07:58.288Z"
    }
  ],
  "createdAt": "2026-06-24T15:10:15.425Z",
  "updatedAt": "2026-06-24T15:10:15.425Z"
}

List Customers

Returns a list of customers for your brand, with optional filtering and sorting.

Update a Customer

Updates fields on an existing customer. Only fields included in the request body will be changed - all other fields remain as they are.

Endpoint: PATCH https://api.superpayments.com/2026-04-01/customers/{id}

The following fields can be updated: firstName, lastName, emailAddress, phoneNumber, metadata.

{
  "emailAddress": "[email protected]",
  "metadata": {
    "yourKey": "updatedValue"
  }
}

🚧

Some fields cannot be changed

externalReference is your unique identifier for the customer and cannot be updated after creation. brandId is also locked once set.