GuidesRecipesAPI ReferenceChangelog
Log In
Guides

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

Field
Type
Description
id
string
Super's unique identifier for the customer. Always prefixed with cus_.
externalReference
string
Your own internal identifier for this customer. Must be unique per brand. Required.
brandId
string (uuid)
The Super brand this customer belongs to. Required.
firstName
string
Customer's first name.
lastName
string
Customer's last name.
emailAddress
string
Customer's email address.
phoneNumber
string
Customer's phone number.
metadata
object
Key-value pairs for storing any additional data against this customer.
paymentMethods
array
Saved card tokens linked to this customer. See Payment Method Object.
createdAt
string
ISO 8601 timestamp of when the customer was created.
updatedAt
string
ISO 8601 timestamp of when the customer was last updated.

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 Business Portal under Developers → API Keys, in the Brand payment initiators and IDs section - select Show next to your brand: business.superpayments.com/dashboard/developers/api-keys

Request example:

{
  "externalReference": "your-internal-customer-id",
  "brandId": "YOUR_BRAND_ID",
  "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": "YOUR_BRAND_ID",
  "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.

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

Parameter
Type
Default
Description
brandId
uuid
n/a
Filter by brand.
externalReference
string
n/a
Filter by your internal customer identifier.
emailAddress
string
n/a
Filter by email address.
by
enum
createdAt
Sort by createdAt or updatedAt.
direction
enum
DESC
ASC or DESC.
pageNumber
number ≥ 1
1
Page number to retrieve.
pageSize
number 1–1000
100
Number of results per page.

Response:

{
  "pageInfo": {
    "hasNextPage": true,
    "currentPage": 1,
    "lastPage": 4,
    "pageSize": 100
  },
  "totalCount": 312,
  "items": [
    {
      "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": "2026-03-15T10:00:00.000Z",
      "updatedAt": "2026-03-15T10:00:00.000Z"
    }
  ]
}
📘

Paging through results

Use pageInfo.hasNextPage to decide whether to request another page, and pageInfo.lastPage for the total number of pages. totalCount is the number of customers matching your filters, not the number returned in items. See Pagination for both paging styles used across the API.

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"
  }
}

Response:

{
  "id": "cus_0123456789",
  "externalReference": "your-internal-customer-id",
  "brandId": "YOUR_BRAND_ID",
  "firstName": "John",
  "lastName": "Smith",
  "emailAddress": "[email protected]",
  "phoneNumber": "07462123456",
  "metadata": {
    "yourKey": "updatedValue"
  },
  "paymentMethods": [],
  "createdAt": "2026-03-15T10:00:00.000Z",
  "updatedAt": "2026-03-15T11:30:00.000Z"
}
🚧

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.

Updated 3 days ago

Did this page help you?