Docs

Support
Home Billing Payments Receivables RevRec Retention
Billing
Home
Billing
Payments
Receivables
RevRec
Retention
API Reference
Release Notes
Tutorials
Frontend Capabilities
API Changelog
API Reference
Release Notes
Tutorials
Frontend Capabilities
API Changelog

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 once 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 and 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 the shipping date of the magazine, the quantity to be shipped, the shipment's share of the invoice amount, status of order processing, tracking URL, and so on.

Once the orders have been created, you can manage them in the following ways:

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

Key Features 

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

  • Creates orders (shipment entities) automatically based on your site configuration.
  • Allows you to tailor shipping schedules to your needs.
  • Integrates with your order management system via API and webhooks.
  • Integrates with ShipStation to manage and fulfill the orders.
  • Assists in revenue recognition by allowing you to record the delivery status of goods.
  • Helps in inventory management by recording the number of goods for each 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, addons, and charges : these settings apply at the plan, addon, or charge level. For each plan, addon, charge price point, you have to specify how frequently shipments are sent to the subscriber.

Note:
Orders for gift subscriptions are generated only on gift claim.

Step 1: Configure site-wide Settings 

Click Settings > Configure Chargebee > Billing LogIQ > Customers & Subscriptions > 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

Enabled Disabled

Orders are generated immediately when the invoice (including imported invoices) enters any of the selected unpaid statuses.

 Orders are generated for the invoice (including imported invoices), only when the invoice status becomes paid.
Used when you don't want orders creation to be stalled till the customer pays. Typically used when your customers are businesses who pay within a term or Net D. Used when you wish to ensure that orders are created only after the customer has paid in full. Used for most consumer products/services where payments are expected immediately.

You must specify the invoice statuses for which the setting is applicable: select one or more of payment due, posted and not paid statuses. 

 NA



Let's look at an example:

Consider... A plan with billing period of 4 months that ships a magazine issue every month.
Say a subscription to it starts on Jan 1
and the payment is made on Jan 25
The toggle "Generate orders for unpaid invoices" is: Enabled Disabled

Order date for order # 1

Order date for order # 2

Order date for order # 3

Order date for order # 4

Jan 1

Feb 1

Mar 1

Apr 1

Jan 25

Feb 1

Mar 1

Apr 1



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:

Order # Order date Items
1 Jan 1

Magazine + Water can
2 Feb 1 Water can
3 Mar 1

Magazine + Water can
4 Apr 1 Water can



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:


 For invoices with a single order For invoices with multiple orders 

Sample plan

A monthly plan that ships a magazine issue every month.

A plan with a 4 month billing period, shipping a magazine every month.
Shipping cut-off setting 20th
Subscription start date Jan 1st
Payment date

Jan 23rd

 March 3rd Jan 23rd March 3rd
Generate orders on late payment (Setting 3 on this page) Disabled  Enabled Disabled Enabled
Effect on order(s) The order is cancelled and a refundable credit note is raised for the order amount. The order is cancelled and a refundable credit note is raised for the order amount.

The first order is cancelled and a refundable credit note is raised for the order amount.

 The first 2 orders (order dates Jan 1st and Feb 1st) are cancelled and refundable credit notes are raised for their order amounts. The order for March is not cancelled as its shipping cut off (Mar 20th) has not been overstepped.



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, addons, and charges 

For orders to be created for plans and addons, they must be marked shippable and their shipping frequency must be set.

To display fields to specify if a product is shippable and collect shipping frequency at the plan and addon level, click Settings > Configure Chargebee > Billing LogIQ > Customers & Subscriptions > Shipping Fields > Enable.

Shipping fields get added to your plans and addons. To add their shipping preferences, follow these steps:

  1. Click Product Catalog > Plans/Addons/Charge, select the plan or addon or charge to be configured for shipping and select Edit Plan/Addon/Charge accordingly.

  2. In the Shipping Preference section, select the box to mark the product as shippable.

  3. Click Save.

  4. You can now add shipping frequency for each price point under the plan or addon. Select the price point, click Edit.

  5. In the Ships every field, select how often the product is shipped.

Note

The Ships every field is not applicable to charges, since charges are non-recurring.

Ship every field value is restricted based on the billing frequency of the plan or addon price point. The table below explains this:

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

SHIPPING FREQUENCY
BILLING FREQUENCY Years Months Weeks Days
Years Yes Yes No No
Months No Yes No No
Weeks No No Yes No
Days No No No Yes

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:

See also

How Payments and Credits are linked to Orders.

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

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:

Order status Description
Queued 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.
Awaiting shipment Used to indicate that the orders have been moved to the integration platform/external fulfillment system.
On-hold Indicates that the order processing has been put on hold.
Cancelled Indicates that the order has been cancelled.
Shipped The order is in transit.
Partially delivered The order is only partially delivered.
Delivered The order has been delivered.
Returned The order has been returned after delivery

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

Note:
The arrow inside the central box only shows 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 the status of an order, several actions can be performed on orders from the user interface.

  • Edit order details: This action will help you change details like order status, shipping date, and order date. 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.
    Note: This action is applicable to an order that was previously canceled.
    You can choose to resend the entire order or select specific items of the order that you want to resend. Selection of a Reason to resend the order is mandatory.
    Click Change if you wish to change the shipping date.
    Once you select to resend the order, the original order is marked as resent and a new associated child order is generated.

  • 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: This action is applicable to an order that was previously canceled.
    This action sets the order status to the same as that before cancellation. Depending on the refundable credit credits, the prompts will change.

  • 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 does not exist then the order re-opened with the previous payment.

  • 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 the more options button next to the order search box. Click Export as 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.

    1. Go to Settings > Import & Export Data > Choose a bulk operation.

    2. Select Orders from the Choose an operation drop-down list.

    3. Select the applicable action and click Proceed.

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

See also

Impacts of external actions in Chargebee on orders.

Note
  • The resend order action is not available when the order is in Queued status.
  • The resend order action is available only for a limited number of days as specified in the site-wide settings.
  • While resending an order, you can not send more than the original quantity of the item.
  • Orders in Awaiting shipment status that are fully resent get canceled automatically. Orders in other statuses that are being resent can be canceled manually if required.

Order Fields 

Note

For all timestamp fields mentioned here, the time component cannot be set by you if Chargebee is running on day-based billing mode. The implied time for the fields in such a case would be 00:00:00.000 hrs.

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 identify 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 platform. 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. Child orders that are created for every resend are listed here, and tagged as partially resent or fully resent, based on the whether select items of the order or the entire order was resent.
Cancellation Reason Can be manually chosen Can be system generated
Shipping cut off passed No Yes
Product unsatisfactory Yes No
3rd-party cancellation Yes No
Product not available Yes No
Product not required Yes No
Delivery date issue Yes No
Fraudulent transaction Yes No
Payment declined Yes No
Other better alternatives Yes No
Invoice voided No Yes
Invoice written-off Yes Yes
Subscription cancelled Yes No
Others Yes No

Events & Webhooks 

Events  in Chargebee also include order-related events . You can configure webhooks to notify your application of such events.

FAQs 

1) 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.

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

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

Sign-up Period Shipping Day for the First Issue
1st - 10th 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:

  1. Enable calendar billing with

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

  2. Configure Chargebee Orders as:

    • Shipping date: 10th
    • Shipping cutoff: 15th

4) 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.

5) I'm cancelling a subscription, how can I ensure that the unfulfilled orders alone are refunded?

See this FAQ.

Was this article helpful?
Loading…