Skip to main content
A customer is someone who uses your product or service and pays you for it. This can be a person or a business. When customers sign up, add them to your PayPal business account. This helps you:
  • Set up their subscription
  • Charge them based on their usage
  • Manage their payments automatically
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 send a GET request to /v1/commerce/billing/customers/{external_id}. On successful retrieval, PayPal returns customer information including their latest payment_method_token. If no payment method is saved, the response does not contain payment_method_token. 
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>'

​
Response parameter

Parameter nameDescription and further action
payment_method_token
string		Payment method token identifier.
Use this value to get payment method details for customer confirmation.
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 send a GET request to /v3/vault/payment-tokens/{payment_method_token}, with the payment_method_token retrieved in the previous step. On successful retrieval, the PayPal server returns a vault customer ID and the saved payment method details. 
curl -X GET 'https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/6ta69628uw121251c' \
-H 'Authorization: Bearer <ACCESS-TOKEN>'
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 send a POST request to /v1/commerce/billing/customers with all required request parameters. On successful customer creation, PayPal returns the customer ID you entered in external_id. 
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",
  "email": "finance@techstart.io",
  "external_id": "5eb02857-a71e-4ea2-bcf9-1753828835",
  "billing_entity_code": "US_ENTITY",
  "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": "91e302870k7094302",
  "metadata": [
    {
      "key": "Purchase Order",
      "value": "PO-2023-4521",
      "display_in_invoice": true
    },
    {
      "key": "Sales Region",
      "value": "West Coast",
      "display_in_invoice": false
    }
  ]
}'

​
Request body parameters

Note: This section documents only a subset of relevant request parameters. For the exhaustive list of request parameters, see API reference.
Parameter nameDescription
external_id
Required, string		External identifier for the customer. Must contain only alphanumeric characters, underscores, and hyphens. Maximum 64 characters.
name
Required, string		Full name of the customer or business name. Maximum 512 characters.
email
Required, string		Customer’s email address.
address
object		Customer’s billing address with fields: line1, line2, city, state, postal_code, country.
phone
string		Primary phone number of the customer, including country code if available.
payment_method_token
string		Token representing the customer’s saved payment method in PayPal Vault. Obtain this token either by creating a new payment method token or retrieving an existing one.
billing_entity_code
string		Code identifying the billing entity associated with this customer.
tax_codes
array		List of unique codes used to identify taxes to be applied to this customer. Example: ["standard_vat"].
metadata
array		Array of custom key-value metadata objects for storing extra customer attributes. Each object has key, value, and display_in_invoice properties.

​
Response parameters

Note: This section documents only the response parameters relevant for the next step. For the exhaustive list of response parameters, see API reference.
Parameter nameDescription and further action
id
string		PayPal’s unique identifier for the customer.
external_id
string		Your unique identifier for the customer.
Use this to reference the customer, such as while creating a subscription.
payment_method_type
string		Type of payment method saved (for example, CARD, PAYPAL, ACH).

​
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 metadataUpdates customer information while preserving all active subscriptions and billing
Change payment method: Create new payment method token and update customer recordSwitches payment method for future billing while maintaining active subscriptions
Delete customer: Remove customer data from your billing systemPermanently removes customer and terminates all subscriptions, billing, and wallets
⌘I