Order API Endpoints

Following is a list of the available order endpoints for retrieving orders and for managing an orders status:

Supplier can refer to a standard order process flow as below. It is strongly recommended that supplier connect to order API as this flow.

Acknowledge an Order

Use this endpoint to set the status of an order to "Acknowledged".

Request Parameters

Endpoint: POST https://sandbox.voyageone.com/v1/restapi/supplier/order/acknowledge
Parameter Data Type Description Example
orderId string Required. The order ID of the order being updated. "10018734"
"1181000069298115"

Response Format

On success, the HTTP status code in the response header is 200 OK and the response body contains an order result object in JSON format. On error, the response body contains an error object.

Example Request


curl -X POST https://sandbox.voyageone.com/v1/restapi/supplier/order/acknowledge \
-H "Client-Id: {your Client ID}" \
-H "Authorization: Bearer {your Token}" \
-H "Content-Type: application/json" \
-d \
'{
  "orderId": "10000888"
}'

Example Response


{
  "code": "0",
  "data":
  {
    "orderId": "10000888"
  }
}

Apply for a waybill

Use this endpoint to apply for an order waybill after confirmed that the order can be fulfilled.

Request Parameters

Endpoint: POST https://sandbox.voyageone.com/v1/restapi/supplier/order/waybill/apply
Parameter Data Type Description Example
orderId string Required. The order ID of the order to apply for a waybill. "10018734"
"1181000069298115"
thirdOrderId string A reference number defined by the vendor. "1209328"

Response Format

On success, the HTTP status code in the response header is 200 OK and the response body contains an order result object in JSON format. On error, the response body contains an error object.

Example Request


curl -X POST https://sandbox.voyageone.com/v1/restapi/supplier/order/waybill/apply
-H "Client-Id: {your Client ID}" \
-H "Authorization: Bearer {your Token}" \
-H "Content-Type: application/json" \
-d \
'{
  "orderId": "10000888"
  "thirdOrderId": "1209328"
}'

Example Response


{
  "code": "0",
  "data": ""
}

Get a waybill

Use this endpoint to get a waybill data of an order, Please be noted that it should be a time interval(about several minutes) between applying a waybill and generating waybill data. Supplier should use this endpoint several minutes after applying endpoint.
And it will return an error message if the order has been cancelled by customer. It is recommended that supplier use this endpoint just before shipping the order.

Request Parameters

Endpoint: POST https://sandbox.voyageone.com/v1/restapi/supplier/order/waybill/info
Parameter Data Type Description Example
orderId string Required. The order ID to get a waybill of the order. "10018734"
"1181000069298115"

Response Format

On success, the HTTP status code in the response header is 200 OK and the response body contains an order result object in JSON format. On error, the response body contains an error object.

Example Request


curl -X POST https://sandbox.voyageone.com/v1/restapi/supplier/order/waybill/info
-H "Client-Id: {your Client ID}" \
-H "Authorization: Bearer {your Token}" \
-H "Content-Type: application/json" \
-d \
'{
  "orderId": "10000888"
}'

Example Response


{
  "code": "0",
  "data":
  {
    "orderId": "10000888",
    "deliveryType": "SYB",
    "trackingNo": "LP1234567893",
    "shipLabelType": "pdf",
    "shipLabelValue": "https://cdn.alibaba.com/pdf/printlabel001.pdf"
  }
}

Cancel an Order

Use this endpoint to set the status of an order to "Canceled".

Request Parameters

Endpoint: POST https://sandbox.voyageone.com/v1/restapi/supplier/order/cancel
Parameter Data Type Description Example
orderId string Required. The order ID of the order being updated. "10018734"
"1181000069298115"

Response Format

On success, the HTTP status code in the response header is 200 OK and the response body contains an order result object in JSON format. On error, the response body contains an error object.

Example Request


curl -X POST https://sandbox.voyageone.com/v1/restapi/supplier/order/cancel \
-H "Client-Id: {your Client ID}" \
-H "Authorization: Bearer {your Token}" \
-H "Content-Type: application/json" \
-d \
'{
  "orderId": "10000900"
}'

