Concepts

This topic describes the components of the Rebilly product. In Rebilly, components are called resources.

Use this topic to understand how Rebilly works and to aid with your integration. This topic is for a developer audience.

Resources

The following table describes the entity relationships between each resource in Rebilly.

Customer

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 is purchasing 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 using 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 customers collections by recency, frequency, and monetary value for traditional marketing segmentation. For more information, see Using filter with collections.

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 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 Using filter with collections .

   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.

Payment instruments

A payment instrument is a term which describes any means of making a digital payment, such as: credit cards, debit cards, direct debits, payment service providers, and digital wallets.

A payment instrument is not a resource. It is a term used to describe a specific set of resources, such as payment cards and bank accounts.

Lifecycle

Use the following libraries to manage PCI DSS compliance and automate the collection of risk metadata and lead source data:

• FramePay library : Use this library to create a highly customized integration.
• Rebilly Instruments library : Use this library to create a quick integration.

Payment card lifecycle statuses:

• inactive or verification-needed : Payment card is registered but has not completed a payment transaction.
• active : One or more payments have been completed using the payment card.
• expired : Payment card expiration date has exceeded.
• deactivated : Payment card is removed and is no longer valid.

For more information, see Payment card lifecycle.

Alternative, bank account, PayPal, and Khelocard lifecycle statuses:

• inactive or verification-needed : Payment instrument is registered but has not completed a payment transaction.
• active : One or more payments have been completed using the payment instrument.
• deactivated : Payment instrument is removed and is no longer valid.

Usage

Payment instruments are defined in the paymentInstrument object. A customer may have a default or primary payment instrument. For more information, see Payment instruments.

Payment instrument object example

{
    "method": "payment-card",
    "paymentInstrumentId": "<id generated by API>"
}

Store for future use

To store payment instruments for future use, before they are used, the following actions may be required:

• Post an authorize transaction with the selected payment instrument, particularly for payment cards. You may also be required to void the authorizing transaction.
• Perform Strong Customer Authentication (SCA), particularly for 3DS authorization.

Each payment method and gateway has different setup requirements, to create a uniform setup:

1. Configure GatewayAccount.setupInstruction , to contain the required action for the specified payment method and payment gateway.
2. Use a transaction with type setup . This transaction performs the required actions on the specified payment instrument.

Transactions

Types

• authorize : Confirms that the payment instrument is valid, that the customer is associated with the payment instrument, and that the funds are available. For payment cards, this transaction results in a hold placed on the cardholder's account for the authorized amount. An authorized transaction can be captured or voided.
• capture : A capture debits funds from a cardholder's account, and on settlement, moves the funds to the merchant's account.
• sale : A sale combines the authorization and capture process in one transaction. A sale can be voided prior to settlement, and can be refunded after settlement.
• void : Reverses an authorization, capture, or sale transaction. A void can only occur before settlement, otherwise a refund must be used to credit the customer.
• refund : Transfers funds from the merchant back to a customer. A refund is similar to a void, except a void must happen before the settlement of funds. On some occasions, a refund transaction can be voided.
• credit : A credit is a special and rare type of transaction. It permits payments to customer cards that exceed a just refund. It requires special permissions from your acquiring bank.
• 3ds-authentication : 3D Secure authentication validates cardholders by instructing the cardholder to authenticate their card against the issuing bank's website. This enables the merchant to shift liability from themselves to the issuing bank. 3D Secure requires the cardholder's interaction.
• setup : Initializes the process to make a payment instrument available for future use.

Results

Completed transactions have one of the following results:

Offsite and instant transactions

• Offsite transactions: Customers must interact with a third-party website to complete a transaction. This interaction may be required as part of payment regulation.
• Instant transactions: No customer interaction is required to complete a transaction.

Prevent duplicate transactions

To prevent a duplicate transaction, generate a unique ID that you pass to the client form. Include the ID as the requestId property value in your transaction request.

Only regenerate a different ID for the client form after you receive a completed status in the response from Rebilly.

Invoices

An invoice is a bill for a list of goods and services provided. If your invoice includes subscription items, it also includes the corresponding service periods and prices.

Invoice components

An invoice is sent from an organization to a customer. The customer may have a billing address and delivery address.

Invoices are sequentially numbered for each customer.

If an invoice is associated with a subscription order, the subscriptionId value is displayed.

Invoices contain line items. Each line item may have a product ID, plan ID, quantity, service period and pricing information.

The invoice may have associated coupons & discounts, shipping, taxes, and credit memos.

