Cresora Commerce Documentation

Payer customers under a merchant. A customer owns the merchant's stored payment methods (the tokenization vault). Partner self-service (`customer:read` / `customer:write`); the merchant is the path scope and the partner is scoped from your API key.

🔬Planned operations — published for review, not callable

This reference includes operations marked x-cresora-status: planned in the canonical contract: they have no route on any host and return 404 (or 501 for reserved discriminator variants) until released. There is no separate preview stream, no feature flag to enable one, and no enrollment — the badge on each operation tells you whether it is served. See the stable /api/v1 reference for what you can call today. Like the stable API, these operations are server-to-server: there is no interactive console here. Download the preview spec (YAML).

List merchant customers

GET/merchants/{merchantId}/customers

Authorization

BearerAuth

AuthorizationBearer <token>

Cresora API key, sent as an opaque bearer token in the Authorization header. Format:

csk_<prefix>_<random>

<prefix> — 8 URL-safe chars, shown in UI and logs for identification without revealing the full key (e.g. csk_Ab3kX9mQ…). Use ApiKey.prefix to match.
<random> — 24+ cryptographically random URL-safe chars.

Obtain via Partner Portal → Settings → API keys. Keys are only shown in full at creation/rotation time — Cresora does not retain the full value in retrievable form. Rotate any key that may have been exposed via logs, client code, or source control.

In: header

Path Parameters

merchantId*string

Formatuuid

Query Parameters

cursor?string

Opaque pagination cursor from previous response. Do not parse.

Lengthlength <= 256

page_size?integer

Items per page (1–100).

Range1 <= value <= 100

Default25

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08/customers"

{  "data": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",      "partner_id": "6a3a39f6-861b-4a48-b868-5de838400e06",      "email": "user@example.com",      "display_name": "string",      "phone": "string",      "gateway_linked": true,      "address": {        "line1": "string",        "line2": "string",        "city": "string",        "state": "string",        "postal_code": "string",        "country": "string"      },      "created_at": "2019-08-24T14:15:22Z",      "version": 0    }  ],  "pagination": {    "next_cursor": "string",    "has_more": true,    "total_count": 0  }}

Create a customer under a merchant

POST/merchants/{merchantId}/customers

Authorization

BearerAuth

AuthorizationBearer <token>

Cresora API key, sent as an opaque bearer token in the Authorization header. Format:

csk_<prefix>_<random>

<prefix> — 8 URL-safe chars, shown in UI and logs for identification without revealing the full key (e.g. csk_Ab3kX9mQ…). Use ApiKey.prefix to match.
<random> — 24+ cryptographically random URL-safe chars.

In: header

Path Parameters

merchantId*string

Formatuuid

Header Parameters

Idempotency-Key*string

Client-generated unique key — a UUIDv4 is the recommended form. Cresora deduplicates within a 24-hour window scoped to the partner.

Format: 1–128 characters of letters, digits, . _ : -. Anything else is rejected with 400 validation_error. The character set is narrower than base64: padded base64 (+ / =) is NOT accepted, base64url is. The key is forwarded verbatim to the payment gateway on transaction creates, so it must satisfy the gateway's key contract too — rejecting locally gives you an actionable error instead of an opaque upstream failure mid-request.

Reserved prefixes — rejected with 400 idempotency_key_reserved:

hpp:, recurring: — Cresora's own server-minted deterministic keys. A client key in these namespaces could collide with a platform-generated record.
rb:, inv-charge:, inv-installment: — reserved by the payment gateway for its internally-minted keys.

Replay semantics:

Same key + same request body → Cresora returns the cached response from the original call. Response includes header X-Idempotent-Replay: true so the client can distinguish replays from fresh executions. Status code, body and side effects are identical to the original call.
Same key + different body → 422 idempotency_key_reused. Generate a new key and retry, or re-send the original body.
Key older than 24 hours → treated as a fresh key; no replay guarantee from beyond the window.

Retrying after an indeterminate failure. On 502 gateway_outcome_unknown the transaction is recorded as pending and the outcome is not yet known — retry with the SAME key (a fresh key risks a double charge) or poll the transaction. This is also what a gateway-side "an earlier request with this key is still in flight" response surfaces as.

Do NOT reuse keys across different partners. Scope is enforced per partner_id so the same key in partner A and partner B is independent.

Match^[A-Za-z0-9._:\-]+$

Length1 <= length <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

email*string

Formatemail

Lengthlength <= 320

display_name?|

Optional. When present it is also the customer's display name at the payment gateway, which bounds it to 2..100 characters and requires it to be unique within the merchant (case-insensitive) — a duplicate is refused with a 422 naming display_name. When omitted, the email is used as the gateway display name instead.

Length2 <= length <= 100

phone?|

Lengthlength <= 32

address?

Optional. A customer with no address on file is a valid state at the payment gateway; supply one when you have it.

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08/customers" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "email": "user@example.com"  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",  "partner_id": "6a3a39f6-861b-4a48-b868-5de838400e06",  "email": "user@example.com",  "display_name": "string",  "phone": "string",  "gateway_linked": true,  "address": {    "line1": "string",    "line2": "string",    "city": "string",    "state": "string",    "postal_code": "string",    "country": "string"  },  "created_at": "2019-08-24T14:15:22Z",  "version": 0}

Get a customer by id

GET/merchants/{merchantId}/customers/{customerId}

