Endpoint

Create a customer

POST/v1/customers

Creates a customer and returns the customer object. Send an Idempotency-Key: a retry with the same key and body gets the first answer again, so it never creates a second customer.

Scope a restricted key needs: customers:write
Publishable key: Not allowed: secret or restricted key only
Idempotency-Key: Recommended. It makes a retry safe.

Parameters

Parameters of Create a customer
Parameter	Type and place	Meaning
`Orrerie-Version`	stringheader	API version date. Default: the version the key was created with. Example `2026-10-11`.
`Idempotency-Key`	stringheader	Makes a retry safe. Kept 24 hours. 1 to 255 characters.

Request body

A JSON object. The body may be left out. A field the call does not list is refused with parameter_unknown.

Request body of Create a customer
Field	Type	Meaning
`name`	string	Up to 200 characters.
`email`	string	Needed for invoices, subscriptions and receipts.
`description`	string	Your own note about the customer.
`billing_address`	object	`{line1, line2, city, region, postal_code, country}`; country is ISO 3166-1 alpha-2.
`locale`	string	`en`.
`metadata`	object	Your own key-value data (rules in Metadata).

Example request

curl

curl https://api.orrerie.com/v1/customers \
  -H "Authorization: Bearer $ORRERIE_SECRET_KEY" \
  -H "Idempotency-Key: 8f14e45f-ceea-467f-a9d2-6f1c2b3d4e5a" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "description": "Wholesale buyer",
  "metadata": {
    "crm_id": "88213"
  }
}'

JavaScript

const response = await fetch("https://api.orrerie.com/v1/customers", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ORRERIE_SECRET_KEY}`,
    "Idempotency-Key": "8f14e45f-ceea-467f-a9d2-6f1c2b3d4e5a",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Jane Doe",
    "email": "jane@example.com",
    "description": "Wholesale buyer",
    "metadata": {
      "crm_id": "88213"
    }
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result);

Python

import os
import requests

response = requests.post(
    "https://api.orrerie.com/v1/customers",
    headers={"Authorization": f"Bearer {os.environ['ORRERIE_SECRET_KEY']}", "Idempotency-Key": "8f14e45f-ceea-467f-a9d2-6f1c2b3d4e5a"},
    json={
        "name": "Jane Doe",
        "email": "jane@example.com",
        "description": "Wholesale buyer",
        "metadata": {
            "crm_id": "88213",
        },
    },
    timeout=30,
)
result = response.json()
if not response.ok:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
print(result)

PHP

<?php
$request = curl_init('https://api.orrerie.com/v1/customers');
curl_setopt_array($request, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('ORRERIE_SECRET_KEY'),
        'Idempotency-Key: 8f14e45f-ceea-467f-a9d2-6f1c2b3d4e5a',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'name' => 'Jane Doe',
        'email' => 'jane@example.com',
        'description' => 'Wholesale buyer',
        'metadata' => [
            'crm_id' => '88213',
        ],
    ]),
]);
$body = curl_exec($request);
if ($body === false) {
    throw new RuntimeException(curl_error($request));
}
$result = json_decode($body, true);
if (curl_getinfo($request, CURLINFO_HTTP_CODE) >= 400) {
    throw new RuntimeException($result['error']['code'] . ': ' . $result['error']['message']);
}
print_r($result);

Responses

`201` Created

The answer is the customer object. Headers: Orrerie-Request-Id.

Example response, 201

{
  "id": "cus_8ea07c40qsvv19f7rgmeb8ha",
  "object": "customer",
  "livemode": true,
  "created": "2026-10-01T08:00:00.000Z",
  "updated": "2026-10-01T08:00:00.000Z",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "description": "Wholesale buyer",
  "billing_address": null,
  "refund_addresses": [],
  "credit_balance": {
    "amount": "0.00",
    "currency": "USD"
  },
  "locale": "en",
  "metadata": {
    "crm_id": "88213"
  }
}

Any other status: an error

A status of 400 or above answers with the error object. Branch on its code, never on its message.

Errors

This call has no error of its own. It answers with the errors every call can answer with: a bad key, a missing scope, an object that does not exist, the rate limit. Every error code has its own entry.