Skip to main content
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. 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 make a GET call to the /v3/vault/payment-tokens/{payment_method_token} endpoint, 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 make a POST call to the /v1/commerce/billing/customers endpoint 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",
  "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
    }
  ]
}'

​
Request body parameters

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.
metadata[].key
Required when metadata[] provided, string		Metadata key name. Maximum 20 characters.
metadata[].value
Required when metadata[] provided, string		Metadata value. Maximum 100 characters.
metadata[].display_in_invoice
Required when metadata[] provided, boolean		Whether to display this metadata on customer invoices.

​
Response parameters

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
external_id
string		Unique external identifier for the customer.
Use this external_id in future operations, such as when creating subscriptions or offering billing credits.
payment_method_type
string		Type of payment method saved.
Possible values: CARD, PAYPAL, ACH, APPLE_PAY.

​
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.