Example Response


{
  "code": "0",
  "data":
  {
    "orderId": "10000900"
  }
}

Get an Order

Use this endpoint to get an order.

Request Parameters

Endpoint: POST https://sandbox.voyageone.com/v1/restapi/supplier/order/info
Parameter Data Type Description Example
orderId string Required. The order ID of the order you wish to retrieve. "10018734"
"1181000069298115"

Response Format

On success, the HTTP status code in the response header is 200 OK and the response body contains an order object in JSON format. On error, the response body contains an error object.

Example Request


curl -X POST https://sandbox.voyageone.com/v1/restapi/supplier/order/info \
-H "Client-Id: {your Client ID}" \
-H "Authorization: Bearer {your Token}" \
-H "Content-Type: application/json" \
-d \
'{
  "orderId": "10000941"
}'

Example Response


{
  "code": "0",
  "data":
  {
    "orderId": "10000941",
    "orderStatus": "Open",
    "orderType": "normal",
    "orderTime": 1547437201000,
    "orderAmount": 748.64,
    "orderTax": 0,
    "deliveryType": "CaiNiao",
    "trackingNo": "1234567890",
    "shipLabelType": "pdf",
    "shipLabelValue": "https://cdn.alibaba.com/pdf/printlabel001.pdf",
    "orderDiscount": 0,
    "shippingFee": 0,
    "billInfo":
    {
      "firstName": "Demo Marketplace",
      "lastName": "Demo Vendor",
      "emailAddress": "demo@voyageone.com",
      "daytimePhone": "0123456789",
      "eveningPhone": "",
      "companyName": "",
      "country": "us",
      "stateOrProvince": "CA",
      "city": "Cerritos",
      "addressLine1": "16010 Bloomfield Ave.",
      "addressLine2": "",
      "postalCode": "90703"
    },
    "shipToInfo":
    {
      "firstName": "VoyageOne Receiving Dept",
      "lastName": "ATTN: Demo Vendor",
      "emailAddress": "vms-support@voyageone.cn",
      "daytimePhone": "1-562-977-6408",
      "eveningPhone": "1-562-977-6408",
      "companyName": "",
      "country": "US",
      "stateOrProvince": "CA",
      "city": "Cerritos",
      "addressLine1": "16010 Bloomfield Ave.",
      "addressLine2": "PID:10000941",
      "postalCode": "90703",
      "warehouse": "LA"
    },
    "items":
    [
      {
        "sku": "b37572-8.5",
        "size": "8.5",
        "title": "Adidas Yeezy Boost 350 V2",
        "qty": 1,
        "unitPrice": 169.95,
        "unitDiscount": 0,
        "unitTax": 0
      },
      {
        "sku": "b37572-9.5",
        "size": "9.5",
        "title": "Adidas Yeezy Boost 350 V2",
        "qty": 1,
        "unitPrice": 169.95,
        "unitDiscount": 0,
        "unitTax": 0
      },
      {
        "sku": "cp9654-9.5",
        "size": "9.5",
        "title": "Adidas Yeezy Boost 350 V2 (Zebra)",
        "qty": 1,
        "unitPrice": 139.95,
        "unitDiscount": 0,
        "unitTax": 0
      },
      {
        "sku": "531592",
        "size": "75ml/2.5oz",
        "title": "Gucci Bamboo Perfume",
        "qty": 1,
        "unitPrice": 33.94,
        "unitDiscount": 0,
        "unitTax": 0
      },
      {
        "sku": "inco300158-kak-onesize",
        "size": "onesize",
        "title": "Incase City Market Tote",
        "qty": 1,
        "unitPrice": 45.95,
        "unitDiscount": 0,
        "unitTax": 0
      },
      {
        "sku": "lw181k52-940-L",
        "size": "L",
        "title": "FILA Viola 2 Dress",
        "qty": 1,
        "unitPrice": 48.95,
        "unitDiscount": 0,
        "unitTax": 0
      },
      {
        "sku": "cp9654-9.5",
        "size": "9.5",
        "title": "Adidas Yeezy Boost 350 V2 (Zebra)",
        "qty": 1,
        "unitPrice": 139.95,
        "unitDiscount": 0,
        "unitTax": 0
      }
    ]
  }
}

