# Customers

The customer resource is the main resource for most integrations. A customer may be a person or an organization and each customer has a unique ID.

A customer is an entity that purchases goods or services from a merchant, and is the payee in any transaction that is credited to the merchant. Customers are associated with payment instruments, subscriptions, invoices, and other miscellaneous related models. To extend the customer resource to incorporate additional data, see [Extend resources](/docs/dev-docs/concepts#extend-resources).

A customer may have a default payment instrument. The default payment instrument is used to automatically pay subscription renewals, and for transaction requests where a specific payment instrument is not provided.

## Lead source attribution

A customer may be associated with a lead sources object. A lead source is the marketing campaign that generates customer interaction, a sale, or a trial. This metadata is added to the customer's information, and contains common attributes from Google Analytics and affiliate tracking applications. For more information, see [Lead sources](/docs/dev-docs/lead-source-attribution).

## Tags and filters

Use tags to organize and categorize customers for reporting and automation tasks. For more information, see [Tags](/docs/dev-docs/api/tags/).

Use filters to organize and categorize customer collections by recency, frequency, and monetary value for traditional marketing segmentation. For more information, see [Search filters](/docs/dev-docs/search-filters).

## Lifecycle

The customer resource does not have its own lifecycle status. Rebilly records the following:

- Recency — the last paid transaction.
- Frequency — the number of transactions.
- Total lifetime revenue for each customer.


## Usage

The customer resource is referenced from other resources. For example, one customer is associated with multiple transactions, orders, invoices and so on. Each customer has a unique ID (`id`) value. This ID is referenced in other related resources as `customerId`.

## Merge duplicate customers

To merge duplicate customer entries, select from the following options:

- [Use the Rebilly UI](/docs/data-tables/manage-customer-information#merge-duplicate-customer-entries).
- [Use the Rebilly API](/docs/dev-docs/api/customers/deletecustomer/).


## Prevent duplicate customers

Use the following strategies to prevent duplicate customers.

### Use predefined customer IDs

If the customer has an identifier within your system prior to the request to create the customer in Rebilly, use the [Upsert a customer with a predefined ID](/docs/dev-docs/api/customers/putcustomer/) operation. This operation adds a new customer with a predefined ID or updates an existing customer. The predefined ID must be a case insensitive URL-safe string of 50 characters or less.

### Update or add a new customer

Use this approach to determine if a customer exists before you create a new customer. This approach checks if a customer exists, if the customer exists it updates the customer. If the customer does not exist it adds a new customer.

1. Determine if the customer exists: Using filters to determine unique customer information, such as email address, execute the [Retrieve a list of customers operation](/docs/dev-docs/api/customers/getcustomercollection/). For more information, see [Search filters](/docs/dev-docs/search-filters).
  - Filter string by email example: `GET customers?filter=primaryAddress.*.email:bob@example.com`
  - Filter by name and email example: `GET customers?filter=primaryAddress.*.email:bob@example.com;firstName:Bob;lastName:Smith`
2. Select one of the following:
  - If the response contains a matching customer, use the ID in the [Upsert a customer with a predefined ID](/docs/dev-docs/api/customers/putcustomer/) operation. This updates the existing customer.
  - If the response does not contain a matching customer, execute the [Create a customer (without an ID)](/docs/dev-docs/api/customers/postcustomer/) operation. This operation creates a new customer with a customer ID generated by Rebilly.
Note: To add a new customer with a predefined ID, without checking to determine if the customer already exists, execute the [Upsert a customer with a predefined ID](/docs/dev-docs/api/customers/putcustomer/) operation.