Orders 

Introduction 

Chargebee handles your subscription billing. If you're selling physical goods, you would certainly want your shipping schedules to be linked to billing. Orders in Chargebee does exactly this. Whether you sell subscription boxes, rent hardware, or sell household items, Chargebee automatically creates shipment entities (orders) that encapsulate all the information related to each shipment.

For example, if you ship a magazine issue every two months, and a customer can sign-up for a yearly subscription. Once the Orders feature has been enabled and configured in Chargebee, order entities for each subscription would be created as soon as the subscription is created/paid for. For our example, once the yearly plan has been signed-up for by a customer, a set of six orders would be created, one each for the six magazine issues that need to be shipped for the year. Each order would consolidate information such as shipping date of the magazine, the quantity to be shipped, the shipment's share of the invoice amount, tracking URL, status of order processing and so on.

Once the orders have been created, you have three ways of managing them:

• Manually using the Chargebee UI.
• Automatically by integrating your order management system with our Orders API  and webhooks.
• Via our third-party integrations to manage and fulfill orders:
  • ShipStation integration.
  • BigCommerce integration.

Key Features 

Here's a summary of what Chargebee Orders can do for you:

• Create orders (shipment entities) automatically based on your site configuration.
• Allow you to tailor shipping schedules to your needs.
• Integrate with your order management system via API and webhooks.
• Integrate with ShipStation to manage and fulfill the orders.
• Assist in revenue recognition by allowing you to record the delivery status of goods.
• Help inventory management by recording the quantity of goods for each order.
• Every order supports cancellation, refund and recording return of goods.

Configuration 

Chargebee Orders must be enabled and configured before the automated creation and processing of orders can begin. This involves two steps:

1. Setting up the site-wide configuration : this involves setting up some general site-wide rules on how orders should be generated.
2. Setting up shipping preferences for plans and addons : these settings apply at the plan or addon level. For each plan and recurring addon, this would involve specifying how often shipments are sent to the subscriber.

Note:
Orders for gift subscriptions are 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. Proceed with configuring each section carefully.

Note:
Any changes made here, once saved, only apply to newly generated invoices from that moment on.

Order number and prefix

• Set an optional prefix for your order numbers. This would help you identify all orders generated on your Chargebee site. As mentioned in the note above, once saved, all newly generated orders from then on would have the prefix in their order numbers. 
• Set the number from which order numbering should start. Once set, this cannot be changed in your site.

Generate orders for unpaid invoices

Let's look at an example:

As you can see in the table above, when orders are generated only on invoice payment, the first order date is subject to the date of payment (Jan 25 in our example). When orders are generated for unpaid invoices, the order dates follow the normal order scheduling.

Resend Orders

Shipped goods can sometimes get lost or damaged during their transit. In such cases, you can resend the complete order or specific items in an order instead of canceling the order altogether or providing a refund. You can enable the Resend Orders from Chargebee setting and configure the following:

• Select how many days after resend you want to ship the order: The order gets shipped after the specified number of days from when the order is set to be resent. You can select up to 31 days. You can override this site-wide setting for individual orders while resending the order.
• Choose the maximum number of days after creation that an order can be resent: You can only resend the order till the specified number of days from the order generation.

Late payment

If, in the previous setting, you have chosen to create orders only for paid invoices (whether for some or all invoice statuses), you must also choose what should happen when the payment is late. Late payment means one of two things depending on the scenario:

1. Invoices with single order : Such an invoice would be for a plan that ships only once in its billing cycle.
   Eg. Consider that a monthly plan for a magazine that ships once a month, is subscribed to on Jan 1st. Payment would be late for such an invoice if it happens after the billing cycle: in this case, after Jan 31st. If you are okay with such a late payment, enable For invoices with a single order, generate orders if payment is received after the billing period. Now whenever payment happens, the order would be generated and the order date would be the same as determined during invoicing.
2. Invoices with multiple orders : This kind of an invoice would have multiple orders associated with it. Let's look at an example: Say you have a plan which ships magazine issues every 2 months with a billing period of 4 months. Now say a customer subscribes to this plan on Jan 1st along with a recurring addon for a water can that ships every month.

The order schedule for the invoice would look as follows:

Late payment for such an invoice would be when the payment happens on or after the second order date: in this case, Feb 1.

Enable the option For invoices with multiple orders, generate orders if payment is received on or after the second order date to allow payments for invoices after the second order date. The orders are generated when the payment happens, and the order dates would be the dates when the invoices were created or imported into Chargebee.

Note:
If the toggles for order generation on late payment are disabled, no orders would be generated on late payment for the respective conditions. So when late payments do happen, you may remove them and void the invoices. However, if you wish to retain the payment and fulfill the orders, you would have to create and manage the orders manually in your fulfillment platform.

Shipping date

Every order has a shipping date associated with it. You can choose how this date is determined in Chargebee:

For products that ship every month or year or every so many months or years, you have the following options:

• You can choose the shipping date to be so many days from the order date. OR
• You can choose the shipping date to be a specific day of the month. Choose 31 if you want it to be the last day of the month.
• On choosing the latter, if you want the first order of a new subscription to be shipped immediately instead of on the specified day, you can configure accordingly. Moreover, you can choose to limit this behavior to just gift subscriptions (the first order would be shipped on gift claim instead of on the specific day of the month chosen here).

