All the information on this page is for the latest version of Chargebee Orders. You may be using the legacy version if you enabled Orders in Chargebee before 28th September 2018.
If you are a business that ships physical goods to your customers through subscriptions, Chargebee Orders helps manage your deliveries. For instance, you could benefit from this feature if you are a merchant who sells subscription boxes, magazines, products that need to be replenished on regular intervals or rents devices, charging monthly-recurring amounts and more.
Once you configure Orders, Chargebee automatically generates shipping schedules based on the subscriptions that your customers sign-up for. Shipments in Chargebee are represented by entities called "orders". Each order has all the associated information for the shipment such as the shipping date, status of processing, linked invoice amounts etc. This information can now be used by your fulfillment platform to complete the deliveries. The processing of these orders in Chargebee may be done via the web interface, API or through a fulfillment platform (such as ShipStation) integrations.
Chargebee Orders helps your business by:
- Creating orders automatically based on your site settings and plan/addon configuration.
- Automatically tracking and managing information associated with every shipment via integrations with platforms such as Shipstation and Shopify or via API and webhooks.
- Assisting in revenue recognition by allowing you to record the delivery status of goods.
- Facilitating inventory management by providing information on the quantity of goods to be shipped.
- Accounting for and managing cancellations, refunds and return of goods by customers.
- Tailoring your shipping preferences by letting you choose a specific day/date for shipping orders.
Chargebee Orders must be enabled and configured before the automated creation and processing of orders can begin.
Orders are only generated in Chargebee for paid invoices except for gift subscriptions, for which they're generated only on gift claim.
In this section, we shall see how the configuration is done.
Step 1: Configure Site-wide Settings
Navigate to Settings > Configure Chargebee > Orders to enable Orders.
Here you can:
- Configure order numbering by
- setting the first order number and
- optionally setting a prefix for the order numbers in Chargebee.
- Set a shipping date setting for your orders as
- a fixed number of days from the order date or
- a specific day of the month or week. You can further choose if the first order for an order schedule is shipped immediately instead of on the preferred shipping day set here. Moreover, this exception can be made for all orders or those of gift subscriptions alone.
- Set a shipping cut-off that defines the day of month beyond which if the payment is delayed, the first order is unserviceable. (Choose 31 if you want it to be the last day of the month.)
Once Orders have been enabled, the orders index page that lists all orders can be launched by clicking the Orders option on the left navigation panel. This page also allows you to export orders as CSV. You can also export orders by navigating to Settings > Import & Export Data > Export data.
You can also perform operations for multiple orders at once by navigating to Settings > Import & Export Data > Choose a bulk operation > Select Orders under Choose an operation. (
Create Orders operation is only applicable for the legacy orders system.)
- First order number can only be set once.
- Order numbers are created on the order date or on the date when the order is synced to a shipment platform such as Shipstation, whichever is earlier.
- Shipping cut-off cannot be set for weekly orders. It is also not applicable for gift subscriptions.
- If you use Calendar Billing, please ensure that the calendar billing cut-off, shipping cut-off and shipping date settings are aligned to work properly.
Step 2: Configure Plan and Addon Settings
Once the above settings have been configured, a new section, called Shipping preferences is enabled for plans and addons where you must
- set if the plan or addon contains products that are shippable and if so
- configure the ship every field to determine how often the products are shipped.
The options available for ship every depend on the billing frequency of the plan/addon. The table below shows which ship every field values are compatible for different billing periods.
Note: The ship every field for a plan/addon is not editable as long as a linked order exists.
Based on the above settings, Chargebee schedules orders automatically for your plans and addons. Once a customer signs-up for a subscription, subject to certain conditions, the schedule of orders is created:
- All orders that are linked to a customer or subscription are listed near the bottom of the details page of the customer/subscription under the orders tab.
- Also note that for gift subscriptions, the orders are listed under the gift recipient's customer details page.
- For invoices/credit notes, the associated orders are listed on the details page under a section titled linked orders.
Statuses and Lifecycle
Order statuses indicate at what stage a particular order is in its lifecycle.
The following are the various statuses that an order can have in Chargebee:
||This is the initial status of orders waiting to be processed. This is typically their state before they have been moved to an integration platform/external fulfillment system.
||Used to indicate that the orders have been moved to the integration platform/external fulfillment system.
||Indicates that the order processing has been put on hold.
||Indicates that the order has been cancelled.
||The order is in transit.
||The order is only partially delivered.
||The order has been delivered.
||The order has been returned after delivery
The state diagram below shows how orders transition between statuses. The arrows show the allowed status changes.
The green arrows inside the central box only show the typical direction of status change. All order statuses within the box can change between each other without restrictions.
When in cancelled status, an order can only change status (via the re-open order action) to the one immediately before being cancelled.
When in on hold status, an order can change status to:
- the status before being put on hold or
- cancelled status
Also, when an on hold order is cancelled and then re-opened, it goes into on hold status. From here, it can still go to the status it was in before being originally put on hold.
If an awaiting shipment order is put on hold and then cancelled, then on re-opening, it goes into on hold status. From here, it can either go to awaiting shipment again or be cancelled.
Depending on what status an order is in, several actions can be performed on orders from the user interface. In the order details page, the actions pane on the right lists the available actions:
- Edit order details: This action helps you change order details such as status, order date, shipping date etc. The attributes available for editing depend on the status of the order.
- Update Order Shipping Info: All the shipping related information pertaining to the order can be edited using this action. This includes shipping address, name, email, company etc. Order shipping info can only be changed for orders in the queued status.
- Refund Order: This action creates a refundable credit note for the order. The amount to create the credit note for (maximum refundable value is pre-filled) and the reason for doing so (from the available list) must be specified.
- Cancel Order: This action sets the order status as cancelled. A refund amount may be specified for which a refundable credit note will be raised (leave it blank if no credits are being given). Also, you must choose from the available cancellation reasons.
- Re-open Order: re-opens a cancelled order: sets the order status to the same as that before cancellation. Also, if any unused refundable credit notes with reason code order cancellation exist against the order, an option to void them is made available. If the credit note has been refunded already, then a warning will be shown for it and the order can still be re-opened.
Impacts of external actions in Chargebee on orders.
Orders have attributes or properties that can be viewed and edited using the web interface. We list them below. If you use our API, then you have access to many more attributes as part of the order resource .
Note: For any given order, unless specified otherwise, the attributes are available and editable in all circumstances. However, an attribute is editable for an order that is on hold or cancelled only if it was editable in the previous status (unless otherwise mentioned for specific attributes).
- Order status: This attribute represents the various states that an order can take during its lifecycle in Chargebee.
- Order date: The preferred date around which the order is to be processed. This date is automatically determined by Chargebee at the time of invoicing/payment based on the shipping preferences for plans/addons, and the Calendar Billing settings for your site. This date can only be modified for orders in queued status.
- Shipping date: The preferred date around which the order is to be shipped. This date is also automatically determined by Chargebee at the time of invoicing/payment and is assigned based on the site settings for orders and the plan and addon settings. This date can only be modified for an order when it is in queued status.
More about how order dates and shipping dates are calculated is explained here.
- Order Id: This is the API Id used to uniquely identify orders in Chargebee. This is assigned to an order as soon as it is created in Chargebee.
- Order number: This is a unique document number used to identity an order in Chargebee. It is assigned to orders serially as they are processed in Chargebee (assigned on the order date or on the sync date with the integration platform, whichever is earlier). The format of the order number is based on site settings for this field.
- Shipping information: All the shipping related information pertaining to the order. This includes shipping address, name, email, company etc. and can be changed for an order only when it is in the queued state.
- Order notes: Notes about the order can be added here. This is part of the order API resource and can thus be passed to third-party integration platforms. These notes are intended to be internal ones for the reference of fulfillment personnel and are not published to your customers in any way by Chargebee.
- Fulfillment status: When you use Chargebee Orders with other order management systems or third-party integration platforms, they may have different status field values for orders than those in Chargebee. This field captures the status field for the order from such an external system. It cannot be captured/updated for orders in queued status.
- Tracking Id: The shipment tracking Id. Usually obtained from the order management system or the integration platform. This attribute cannot be captured/edited for orders in queued status.
- Batch Id: The shipment batch Id. Usually obtained from the order management system or the integration platform. This attribute cannot be captured/edited for orders in queued status.
- Reference Id: This Id is used to hold the unique Id of the order in the external system or integration platform. This attribute cannot be captured/edited for orders in queued status.
- Shipment carrier: The shipment carrier details. Usually obtained from the order management system or the integration platform. This attribute cannot be captured/edited for orders in queued status.
- Shipped at: Used to capture the date and time the order was actually shipped. This field is available for capture and update for orders with the following statuses: shipped, partially delivered, delivered, and returned. If an order moves out of those statuses, the shipped at data is deleted (except when moved to cancelled or on hold statuses). Also, shipped at cannot be edited for orders that are cancelled or on hold.
- Delivered at: Captures the date and time the order was delivered. This date is available for capture and update for orders with the following statuses: partially delivered, delivered and returned. If an order moves out of those statuses, the delivered at data is deleted (except when moved to cancelled or on hold statuses). Also, delivered at cannot be edited for orders that are cancelled or on **hold.
- Cancellation reason: For cancelled orders, this field specifies the reason for order cancellation. Thus, the field is applicable only for cancelled orders and gets deleted if the order is reopened. If system generated, it cannot be changed manually. The table below lists the possible cancellation reason field values.
||Can be manually chosen
||Can be system generated
|Shipping cut off passed
|Product not available
|Product not required
|Delivery date issue
|Other better alternatives
Events & Webhooks
Events in Chargebee also include order-related events . You can configure webhooks to notify your application of such events.
Legacy Version of Orders
If you have been a user of Chargebee Orders from before 28th September 2018, then you have been using the legacy version. In such a case, although we encourage you to use the latest system, there are some things to be considered:
Once the latest system is enabled, any new invoices created would be subject to the latest system only. If you are an API user of the legacy system, to avoid erroneous operations, the latest system is restricted from being enabled for your live site. Contact email@example.com to help enable it.
Any orders created using the legacy system can continue to be processed using that system.
Our business involves shipping a product to the customer and then charging a rental on it every month. How is this configured in Chargebee?
You can create a monthly non-shippable plan in Chargebee for charging the rental. For the shipped item itself, a non-recurring shippable addon may be created and attached to the subscription.
How do I add shipping charges to orders?
Shipping charges are not available as a separate line-item in Chargebee yet. However, you can include shipping charges by creating addons for them in Chargebee and marking them as shippable so that they are included in the orders.
We only ship products to our customers during a certain time of the month (or particular day of the month). How can this be setup?
Consider selling a 6-month subscription for monthly magazine issues for which you wish to bill your customers on the 25th of the month and ship issues on the 10th, every month. Further, based on when the customer signs up during the month, say you wish to ship the first issue as follows (subject to payment):
||Shipping Day for the First Issue
|1st - 10th
|11th - 15th
||Same as payment day
|16th - end of the month
||10th of next month
Moreover, if the payment for the subscription is delayed beyond say, 15th, you wish to cancel the first shipment.
Then you would configure Chargebee as follows:
Enable calendar billing with
- Calendar billing date: 25th
- Billing cutoff date: 15th
Configure Chargebee Orders as:
- Shipping date: 10th
- Shipping cutoff: 15th
I have calendar billing enabled for my site. Do orders for gift subscriptions align with those settings?
No, calendar billing has no effect on gift subscriptions. Also, order schedules for gift subscriptions are both determined and created only on gift claim.
I'm cancelling a subscription, how can I ensure that the unfulfilled orders alone are refunded?
See this FAQ.