Developer docs v0.1.0

Customers

People you bill.

GET /v1/customers

List customers

Cursor-paginated (limit, starting_after).

Authentication
Merchant API key
Effect
Read-only.

Query parameters

NameTypeRequiredDescription
limitintegernoPage size (1–100). · ≥ 1, ≤ 100, default 20
starting_afterstringnoObject ID; return objects after it (ascending ID order). · 26 chars

Responses

StatusMeaningBody / error codes
200Success.object
400Invalid query parameter.invalid_query_param
401Missing or invalid API key.authentication_error
429Rate limited; honor retry-after.rate_limit_exceeded too_many_auth_failures
500Server error.api_error
Example response
{
  "object": "list",
  "url": "string",
  "has_more": false,
  "data": [
    {
      "object": "customer",
      "id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
      "merchant_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
      "email": "ana@example.com",
      "name": "string",
      "phone": "string",
      "metadata": {},
      "created_at": "2026-10-25T18:00:00.000Z",
      "updated_at": "2026-10-25T18:00:00.000Z"
    }
  ]
}

POST /v1/customers

Create a customer

Remote (NETOPIA Payments) charges later require the full metadata.billing object.

Authentication
Merchant API key
Effect
Creates a customer; emits customer.created.

Headers

NameTypeRequiredDescription
Idempotency-KeystringnoMakes retries safe: same key + body replays the stored response (idempotency-replayed: true); a different body returns 409 idempotency_key_in_use. · ≤ 96 chars

Request body

FieldTypeRequiredDescription
emailstring (email)yes≤ 255 chars
namestringno≤ 255 chars
phonestringno≤ 50 chars
metadataobjectnoFree-form key/value data. Each value ≤16 KiB of JSON, ≤8 nesting levels, ≤100 properties/elements.
Example request
{
  "email": "ana@example.com",
  "name": "string",
  "phone": "string",
  "metadata": {}
}

Responses

StatusMeaningBody / error codes
201Customer created.Customer
400Invalid body.validation_failed invalid_json
401Missing or invalid API key.authentication_error
429Rate limited; honor retry-after.rate_limit_exceeded too_many_auth_failures
500Server error.api_error
Example response
{
  "object": "customer",
  "id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
  "merchant_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
  "email": "ana@example.com",
  "name": "string",
  "phone": "string",
  "metadata": {},
  "created_at": "2026-10-25T18:00:00.000Z",
  "updated_at": "2026-10-25T18:00:00.000Z"
}

GET /v1/customers/:id

Retrieve a customer

Authentication
Merchant API key
Effect
Read-only.

Path parameters

NameTypeRequiredDescription
idstringyesObject ID (ULID). · 26 chars

Responses

StatusMeaningBody / error codes
200Success.Customer
401Missing or invalid API key.authentication_error
404Not found, or not yours.resource_missing
429Rate limited; honor retry-after.rate_limit_exceeded too_many_auth_failures
500Server error.api_error
Example response
{
  "object": "customer",
  "id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
  "merchant_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
  "email": "ana@example.com",
  "name": "string",
  "phone": "string",
  "metadata": {},
  "created_at": "2026-10-25T18:00:00.000Z",
  "updated_at": "2026-10-25T18:00:00.000Z"
}

POST /v1/customers/:id

Update a customer

Partial update.

Authentication
Merchant API key
Effect
Updates the customer; emits customer.updated.

Path parameters

NameTypeRequiredDescription
idstringyesObject ID (ULID). · 26 chars

Headers

NameTypeRequiredDescription
Idempotency-KeystringnoMakes retries safe: same key + body replays the stored response (idempotency-replayed: true); a different body returns 409 idempotency_key_in_use. · ≤ 96 chars

Request body

FieldTypeRequiredDescription
emailstring (email)no≤ 255 chars
namestringno≤ 255 chars
phonestringno≤ 50 chars
metadataobjectnoFree-form key/value data. Each value ≤16 KiB of JSON, ≤8 nesting levels, ≤100 properties/elements.
Example request
{
  "email": "ana@example.com",
  "name": "string",
  "phone": "string",
  "metadata": {}
}

Responses

StatusMeaningBody / error codes
200Success.Customer
400Invalid body or no fields to update.validation_failed invalid_json empty_update
401Missing or invalid API key.authentication_error
404Not found, or not yours.resource_missing
429Rate limited; honor retry-after.rate_limit_exceeded too_many_auth_failures
500Server error.api_error
Example response
{
  "object": "customer",
  "id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
  "merchant_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
  "email": "ana@example.com",
  "name": "string",
  "phone": "string",
  "metadata": {},
  "created_at": "2026-10-25T18:00:00.000Z",
  "updated_at": "2026-10-25T18:00:00.000Z"
}

DELETE /v1/customers/:id

Delete a customer

Soft delete: the customer disappears from the API, its instruments are detached, history is kept.

Authentication
Merchant API key
Effect
Soft-deletes the customer and detaches its instruments; emits customer.deleted.

Path parameters

NameTypeRequiredDescription
idstringyesObject ID (ULID). · 26 chars

Headers

NameTypeRequiredDescription
Idempotency-KeystringnoMakes retries safe: same key + body replays the stored response (idempotency-replayed: true); a different body returns 409 idempotency_key_in_use. · ≤ 96 chars

Responses

StatusMeaningBody / error codes
200Success.DeletedObject
401Missing or invalid API key.authentication_error
404Not found, or not yours.resource_missing
409A subscription is not canceled/incomplete_expired.customer_has_active_subscriptions
429Rate limited; honor retry-after.rate_limit_exceeded too_many_auth_failures
500Server error.api_error
Example response
{
  "object": "string",
  "id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
  "deleted": true
}