Skip to main content
Limited Release
A customer is someone who uses your product or service and pays you for it. When customers sign up, add them to your PayPal business account. Customers connect the following:
  • Subscriptions that link customers to pricing plans.
  • Billing entities for regional billing configurations.
  • Payment methods that enable automatic billing based on usage.
To add customers:
  1. Save their payment method: Verify whether the customer’s payment method is saved with PayPal.
    • If they already have a saved payment method, retrieve their latest payment method and display it to them for confirmation.
      • If the customer doesn’t modify the displayed payment method, use those details to register the customer profile.
      • If the customer creates a new payment method instead, save it as their new payment method and then use it to register the customer profile.
    • If they don’t have a saved payment method, ask the customer to provide their payment method details and save it as a new payment method.
  2. Register customer profile: Use the saved payment method and create a customer profile.

​
Prerequisite

Before you register customers, ensure you have the customer’s payment information (to save) or external customer ID (to retrieve a saved payment method).

​
1. Save payment method and get Payment Method Token (PMT)

A Payment Method Token (PMT) is a secure reference to a customer’s payment information that is stored in PayPal’s PCI-compliant vault. Instead of storing sensitive payment details directly in your system, you save them with PayPal, create a PMT, and use the PMT for transactions.

​
Verify if customer has saved a payment method

If you have the customer’s external ID, use a valid access token and make a GET call to the /v1/commerce/billing/customers/{external_customer_id} endpoint. Path parameter: external_customer_id is the external_id you provided when you registered the customer. 
curl -X GET 'https://api-m.sandbox.paypal.com/v1/commerce/billing/customers/5eb02857-a71e-4ea2-bcf9-1753826282' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS-TOKEN>'
A successful call returns a 200 OK response with customer information. If the customer has a saved payment method, the response includes payment_method_token. The response includes the following parameter:
ParameterDescriptionFurther action
payment_method_token
string		Payment method token identifier.Use this payment_method_token to get payment method details for customer confirmation.
For information on all parameters, see API reference. If this is a new customer and you do not have their external ID or if they have not saved their payment method, collect their payment information and save the new payment method with their consent.

​
Get saved payment method details for customer confirmation

If the customer has saved a payment method, use a valid access token and make a GET call to the /v3/vault/payment-tokens/{payment_method_token} endpoint. Path parameter: payment_method_token is the token retrieved when you verified the customer’s saved payment method. 
curl -X GET 'https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/6ta69628uw121251c' \
-H 'Authorization: Bearer <ACCESS-TOKEN>'
On successful retrieval, the PayPal server returns a vault customer ID and the saved payment method details. Display the payment method details to the customer and ask them to confirm or modify their payment method:

​
Save a new payment method

For new customers or existing customers without saved payment methods, collect their payment information and ask for consent to save it for billing. After they agree, save the payment method and create the PMT. Supported payment methods:

​
2. Register customer profile

After you get a payment method token (either newly created or retrieved from existing saved payment methods), register the customer profile in your PayPal billing system. Use a valid access token and make a POST call to the /v1/commerce/billing/customers endpoint. Include the following parameters:
ParameterAction
external_id
Required, string		Set a unique identifier for the customer. Use only alphanumeric characters, underscores, and hyphens (maximum 64 characters).
name
Required, string		Provide the customer’s full name or business name (maximum 512 characters).
email
Required, string		Provide the customer’s email address.
address
object		Provide the customer’s billing address with fields: line1, line2, city, state, postal_code, country.
phone
string		Provide the customer’s primary phone number, including country code if available.
payment_method_token
string		Set to the token returned when you created a new payment method or retrieved an existing one.
billing_entity_code
string		Set to the code returned when you created the billing entity.
tax_codes
array		Provide an array of tax codes to apply to this customer (for example, ["standard_vat"]).
metadata[]
array		Add custom key-value metadata objects for storing extra customer attributes.
metadata[].key
Required when metadata[] provided, string		Set the metadata key name (maximum 20 characters).
metadata[].value
Required when metadata[] provided, string		Set the metadata value (maximum 100 characters).
metadata[].display_in_invoice
Required when metadata[] provided, boolean		Set to true to display this metadata on customer invoices or false to hide it.
For information on all parameters, see API reference. 
curl -X POST 'https://api-m.sandbox.paypal.com/v1/commerce/billing/customers' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS-TOKEN>' \
-d '{
  "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",
  "billing_entity_code": "acme_inc",
  "tax_codes": [
    "standard_vat"
  ],
  "metadata": [
    {
      "key": "Purchase Order",
      "value": "PO-2023-4521",
      "display_in_invoice": true
    },
    {
      "key": "Sales Region",
      "value": "West Coast",
      "display_in_invoice": false
    }
  ]
}'
A successful call returns a 201 Created response. The response includes the following parameter:
ParameterDescriptionFurther action
external_id
string		Unique external identifier for the customer.Use this external_id when creating subscriptions or offering billing credits.
For information on all parameters, see API reference.

​
3. Understand customer lifecycle and manage customers

After you register customers, you can perform various management actions throughout their relationship with your business.
Possible management actionsImpact
Update customer details: Modify name, email, address, phone, and metadata.Updates customer information while preserving all active subscriptions and billing.
Change payment method: Create new payment method token and update customer record.Switches payment method for future billing while maintaining active subscriptions.
Delete customer: Remove customer data from your billing system.Permanently removes customer and terminates all subscriptions, billing, and wallets.