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.

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 using FramePay. 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. Lead source information is passed automatically when the payment token is created using FramePay to collect payment card data. Rebilly records the following lead source information:

• Original lead source: Entity that introduces the customer to your application.
• Intermediary lead sources: Entities that influence the customer to use or return to your application.
• Most recent lead source: The last entity which interacts with the customer before they complete a payment in your application.

For more information, see Lead sources.

Tags and filters

Use tags to organize and categorize customers for reporting and automation tasks. For more information, see 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.

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.
• Use the Rebilly API.

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 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. For more information, see 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 operation. This updates the existing customer.

   • If the response does not contain a matching customer, execute the Create a customer (without an ID) 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 operation.