# 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 } ```