Sign in

v51

latestOpenAPI 3.0.0Apache 2.0raw.githubusercontent.com2026-08-011534301009.2 KB
Customers

Create customer

Create a new customer.

post/api/v1/customers

Request body

namestring required

Human-readable name for the resource. Between 1 and 256 characters.

descriptionstring

Optional description of the resource. Maximum 1024 characters.

metadataMetadata

Set of key-value pairs. Metadata can be used to store additional information about a resource.

keystring

An optional unique key of the customer. Either key or usageAttribution.subjectKeys must be provided. Useful to reference the customer in external systems. For example, your database ID.

primaryEmailstring

The primary email address of the customer.

currencystring

Three-letter ISO4217 currency code. Custom three-letter currency codes are also supported for convenience.

Example request

{
  "metadata": {
    "externalId": "019142cc-a016-796a-8113-1a942fecd26d"
  },
  "currency": "USD",
  "billingAddress": {
    "country": "US"
  }
}

Response

The request has succeeded and a new resource has been created as a result.

idstring required

A unique identifier for the resource.

namestring required

Human-readable name for the resource. Between 1 and 256 characters.

descriptionstring

Optional description of the resource. Maximum 1024 characters.

metadataMetadata

Set of key-value pairs. Metadata can be used to store additional information about a resource.

createdAtstring date-time required

Timestamp of when the resource was created.

updatedAtstring date-time required

Timestamp of when the resource was last updated.

deletedAtstring date-time

Timestamp of when the resource was permanently deleted.

keystring

An optional unique key of the customer. Either key or usageAttribution.subjectKeys must be provided. Useful to reference the customer in external systems. For example, your database ID.

primaryEmailstring

The primary email address of the customer.

currencystring

Three-letter ISO4217 currency code. Custom three-letter currency codes are also supported for convenience.

currentSubscriptionIdstring

The ID of the Subscription if the customer has one.

annotationsAnnotations

Set of key-value pairs managed by the system. Cannot be modified by user.

Example response

{
  "id": "01G65Z755AFWAKHE12NY0CQ9FH",
  "name": "ACME Inc.",
  "usageAttribution": {
    "subjectKeys": [
      "my_subject_key"
    ]
  },
  "createdAt": "2024-01-01T01:01:01.001Z",
  "updatedAt": "2024-01-01T01:01:01.001Z"
}