Orders

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": 1528093635, "status_update_at": 1528093635, "object": "order" }

API Index URL GET

https://{site}.chargebee.com/api/v2/orders

Order attributes

id
Uniquely identifies the order.
string, max chars=40
invoice_id
The invoice number which acts as an identifier for invoice and is generated sequentially.
string, max chars=50
status
The status of this order.
optional, enumerated string, default=new
Possible values are
newOrder has been created.processingOrder is being processed.completeOrder has been processed successfully.cancelledOrder has been cancelled.voidedOrder has been voided.
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=250
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

Create an order

Creates an order for an invoice. If 'status' is not passed while creating an order, the default status('new') is set.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/orders \
     -u {site_api_key}: \
     -d invoice_id="1"
copy
curl  https://{site}.chargebee.com/api/v2/orders \
     -u {site_api_key}: \
     -d invoice_id="1"

Sample Response [ JSON ]

{"order": { "id": "5SK0b8q3QtyveuP54", "invoice_id": "1", "status": "new", "created_by": "full_access_key_v1", "created_at": 1528093753, "status_update_at": 1528093753, "object": "order" }}

URL Format POST

https://{site}.chargebee.com/api/v2/orders

Input Parameters

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 status of this order.
optional, enumerated string, default=new
Possible values are
newOrder has been created.processingOrder is being processed.completeOrder has been processed successfully.cancelledOrder has been cancelled.voidedOrder has been voided.
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=250
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

Returns

order
Resource object representing order.
always returned

Update an order

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/v2/orders/XpbG8t4OvwWgjzM \
     -u {site_api_key}: \
     -d status="processing"
copy
curl  https://{site}.chargebee.com/api/v2/orders/XpbG8t4OvwWgjzM \
     -u {site_api_key}: \
     -d status="processing"

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": 1528093635, "status_update_at": 1528093753, "object": "order" }}

URL Format POST

https://{site}.chargebee.com/api/v2/orders/{order_id}

Input Parameters

status
The status of this order.
optional, enumerated string
Possible values are
newOrder has been created.processingOrder is being processed.completeOrder has been processed successfully.cancelledOrder has been cancelled.voidedOrder has been voided.
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=250
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

Returns

order
Resource object representing order.
always returned

Retrieve an order

Retrieves an order corresponding to the order id passed.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/orders/XpbG8t4OvwWgjzM \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/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": 1528093635, "status_update_at": 1528093753, "object": "order" }}

URL Format GET

https://{site}.chargebee.com/api/v2/orders/{order_id}

Returns

order
Resource object representing order.
always returned

Sample admin console URL

https://{site}.chargebee.com/admin-console/orders/XpbG8t4OvwWgjzM

List orders

Lists the available orders.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/orders \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5" \
     --data-urlencode status[is]="processing" \
     --data-urlencode sort_by[asc]="created_at"
copy
curl  https://{site}.chargebee.com/api/v2/orders \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5" \
     --data-urlencode status[is]="processing" \
     --data-urlencode sort_by[asc]="created_at"

Sample Response [ JSON ]

{ "list": [ {"order": { "id": "5SK0b8q3QtyveuP54", "invoice_id": "1", "status": "new", "created_by": "full_access_key_v1", "created_at": 1528093753, "status_update_at": 1528093753, "object": "order" }}, {..} ], "next_offset": "[\"1528093753000\",\"214000000003\"]" }

URL Format GET

https://{site}.chargebee.com/api/v2/orders

Input Parameters

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
sort_by[<sort-order>]
Sorts based on the specified attribute.
Supported attributes : created_at
Supported sort-orders : asc, desc

Example → sort_by[asc] = "created_at"
This will sort the result based on the 'created_at' attribute in ascending(earliest first) order.
optional, string filter
Filter Params
For operator usages, see the Pagination and Filtering section.
id[<operator>]
To filter based on Order Id.
Supported operators : is, is_not, starts_with, in, not_in

Example → id[is] = "890"
optional, string filter
invoice_id[<operator>]
To filter based on Order Invoice Id.
Supported operators : is, is_not, starts_with, in, not_in

Example → invoice_id[is] = "INVOICE_982"
optional, string filter
status[<operator>]
To filter based on Order Status. Possible values are : new, processing, complete, cancelled, voided.
Supported operators : is, is_not, in, not_in

Example → status[is] = "processing"
optional, enumerated string filter
created_at[<operator>]
To filter based on Order Created At.
Supported operators : after, before, on, between

Example → created_at[after] = "1435054328"
optional, timestamp(UTC) in seconds filter

Returns

order
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