Get a List of Orders

Use this endpoint to get a list of orders.

Request Parameters

Endpoint: POST https://sandbox.voyageone.com/v1/restapi/supplier/order/list
Parameter Data Type Description Example
pageNo number The specific page number in a paginated list of results. Including this parameter in your request will limit the response to a single page matching the page sequence order represented by the page number. 1
23
164
pageSize number The number of orders to include in the page of results. Including this parameter in your call will adjust the response to only include no more than the number of orders that you specify on each page.

Note: The maximum number of orders that can be included regardless of the amount you specify is 100.

 1
10
58
100
status array of strings A list of one or more order statuses used to filter the API request. ["Open"]

[
"Canceled",
"Complete"
]
orderTime number Required. The specified time range for which the order’s orderTime property equals or is within the specified range.

To specify a time range, include the starting and ending UTC timestamps in milliseconds. For example, to specify January 1, 2018 through December 31, 2018, you would specify [1514764800000, 1546214400000] as the value. To get a list of all orders, specify the value as [null, null].

 [1514764800000, 1546214400000]
[1540988103000, 1540988103000]
modifiedTime number Optional. The specified time range for which the order’s modifiedTime property equals or is within the specified range.

To specify a time range, include the starting and ending UTC timestamps in milliseconds. For example, to specify January 1, 2018 through December 31, 2018, you would specify [1514764800000, 1546214400000] as the value. To get a list of all orders, specify the value as [null, null] or do not set.

 [1514764800000, 1546214400000]
[1540988103000, 1540988103000]

Response Format

On success, the HTTP status code in the response header is 200 OK and the response body contains one or more order objects in JSON format. On error, the response body contains an error object.

Example Request


curl -X POST https://sandbox.voyageone.com/v1/restapi/supplier/order/list \
-H "Client-Id: {your Client ID}" \
-H "Authorization: Bearer {your Token}" \
-H "Content-Type: application/json" \
-d \
'{
  "pageNo": 1,
  "pageSize": 100,
  "status": ["Open"],
  "orderTime": [1547437201000, 1547437201000],
  "modifiedTime": [1547437501000, 1547437501000]
}'

Example Response