Authorization

BearerAuth

AuthorizationBearer <token>

Cresora API key, sent as an opaque bearer token in the Authorization header. Format:

csk_<prefix>_<random>

<prefix> — 8 URL-safe chars, shown in UI and logs for identification without revealing the full key (e.g. csk_Ab3kX9mQ…). Use ApiKey.prefix to match.
<random> — 24+ cryptographically random URL-safe chars.

In: header

Path Parameters

merchantId*string

Formatuuid

customerId*string

Formatuuid

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08/customers/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",  "partner_id": "6a3a39f6-861b-4a48-b868-5de838400e06",  "email": "user@example.com",  "display_name": "string",  "phone": "string",  "gateway_linked": true,  "address": {    "line1": "string",    "line2": "string",    "city": "string",    "state": "string",    "postal_code": "string",    "country": "string"  },  "created_at": "2019-08-24T14:15:22Z",  "version": 0}

Update mutable customer fields

PATCH/merchants/{merchantId}/customers/{customerId}

Authorization

BearerAuth

AuthorizationBearer <token>

Cresora API key, sent as an opaque bearer token in the Authorization header. Format:

csk_<prefix>_<random>

<prefix> — 8 URL-safe chars, shown in UI and logs for identification without revealing the full key (e.g. csk_Ab3kX9mQ…). Use ApiKey.prefix to match.
<random> — 24+ cryptographically random URL-safe chars.

In: header

Path Parameters

merchantId*string

Formatuuid

customerId*string

Formatuuid

Header Parameters

Idempotency-Key*string

Client-generated unique key — a UUIDv4 is the recommended form. Cresora deduplicates within a 24-hour window scoped to the partner.

Reserved prefixes — rejected with 400 idempotency_key_reserved:

hpp:, recurring: — Cresora's own server-minted deterministic keys. A client key in these namespaces could collide with a platform-generated record.
rb:, inv-charge:, inv-installment: — reserved by the payment gateway for its internally-minted keys.

Replay semantics:

Same key + same request body → Cresora returns the cached response from the original call. Response includes header X-Idempotent-Replay: true so the client can distinguish replays from fresh executions. Status code, body and side effects are identical to the original call.
Same key + different body → 422 idempotency_key_reused. Generate a new key and retry, or re-send the original body.
Key older than 24 hours → treated as a fresh key; no replay guarantee from beyond the window.

Do NOT reuse keys across different partners. Scope is enforced per partner_id so the same key in partner A and partner B is independent.

Match^[A-Za-z0-9._:\-]+$

Length1 <= length <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Partial update — omitted/null fields are left unchanged. email is required-when-present (a blank value is rejected); display_name and phone accept "" to clear. A non-blank display_name is bounded 2..100 characters (the gateway's display-name contract).

The address has three spellings: omit address to leave the stored one unchanged, send a complete address to replace it, or send clear_address: true to remove it. address and clear_address are mutually exclusive (400 otherwise).

email?|

Formatemail

Length1 <= length <= 320

display_name?|

Lengthlength <= 100

phone?|

Lengthlength <= 32

address?

Replace the stored address with this complete one. Omit to leave it unchanged.

clear_address?boolean

Remove the stored address (the customer is left with no address on file, which the payment gateway accepts). Mutually exclusive with address.

Defaultfalse

Response Body

`application/json`

`application/problem+json`

curl -X PATCH "https://example.com/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08/customers/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",  "partner_id": "6a3a39f6-861b-4a48-b868-5de838400e06",  "email": "user@example.com",  "display_name": "string",  "phone": "string",  "gateway_linked": true,  "address": {    "line1": "string",    "line2": "string",    "city": "string",    "state": "string",    "postal_code": "string",    "country": "string"  },  "created_at": "2019-08-24T14:15:22Z",  "version": 0}

Soft-delete a customer

DELETE/merchants/{merchantId}/customers/{customerId}

Authorization

BearerAuth

AuthorizationBearer <token>

Cresora API key, sent as an opaque bearer token in the Authorization header. Format:

csk_<prefix>_<random>

<prefix> — 8 URL-safe chars, shown in UI and logs for identification without revealing the full key (e.g. csk_Ab3kX9mQ…). Use ApiKey.prefix to match.
<random> — 24+ cryptographically random URL-safe chars.

In: header

Path Parameters

merchantId*string

Formatuuid

customerId*string

Formatuuid

Response Body

`application/problem+json`

curl -X DELETE "https://example.com/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08/customers/497f6eca-6276-4993-bfeb-53cbbbba6f08"

Empty

Customers

200application/json

401application/problem+json

403application/problem+json

404application/problem+json

429application/problem+json

500application/problem+json

200application/json

201application/json

400application/problem+json

401application/problem+json

403application/problem+json

404application/problem+json

409application/problem+json

422application/problem+json

429application/problem+json

500application/problem+json

502application/problem+json

200application/json

401application/problem+json

403application/problem+json

404application/problem+json

429application/problem+json

500application/problem+json

200application/json

400application/problem+json

401application/problem+json

403application/problem+json

404application/problem+json

409application/problem+json

422application/problem+json

429application/problem+json

500application/problem+json

502application/problem+json

204

401application/problem+json

403application/problem+json

404application/problem+json

429application/problem+json

500application/problem+json

502application/problem+json

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/json`

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`