Invoice status lifecycle

For information on the invoice lifecyle and invoice statuses, see Invoice lifecycle.

Usage

If you follow the suggested order workflow, you may utilize the invoice using the expand=recentInvoice query string parameter and value on the order API requests.

You may also retrieve any invoice by its ID, for example: GET invoices/123.

In other resources, the invoice ID may be referred to as the invoiceId, recentInvoiceId, initialInvoiceId or a value with "invoiceId" in the name.

Webhooks

Use webhooks to notify your systems when certain events occur, and to collect information about the events. For more information, see Webhooks.

To record paid invoices in your own system, or push the data to third parties, create a trigger on the Invoice paid event.

Rebilly also provides custom webhooks, that enable you to control the payload using placeholders. These may be useful for integrating directly to third parties without needing to mediate the requests and responses.

Automate emailing invoices

Use Rebilly to email invoices to your customers. For more information, see Automate emailing invoices.

Taxes

Rebilly supports automated tax calculations internationally, using the location of your organization and the location of your customer. You may also manually adjust the taxes on an unpaid invoice. Rebilly calculates taxes after an invoice is issued and recalculates them on every invoice change. The shipping amount is added to tax calculations. For more information, see Taxes.

To calculate taxes:

• The product must be taxable.
• Your organization must have a full address.
• The customer must have a full address.

If you would like to use third-party tax calculators, Contact us.

Coupons and discounts

For information on coupons and discounts, see Coupons and discounts and the Coupons operations.

Credit memos

A credit memo is a record which describes a certain amount that is owed to a customer for a particular invoice or invoice item. A credit memo is also a means of providing a customer with store credit.

A credit memo is similar to an invoice. It includes items, taxes, and shipping, but its total is subtracted from the invoice amount. A common use case for a credit memo is to provide a customer with store credit, rather than a refund, if the customer pays more than they owe or returns a product.

For your records, when paid items are returned, specify the particular invoice ID or invoice item IDs which are credited. This is informative only, and has no effect on the application of the credit. For more information, see Credit memo API operations.

Statuses

• issued : A credit memo has been created but has not been allocated. The full amount of the credit memo is unused.
• partially-applied : A credit memo has been partially allocated. Some of the credit memo amount is unused.
• applied : A credit memo amount has been fully allocated.
• voided : A credit memo unused amount is set to zero. The credit memo and its allocations cannot be changed.

Allocations

A credit memo has an amount (unusedAmount), which is used to allocate to transactions, and used to partially or fully pay invoices. The credit memo account can be allocated in several smaller portions or in one full allocation of the full credit memo amount.

Example: PATCH /credit-memos/{creditMemoId}/.

{
  "allocations": {
    "invoices": [
      {
        "invoiceId": "invoice-external-id",
        "amount": 404
      }
    ]
  }
}

For partially paid invoices, the allocation can also be reduced or removed. This reduces the received amount of the invoice. For more information on invoice allocations, see Upsert a credit memo, Partially update a credit memo, and Retrieve a credit memo.

Allocating a credit memo to a transaction reduces the credit memo unusedAmount, but it does not affect the transaction itself. This is useful when allocating a refund transaction, to reduce the credit memo unusedAmount by the refund amount. For more information on transaction allocations, see Upsert a credit memo, Partially update a credit memo, and Retrieve a credit memo.

Order billing

When an upcoming order invoice is issued, depending on the order settings, it may be scheduled for an auto payment. When auto payment occurs, the invoice retrieves allocations from all credit memos with an unused amount until it is paid or there are no more issued, or partially applied, credit memos.

Products

Products are the goods and services that your business sells. A product also describes sales items on invoices and receipts. Product pricing is defined in plans. A product can have one or many plans.

For more information, select from the following:

• Use the API to create or manage products — see Products .
• Use the UI to create a product and plan — see Create a product and pricing plan .

Plans

Pricing plans describe how the customer must pay for products.

Rebilly provides the following plan types:

• Trial only: Use this plan to create and offer a free or discounted trial period for your product. For example, a free 2 week trail of an internet service. After the trial, the customer can choose to sign up for a paid subscription, or stop using the service.
• Recurring: Use this plan to create and offer a subscription for your product. For example, a monthly subscription to an internet service that is charged at 20 USD per month.
• One time sale: Use this plan to create and offer a one-off sale for your products. For example, a one time purchase of two bags of coffee.

For more information, select from the following:

