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

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 ]

{ "created_at": 1517679533, "created_by": "full_access_key_v1", "id": "__test__5SK0bLNFRFuCBmQJV", "invoice_id": "__demo_inv__2", "object": "order", "status": "new", "status_update_at": 1517679533 }

API Index URL GET

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

Order attributes

id
string, max chars=40
Uniquely identifies the order. It is the api identifier for the order
invoice_id
optional, string, max chars=50
The invoice number which acts as an identifier for invoice and is generated sequentially.
status
optional, enumerated string, default=new
The status of this order.
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
optional, string, max chars=50
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.
fulfillment_status
optional, string, max chars=50
The fulfillment status of an order as reflected in the shipping/order management application. Typical statuses include Shipped,Awaiting Shipment,Not fulfilled etc;
note
optional, string, max chars=600
The custom note for the order.
tracking_id
optional, string, max chars=50
The tracking id of the order.
batch_id
optional, string, max chars=50
Unique id to identify a group of orders.
created_by
optional, string, max chars=50
The source (or the user) from where the order has been created.
created_at
timestamp(UTC) in seconds
The time at which the order was created
status_update_at
optional, timestamp(UTC) in seconds
The time at which the order status was last updated.
currency_code
optional, string, max chars=3
The currency code (ISO 4217 format) for the invoice

Create an order

Idempotency Supported
This API is used to retrieve an order.
Sample Request 
curl  https://{site}.chargebee.com/api/v1/orders \
     -u {site_api_key}:\
     -d invoice_id="__demo_inv__2"
copy
curl  https://{site}.chargebee.com/api/v1/orders \
     -u {site_api_key}:\
     -d invoice_id="__demo_inv__2"

Sample Response [ JSON ]

Show more...
{"order": { "created_at": 1517679533, "created_by": "full_access_key_v1", "id": "__test__5SK0bLNFRFuCBmQJV", "invoice_id": "__demo_inv__2", "object": "order", "status": "new", "status_update_at": 1517679533 }}

URL Format POST

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

Input Parameters

id
optional, string, max chars=40
Uniquely identifies the order. If not given, this will be auto-generated.
invoice_id
required, string, max chars=50
The invoice number which acts as an identifier for invoice and is generated sequentially.
status
optional, enumerated string
The order status.
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 systemcompleteOrder has been processed successfully. Applicable only if you are using Chargebee's legacy order management systemcancelledOrder has been cancelled. Applicable only if you are using Chargebee's legacy order management systemvoidedOrder has been voided. Applicable only if you are using Chargebee's legacy order management system
reference_id
optional, string, max chars=50
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.
fulfillment_status
optional, string, max chars=50
The fulfillment status of an order as reflected in the shipping/order management application. Typical statuses include Shipped,Awaiting Shipment,Not fulfilled etc;.
note
optional, string, max chars=600
The custom note for the order.
tracking_id
optional, string, max chars=50
The tracking id of the order.
batch_id
optional, string, max chars=50
Unique id to identify a group of orders.

Returns

order
always returned
Resource object representing order

Update an order

Idempotency Supported
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/__test__5SK0bLNFRFuCD1gLa \
     -X POST  \
     -u {site_api_key}:\
     -d status="processing"
copy
curl  https://{site}.chargebee.com/api/v1/orders/__test__5SK0bLNFRFuCD1gLa \
     -X POST  \
     -u {site_api_key}:\
     -d status="processing"

Sample Response [ JSON ]

Show more...
{"order": { "created_at": 1517679538, "created_by": "full_access_key_v1", "id": "__test__5SK0bLNFRFuCD1gLa", "invoice_id": "__demo_inv__2", "object": "order", "status": "processing", "status_update_at": 1517679538 }}

URL Format POST

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

Input Parameters

reference_id
optional, string, max chars=50
Reference id is the unique identifier of the order in the shipping/order management application.
batch_id
optional, string, max chars=50
Unique id to identify a group of orders.
note
optional, string, max chars=600
The custom note for the order.
tracking_id
optional, string, max chars=50
The tracking id of the order.
fulfillment_status
optional, string, max chars=50
The fulfillment status of an order as reflected in the shipping/order management application. Typical statuses include Shipped,Awaiting Shipment,Not fulfilled etc;.
status
optional, enumerated string
The order status.
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 systemcompleteOrder has been processed successfully. Applicable only if you are using Chargebee's legacy order management systemcancelledOrder has been cancelled. Applicable only if you are using Chargebee's legacy order management systemvoidedOrder 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]
optional, string, max chars=150
The first name of the contact.
shipping_address[last_name]
optional, string, max chars=150
The last name of the contact.
shipping_address[email]
optional, string, max chars=70
The email address.
shipping_address[company]
optional, string, max chars=250
The company name.
shipping_address[phone]
optional, string, max chars=50
The phone number.
shipping_address[line1]
optional, string, max chars=150
Address line 1
shipping_address[line2]
optional, string, max chars=150
Address line 2
shipping_address[line3]
optional, string, max chars=150
Address line 3
shipping_address[city]
optional, string, max chars=50
The name of the city.
shipping_address[state_code]
optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
shipping_address[state]
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
shipping_address[zip]
optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.
shipping_address[country]
optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Note: If you enter an invalid country code, the system will return an error.

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.

Returns

order
always returned
Resource object representing order

Retrieve an order

Retrieves an order corresponding to the order id passed.
Sample Request 
curl  https://{site}.chargebee.com/api/v1/orders/1 \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v1/orders/1 \
     -u {site_api_key}:

Sample Response [ JSON ]

Show more...
{"order": { "created_at": 1517506737, "created_by": "Auto generated by system", "currency_code": "USD", "id": "1", "invoice_id": "__demo_inv__1", "object": "order", "status": "queued" }}

URL Format GET

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

Returns

order
always returned
Resource object representing order

Sample admin console URL

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

List orders

This API is used to retrieve a list of all the available orders.
Sample Request 
curl  https://{site}.chargebee.com/api/v1/orders \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=3
copy
curl  https://{site}.chargebee.com/api/v1/orders \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=3

Sample Response [ JSON ]

Show more...
{"list": [ {"order": { "created_at": 1517506735, "created_by": "Auto generated by system", "currency_code": "USD", "id": "1", "invoice_id": "__demo_inv__1", "object": "order", "status": "queued" }}, {..} ]}

URL Format GET

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

Input Parameters

limit
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
offset
optional, string, max chars=1000
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.

Returns

order
always returned
Resource object representing order
next_offset
optional, string, max chars=1000
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”.

List orders for an invoice

Retrieves the orders corresponding to an invoice, with the latest ones on top.
Sample Request 
curl  https://{site}.chargebee.com/api/v1/invoices/__demo_inv__2/orders \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2
copy
curl  https://{site}.chargebee.com/api/v1/invoices/__demo_inv__2/orders \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2

Sample Response [ JSON ]

Show more...
{"list": [ {"order": { "created_at": 1517679534, "created_by": "full_access_key_v1", "id": "__test__5SK0bLNFRFuCC7aK4", "invoice_id": "__demo_inv__2", "object": "order", "status": "new", "status_update_at": 1517679534 }}, {..} ]}

URL Format GET

https://{site}.chargebee.com/api/v1/invoices/{invoice_id}/orders

Input Parameters

limit
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
offset
optional, string, max chars=1000
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.

Returns

order
always returned
Resource object representing order
next_offset
optional, string, max chars=1000
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”.