# Orders

An order is a customer's request to purchase items.
Orders contain one-time sales items, subscription items, or both.
Orders generate [invoices](/docs/dev-docs/invoices) that the customer must pay to receive the items.

This topic describes the current order model.

In the legacy order model, an order represents a subscription.
All items in the order use the same recurring interval, trial, and service period anchor.
The `billingStatus` field contains the status of the most recent invoice.
If the order has no recent invoice, `billingStatus` is `unpaid`.

In the current order model, an order is a container for subscription items and one-time sale items.
An order does not include `billingStatus`.
An order can contain multiple subscription items, multiple one-time sale items, or both.
Subscription items can use different billing periods if the anchors for the service period are compatible.
For more information, see [Orders with multiple subscription items and mixed plans](#orders-with-multiple-subscription-items-and-mixed-plans).
Create new orders with [Create an order](/docs/dev-docs/api/orders/postorder).
`POST /subscriptions` creates a legacy order, and organizations on the current order model reject that request.
To move an existing organization to the current order model, [contact Rebilly support](/support/).

For detailed information on order API endpoints and their properties, see [Order operations](/docs/dev-docs/api/orders/).

## Types of order items

Two types of items can be included in an order:

- [One-time sales](/docs/dev-docs/one-time-sales): Single, non-recurring, charges for products or services.
  Example: A one-time purchase of an internet modem.
- [Subscriptions](/docs/dev-docs/subscriptions): Recurring charges for subscription items 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.

## Orders with multiple subscription items and mixed plans

Orders can contain multiple subscription items and one-time sales.
For example, a customer purchases a monthly subscription to a streaming service, a subscription to a support service, and a one-time sale of a streaming device.

Orders can contain subscription items with different billing periods.

If one subscription item in the order has a service period anchor configured, you must configure compatible service period anchors for the other subscription items in the order.
Use one of the following configurations:

- Use the same billing period for all subscription items and set the same service period anchor for all subscription items.
- Use a mix of monthly and yearly subscription items.
  Set the service period anchor for monthly subscription items to the same day of the month.
  Set the service period anchor for yearly subscription items to the same day and month of the year.

Use the following properties to configure when invoices are issued and due for subscription items on an order.

### Start time

Use the `startTime` property to set the start date of the service period for subscription items on an order.
The `startTime` property sets the date and time when the service period begins.
For more information, see [Start time](/docs/dev-docs/api/orders/postorder#!t=request&path=0/startTime).

### Recurring interval

Use the `recurringInterval` property to override the plan settings for subscription items on an order.
The `recurringInterval` property sets the length of the service period for a subscription item.
For more information, see [Create an order](/docs/dev-docs/api/orders/postorder).

### Invoice issue and due time shift

Use invoice time shift to adjust when the invoices for subscription items on an order are issued and made payable.
Use due time shift to adjust when the payment is due.
If autopay is on, the payment is collected at the due time.
If the invoice is not paid, the invoice moves to past due status after 24 hours.
For more information, see [Invoice time and due time shift](/docs/settings/products-and-pricing#invoice-time-and-due-time-shift).

On an order that does not use invoice time shift or due time shift, the invoice is issued on the renewal date and time.
The invoice is due 1 hour after it is issued.

## Order forms

Use order forms to collect payment for an order.
Rebilly provides [hosted payment forms](/docs/dev-docs/create-a-hosted-payment-form) and also [Billing portals](/docs/settings/billing-portals).
To create your own form, see [Get started](/docs/dev-docs#get-started).

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, an order that contains subscription items is set to `active`, and a one-time order is set to `completed`.
The `activationTime` property is also set.

To find information on the most recent invoice:

- Reference the `recentInvoiceId`, or [`expand`](#expand-resources) the `recentInvoice` element in the API resource.
  For more information, see [Search filters](/docs/dev-docs/search-filters).
- Use the [retrieve a list of invoices](/docs/dev-docs/api/invoices/getinvoicecollection/) operation.
- Use the UI to [view invoices](/docs/data-tables/manage-invoices#view-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](/docs/dev-docs/expand-embedded-resources).

## 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 order, or when invoices get paid, see [Webhooks](/docs/dev-docs/webhooks-configuration).

Alternatively, use the UI to automate notifications and related tasks.
[Create event-based email notifications](/docs/automations/email-notifications#create-event-based-email-notifications) using the invoice paid and order activated events.

### Subscription renewal reminders

Reminders are sent 30 days, 7 days, and 1 day before an active order that contains subscription items renews.
Each reminder is sent only when the recurring interval of the order meets the minimum for that reminder.
Reminders are not sent for an order that is paused, or that has a pause scheduled to start before the renewal.
Reminders are not sent for the renewal at the end of a trial.
To notify your systems before a trial ends, subscribe to the [Subscription trial end reminder](/docs/automations/webhook-events#subscription-trial-end-reminder) webhook.
Each reminder is sent once for that renewal.
When the renewal time changes, the reminders are sent again for the new renewal time.

| **Reminder** | **When it is sent** | **Recurring interval** | **Event type** |
| --- | --- | --- | --- |
| 30 days | From 30 days before the order renews until 7 days before the order renews. | 90 days or more | `subscription-renewal-reminder-30-days` |
| 7 days | From 7 days before the order renews until 1 day before the order renews. | 14 days or more | `subscription-renewal-reminder-7-days` |
| 1 day | From 1 day before the order renews until the order renews. | Longer than 1 day | `subscription-renewal-reminder-1-day` |

A reminder is not sent after its period ends.
For example, if the renewal time of an order with a yearly recurring interval changes to 5 days from now, the order receives the 7-day and 1-day reminders.

To notify your systems, subscribe to these webhooks:

- [Subscription renewal reminder, 30 days before renewal](/catalog/all/orders/subscription-renewal-reminder-30-days)
- [Subscription renewal reminder, 7 days before renewal](/catalog/all/orders/subscription-renewal-reminder-7-days)
- [Subscription renewal reminder, 1 day before renewal](/catalog/all/orders/subscription-renewal-reminder-1-day)

## 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 payable invoices are abandoned.

Only pending orders can be abandoned.

Choose from the following options to set the `abandonTime`:

- To set the date and time when the order is abandoned, use the [`abandonTime` parameter](/docs/dev-docs/api/orders/postorder#!t=request&path=0/abandonTime) when you create an order.
- To deactivate automatic abandonment, pass a `null` value in the [`abandonTime` parameter](/docs/dev-docs/api/orders/postorder#!t=request&path=0/abandonTime).
- 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.

## Retain a recurring order in the sandbox using the API

From December 8, 2026, at 09:00 UTC, recurring orders in the sandbox environment are automatically canceled 90 days after they are created if they are not explicitly retained.
For more information, see [Recurring order retention in the sandbox](/docs/data-tables/manage-subscriptions#recurring-order-retention-in-the-sandbox).

Use this process to retain a recurring order in the sandbox environment using the API.
To retain an order using the UI, see [Retain a sandbox recurring order](/docs/data-tables/manage-subscriptions#retain-a-sandbox-recurring-order).

Behavior when an order is canceled based on the sandbox recurring order retention policy:

- Recurring orders in the sandbox environment are automatically canceled 90 days after they are created unless a member of the organization chooses to retain them.
  When the order is canceled, `canceledBy` is set to `rebilly` and `cancelCategory` is set to `sandbox-retention`.
  The [Subscription order canceled](/catalog/all/orders-(legacy)/subscription-canceled) and [Subscription order churned](/catalog/all/orders-(legacy)/subscription-churned) webhooks are sent.
  No cancellation email is sent, even if an email notification is configured for the `subscription-canceled` event.
- Recurring orders that are paused are canceled on the same schedule and the cancellation ends the pause.
- Active or paused trial-only recurring orders are not canceled.
  The trial ends 90 days after the order is created and the status changes to `trial-ended`.
- Pending orders that are older than 90 days are abandoned and the status changes to `abandoned`.
  The [Order abandoned](/catalog/all/orders-(legacy)/order-abandoned) webhook is sent.
  If an email notification is configured for the `order-abandoned` event, the email is sent.

To retain an order, set `excluded` to `true` when you create or update the order.
Use the [Upsert an order](/catalog/all/orders/putorder) operation for an order, or the [Upsert an order (legacy)](/catalog/all/orders-(legacy)/putsubscription) operation for a legacy order.

In the sandbox environment, a recurring order includes a `sandboxRetention` object.
The `autoCancelTime` value is the date and time when the order is canceled.
This value is `null` when the organization is excluded from automatic cancellation.
This value is `null` for an order that can no longer bill.

```text
PUT https://api-sandbox.rebilly.com/organizations/{organizationId}/orders/{id}

{
  ...,
  "sandboxRetention": {
    "excluded": true
  }
}
```

The response includes the updated object.

```json
{
  "id": "ord_0YV7DES3WPC5J8JD8QTVNZBZNJ",
  "status": "active",
  "sandboxRetention": {
    "autoCancelTime": "2027-03-08T09:00:00+00:00",
    "excluded": true
  }
}
```

A request that exceeds the limit of 50 retained recurring orders is rejected with a validation error.

For more information, see [Recurring order retention in the sandbox](/docs/data-tables/manage-subscriptions#recurring-order-retention-in-the-sandbox).