Customers | OrderCard Documentation

Your customers, with OrderCard's id and your own reference. Group cards and transactions by them.

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 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.

Required ability: payment_methods:write
Rate limit: 300 requests/minute per API key

Body parameters

referencestringoptional: Your own id for this customer, unique within the environment. Max 255 characters.
Example: user_1001
namestringoptional: Max 200 characters.
emailstringoptional: Stored trimmed and in lowercase.
metadataobjectoptional: 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.

Requestbash

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

201The customer.

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

409Another customer already has this reference.

{ "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.

Required ability: payment_methods:read
Rate limit: 300 requests/minute per API key

Query parameters

referencestringoptional: The customer with this reference of yours.
emailstringoptional: Customers with this email, in any case.
limitintegeroptional: 1 to 100, default 25.
cursorstringoptional: The meta.next_cursor of the previous page.

Requestbash

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

200A page of customers.

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

Required ability: payment_methods:read
Rate limit: 300 requests/minute per API key

Path parameters

idstringrequired: The customer's id.
Example: cus_01jaxr9m4q7t0w3y6b9d2f5h8k

Requestbash

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

200The customer.

{
  "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.

Required ability: payment_methods:write
Rate limit: 300 requests/minute per API key

Path parameters

idstringrequired: The customer's id.
Example: cus_01jaxr9m4q7t0w3y6b9d2f5h8k

Body parameters

referencestringoptional: Your own id for this customer, unique within the environment. Max 255 characters.
Example: user_1001
namestringoptional: Max 200 characters.
emailstringoptional: Stored trimmed and in lowercase.
metadataobjectoptional: 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.

Requestbash

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

200The updated customer.

{
  "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.

Required ability: payment_methods:redact
Rate limit: 300 requests/minute per API key

Path parameters

idstringrequired: The customer's id.
Example: cus_01jaxr9m4q7t0w3y6b9d2f5h8k

Caveats

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

Requestbash

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

200Confirmation, with how many cards were redacted.

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