Docs

Create a customer

Creates a new customer.

POST /customers

Creates a new customer.

If successful, your response includes a copy of the new customer entity.

Requires customer.write permission.

Request body

namestring | null
Full name.
Max length: 1024
emailstring (email)required
Example: test@paddle.com
Email address for this customer.
Length: 1–320
custom_dataobject | null
Example: {"customer_reference_id":"abcd1234"}
Your own structured key-value data.
localestring
Default: en
Valid IETF BCP 47 short form locale tag. If omitted, defaults to en.

Response (201)

dataobjectrequired
Represents a customer entity.
idstringrequired
Example: ctm_01grnn4zta5a1mf02jjze7y2ys
Unique Paddle ID for this customer entity, prefixed with ctm_.
Pattern: ^ctm_[a-z\d]{26}$
namestring | nullrequired
Full name.
Max length: 1024
emailstring (email)required
Example: test@paddle.com
Email address for this customer.
Length: 1–320
marketing_consentbooleanrequired
Default: false
Whether this customer opted into marketing from you. false unless customers check the marketing consent box when using Paddle Checkout. Set automatically by Paddle.
statusstringrequired
Default: active
Whether this entity can be used in Paddle.
Values
  • active
    Entity is active and can be used.
  • archived
    Entity is archived, so can't be used.
custom_dataobject | nullrequired
Example: {"customer_reference_id":"abcd1234"}
Your own structured key-value data.
localestringrequired
Default: en
Valid IETF BCP 47 short form locale tag. If omitted, defaults to en.
created_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
import_metaobject | nullrequired
Import information for this entity. null if this entity is not imported.
external_idstring | null
Example: 9b95b0b8-e10f-441a-862e-1936a6d818ab
Reference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example: paddle_classic
Name of the platform or provider where this entity was imported from.
Length: 1–200
metaobjectrequired
Information about this response.
request_idstringrequired
Example: b15ec92e-8688-40d4-a04d-f44cbec93355
Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
Request
{
  "email": "jo@example.com",
  "name": "Jo Brown"
}
Response
{
  "data": {
    "id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4",
    "status": "active",
    "custom_data": null,
    "name": "Jo Brown",
    "email": "jo@example.com",
    "marketing_consent": false,
    "locale": "en",
    "created_at": "2024-04-11T15:57:24.813Z",
    "updated_at": "2024-04-11T15:57:24.813Z",
    "import_meta": null
  },
  "meta": {
    "request_id": "9bcdcc29-e180-4055-ad3d-d37e5dc5e56d"
  }
}

Was this page helpful?