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.

Resource Relationship Resource
Customer 1 to many Payment instrument
Customer 0 to many Transactions
Payment instrument 0 to many Transactions
Customer 0 to many Order
Order 1 to many Invoice
Invoice many to many Transactions
Credit memo many to many Invoice
Invoices & orders 1 to many Products & plans (as "items")
Product 1 to many Plans

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:

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:

    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:

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.

note

Not all payment instruments are suitable for recurring autopay transactions.

Payment instrument object example
Copy
Copied
{
    "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:

Result
Description When your application receives this result:
approved The result of a valid transaction that is accepted by the issuing bank. Present the customer with a thank you page which displays the billing descriptor.
declined A payment transaction is not approved by the issuing bank. A reason code is supplied, which describes why the transaction is declined, such as: insufficient funds, incorrect billing address or CVV, and so on. Present the customer with a message stating that the transaction is declined.
abandoned Occurs when a customer begins payment but does not complete it. Trigger some abandoned cart outreach campaign.
canceled The customer cancels the transaction before funds are removed from their account. Present the customer with an option to select a different payment method.
unknown The transaction is in process, the status changes as it is processed. Check if the status is waiting-approval. If it is, within the response, in the _links object, locate the approvalUrl and direct the customer to it.

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 pay invoices partially or fully. Amounts up to the credit memo's amount can be allocated.

Example: PUT /invoices/INV1/credit-memo-allocations/MEM1.

For partially paid invoices, the allocation can also be reduced, or removed. This reduces the invoice's received amount. For more information, Apply a credit memo to an invoice and Delete credit memo's allocation from the invoice.

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:

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:

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.

BillingStatus Description When your application receives this billingStatus:
unpaid An invoice which has been issued to the customer. It is not paid. The payment time-frame has not exceeded. Email the invoice to your customer, see Automate emailing invoices. If autopay is turned off, Collect a payment.
past-due An invoice which has been issued to the customer. It is not paid. The payment time-frame has exceeded by more than 24 hours. Send a past due invoice reminder. Letting the customer know they have a past due invoice with in-app messaging. Depending on your service costs, you may wish to remove access and delivery.
abandoned An invoice that has not been paid, or not paid in full, and has been abandoned by the customer. Remove service access and delivery.
paid An invoice which has been paid by the customer. Grant service access and delivery. Send an invoice email confirmation; see Send a paid invoice notification.
partially-paid An amount has been paid but it is less than the balance due on the invoice. Attempt to collect the remaining balance using email outreach.
voided Sets the amount of the invoice to zero. Voiding will keep the invoice number and list it in reports but changes the amounts to zero. Remove service access and delivery, if it was granted.
disputed A customer disputes an amount paid or received. Remove service access and delivery.
refunded An invoice amount that has been fully refunded to the customer. Remove service access and delivery, if appropriate.
partially-refunded Invoice amount that has been partially refunded to the customer. No action required.

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:

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.

Cancel a subscription order

Select from the following cancelation options:

Edit subscription order details

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

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.

Copy
Copied
{
    "customFields": {
        "preferredCommunicationChannel": "email"
    }
}

For more information, select from the following:

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.