Register customers - Paypal Docs

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:

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

{
    "name": "TechStart Solutions",
    "external_id": "5eb02857-a71e-4ea2-bcf9-1753828835",
    "email": "finance@techstart.io",
    "address": {
        "line1": "123 Innovation Way",
        "line2": "Suite 400",
        "city": "San Francisco",
        "state": "CA",
        "country": "US"
    },
    "phone": "+1 (555) 789-1234",
    "payment_method_token": "6ta69628uw121251c",
    "payment_method_type": "CARD",
    "id": "f772b19c-c5c2-426d-8871-346a6cd094c5"
}

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:

Parameter	Description	Further 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>'

{
    "id": "6ta69628uw121251c",
    "customer": {
        "id": "BdasCNhdlz"
    },
    "payment_source": {
        "card": {
            "name": "Some Name",
            "last_digits": "9855",
            "brand": "VISA",
            "expiry": "2026-05",
            "billing_address": {
                "address_line_1": "2211 N First Street",
                "address_line_2": "17.3.160",
                "admin_area_2": "San Jose",
                "admin_area_1": "CA",
                "postal_code": "95131",
                "country_code": "US",
                "id": "4v"
            }
        }
    }
}

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:

If the customer confirms the existing payment method: Use the existing payment_method_token to register their customer profile.
If the customer wants to add a new payment method: Save a new 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:

PayPal wallet: For information on how to save a PayPal wallet and get the PMT, see Create payment token - PayPal.
Cards (debit and credit cards): For information on how to save Cards and get the PMT, see Create payment token - Cards.
Apple Pay: For information on how to save Apple Pay and get the PMT, see Create payment token - Apple Pay.
Bank accounts (ACH debit): For information on how to save bank account information and get the PMT, see Create payment token - ACH.

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:

Parameter	Action
`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
    }
  ]
}'

{
    "name": "TechStart Solutions",
    "external_id": "5eb02857-a71e-4ea2-bcf9-1753826282",
    "email": "finance@techstart.io",
    "billing_entity_code": "acme_inc",
    "address": {
        "line1": "123 Innovation Way",
        "line2": "Suite 400",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94087",
        "country": "US"
    },
    "taxes": [
        {
            "id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
            "name": "TVA",
            "code": "standard_vat",
            "description": "French standard VAT",
            "rate": "20.00",
            "created_at": "2023-07-06T14:35:58Z"
        }
    ],
    "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"
}

A successful call returns a 201 Created response. The response includes the following parameter:

Parameter	Description	Further 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 actions	Impact
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.

​Prerequisite

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

​Verify if customer has saved a payment method

​Get saved payment method details for customer confirmation

​Save a new payment method

​2. Register customer profile

​3. Understand customer lifecycle and manage customers