Similar options are available for products that ship every week or so many weeks.

Note:

If you use Calendar Billing, please ensure that the calendar billing cut-off, shipping date and shipping cut-off settings are aligned to work properly.

Shipping cut-off

Note:
Shipping cut-off is only applicable when orders are generated for paid invoices.

Suppose that you have set orders to be created for invoices only when they get paid. You can select a shipping cut-off for your site. This is used if you are unable to service orders in a month if the payment comes after a certain date in the month. The setting works in tandem with the late payment setting (point 3 on this page) as follows:

If you want to set this cut-off as the last day of the month, choose 31.

Shipping cut-off is not applicable for day/week based shipping-periods and gift subscriptions.

Turn off default time-based proration

When you make mid-term changes to subscriptions in Chargebee, the charges or credits applied can be prorated. However, this proration is done based on the time of use of the service and hence is only suited if you run, say, a SaaS business. Delivery-based proration is currently unsupported in Chargebee.

If you do not sell any services that are billed based on time-of-use, then turn off enabling proration by default for subscription change.

To do this select Settings > Configure Chargebee > Billing LogIQ > Billing Mode > Under Proration Setting, clear the Enable proration for subscription change checkbox.

Once Orders have been enabled, you can select Orders on the left menu to access the orders list page.

Step 2: Configure shipping preferences for plans and addons 

For orders to be created for plans and addons, they must be marked shippable and their shipping frequency must be set. Here's how:

Select Product Catalog > Plans or Addons and select the plan or addon to be configured for shipping and choose Edit Plan or Edit Addon accordingly.

Under Shipping Preference:

• Check the box to mark the product as shippable.
• In the Ship every field, select how often the product is shipped. (Not applicable for non-recurring addons)

Ship every field values are restricted based on the Bill every field value of the plan or addon. The table below explains this:

Note:

• The shipping frequency should be a multiple of billing frequency i.e if billing frequency is 45 days, then shipping frequency can be 1, 3, 5, 9, 15, 45 days.
• The ship every field for a plan/addon is not editable as long as a linked order exists.

Scheduling 

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:

• as soon as the payment is made (for regular subscriptions)
• as soon as gift is claimed (for gift subscriptions)

Order Statuses 

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:

The state diagram below shows how orders transition between statuses. The arrows show the allowed status changes.

Note:
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.

Example:
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.

Actions 

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 fields 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.

• Resend Order: This action allows you to ship the order once again without charging or refunding your customer. You can choose to resend the entire order, or select specific items of the order that you want to resend. Specify a reason for resending the order, and you can even change the shipping date for resending the order if required. Once your select to resend an order, the original order is marked as resent and a new child order is generated. The details page of the original order displays the Resend History for your reference.

• 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.

• Export Orders
  You can also export all order records as a CSV file. There are two ways to do this:

  1. Select Orders on the left menu, the orders list page appears. Filter the orders you need to export. Click on the more options button next to the order search box. Click Export Orders CSV.

     

  2. Another way is to select Settings > Import & Export Data > Export data > Orders. Click on Select criteria to export.

• Bulk Operations
  You can perform operations on multiple orders at once by using Chargebee's bulk operations. Go to Settings > Import & Export Data > Choose a bulk operation > Select Orders under Choose an operation.

  Note: The Create Orders bulk operation is only applicable for the legacy orders system.

Order Fields 

Orders have fields 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 fields are available and editable in all circumstances. However, a field 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 fields).

1. Order status: This field represents the various states that an order can take during its lifecycle in Chargebee.
2. 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. The time component of this field is the same as that of the subscription start timestamp.
3. 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. The time component of this date is always 00:00:00.000.
   More about how order dates and shipping dates are calculated is explained here.
4. 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.
5. 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.
6. 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.
7. 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.
8. 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.
9. Tracking Id: The shipment tracking Id. Usually obtained from the order management system or the integration platform. This field cannot be captured/edited for orders in queued status.
10. Tracking URL: The shipment tracking URL which is usually obtained from the order management system or the integration platfrom. When multiple shipments are added to the order, tracking URL can be added and tracked for each shipment respectively. This field cannot be captured/edited for orders in queued status.
11. Batch Id: The shipment batch Id. Usually obtained from the order management system or the integration platform. This field cannot be captured/edited for orders in queued status.
12. Reference Id: This Id is used to hold the unique Id of the order in the external system or integration platform. This field cannot be captured/edited for orders in queued status.
13. Shipment carrier: The shipment carrier details. Usually obtained from the order management system or the integration platform. This field cannot be captured/edited for orders in queued status.
14. 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.
15. 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.
16. 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.
17. Resend History: For orders that are resent, this tab displays the resend details. The child orders that are created for every resend, are tagged as partially resent or fully resent, based on the whether select items of the order or the entire order was resent.

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 protected]  to help enable it.

FAQ 

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):

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:

1. Enable calendar billing with

   • Calendar billing date: 25th
   • Billing cutoff date: 15th

2. 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.