> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Register customers

<div className="m-badge-page-wrapper">
  <Badge stroke color="orange" size="sm">Limited Release</Badge>
</div>

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:

* <a href="/limited-release/usage-based-billing/set-up-billing-process/create-subscriptions" target="_blank" rel="noopener noreferrer">Subscriptions</a> that link customers to pricing plans.
* <a href="/limited-release/usage-based-billing/set-up-billing-process/create-billing-entities" target="_blank" rel="noopener noreferrer">Billing entities</a> 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](#get-saved-payment-method-details-for-customer-confirmation) 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](#save-a-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](#save-a-new-payment-method).
2. **Register customer profile**: Use the saved payment method and [create a customer profile](#2-register-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 <a href="/developer/how-to/api/get-started#2-get-an-access-token" target="_blank" rel="noopener noreferrer">valid access token</a> 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](#2-register-customer-profile).

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  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>'
  ```

  ```json lines title="Sample response" theme={null}
  {
      "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"
  }
  ```
</CodeGroup>

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:

| <span style={{textAlign: 'left', display: 'block'}}>Parameter</span>                            | <span style={{textAlign: 'left', display: 'block'}}>Description</span> | <span style={{textAlign: 'left', display: 'block'}}>Further action</span>                                                                               |
| ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment_method_token`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span> | Payment method token identifier.                                       | Use this `payment_method_token` to [get payment method details](#get-saved-payment-method-details-for-customer-confirmation) for customer confirmation. |

For information on all parameters, see <a href="/reference/api/rest/customers/get-a-customer-by-id" target="_blank" rel="noopener noreferrer">API reference</a>.

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](#save-a-new-payment-method) with their consent.

### Get saved payment method details for customer confirmation

If the customer has saved a payment method, use a <a href="/developer/how-to/api/get-started#2-get-an-access-token" target="_blank" rel="noopener noreferrer">valid access token</a> 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](#verify-if-customer-has-saved-a-payment-method).

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  curl -X GET 'https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/6ta69628uw121251c' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>'
  ```

  ```json lines title="Sample response" theme={null}
  {
      "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"
              }
          }
      }
  }
  ```
</CodeGroup>

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](#2-register-customer-profile).
* **If the customer wants to add a new payment method**: [Save 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 <a href="https://developer.paypal.com/docs/checkout/save-payment-methods/purchase-later/js-sdk/paypal/" target="_blank" rel="noopener noreferrer">Create payment token - PayPal</a>.
* **Cards** (debit and credit cards): For information on how to save Cards and get the PMT, see <a href="https://developer.paypal.com/docs/checkout/save-payment-methods/purchase-later/js-sdk/cards/" target="_blank" rel="noopener noreferrer">Create payment token - Cards</a>.
* **Apple Pay**: For information on how to save Apple Pay and get the PMT, see <a href="/limited-release/save-payment-method-purchase-later/save-apple-pay" target="_blank" rel="noopener noreferrer">Create payment token - Apple Pay</a>.
* **Bank accounts** (ACH debit): For information on how to save bank account information and get the PMT, see <a href="/limited-release/save-payment-method-purchase-later/save-ach" target="_blank" rel="noopener noreferrer">Create payment token - ACH</a>.

## 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 <a href="/developer/how-to/api/get-started#2-get-an-access-token" target="_blank" rel="noopener noreferrer">valid access token</a> and make a POST call to the `/v1/commerce/billing/customers` endpoint. Include the following parameters:

| <span style={{textAlign: 'left', display: 'block'}}>Parameter</span>                                                                                                                                   | <span style={{textAlign: 'left', display: 'block'}}>Action</span>                                                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `external_id`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                              | Set a unique identifier for the customer. Use only alphanumeric characters, underscores, and hyphens (maximum 64 characters).                                                                               |
| `name`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                     | Provide the customer's full name or business name (maximum 512 characters).                                                                                                                                 |
| `email`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                    | Provide the customer's email address.                                                                                                                                                                       |
| `address`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>object</span>                                                                                                                     | Provide the customer's billing address with fields: `line1`, `line2`, `city`, `state`, `postal_code`, `country`.                                                                                            |
| `phone`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                                                                       | Provide the customer's primary phone number, including country code if available.                                                                                                                           |
| `payment_method_token`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                                                        | Set to the token returned when you [created a new payment method](#save-a-new-payment-method) or [retrieved an existing one](#get-saved-payment-method-details-for-customer-confirmation).                  |
| `billing_entity_code`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                                                         | Set to the `code` returned when you <a href="/limited-release/usage-based-billing/set-up-billing-process/create-billing-entities" target="_blank" rel="noopener noreferrer">created the billing entity</a>. |
| `tax_codes`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>array</span>                                                                                                                    | Provide an array of tax codes to apply to this customer (for example, `["standard_vat"]`).                                                                                                                  |
| `metadata[]`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>array</span>                                                                                                                   | Add custom key-value metadata objects for storing extra customer attributes.                                                                                                                                |
| `metadata[].key`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required when metadata\[] provided</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                 | Set the metadata key name (maximum 20 characters).                                                                                                                                                          |
| `metadata[].value`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required when metadata\[] provided</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>               | Set the metadata value (maximum 100 characters).                                                                                                                                                            |
| `metadata[].display_in_invoice`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required when metadata\[] provided</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>boolean</span> | Set to `true` to display this metadata on customer invoices or `false` to hide it.                                                                                                                          |

For information on all parameters, see <a href="/reference/api/rest/customers/create-a-new-customer" target="_blank" rel="noopener noreferrer">API reference</a>.

<CodeGroup>
  ```shell lines expandable title="Sample request" theme={null}
  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
      }
    ]
  }'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
      "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"
  }
  ```
</CodeGroup>

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

| <span style={{textAlign: 'left', display: 'block'}}>Parameter</span>                   | <span style={{textAlign: 'left', display: 'block'}}>Description</span> | <span style={{textAlign: 'left', display: 'block'}}>Further action</span>                                                                                                                                                                                                                                                                                          |
| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `external_id`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span> | Unique external identifier for the customer.                           | Use this `external_id` when <a href="/limited-release/usage-based-billing/set-up-billing-process/create-subscriptions" target="_blank" rel="noopener noreferrer">creating subscriptions</a> or <a href="/limited-release/usage-based-billing/set-up-billing-process/offer-billing-credits" target="_blank" rel="noopener noreferrer">offering billing credits</a>. |

For information on all parameters, see <a href="/reference/api/rest/customers/create-a-new-customer" target="_blank" rel="noopener noreferrer">API reference</a>.

## 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                                                                               |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| <a href="/limited-release/usage-based-billing/manage-entities/manage-customers#update-customer-details" target="_blank" rel="noopener noreferrer">Update customer details</a>: Modify name, email, address, phone, and metadata.       | Updates customer information while preserving all active subscriptions and billing.  |
| <a href="/limited-release/usage-based-billing/manage-entities/manage-customers#change-payment-method" target="_blank" rel="noopener noreferrer">Change payment method</a>: Create new payment method token and update customer record. | Switches payment method for future billing while maintaining active subscriptions.   |
| <a href="/limited-release/usage-based-billing/manage-entities/manage-customers#delete-customer-information" target="_blank" rel="noopener noreferrer">Delete customer</a>: Remove customer data from your billing system.              | Permanently removes customer and terminates all subscriptions, billing, and wallets. |