# Order APIs for Checkout
Order APIs for transition of draft order to completed during a checkout.
Last updated: **11-Jun-2024**
Version: **v0.4**
Updated:
- Get order response body, `upsell_product_list` field
- Get order response body, including response after complete order
- API use default domain and shop token
- Remove address company field
- Remove total amount
- Add checkout_id to order create api
- Rename paid_by to payment_gateway
- Add more discount code fields and scenario
- Add updated_at field
---
### R1. Create order
Create a new draft order.
- cart_token: (string) a cart_token also represents a customer, which could have multiple orders
```json
Request:
POST https://{{default_domain}}/api/order
Header: x-shop-token
Body:
{
"checkout_id": "ic_d2cc2ed5a8c6e1d51eb586a2",
"cart_token": "bfcb14324d2cc2ed5a8c6e1d51eb586a",
"cart_type" : 1 , // 购物车类型 1 正常购物车 2立即购买
// "email": "" // optional
}
Response:
200 (OK)
{
"id": "240311160051709", // the most recent incomplete order
"cart_token": "bfcb14324d2cc2ed5a8c6e1d51eb586a", // same cart token
...
"completed": false,
"updated_at": "2024-asdsad03-01T13:01:00Z" // last updated
}
```
### R2. Get order
Get an order details.
```json
Request:
GET https://{{default_domain}}/api/order/:order_id
Header: x-shop-token
Response:
200 (OK)
{
"id":"240513181356740", // Xshop order id
"email":"test-buyer@intercart.io", // Intercart input
"amount":1009.8, //订单金额
"currency": "USD",
"remark":"",
"weight":"0.00",
"cartType":1, //购物车类型
"cart_token":"1ecc1c9a073ac52a54b1e2cfb8549dd6", // Xshop cart token
"hasInvalid":false,
"hasRemoved":false,
"is_diy_tax":0, // 0 非定制 1定制
"tax_amount":0, //税费
"updated_at":"2024-05-13T18:21:14Z",
"checkout_id":"coclw4t3w960001y2g02qu1dii9", // Intercart checkout id
"coupon_type":0, //优惠券类型
"hasLoweroff":false,
"tips_amount":"1.8", // Intercart input
"weight_gram":0,
"goods_amount":"1000.00", //总商品金额, 不包括upseller_list 里面的
"order_amount":"1009.80", //订单金额
"product_list":[ // line items
{
"key":"",
"upc":"",
"utm":"",
"sort":0,
"spec":"[]", //sku 属性
"grams":"0",
"image":{
"new":[
],
"file_preview_resize":"?x-oss-process=image/resize,w_120" //预览图
},
"price":"1000.00", //商品单价
"title":"", //商品标题
"is_del":"0",
"sku_id":"157309", //sku id
"weight":"0.00", //重量
"is_show":"0",
"item_id":"d262c5757c437416d1317cd7bb78bce2",
"new_add":1, //1 最新添加
"options":"",
"shop_id":"197", //店铺id
"sort_by":1715595075.887101,
"image_id":"0", //图片id
"is_lower":0,
"quantity":1, //数量
"sku_code":"11", //sku码
"attribute":[
], //属性
"coupon_id":0, //匹配到的梯度优惠
"is_remove":0,
"unique_id":"6642d3271287e",
"created_at":"2024-05-08 11:43:34",
"data_price":"1000.00",
"is_checked":"1",
"is_invalid":0,
"product_id":"18243",
"properties":"",
"updated_at":"2024-05-08 11:43:34",
"add_to_cart":"2024-05-13 18:11:15",
"is_discount":0,
"preview_url":"/products/car", //商品hander 例如 www.baidu.com/products/hannder
"weight_unit":"g", //重量单位
"coupon_label":"", //优惠券内容
"is_use_stock":"0",
"shipping_fee":"0.00", //运费
"image_tmp_url":"",
"is_limitoffer":0,
"new_customize":"",
"product_stock":100000,
"product_title":"Car",
"product_amount":1000, /
"soldout_policy":"Y",
"total_quantity":1, //总数量
"customize_price":0,
"is_input_number":1,
"product_handler":"car",
"compare_at_price":"2000.00", //原价售价
"insurance_amount":0,
"limitoffer_label":0,
"product_discount":0,
"requires_shipping":"0",
"inventory_quantity":100000,
"is_set_default_img":"0",
"data_compare_at_price":"0.00",
"is_meet_discount_offer":0,
"limitoffer_product_total":0,
"meet_discount_offer_text":"",
"limitoffer_product_discount_total":0
}
],
"total_amount":"1009.80",
"coupon_detail":[
],
"express_title":"",
"shipping_line":{ // Intercart input
"price":"8",
"title":"Standard Shipping"
},
"upsell_amount":0,
"amount_product":"1000.00", // 购物车 + upseller_list 里面的price
"insurance_rate":0,
"amount_discount":0,
"billing_address":{ // Intercart input
"zip":"",
"city":"cc",
"phone":"1231231234",
"country":"United States",
"address1":"AIA Tower",
"address2":"bb",
"province":"New York",
"last_name":"buyer",
"first_name":"test",
"country_code":"US",
"province_code":"NY"
},
"payment_gateway":"stripe", // Intercart settings
"add_payment_info":true, // Intercart input
"amount_logistics":"8",
"express_discount":0,
"insurance_amount":"0.00",
"product_discount":0,
"shipping_address":{ // Intercart input
"zip":"",
"city":"cc",
"phone":"1231231234",
"country":"United States",
"address1":"AIA Tower",
"address2":"bb",
"province":"New York",
"last_name":"buyer",
"first_name":"test",
"country_code":"US",
"province_code":"NY"
},
"coupon_error_code":0,
"notEnoughInventory":false,
"amount_product_ceil":1000,
"discount_code_error":"",
"coupon_gifts_collect":"",
"productCustomizeInfo":[
],
"billing_same_as_shipping":false, // Intercart input
"discount_code": "V2Q7H3", // Intercart input
"upsell_list": [...], // Intercart input, same as Update order input
"upsell_product_list": [ // line items by upsell, fields same as product_list
{
"id": "pocll1ybewi04a5ayg0aa53314k", // upsell_list input
"product_id": "18242", // upsell_list input
"sku_id": "157308", // upsell_list input
"quantity": 1, // upsell_list input
"discount_type": "percentage", // upsell_list input
"discount_value": "30", // upsell_list input
"price": "10.00",
"product_amount": 10, // result
"discount_amount": 3, // result
"amount": 7, // result
"shop_id": "197",
"item_id": "5953f567eab8e3d105261a1495b019bc",
"unique_id": "66715a028b30c",
"is_limitoffer": 0,
"limitoffer_label": 0,
"limitoffer_product_total": 0,
"limitoffer_product_discount_total": 0,
"coupon_label": "",
"product_title": "Test Product 1",
"product_handler": "test-product-1",
"sku_code": "",
"title": "",
"spec": "",
"data_price": "10.00",
"compare_at_price": "20.00",
"data_compare_at_price": "0.00",
"options": "",
"grams": "0",
"weight": "0.00",
"weight_unit": "g",
"image_id": "106053",
"image": {
"file_key": "uploader/9080479ed2d4d07db8556279c518bda3.jpg",
"file_preview": "https://mysail-paas-dev.oss-cn-shenzhen.aliyuncs.com/uploader/9080479ed2d4d07db8556279c518bda3.jpg",
"file_id": "106053",
"file_keys": ",,,uploader/9080479ed2d4d07db8556279c518bda3.jpg",
"file_previews": ",,,https://mysail-paas-dev.oss-cn-shenzhen.aliyuncs.com/uploader/9080479ed2d4d07db8556279c518bda3.jpg",
"new": {
"origin_image": "https://mysail-paas-dev.oss-cn-shenzhen.aliyuncs.com/uploader/9080479ed2d4d07db8556279c518bda3.jpg",
"750": "",
"900": "",
"1080": ""
},
"file_preview_resize": "https://mysail-paas-dev.oss-cn-shenzhen.aliyuncs.com/uploader/9080479ed2d4d07db8556279c518bda3.jpg?x-oss-process=image/resize,w_120"
},
"is_invalid": 0,
"is_remove": 0,
"is_lower": 0,
"inventory_quantity": 100000,
"utm": "",
"preview_url": "/products/test-product-1"
}
]
}
Response: (After complete order)
200 (OK)
{
"id":"240506162409686",
"completed": true,
"thank_you_url": "https://{{domain}}/checkouts/c8SuPaZ0XNG3n4DzyPdY_g/thank_you",
"payment_pending": false
}
```
### R3. Update order
API endpoint and response
```json
Request:
POST https://{{default_domain}}/api/order/:order_id
Header: x-shop-token
Body: {
// payload
}
Response:
200 (OK)
{
"id": "240311160051709", // order_id
... // other order fields
}
```
i. Update contact info
- email: (string) customer email
- accepts_marketing: (boolean) accepts email marketing
- shipping_address: (object)
```json
Request:
{
"email": "test-customer@gmail.com", // customer email
"accepts_marketing": true, // optional, default = false
"shipping_address": { // shipping address
"first_name": "Bob",
"last_name": "Chan",
"address1": "Room 1A",
"address2": "A Building, 1 A Street",
"city": "NY",
"province": "California",
"province_code": "CA",
"country": "United States",
"country_code": "US",
"zip": "999077",
"phone": "+11121212121"
}
}
```
ii. Update shipping line
```json
Request:
{
"shipping_line": {
"title": "Standard Shipping",
"price": "5.99"
}
}
```
iii. Update discount code
Apply discount code
```json
Request:
{
"discount_code": "V2Q7H3"
}
// valid discount code
Response:
{
"discount_code": "V2Q7H3",
"discount_code_valid": true,
"discount_code_error": "",
}
// invalid discount code
Response:
{
"discount_code": "",
"discount_code_valid": false,
"discount_code_error": "not_found", // not_found, expired, inapplicable, invalid (other reasons)
}
```
Example after applying fixed amount counpon
```json
{
"cart_token": "4bd57430d22f0c27b7814287afdca9b8",
"cartType": "2",
"product_list": [
{
"shop_id": "26",
"product_id": "227",
"title": "",
"price": "10.00",
"compare_at_price": "20.00",
"sku_code": "",
"options": "",
"grams": "0",
"weight": "10.00",
"weight_unit": "g",
"upc": "",
"image_id": "2604",
"image_tmp_url": "",
"is_set_default_img": "0",
"spec": "[]",
"sort": 2.2,
"inventory_quantity": 100000,
"requires_shipping": "0",
"utm": "",
"is_checked": "1",
"is_show": "0",
"is_del": "0",
"created_at": "2024-07-12 15:20:39",
"updated_at": "2024-07-12 15:33:38",
"sku_id": "3893",
"is_use_stock": "0",
"soldout_policy": "Y",
"product_stock": 100000,
"product_handler": "test-product-1",
"product_title": "Test Product 1",
"image": {
"file_key": "uploader/344324220ad0dde450624e29e856813a.jpg",
"file_preview": "https://img.withfstatic.com/uploader/344324220ad0dde450624e29e856813a.jpg",
"file_id": "2604",
"file_keys": ",,,uploader/344324220ad0dde450624e29e856813a.jpg",
"file_previews": ",,,https://img.withfstatic.com/uploader/344324220ad0dde450624e29e856813a.jpg",
"new": {
"origin_image": "https://img.withfstatic.com/uploader/344324220ad0dde450624e29e856813a.jpg",
"750": "",
"900": "",
"1080": ""
},
"file_preview_resize": "https://img.withfstatic.com/uploader/344324220ad0dde450624e29e856813a.jpg?x-oss-process=image/resize,w_120"
},
"data_price": "10.00",
"data_compare_at_price": "0.00",
"is_invalid": 0,
"is_remove": 0,
"is_lower": 0,
"new_customize": "",
"quantity": 1,
"new_add": 1,
"properties": "",
"item_id": "8bfe955f9b61ac419887cc4d5f560da7",
"attribute": [],
"sort_by": 0,
"unique_id": "6690f9c928266",
"is_limitoffer": 0,
"limitoffer_label": 0,
"limitoffer_product_total": 0,
"limitoffer_product_discount_total": 0,
"coupon_label": "",
"product_discount": "1.20",
"product_amount": "8.80",
"is_discount": 0,
"coupon_id": 0,
"is_input_number": 1,
"is_meet_discount_offer": 0,
"meet_discount_offer_text": "",
"insurance_amount": 0,
"customize_price": 0,
"preview_url": "/products/test-product-1",
"total_quantity": 1,
"key": "48UWW8",
"shipping_fee": "0.00"
}
],
"coupon_detail": [
{
"ret": 1,
"coupon_code": "48UWW8",
"coupon_id": "1",
"coupon_type": "1",
"order_number": "240712171712871",
"applicable_range": "1",
"total_discount": "1.20",
"discount_type": "goods",
"coupon": "1.20",
"error_code": 0,
"condition": "10.00",
"is_auto": "0",
"is_unlimited": "1",
"reached_amount": "0.00",
"coupon_desc": "Fixed amount",
"desc": "48UWW8",
"field": "orderAmount",
"match_list": {
"6690f9c928266": {
"key": "48UWW8",
"goods_discount": "1.20",
"goods_amount": "8.80"
}
},
"condition_type": 0,
"type": 1,
"coupon_label": ""
}
],
"coupon_error_code": 0,
"discount_code_error": "",
"express_title": "",
"remark": "",
"weight": "10.00",
"weight_gram": 10,
"amount_logistics": "5.95",
"amount_product": "10.00",
"amount_product_ceil": 10,
"goods_amount": "8.80",
"amount_discount": "1.20",
"product_discount": "1.20",
"express_discount": 0,
"amount": 14.75,
"order_amount": "14.75",
"insurance_rate": 0,
"insurance_amount": "0.00",
"hasInvalid": false,
"hasRemoved": false,
"hasLoweroff": false,
"coupon_type": "1",
"notEnoughInventory": false,
"productCustomizeInfo": [],
"coupon_gifts_collect": "",
"is_diy_tax": 0,
"tax_amount": 0,
"tips_amount": "0.00",
"discount_code_valid": true,
"buyer_id": 3250345461,
"checkout_id": "coclyihp7x600k949cx78ls6nl6",
"payment_gateway": "airwallex",
"shipping_address": {
"first_name": "Test",
"last_name": "BuyerUS",
"address1": "1 Main St",
"address2": "",
"city": "San Jose",
"province": "California",
"province_code": "CA",
"country": "United States",
"country_code": "US",
"zip": "95131",
"phone": ""
},
"email": "test-buyer+us@000000.io",
"shipping_line": {
"title": "Standard shipping",
"price": "5.95"
},
"discount_code": "48UWW8",
"id": "240712171712871",
"total_amount": "14.75",
"upsell_amount": 0,
"updated_at": "2024-07-12T17:23:40Z"
}
```
Example after applying percent discount
```json
{
"cart_token": "4bd57430d22f0c27b7814287afdca9b8",
"cartType": "2",
"product_list": [
{
"shop_id": "26",
"product_id": "227",
"title": "",
"price": "10.00",
"compare_at_price": "20.00",
"sku_code": "",
"options": "",
"grams": "0",
"weight": "10.00",
"weight_unit": "g",
"upc": "",
"image_id": "2604",
"image_tmp_url": "",
"is_set_default_img": "0",
"spec": "[]",
"sort": 2,
"inventory_quantity": 100000,
"requires_shipping": "0",
"utm": "",
"is_checked": "1",
"is_show": "0",
"is_del": "0",
"created_at": "2024-07-12 15:20:39",
"updated_at": "2024-07-12 15:33:38",
"sku_id": "3893",
"is_use_stock": "0",
"soldout_policy": "Y",
"product_stock": 100000,
"product_handler": "test-product-1",
"product_title": "Test Product 1",
"image": {
"file_key": "uploader/344324220ad0dde450624e29e856813a.jpg",
"file_preview": "https://img.withfstatic.com/uploader/344324220ad0dde450624e29e856813a.jpg",
"file_id": "2604",
"file_keys": ",,,uploader/344324220ad0dde450624e29e856813a.jpg",
"file_previews": ",,,https://img.withfstatic.com/uploader/344324220ad0dde450624e29e856813a.jpg",
"new": {
"origin_image": "https://img.withfstatic.com/uploader/344324220ad0dde450624e29e856813a.jpg",
"750": "",
"900": "",
"1080": ""
},
"file_preview_resize": "https://img.withfstatic.com/uploader/344324220ad0dde450624e29e856813a.jpg?x-oss-process=image/resize,w_120"
},
"data_price": "10.00",
"data_compare_at_price": "0.00",
"is_invalid": 0,
"is_remove": 0,
"is_lower": 0,
"new_customize": "",
"quantity": 1,
"new_add": 1,
"properties": "",
"item_id": "8bfe955f9b61ac419887cc4d5f560da7",
"attribute": [],
"sort_by": 0,
"unique_id": "6690fc0738772",
"is_limitoffer": 0,
"limitoffer_label": 0,
"limitoffer_product_total": 0,
"limitoffer_product_discount_total": 0,
"coupon_label": "",
"product_discount": "1.00",
"product_amount": "9.00",
"is_discount": 0,
"coupon_id": 0,
"is_input_number": 1,
"is_meet_discount_offer": 0,
"meet_discount_offer_text": "",
"insurance_amount": 0,
"customize_price": 0,
"preview_url": "/products/test-product-1",
"total_quantity": 1,
"key": "TM7HWK",
"shipping_fee": "0.00"
}
],
"coupon_detail": [
{
"ret": 1,
"coupon_code": "TM7HWK",
"coupon_id": "2",
"coupon_type": "2",
"order_number": "240712171712871",
"applicable_range": "1",
"total_discount": "1.00",
"discount_type": "goods",
"coupon": "10.00",
"error_code": 0,
"condition": "10.00",
"is_auto": "0",
"is_unlimited": "1",
"reached_amount": "0.00",
"coupon_desc": "Percentage",
"desc": "TM7HWK",
"field": "orderAmount",
"match_list": {
"6690fc0738772": {
"key": "TM7HWK",
"goods_discount": "1.00",
"goods_amount": "9.00"
}
},
"condition_type": 0,
"type": 1,
"coupon_label": ""
}
],
"coupon_error_code": 0,
"discount_code_error": "",
"express_title": "",
"remark": "",
"weight": "10.00",
"weight_gram": 10,
"amount_logistics": "5.95",
"amount_product": "10.00",
"amount_product_ceil": 10,
"goods_amount": "9.00",
"amount_discount": "1.00",
"product_discount": "1.00",
"express_discount": 0,
"amount": 14.95,
"order_amount": "14.95",
"insurance_rate": 0,
"insurance_amount": "0.00",
"hasInvalid": false,
"hasRemoved": false,
"hasLoweroff": false,
"coupon_type": "2",
"notEnoughInventory": false,
"productCustomizeInfo": [],
"coupon_gifts_collect": "",
"is_diy_tax": 0,
"tax_amount": 0,
"tips_amount": "0.00",
"discount_code_valid": true,
"buyer_id": 3250345461,
"checkout_id": "coclyihp7x600k949cx78ls6nl6",
"payment_gateway": "airwallex",
"shipping_address": {
"first_name": "Test",
"last_name": "BuyerUS",
"address1": "1 Main St",
"address2": "",
"city": "San Jose",
"province": "California",
"province_code": "CA",
"country": "United States",
"country_code": "US",
"zip": "95131",
"phone": ""
},
"email": "test-buyer+us@000000.io",
"shipping_line": {
"title": "Standard shipping",
"price": "5.95"
},
"discount_code": "TM7HWK",
"id": "240712171712871",
"total_amount": "14.95",
"upsell_amount": 0,
"updated_at": "2024-07-12T17:39:21Z"
}
```
Remove discount code
```json
Request:
{
"discount_code": ""
}
Response:
{
"discount_code": "",
"discount_code_valid": false,
"discount_code_error": "",
}
```
iv. Apply tips
- tips_amount: "xx.xx"
```json
Request:
{
"tips_amount": "1.5"
}
```
vii. Add payment info
- payment_gateway: (string)
- add_payment_info: (boolean)
- billing_same_as_shipping: (boolean)
- billing_address: (object)
```json
Request:
{
"payment_gateway": "paypal", // airwallex, stripe, etc
"add_payment_info": true,
"billing_same_as_shipping": true,
"billing_address": {
"first_name": "Bob",
"last_name": "Chan",
"address1": "Room 1A",
"address2": "A Building, 1 A Street",
"city": "NY",
"province": "California",
"province_code": "CA",
"country": "United States",
"country_code": "US",
"zip": "999077",
"phone": "+11121212121"
}
}
```
v. Post-purchase upsell
- cart coupon code does not apply to upsell items
- product_id: (string)
- sku_id: (string) product variant id
- quantity: (number)
- discount_title: (string) // apply discount for upsell items only
- discount_type: (string) // percentage, fixed_amount
- discount_value: (string) // apply to each item
Post-purchase step 1:
```json
Request:
{
"upsell_list": [
{
"id": "puxxxxx001",
"product_id": "4550",
"sku_id": "25829",
"quantity": 1,
"discount_title": "SPECIAL_OFFER",
"discount_type": "percentage"
"discount_value": "35.5"
}
]
}
Response:
200 (OK)
{
"id": "240311160051709",
"amount": "30", // original cart amount without upsell
"upsell_amount": "10.5", // amount for upsell only
...
}
```
Post-purchase step N - add more items:
```json
Request:
{
"upsell_list": [
{
"id": "puxxxxx001",
"product_id": "4550",
"sku_id": "25829",
"quantity": 1,
"discount_title": "SPECIAL_OFFER",
"discount_type": "percentage"
"discount_value": "35.5"
},
{
"id": "puxxxxx002",
"product_id": "5550",
"sku_id": "35829",
"quantity": 2,
"discount_title": "SPECIAL_OFFER",
"discount_type": "fixed_amount"
"discount_value": "2.55"
}
]
}
Response:
200 (OK)
{
"id": "240311160051709",
"amount": "30",
"upsell_amount": "30.5",
...
}
```
Post-purchase last step - scenario: payment failed, remove upsell items:
```json
Request:
{
"upsell_list": []
}
Response:
200 (OK)
{
"id": "240311160051709",
"amount": "30",
"upsell_amount": "0",
...
}
```
### R4. Complete order
- {any order update parameters}: update order before complete
- complete: true to complete a draft order
- payment_pending: true when payment is (optional, default = false)
- note_attributes: (array of objects)
```json
Request:
POST https://{{default_domain}}/api/order/:order_id
Header: x-shop-token
Body:
{
"upsell_list": [], // remove upsell list
"complete": true,
"payment_pending": true, // default = false
"note_attributes": [
{
"key": "itc_checkout_id",
"value": "coxxxxxxxx001"
},
{
"key": "itc_gateway_name",
"value": "Paypal Express"
}
]
}
Response:
200 (OK)
{
"id": "240311160051709",
...
"upsell_amount": "0",
"completed": true,
"payment_pending": true
}
```
### R5. Post-order update
- payment_pending: set to false when payment is verified later
- note_attributes: (array of objects) replace existing note_attributes
```json
Request:Å
POST https://{{default_domain}}/api/order/:order_id
Header: x-shop-token
Body:
{
"payment_pending": false,
"note_attributes": [
{
"key": "itc_checkout_id",
"value": "coxxxxxxxx001"
},
{
"key": "itc_payment_gateway",
"value": "PayPal Express Checkout"
},
{
"key": "itc_paypal_merchant_id",
"value": "XXA927H28AUHJ"
},
{
"key": "itc_paypal_merchant_email",
"value": "Thanks@Test-Paypal.com"
},
{
"key": "itc_payment_verified_at",
"value": "2024-03-12T12:01:20.123Z"
}
]
}
Response:
200 (OK)
{
"id": "240311160051709",
...
"completed": true,
"payment_pending": false
}
```