• Use the API to create or manage plans — see Plans .
• Use the UI to create a product and plan — see Create a product and pricing plan .

Orders

An order is a customer's request to purchase items. It can contain subscription and one-time sale items. When an order contains one or more subscription items, it is a subscription order. An order generates an invoice. A subscription order generates an invoice for each service period. For more information, see Order lifecycle.

Service period anchor, and billing timing, and invoice time shift

The following properties are used to configure subscription orders:

• Service period anchor: Used, in conjunction with the start time, to calculate the service period.
• Billing timing: Used to determine when, relative to the service period date, the invoice is issued. Billing timing controls whether the service is prepaid in advance or postpaid in arrears. In most scenarios, the service period anchor is aligned with the billing period. For example, the service period ends on the 1st of the month, and is billed on the 1st of the month.
• Invoice time shift: Used to adjust invoice issue and due date when billing must occur before the service period changes. For example, rent must be paid in advance, so the invoice must be in advance of the billing date. For more information, see Invoice time and due time shift .

Order status transitions

The order status describes the state of a subscription order. For information on the order lifecyle and statuses, see Order lifecycle.

Billing status

The billingStatus represents the status of the most recent invoice. For more information, see Invoice lifecycle.

Order form

Use order forms to collect payment for an order. Rebilly provides hosted payment forms, hosted checkout forms, and also Billing portals. To create your own form, see Choose an integration.

Order forms create an invoice for payment. When the order is created it has the pending status. When you collect the payment against the invoice, the order status is set to active and the activationTime property is also set.

To find information on the most recent invoice:

• Reference the recentInvoiceId , or expand the recentInvoice element in the API resource.
• Use the Retrieve a list of invoices operation.
• Use the UI to View previous invoices .

Expand resources

Some Rebilly API resources support the use of a query string parameter named expand. This parameter is used to request that additional resources are returned in the _embedded property of the response. The expand property accepts a comma-separated list of objects. For more information, see Expand to include embedded objects.

Subscription order renewals

Rebilly automates the scheduling and generation of renewal invoices. If autopay is true, then Rebilly also schedules payment against the invoices automatically.

To stay informed on changes to the subscription, or when invoices get paid, see Webhooks.

Alternatively, use the UI to automate notifications and related tasks. For more information, see Invoice paid and Subscription activated.

Configure automatic abandonment of pending orders

Use this process to configure the automatic abandonment of pending orders.

An order is abandoned when it is created but not activated before abandon time reached.

Choose from the following options to set the abandonTime:

• To explicitly set the date and time the order must be abandoned, when creating an order use the abandonTime parameter .
• To disable automatic abandonment, pass a null value in the abandonTime parameter .
• To calculate the abandonTime automatically based on the time it was created ( createdTime ) and the TTL of the pending order ( organization.settings.billing.pendingOrderTTL ), do not send the abandonTime parameter.

When an order is abandoned all associated invoices are voided.

Only pending orders can be abandoned.

Cancel a subscription order

Select from the following cancelation options:

• Use the API to cancel a subscription order — see Cancel an order .
• Use the UI to manually cancel subscription orders — see Cancel subscription order .
• Use the UI to automate the cancelation of subscriptions, for example if a customer stops paying — see Stop subscriptions .

Edit subscription order details

All subscription order items can be edited or updated. For more information, select from the following:

• Use the UI to edit a subscription order details — Edit a subscription order .
• Use the API to edit a subscription order details — Change an order's items .

Extend resources

Use custom fields to extend a resource scheme to include your custom field.

Include the data within your API requests. Rebilly validates, stores, and returns the data when you retrieve the resource.

Example: To record a customer's preferred communication channel.

{
    "customFields": {
        "preferredCommunicationChannel": "email"
    }
}

For more information, select from the following:

• Use the API to create or manage custom fields — see Custom fields .
• Use the UI to create a custom field — see Add a custom field .

Automation

This section describes some basic automations. For more information, see Automations.

Email notifications

Use email notifications to notify your team, or your customers, when specific event occurs. Rebilly uses a liquid template engine to render the email by replacing merge tags (placeholders) with actual values related to the event.

For more information, see Email notifications.

Webhook notifications

Use webhooks to notify your systems when certain events occur, and to collect information about the events. For more information, see Webhooks.

Events

In the Rebilly rules engine, an event occurs when specific object changes state. An action is an operation that executes when an event occurs.

Use events to:

• Share data with third-party systems.
• Automate certain actions.
• Send email notifications.
• Send webhook notifications.

For more information, see Events.