Orders

API Version

Product Catalog

Library

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

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

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

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

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

reference_id

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

This API is used to retrieve an order.

Sample Request

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v1/orders \
     -u {site_api_key}:\
     -d invoice_id="__demo_inv__2"

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "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

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

reference_id[]

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.

order

always returned
Resource object representing 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

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v1/orders/__test__5SK0bLNFRFuCD1gLa \
     -u {site_api_key}:\
     -d status="PROCESSING"

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "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}

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, default=new
The order status.

Possible values are

shipping_address

Parameters for shipping_address
pass parameters as shipping_address[<param name>]

shipping_address[first_name]

optional, string, max chars=150

shipping_address[last_name]

optional, string, max chars=150

shipping_address[email]

optional, string, max chars=70

shipping_address[company]

optional, string, max chars=250

shipping_address[phone]

optional, string, max chars=50

shipping_address[line1]

optional, string, max chars=150

shipping_address[line2]

optional, string, max chars=150

shipping_address[line3]

optional, string, max chars=150

shipping_address[city]

optional, string, max chars=50

shipping_address[state_code]

optional, string, max chars=50

shipping_address[state]

optional, string, max chars=50

shipping_address[zip]

optional, string, max chars=20

shipping_address[country]

optional, string, max chars=50

order

always returned
Resource object representing order

Retrieves an order corresponding to the order id passed.

Sample Request

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v1/orders/1 \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "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}

order

always returned
Resource object representing order

Sample admin console URL

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

This API is used to retrieve a list of all the available orders.

Sample Request

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v1/orders \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=3

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "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

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.

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

Retrieves the orders corresponding to an invoice, with the latest ones on top.

Sample Request

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v1/invoices/__demo_inv__2/orders \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "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

limit[]

optional, integer, default=10, min=1, max=100
The number of resources to be returned.

offset[]

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

Sample order [ JSON ]

API Index URL

Model Class

Order attributes

Consent Fields for Order

Custom Fields for Order

Create an order ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Update an order ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Retrieve an order ¶

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

List orders ¶

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

List orders for an invoice ¶

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL