Customers

#The customer object

spent adds up the amount of each of their payments that's paid, in its currency: what they paid, including a part-payment on an order that's held, and both payments when they paid one order twice. paid_orders_count counts only orders that are paid. What reached your wallet is on each payment.

{
  "id": "cus_Hc7nQ2wVz9KpT4mRb1Ye",
  "object": "customer",
  "livemode": true,
  "email": "maya@example.com",
  "name": "Maya Okafor",
  "phone": "+1 503 555 0142",
  "shipping_address": {
    "name": "Maya Okafor",
    "line1": "418 Linden Avenue",
    "line2": "Apt 3B",
    "city": "Portland",
    "region": "OR",
    "postal_code": "97214",
    "country": "US"
  },
  "billing_address": null,
  "store_accounts": [],
  "orders_count": 3,
  "paid_orders_count": 2,
  "spent": { "USD": "224.31" },
  "created": 1787702525,
  "last_order_at": 1790380525,
  "erased": false
}

#How customers are made

• One customer per email address, in each mode. Case doesn't matter: Maya@Example.com and maya@example.com are one customer. Test and Live customers are separate.
• The email comes from the session. A session's customer_email (or customer.email) makes or finds the customer when it's created; a session created without one gets its customer from the email given when it starts. Railbed's checkouts and payment links use the email the buyer enters, or the one you set on the link.
• The latest details win. Each order's customer.name, customer.phone and addresses replace the saved ones. Details an order leaves out keep their earlier value.
• Details wait for the email. A session created without an email keeps its name, phone and addresses on the order, and saves them to the customer once the buyer gives their email and starts paying.
• Orders follow the email. When a session starts with a different email from the one it was created with, its order moves to the customer with the new email.

The API doesn't create, edit or delete customers: they change only through orders. The dashboard lets you keep a private note on each customer, which is never returned by the API or sent in webhooks.

#Deleted customers

When a buyer asks you to delete their data, open the customer in the dashboard's Customers and choose Delete customer data. It removes their name, email, phone and addresses from the customer, from their orders and payments, and from the bodies stored in your webhook delivery log. Their orders, amounts and payments stay for your records. It can't be undone.

• The customer keeps its id, with erased: true and its contact details and addresses null. Their orders keep customer_id, and their payments' customer_email becomes null.
• Their email is no longer on file, so listing by email doesn't find them, and the same email later starts a new customer.
• Webhooks already delivered can't be recalled. Delete the details from your own systems too.

#Retrieve a customer

GET/v1/customers/:id

Returns a customer of yours in the key's mode. Another account's customer, or one in the other mode, is 404 not_found.

curl https://pay.railbed.io/v1/customers/cus_Hc7nQ2wVz9KpT4mRb1Ye \
  -H "Authorization: Bearer $RAILBED_SECRET_KEY"

const customer = await fetch(`https://pay.railbed.io/v1/customers/${id}`, {
  headers: { Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}` },
}).then((r) => r.json());

customer = requests.get(
    f"https://pay.railbed.io/v1/customers/{id}",
    headers={"Authorization": f"Bearer {os.environ['RAILBED_SECRET_KEY']}"},
    timeout=15,
).json()

<?php
$ch = curl_init('https://pay.railbed.io/v1/customers/' . rawurlencode($id));
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('RAILBED_SECRET_KEY'),
  ],
]);
$customer = json_decode(curl_exec($ch), true);

The response is the customer object. An order's customer_id leads here; for their orders, list orders with customer_id.

#List customers

GET/v1/customers

Returns your customers in the key's mode, newest first by created. Pass email to find one buyer.

curl -G https://pay.railbed.io/v1/customers \
  --data-urlencode "email=maya@example.com" \
  -H "Authorization: Bearer $RAILBED_SECRET_KEY"

const url = new URL('https://pay.railbed.io/v1/customers');
url.searchParams.set('email', 'maya@example.com');
const page = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}` },
}).then((r) => r.json());
const customer = page.data[0] ?? null;

page = requests.get(
    "https://pay.railbed.io/v1/customers",
    headers={"Authorization": f"Bearer {os.environ['RAILBED_SECRET_KEY']}"},
    params={"email": "maya@example.com"},
    timeout=15,
).json()
customer = page["data"][0] if page["data"] else None

<?php
$query = http_build_query(['email' => 'maya@example.com']);
$ch = curl_init('https://pay.railbed.io/v1/customers?' . $query);
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('RAILBED_SECRET_KEY'),
  ],
]);
$page = json_decode(curl_exec($ch), true);
$customer = $page['data'][0] ?? null;

{
  "data": [
    {
      "id": "cus_Hc7nQ2wVz9KpT4mRb1Ye",
      "object": "customer",
      "email": "maya@example.com",
      "name": "Maya Okafor",
      "paid_orders_count": 2
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Each item is a full customer object (trimmed here). With email, the list has at most one customer; an empty data means no customer has that email in this mode. Page through the whole list with next_cursor as on List payments. An invalid limit is 400 invalid_limit; a cursor that isn't one of your customers in this mode is 400 invalid_cursor.