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 |
Credit memo | many to many | Transaction |
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.
-
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
-
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
orverification-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
orverification-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
{
"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:
-
Configure
GatewayAccount.setupInstruction
, to contain the required action for the specified payment method and payment gateway. -
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 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.
note
A credit memo can be allocated to transactions of the type refund
and payout
, and transactions of the type capture
and sale
that have the status disputed
or voided
.
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.
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:
-
Reference the
recentInvoiceId
, or expand therecentInvoice
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 theabandonTime
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 theabandonTime
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.