CommetCommet
GitHubDiscordStatus
Batch create customers POSTGrant customer credit POSTCreate customer POSTGrant temporary plan access POSTGet customer GETList customer credits GETList customers GETList plan grants GETRevoke remaining customer credit POSTRevoke temporary plan access POSTUpdate customer PATCHUpdate temporary access expiration PATCH
DocumentationKnowledge BaseBuild with AIAPI ReferenceWebhooks

Create customer

Create a new customer. Idempotent when customerId is provided.

POST
/customers

Create a new customer. Idempotent when customerId is provided.

Authorization

ApiKeyAuth
x-api-key<token>

In: header

Header Parameters

Idempotency-Key?string

Unique key used to safely retry this write for 24 hours without applying it twice.

Length1 <= length <= 200

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/customers" \  -H "Content-Type: application/json" \  -d '{    "email": "user@example.com"  }'
{  "id": "cus_1a2b3c4d",  "externalId": null,  "fullName": "user@example.com",  "email": "user@example.com",  "taxDocument": null,  "documentType": null,  "timezone": "UTC",  "metadata": {},  "createdAt": "2026-09-07T12:00:00.000Z",  "updatedAt": "2026-09-07T12:00:00.000Z",  "object": "customer",  "livemode": false}
{  "error": {    "type": "validation_error",    "code": "validation_error",    "message": "The request contains an invalid parameter.",    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md"  }}
{  "error": {    "type": "authentication_error",    "code": "unauthorized",    "message": "A valid API key is required.",    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md"  }}
{  "error": {    "type": "authentication_error",    "code": "forbidden",    "message": "You do not have permission to perform this operation.",    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md"  }}
{  "error": {    "type": "conflict_error",    "code": "idempotency_in_progress",    "message": "A request with this idempotency key is still being processed.",    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md"  }}
{  "error": {    "type": "rate_limit_error",    "code": "rate_limited",    "message": "Too many requests. Retry after the interval specified in the Retry-After header.",    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md"  }}
{  "error": {    "type": "internal_error",    "code": "internal_error",    "message": "An unexpected error occurred while processing the request.",    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md"  }}
{  "error": {    "type": "internal_error",    "code": "idempotency_unavailable",    "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.",    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md"  }}

Grant customer credit POST

Grant monetary credit in one currency. Credit is applied FIFO before tax to eligible recurring invoices.

Grant temporary plan access POST

Temporarily expand an active subscription's feature access using a higher plan in the same plan group. Billing, prices, periods, invoices, and the base subscription remain unchanged.

id?string
Lengthlength <= 100
externalId?string
Lengthlength <= 100
fullName?string
Lengthlength <= 200
taxDocument?string
Lengthlength <= 50
address?
addressId?string
Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
email*string
Match^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
Formatemail
Lengthlength <= 200
timezone?Timezone
Default"UTC"

Value in

  • "UTC"
  • "America/New_York"
  • "America/Chicago"
  • "America/Denver"
  • "America/Los_Angeles"
  • "America/Sao_Paulo"
  • "America/Mexico_City"
  • "America/Buenos_Aires"
  • "America/Santiago"
  • "America/Bogota"
  • "America/Lima"
  • "America/Asuncion"
  • "Europe/London"
  • "Europe/Paris"
  • "Europe/Berlin"
  • "Europe/Madrid"
  • "Asia/Tokyo"
  • "Asia/Shanghai"
  • "Asia/Singapore"
  • "Asia/Dubai"
  • "Australia/Sydney"
metadata?
Default{}