{
  "code": "0",
  "data":
  [
  {
      "orderId": "10000888",
      "orderStatus": "Open",
      "orderType": "normal",
      "orderTime": 1547437201000,
      "orderAmount": 479.85,
      "orderTax": 0,
      "deliveryType": "CaiNiao",
      "trackingNo": "1234567890",
      "shipLabelType": "pdf",
      "shipLabelValue": "https://cdn.alibaba.com/pdf/printlabel001.pdf",
      "orderDiscount": 0,
      "shippingFee": 0,
      "billInfo":
      {
        "firstName": "Demo Marketplace",
        "lastName": "Demo Vendor",
        "emailAddress": "demo@voyageone.com",
        "daytimePhone": "0123456789",
        "eveningPhone": "",
        "companyName": "",
        "country": "us",
        "stateOrProvince": "CA",
        "city": "Cerritos",
        "addressLine1": "16010 Bloomfield Ave.",
        "addressLine2": "",
        "postalCode": "90703"
      },
      "shipToInfo":
      {
        "firstName": "VoyageOne Receiving Dept",
        "lastName": "ATTN: Demo Vendor",
        "emailAddress": "vms-support@voyageone.cn",
        "daytimePhone": "1-562-977-6408",
        "eveningPhone": "1-562-977-6408",
        "companyName": "",
        "country": "US",
        "stateOrProvince": "CA",
        "city": "Cerritos",
        "addressLine1": "16010 Bloomfield Ave.",
        "addressLine2": "PID:10000888",
        "postalCode": "90703",
        "warehouse": "LA"
      },
      "items":
      [
        {
          "sku": "b37572-8.5",
          "size": "8.5",
          "title": "Adidas Yeezy Boost 350 V2",
          "qty": 1,
          "unitPrice": 169.95,
          "unitDiscount": 0,
          "unitTax": 0
        },
        {
          "sku": "b37572-9.5",
          "size": "9.5",
          "title": "Adidas Yeezy Boost 350 V2",
          "qty": 1,
          "unitPrice": 169.95,
          "unitDiscount": 0,
          "unitTax": 0
        },
        {
          "sku": "cp9654-9.5",
          "size": "9.5",
          "title": "Adidas Yeezy Boost 350 V2 (Zebra)",
          "qty": 1,
          "unitPrice": 139.95,
          "unitDiscount": 0,
          "unitTax": 0
        }
      ]
    },
    {
      "orderId": "10000889",
      "orderStatus": "Open",
      "orderType": "normal",
      "orderTime": 1547437201000,
      "orderAmount": 169.95,
      "orderTax": 0,
      "deliveryType": "CaiNiao",
      "trackingNo": "1234567890",
      "shipLabelType": "pdf",
      "shipLabelValue": "https://cdn.alibaba.com/pdf/printlabel001.pdf",
      "orderDiscount": 0,
      "shippingFee": 0,
      "billInfo":
      {
        "firstName": "Demo Marketplace",
        "lastName": "Demo Vendor",
        "emailAddress": "demo@voyageone.com",
        "daytimePhone": "0123456789",
        "eveningPhone": "",
        "companyName": "",
        "country": "us",
        "stateOrProvince": "CA",
        "city": "Cerritos",
        "addressLine1": "16010 Bloomfield Ave.",
        "addressLine2": "",
        "postalCode": "90703"
      },
      "shipToInfo":
      {
        "firstName": "VoyageOne Receiving Dept",
        "lastName": "ATTN: Demo Vendor",
        "emailAddress": "vms-support@voyageone.cn",
        "daytimePhone": "1-562-977-6408",
        "eveningPhone": "1-562-977-6408",
        "companyName": "",
        "country": "US",
        "stateOrProvince": "CA",
        "city": "Cerritos",
        "addressLine1": "16010 Bloomfield Ave.",
        "addressLine2": "PID:10000889",
        "postalCode": "90703",
        "warehouse": "LA"
      },
      "items":
      [
        {
          "sku": "b37572-8.5",
          "size": "8.5",
          "title": "Adidas Yeezy Boost 350 V2",
          "qty": 1,
          "unitPrice": 169.95,
          "unitDiscount": 0,
          "unitTax": 0
        }
      ]
    },
    {
      "orderId": "10000900",
      "orderStatus": "Open",
      "orderType": "normal",
      "orderTime": 1547437201000,
      "orderAmount": 1699.5,
      "orderTax": 0,
      "deliveryType": "CaiNiao",
      "trackingNo": "1234567890",
      "shipLabelType": "pdf",
      "shipLabelValue": "https://cdn.alibaba.com/pdf/printlabel001.pdf",
      "orderDiscount": 0,
      "shippingFee": 0,
      "billInfo":
      {
        "firstName": "Demo Marketplace",
        "lastName": "Demo Vendor",
        "emailAddress": "demo@voyageone.com",
        "daytimePhone": "0123456789",
        "eveningPhone": "",
        "companyName": "",
        "country": "us",
        "stateOrProvince": "CA",
        "city": "Cerritos",
        "addressLine1": "16010 Bloomfield Ave.",
        "addressLine2": "",
        "postalCode": "90703"
      },
      "shipToInfo":
      {
        "firstName": "VoyageOne Receiving Dept",
        "lastName": "ATTN: Demo Vendor",
        "emailAddress": "vms-support@voyageone.cn",
        "daytimePhone": "1-562-977-6408",
        "eveningPhone": "1-562-977-6408",
        "companyName": "",
        "country": "US",
        "stateOrProvince": "CA",
        "city": "Cerritos",
        "addressLine1": "16010 Bloomfield Ave.",
        "addressLine2": "PID:10000900",
        "postalCode": "90703",
        "warehouse": "LA"
      },
      "items":
      [
        {
          "sku": "b37572-8.5",
          "size": "8.5",
          "title": "Adidas Yeezy Boost 350 V2",
          "qty": 10,
          "unitPrice": 169.95,
          "unitDiscount": 0,
          "unitTax": 0
        }
      ]
    }
  ]
}

