Skip to main content
POST
/
customers
Create a new customer
curl --request POST \
  --url https://api-m.paypal.com/v1/commerce/billing/customers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "John Doe",
  "external_id": "ext_cust_12345",
  "email": "abc@test.com"
}'
{
  "name": "TechStart Solutions",
  "external_id": "5eb02857-a71e-4ea2-bcf9-1753826282",
  "email": "finance@techstart.io",
  "address": {
    "line1": "123 Innovation Way",
    "line2": "Suite 400",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94087",
    "country": "US"
  },
  "phone": "+1 (555) 789-1234",
  "payment_method_token": "6ta69628uw121251c",
  "payment_method_type": "CARD",
  "metadata": [
    {
      "key": "Purchase Order",
      "value": "PO-2023-4521",
      "display_in_invoice": true
    },
    {
      "key": "Sales Region",
      "value": "West Coast",
      "display_in_invoice": false
    }
  ],
  "id": "f772b19c-c5c2-426d-8871-346a6cd094c5"
}

Authorizations

​
Authorization
string
header
required

Use the /v1/oauth2/token endpoint to obtain an access token and pass it as a Bearer token in the Authorization header.

Body

application/json

Request body for creating a new customer.A customer represents an individual or organization that can be billed for services. It includes personal information, contact details, and metadata.

​
name
string
required

Full name of the customer

Required string length: 1 - 512
Example:

"John Doe"

​
external_id
string
required

External identifier for the customer. Must contain only alphanumeric characters, underscores, and hyphens.

Required string length: 1 - 64
Example:

"ext_cust_12345"

​
email
string
required

The internationalized email address.

Required string length: 3 - 254
Example:

"abc@test.com"

​
billing_entity_code
string

Unique code used to identify the billing entity. Must contain only alphanumeric characters, underscores, and hyphens.

Example:

"acme_inc"

​
address
object

Address of the customer or party.

​
phone
string<phone>

Primary phone number of the customer, including country code if available.

Example:

"+1-234-567-8900"

​
payment_method_token
string

Token representing the customer's saved payment method in PayPal Vault.

Required string length: 1 - 36
Example:

"pm_visa_4242"

​
tax_codes
string[]

List of unique codes used to identify taxes to be applied.

Example:
["standard_vat"]
​
metadata
object[]

Response

Customer created successfully.

A customer represents an individual or organization that can be billed for services. It includes personal information, contact details, and metadata.

​
name
string
required

Full name of the customer

Required string length: 1 - 512
Example:

"John Doe"

​
external_id
string
required

External identifier for the customer. Must contain only alphanumeric characters, underscores, and hyphens.

Required string length: 1 - 64
Example:

"ext_cust_12345"

​
email
string
required

The internationalized email address.

Required string length: 3 - 254
Example:

"abc@test.com"

​
billing_entity_code
string

Unique code used to identify the billing entity. Must contain only alphanumeric characters, underscores, and hyphens.

Example:

"acme_inc"

​
address
object

Address of the customer or party.

​
phone
string<phone>

Primary phone number of the customer, including country code if available.

Example:

"+1-234-567-8900"

​
payment_method_token
string

Token representing the customer's saved payment method in PayPal Vault.

Required string length: 1 - 36
Example:

"pm_visa_4242"

​
payment_method_type
enum<string>

Type of payment method used (e.g., CARD, ACH_DEBIT)

Available options:
CARD,
PAYPAL,
ACH_DEBIT,
APPLE_PAY
Example:

"CARD"

​
taxes
object[]

List of tax entities configured for the customer.

​
metadata
object[]
​
id
string
⌘I