Docs

Create a business for a customer

Creates a new business for a customer.

POST /customers/{customer_id}/businesses

Creates a new business for a customer.

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

Requires business.write permission.

Path parameters

customer_idstringrequired
Example: ctm_01grnn4zta5a1mf02jjze7y2ys
Unique Paddle ID for this customer entity, prefixed with ctm_.
Pattern: ^ctm_[a-z\d]{26}$

Request body

namestringrequired
Name of this business.
Length: 1–1024
company_numberstring | null
Example: 123456789
Company number for this business.
Max length: 1024
tax_identifierstring | null
Example: AB0123456789
Tax or VAT Number for this business.
Max length: 1024
contactsarray | null
List of contacts related to this business, typically used for sending invoices.
Items: max 100, unique
namestring
Full name of this contact.
Max length: 1024
emailstring (email)required
Example: test@paddle.com
Email address for this contact.
Length: 1–320
custom_dataobject | null
Example: {"customer_reference_id":"abcd1234"}
Your own structured key-value data.

Response (201)

dataobjectrequired
Represents a business entity.
idstringrequired
Example: biz_01grrebrzaee2qj2fqqhmcyzaj
Unique Paddle ID for this business entity, prefixed with biz_.
Pattern: ^biz_[a-z\d]{26}$
customer_idstringrequired
Example: ctm_01grnn4zta5a1mf02jjze7y2ys
Paddle ID for the customer related to this business, prefixed with cus_.
Pattern: ^ctm_[a-z\d]{26}$
namestringrequired
Name of this business.
Length: 1–1024
company_numberstring | nullrequired
Example: 123456789
Company number for this business.
Max length: 1024
tax_identifierstring | nullrequired
Example: AB0123456789
Tax or VAT Number for this business.
Max length: 1024
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.
contactsarrayrequired
List of contacts related to this business, typically used for sending invoices.
Items: max 100, unique
namestringrequired
Full name of this contact.
Max length: 1024
emailstring (email)required
Example: test@paddle.com
Email address for this contact.
Length: 1–320
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.
custom_dataobject | nullrequired
Example: {"customer_reference_id":"abcd1234"}
Your own structured key-value data.
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
{
  "name": "Uplift Inc.",
  "company_number": "555775291485",
  "tax_identifier": "555952383",
  "contacts": [
    {
      "name": "Parker Jones",
      "email": "parker@example.com"
    }
  ]
}
Response
{
  "data": {
    "id": "biz_01hv8hkr641vmpwytx38znv56k",
    "status": "active",
    "customer_id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4",
    "name": "Uplift Inc.",
    "company_number": "555775291485",
    "tax_identifier": "555952383",
    "contacts": [
      {
        "name": "Parker Jones",
        "email": "parker@example.com"
      }
    ],
    "custom_data": null,
    "created_at": "2024-04-12T06:58:37.892Z",
    "updated_at": "2024-04-12T06:58:37.892Z",
    "import_meta": null
  },
  "meta": {
    "request_id": "e925073f-12cd-4871-825d-2c43632edbc0"
  }
}

Was this page helpful?