You are viewing the documentation for the older version of our API (V1). Click here for information on upgrading to the latest version (V2).

The Order resource can be used for integrating Chargebee with any shipping/order management application (like ShipStation)

Orders are not automatically generated or updated by Chargebee currently. They have to be created/updated either via api or merchant web console (a.k.a admin console).

An order can be created against an invoice irrespective of the status of the invoice and an invoice can have multiple orders associated with it.

Sample order [ JSON ]

{ "id": "XpbG8t4OvwWgjzM", "invoice_id": "1", "status": "new", "reference_id": "1002", "fulfillment_status": "Awaiting Shipment", "note": "This is a test note", "created_at": 1484646413, "status_update_at": 1484646413, "object": "order" }

API Index URL GET

https://{site}.chargebee.com/api/v1/orders
id
Uniquely identifies the order. It is the api identifier for the order.
string, max chars=40
invoice_id
The invoice number which acts as an identifier for invoice and is generated sequentially.
optional, string, max chars=50
status
The status of this order.
optional, enumerated string, default=new
Possible values are
newOrder has been created. Applicable only if you are using Chargebee's legacy order management system.processingOrder is being processed. Applicable only if you are using Chargebee's legacy order management system.completeOrder has been processed successfully. Applicable only if you are using Chargebee's legacy order management system.cancelledOrder has been cancelled. Applicable only if you are using Chargebee's legacy order management system.voidedOrder has been voided. Applicable only if you are using Chargebee's legacy order management system.
reference_id
Reference id can be used to map the orders in the shipping/order management application to the orders in ChargeBee. The reference_id generally is same as the order id in the third party application.
optional, string, max chars=50
fulfillment_status
The fulfillment status of an order as reflected in the shipping/order management application. Typical statuses include Shipped,Awaiting Shipment,Not fulfilled etc;.
optional, string, max chars=50
note
The custom note for the order.
optional, string, max chars=600
tracking_id
The tracking id of the order.
optional, string, max chars=50
batch_id
Unique id to identify a group of orders.
optional, string, max chars=50
created_by
The source (or the user) from where the order has been created.
optional, string, max chars=50
created_at
The time at which the order was created.
timestamp(UTC) in seconds
status_update_at
The time at which the order status was last updated.
optional, timestamp(UTC) in seconds
currency_code
The currency code (ISO 4217 format) for the invoice.
optional, string, max chars=3
Creates an order for an invoice. If 'status' is not passed while creating an order, the default status('new') is set. This api endpoint is only applicable if you are using Chargebee's legacy order management system.
Sample Request
curl  https://{site}.chargebee.com/api/v1/orders \
     -u {site_api_key}: \
     -d invoice_id="1"
copy
curl  https://{site}.chargebee.com/api/v1/orders \
     -u {site_api_key}: \
     -d invoice_id="1"

Sample Response [ JSON ]

{"order": { "id": "3Nl8YTUQ8YbQdU7L", "invoice_id": "1", "status": "new", "created_by": "full_access_key_v1", "created_at": 1484646503, "status_update_at": 1484646503, "object": "order" }}

URL Format POST

https://{site}.chargebee.com/api/v1/orders
id
Uniquely identifies the order. If not given, this will be auto-generated.
optional, string, max chars=40
invoice_id
The invoice number which acts as an identifier for invoice and is generated sequentially.
required, string, max chars=50
status
The order status.
optional, enumerated string
Possible values are
newOrder has been created. Applicable only if you are using Chargebee's legacy order management system.processingOrder is being processed. Applicable only if you are using Chargebee's legacy order management system.completeOrder has been processed successfully. Applicable only if you are using Chargebee's legacy order management system.cancelledOrder has been cancelled. Applicable only if you are using Chargebee's legacy order management system.voidedOrder has been voided. Applicable only if you are using Chargebee's legacy order management system.
reference_id
Reference id can be used to map the orders in the shipping/order management application to the orders in ChargeBee. The reference_id generally is same as the order id in the third party application.
optional, string, max chars=50
fulfillment_status
The fulfillment status of an order as reflected in the shipping/order management application. Typical statuses include Shipped,Awaiting Shipment,Not fulfilled etc;.
optional, string, max chars=50
note
The custom note for the order.
optional, string, max chars=600
tracking_id
The tracking id of the order.
optional, string, max chars=50
batch_id
Unique id to identify a group of orders.
optional, string, max chars=50
Resource object representing order.
always returned
Updates an order. If the status of an order is changed while updating the order, the status_update_at attribute is set with the current time.
Sample Request
curl  https://{site}.chargebee.com/api/v1/orders/XpbG8t4OvwWgjzM \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v1/orders/XpbG8t4OvwWgjzM \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{"order": { "id": "XpbG8t4OvwWgjzM", "invoice_id": "1", "status": "processing", "reference_id": "1002", "fulfillment_status": "Awaiting Shipment", "note": "This is a test note", "created_at": 1484646413, "status_update_at": 1484646503, "object": "order" }}

