---
title: "Customers"
description: "Your customers, with OrderCard's id and your own reference. Group cards and transactions by them."
image: "https://docs.ordercard.io/og.png"
---

> API Reference Index
> Fetch the complete API index at: https://docs.ordercard.io/api/llms.txt
> Use this file to discover all available pages before exploring further.

# Customers

A customer is one of the people who pay you. It has two ids: OrderCard's `id` (`cus_…`), which never changes, and your own `reference` (your user or account id), which is unique within the environment. Use whichever is easier to keep.

Cards and transactions point at their customer with `customer` and carry a copy of its `customer_reference`. Only your server links a card to a customer, with a secret key:

- **When you charge.** Send `customer` or `customer_reference` with a purchase, authorization or verification. A card with no customer is linked once the charge succeeds and the card is kept; a card that belongs to someone else is refused with `customer_mismatch`.
- **When you save a card.** Send either field to [retain](/api/payment-methods) a hosted fields token, or with `PATCH /v1/payment_methods/{token}`. Send `null` to unlink.
- **When you tokenize from your server** with `POST /v1/payment_methods`.

A `customer_reference` OrderCard has not seen yet creates the customer, so you never need a separate call first. Hosted fields cannot set either field: anything the browser sends is what the shopper typed, and which wallet a card lands in is your server's decision.

Deleting a customer redacts all of their cards. Their transactions keep the customer's id.

## Create a customer

`POST /v1/customers`

Creates a customer. You rarely need to: a customer_reference OrderCard has not seen yet, sent when you charge or save a card, creates the customer for you.

- **Operation id:** `customers.create`
- **Required ability:** `payment_methods:write`
- **Rate limit:** 300 requests/minute per API key

#### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `reference` | string | no | Your own id for this customer, unique within the environment. Max 255 characters. Example: `user_1001` |
| `name` | string | no | Max 200 characters. |
| `email` | string | no | Stored trimmed and in lowercase. |
| `metadata` | object | no | Up to 50 keys of your own, each with a text value of up to 500 characters. Replaces any metadata the customer had. See Conventions for the rules. |

#### Request

```bash
curl -X POST https://api.ordercard.io/v1/customers \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reference": "user_1001", "name": "Jane Doe", "email": "jane@example.com" }'
```

#### Responses

##### 201 — The customer.

```json
{
  "object": "customer",
  "id": "cus_01jaxr9m4q7t0w3y6b9d2f5h8k",
  "reference": "user_1001",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "metadata": {},
  "environment": "sandbox",
  "created_at": "2026-10-17T15:02:10+00:00",
  "updated_at": "2026-10-17T15:02:10+00:00"
}
```

##### 409 — Another customer already has this reference.

```json
{ "error": { "code": "customer_reference_taken", "message": "Another customer already has this reference.", "param": "reference" } }
```

## List customers

`GET /v1/customers`

Lists the customers of the key's team and environment, newest first, with cursor pagination.

- **Operation id:** `customers.list`
- **Required ability:** `payment_methods:read`
- **Rate limit:** 300 requests/minute per API key

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `reference` | string | no | The customer with this reference of yours. |
| `email` | string | no | Customers with this email, in any case. |
| `limit` | integer | no | 1 to 100, default 25. |
| `cursor` | string | no | The meta.next_cursor of the previous page. |

#### Request

```bash
curl "https://api.ordercard.io/v1/customers?reference=user_1001" \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY"
```

#### Responses

##### 200 — A page of customers.

```json
{ "data": [ {
    "object": "customer",
    "id": "cus_01jaxr9m4q7t0w3y6b9d2f5h8k",
    "reference": "user_1001",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "metadata": {},
    "environment": "sandbox",
    "created_at": "2026-10-17T15:02:10+00:00",
    "updated_at": "2026-10-17T15:02:10+00:00"
  } ], "links": { "...": "..." }, "meta": { "...": "..." } }
```

## Retrieve a customer

`GET /v1/customers/{id}`

Returns one customer. List their cards with GET /v1/payment_methods?customer={id} and their transactions with GET /v1/transactions?customer={id}.

- **Operation id:** `customers.get`
- **Required ability:** `payment_methods:read`
- **Rate limit:** 300 requests/minute per API key

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The customer's id. Example: `cus_01jaxr9m4q7t0w3y6b9d2f5h8k` |

#### Request

```bash
curl https://api.ordercard.io/v1/customers/cus_01jaxr9m4q7t0w3y6b9d2f5h8k \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY"
```

#### Responses

##### 200 — The customer.

```json
{
  "object": "customer",
  "id": "cus_01jaxr9m4q7t0w3y6b9d2f5h8k",
  "reference": "user_1001",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "metadata": {},
  "environment": "sandbox",
  "created_at": "2026-10-17T15:02:10+00:00",
  "updated_at": "2026-10-17T15:02:10+00:00"
}
```

## Update a customer

`PATCH /v1/customers/{id}`

Changes the reference, name, email or metadata. Only the fields you send change. A new reference is copied to the customer's cards; past transactions keep the reference they were made with.

- **Operation id:** `customers.update`
- **Required ability:** `payment_methods:write`
- **Rate limit:** 300 requests/minute per API key

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The customer's id. Example: `cus_01jaxr9m4q7t0w3y6b9d2f5h8k` |

#### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `reference` | string | no | Your own id for this customer, unique within the environment. Max 255 characters. Example: `user_1001` |
| `name` | string | no | Max 200 characters. |
| `email` | string | no | Stored trimmed and in lowercase. |
| `metadata` | object | no | Up to 50 keys of your own, each with a text value of up to 500 characters. Replaces any metadata the customer had. See Conventions for the rules. |

#### Request

```bash
curl -X PATCH https://api.ordercard.io/v1/customers/cus_01jaxr9m4q7t0w3y6b9d2f5h8k \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane.doe@example.com" }'
```

#### Responses

##### 200 — The updated customer.

```json
{
  "object": "customer",
  "id": "cus_01jaxr9m4q7t0w3y6b9d2f5h8k",
  "reference": "user_1001",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "metadata": {},
  "environment": "sandbox",
  "created_at": "2026-10-17T15:02:10+00:00",
  "updated_at": "2026-10-17T15:02:10+00:00"
}
```

## Delete a customer

`DELETE /v1/customers/{id}`

Forgets the customer: every one of their cards is redacted, exactly as DELETE /v1/payment_methods/{token} would, and the customer is removed. Their transactions keep the customer's id.

- **Operation id:** `customers.delete`
- **Required ability:** `payment_methods:redact`
- **Rate limit:** 300 requests/minute per API key

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The customer's id. Example: `cus_01jaxr9m4q7t0w3y6b9d2f5h8k` |

#### Request

```bash
curl -X DELETE https://api.ordercard.io/v1/customers/cus_01jaxr9m4q7t0w3y6b9d2f5h8k \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY"
```

#### Responses

##### 200 — Confirmation, with how many cards were redacted.

```json
{ "object": "customer", "id": "cus_01jaxr9m4q7t0w3y6b9d2f5h8k", "deleted": true, "redacted_payment_methods": 2 }
```

#### Caveats

- This cannot be undone: the redacted cards can never be charged again.

Source: https://docs.ordercard.io/api/customers/index.mdx