Ship an Order

Use this endpoint to set the status of an order to "Shipped" and to add the tracking information for the shipment.

Important: Only one shipment update is allowed per order. Therefore, once an order’s status is "Shipped", the shipment details cannot be changed.

Request Parameters

Endpoint: POST https://sandbox.voyageone.com/v1/restapi/supplier/order/ship
Parameter Data Type Description Example
carrierCode string Required. The name or code of the carrier. "FedEx"
"UPS"
"DHL"
orderId string Required. The order ID of the order being updated. "10018734"
"1181000069298115"
shipFromInfo ship from address object Required. The shipping address from where the order is shipped.
shipTime number Required. The time the order is shipped. Timestamps are expressed using the UTC format in milliseconds. 1543873864341
trackingNo string Required. The tracking number from the carrier. "784913953037"
"1Z999AA10123456784"

Response Format

On success, the HTTP status code in the response header is 200 OK and the response body contains a tracking result object in JSON format. On error, the response body contains an error object.

Example Request


curl -X POST https://sandbox.voyageone.com/v1/restapi/supplier/order/ship \
-H "Client-Id: {your Client ID}" \
-H "Authorization: Bearer {your Token}" \
-H "Content-Type: application/json" \
-d \
'{
  "orderId": "10000888",
  "carrierCode": "FedEx",
  "trackingNo": "794801750850",
  "shipTime": 1530067210115,
  "shipFromInfo":
  {
    "firstName": "VoyageOne",
    "lastName": "ATTN: Demo Vendor",
    "nameSuffix": "",
    "emailAddress": "vms-support@voyageone.cn",
    "daytimePhone": "1-562-977-6408",
    "eveningPhone": "1-562-977-6408",
    "companyName": "VO",
    "country": "US",
    "stateOrProvince": "NY",
    "city": "Cerritos",
    "addressLine1": "416 Senator St Brooklyn",
    "addressLine2": "PID:10000888",
    "postalCode": "11220"
  }
}'

Example Response


{
  "code": "0",
  "data":
  {
    "trackingId": "5c4b9beabf2d8c24e5c4d88c"
  }
}

Update the arrival of a shipment

Use this endpoint to share the receipt from CAINIAO to prove the arrival status of a shipment

Request Parameters

Endpoint: POST https://sandbox.voyageone.com/v1/restapi/supplier/order/receipt
Parameter Data Type Description Example
receiptNo string Required. The code of receipt after Cainiao accepted the shipment. "202103081244001"
receiptTime number Required. Time of shipment arrival in format of timestamp. 1543873864341
receiptImages array of strings Required. URL of receipts in digital copy, accepted format in JPG,JPEG,PNG and PDF. [
"http://imageerp.voyageone.cn/581_test_20210308021801.pdf",
"http://imageerp.voyageone.cn/581_test_20210308021802.pdf",
"http://imageerp.voyageone.cn/581_test_20210308021803.jpg"
]
orderIds array of strings Required. The order IDs under this shipment. [
"1201000118781901",
"1201000118781902",
"1201000118781903",
"1201000118781904"
]
comment string Optional

Example Request


'{
  "receiptNo": "202103081244001",
  "receiptTime": 1543873864341,
  "receiptImages": [
    "http://imageerp.voyageone.cn/581_test_20210308021801.pdf",
    "http://imageerp.voyageone.cn/581_test_20210308021802.pdf",
    "http://imageerp.voyageone.cn/581_test_20210308021803.jpg"
  ],
  "orderIds": [
    "1201000118781901",
    "1201000118781902",
    "1201000118781903",
    "1201000118781904",
  ],
  "comment": "菜鸟韩国集货仓20210308 收货"
}'

Example Response


{
  "code": "0",
  "message": ""
}