Skip to main content
POST
Create (or get) a customer

Authorizations

X-Suby-Api-Key
string
header
required

Secret API key. sk_live_… (production) or sk_sandbox_… (sandbox).

Headers

Idempotency-Key
string

Optional key (≤255 chars, e.g. a UUID v4) that makes this POST safe to retry: the first request executes and its response is cached for 24h; a retry with the SAME key replays that response instead of re-executing (no duplicate payment/subscription). A reused key with a different request → 422 IDEMPOTENCY_KEY_CONFLICT; a retry while the first is still in flight → 409. See the Idempotency guide.

Maximum string length: 255
Example:

"5f3b9c2e-1a4d-4f2b-9c31-7e2a1b6d8c04"

Body

application/json

Idempotent get-or-create keyed on email (per org + environment) — the same email always resolves to the same customer.

email
string<email>
required

Identity key. Required.

Maximum string length: 320
firstName
string

Optional; forwarded to the PSP on card charges.

Maximum string length: 100
lastName
string
Maximum string length: 100
billingAddress
object

Optional; drives VAT country + pre-fills future charges.

externalRef
string

Your business reference (CRM/customer id). Stored + echoed + filterable via ?externalRef=. Not unique.

Maximum string length: 120
metadata
object

Key-value pairs. ≤50 keys, keys ≤40 chars, values are strings ≤500 chars (or null to clear). Nested structures must be JSON-stringified into a single string value.

Response

Existing customer returned

success
boolean
required
Example:

true

data
object
required

Endpoint-specific payload.

message
string