URL Format POST

https://{site}.chargebee.com/api/v1/orders/{order_id}
reference_id
Reference id is the unique identifier of the order in the shipping/order management application.
optional, string, max chars=50
batch_id
Unique id to identify a group of orders.
optional, string, max chars=50
note
The custom note for the order.
optional, string, max chars=600
tracking_id
The tracking id of the order.
optional, string, max chars=50
fulfillment_status
The fulfillment status of an order as reflected in the shipping/order management application. Typical statuses include Shipped,Awaiting Shipment,Not fulfilled etc;.
optional, string, max chars=50
status
The order status.
optional, enumerated string
Possible values are
newOrder has been created. Applicable only if you are using Chargebee's legacy order management system.processingOrder is being processed. Applicable only if you are using Chargebee's legacy order management system.completeOrder has been processed successfully. Applicable only if you are using Chargebee's legacy order management system.cancelledOrder has been cancelled. Applicable only if you are using Chargebee's legacy order management system.voidedOrder has been voided. Applicable only if you are using Chargebee's legacy order management system.
shipping_address
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
shipping_address[first_name]
First name.
optional, string, max chars=150
shipping_address[last_name]
Last name.
optional, string, max chars=150
shipping_address[email]
Email.
optional, string, max chars=70
shipping_address[company]
Company name.
optional, string, max chars=250
shipping_address[phone]
Phone number.
optional, string, max chars=50
shipping_address[line1]
Address line 1.
optional, string, max chars=180
shipping_address[line2]
Address line 2.
optional, string, max chars=150
shipping_address[line3]
Address line 3.
optional, string, max chars=150
shipping_address[city]
City.
optional, string, max chars=50
shipping_address[state_code]
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set the state_code as AZ (not US-AZ). or, for Tamil Nadu (India), set the state_code as TN (not IN-TN). or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50
shipping_address[state]
The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50
shipping_address[zip]
Zip or Postal code.
optional, string, max chars=20
shipping_address[country]
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
Resource object representing order.
always returned
Retrieves an order corresponding to the order id passed.
Sample Request
curl  https://{site}.chargebee.com/api/v1/orders/XpbG8t4OvwWgjzM \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v1/orders/XpbG8t4OvwWgjzM \
     -u {site_api_key}:

Sample Response [ JSON ]

{"order": { "id": "XpbG8t4OvwWgjzM", "invoice_id": "1", "status": "processing", "reference_id": "1002", "fulfillment_status": "Awaiting Shipment", "note": "This is a test note", "created_at": 1484646413, "status_update_at": 1484646503, "object": "order" }}

URL Format GET

https://{site}.chargebee.com/api/v1/orders/{order_id}
Resource object representing order.
always returned

Sample admin console URL

https://{site}.chargebee.com/admin-console/orders/XpbG8t4OvwWgjzM
Lists the available orders.
Sample Request
curl  https://{site}.chargebee.com/api/v1/orders \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5"
copy
curl  https://{site}.chargebee.com/api/v1/orders \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5"

Sample Response [ JSON ]

{ "list": [ {"order": { "id": "3Nl8YTUQ8YbQdU7L", "invoice_id": "1", "status": "new", "created_by": "full_access_key_v1", "created_at": 1484646503, "status_update_at": 1484646503, "object": "order" }}, {..} ], "next_offset": "[\"1484646503000\",\"145000000005\"]" }

URL Format GET

https://{site}.chargebee.com/api/v1/orders
limit
Limits the number of resources to be returned.
optional, integer, default=10, min=1, max=100
offset
Allows you to fetch the next set of resources. The value used for this parameter must be the value returned for next_offset parameter in the previous API call.
optional, string, max chars=1000
Resource object representing order.
always returned
next_offset
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter “offset”.
optional, string, max chars=1000
Retrieves the orders corresponding to an invoice, with the latest ones on top.
Sample Request
curl  https://{site}.chargebee.com/api/v1/invoices/1/orders \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5"
copy
curl  https://{site}.chargebee.com/api/v1/invoices/1/orders \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5"

Sample Response [ JSON ]

{ "list": [ {"order": { "id": "3Nl8YTUQ8YbQdU7L", "invoice_id": "1", "status": "new", "created_by": "full_access_key_v1", "created_at": 1484646503, "status_update_at": 1484646503, "object": "order" }}, {..} ], "next_offset": "[\"1484646503000\",\"145000000005\"]" }

URL Format GET

https://{site}.chargebee.com/api/v1/invoices/{invoice_id}/orders
limit
Limits the number of resources to be returned.
optional, integer, default=10, min=1, max=100
offset
Allows you to fetch the next set of resources. The value used for this parameter must be the value returned for next_offset parameter in the previous API call.
optional, string, max chars=1000
Resource object representing order.
always returned
next_offset
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter “offset”.
optional, string, max chars=1000