These docs are intended for a developer audience.
Orders
An order is a customer's request to purchase items. Orders contain one-time sales items, subscription items, or both. Orders generate invoices that the customer must pay to receive the items.
For detailed information on order API endpoints and their properties, see Order operations.
Types of order items
Two types of items can be included in an order:
One-time sales: Single, non-recurring, charges for products or services. Example: A one-time purchase of an internet modem.
Subscriptions: Recurring charges for products or services that are billed at regular intervals, such as monthly or annually. These periods are referred to as service periods. An invoice is generated for each service period. Example: A monthly pre-paid subscription to an internet service provider.
Billing status
billingStatus describes the status of the most recent invoice in the order.
| BillingStatus | Description | When your application receives this billingStatus: |
|---|---|---|
unpaid | Invoice is issued to the customer. It is not paid. The payment time-frame has not exceeded. | Email the invoice to the customer, see Automate emailing invoices. If autopay is turned off, Collect a payment. |
past-due | Invoice is 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. Let the customer know they have a past due invoice with in-app messaging. Depending on your service costs, you may want to remove access and delivery. |
abandoned | An invoice is not paid, or not paid in full, and has been abandoned by the customer. | Remove service access and delivery. |
paid | Invoice is paid by the customer. | Grant service access and delivery. Send an invoice email confirmation; see Send a paid invoice notification. |
partially-paid | Invoice amount is partially paid by the customer | Attempt to collect the remaining balance using email outreach. |
voided | Invoice amount is set to zero. Voiding retains the invoice number and lists it in reports but changes the amounts to zero. | Remove service access and delivery, if it was granted. |
disputed | Invoice amount paid is disputed by the customer or merchant | Remove service access and delivery. |
refunded | Invoice amount is fully refunded to the customer. | Remove service access and delivery, if appropriate. |
partially-refunded | Invoice amount is partially refunded to the customer. | No action required. |
Order forms
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 an 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, orexpandtherecentInvoiceelement in the API resource. For more information, see Search filters. - Use the retrieve a list of invoices operation.
- Use the UI to view previously issued 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 Embedded resources.
Subscription order renewals
Rebilly automates the scheduling and generation of renewal invoices. If autopay is active, the payment against the invoices is scheduled 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 the abandon time is reached. When an order is abandoned all associated invoices are voided.
Only pending orders can be abandoned.
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
abandonTimeparameter. - To deactivate automatic abandonment, pass a
nullvalue in theabandonTimeparameter. - To calculate the
abandonTimeautomatically based on the time it was created (createdTime) and the TTL of the pending order (organization.settings.billing.pendingOrderTTL), do not send theabandonTimeparameter.