Shipping Orders
- Pinthip Chantanalert
- Mark Rachelski
- Nuchjaree Laetee (Unlicensed)
- Former user (Deleted)
Overview
The aCommerce Shipping Order API allows for a shipping partner to submit orders for delivery using the aCommerce shipping management system. As the processing of a Shipping Order is a complex and lengthy logistics process, any system submitting a Shipping Order will likely need to also interact with the Shipping Order Status API to learn about the progress of the order. However, the aCommerce system will go through lengthy steps to validate the order at the time of submission and it is critical that a caller process the HTTP status codes returned from this API. In general, if you receive a 4xx or 5xx error, then your request to submit, modify or delete an order has not been accepted and you should behave accordingly. A 4xx error indicates that you will need to make changes to resubmit the order. A 5xx error indicates there is a processing error in the aCommerce system and a retry of your call may succeed in the future.
A calling system should be written to respond to both errors being returned from this API call AND errors being returned in the Shipping Order Status API. aCommerce may change the reporting mechanism between these two alternatives for a particular error without notice. (I.E. an error that previously was reported through a Shipping Order Status HTTP return code may switch to being reported through an Shipping Order Status code and vice versa).
Rate Limiting
All aCommerce APIs are subject to rate limiting (see Public API). However, since the submission of a Shipping Order represents a contract, the aCommerce system will implement more stringent rate limits for Shipping Order PUT limits to protect a customer from misbehaving applications.
Implemented verbs and end-points
Shipping Order Creation
PUT https://shipping.api.acommerce.asia/partner/:shippingPartnerID/order/:shipOrderId
This endpoint is used to allow a shipping partner to put a shipping order to the aCommerce system for action using an identifier that the shipping partner can refer to later. The caller issues an HTTPS call to the specified endpoint with a JSON body described in the Shipping Order endpoint schema. A shipping partner is required to make orderId unique across time in order to utilize this API effectively. Failure to do so will cause a partner to modify a previously created shipping order.
An order must contains at least shipSender and shipShipment, and shipPickup will be use when package pickup service is required.
The JSON body of a PUT request should conform to the Shipping Order Schema defined below
Shipping Order Retrieval
GET https://shipping.api.acommerce.asia/partner/:shippingPartnerID/order/:shipOrderId
This endpoint is primarily provided for completeness. It is doubtful it will be used much by a partner as they should know what orders they have already submitted. This API call cannot be used to query the status of an order as it only returns the original orders that aCommerce has received from the partner. This endpoint does not update based upon shipping status changes. However, it will return the current understanding that aCommerce has of this order when all PUT calls have been applied. Additionally, this call will return an HTTP 404 NOT FOUND if the shipping partner has previously called DELETE using this ID.
The JSON body of a GET request and response should conform to the Shipping Order Schema defined below
Shipping Order Modification (Currently Unavailable)
PUT https://shipping.api.acommerce.asia/partner/:shippingPartnerID/order/:shipOrderId
This endpoint is used to allow a partner to update an shipping order to the aCommerce system after it has already been placed. The aCommerce system will match this PUT request against an order with the same shipOrderId. This API will reject the PUT request if the order is in a state where it cannot be updated (e.g. a pickup was requested, the pickup location cannot be changed after the driver is in route). In such cases, this endpoint will return a will return a "409 Conflict" error with a JSON document providing more detail about the error condition.
The JSON body of a PUT request should conform to the Shipping Order Schema defined below.
Shipping Order Cancellation (Currently Unavailable)
DELETE https://shipping.api.acommerce.asia/partner/:shippingPartnerID/order/:shipOrderId
This endpoint is used to allow a shipping partner to cancel an order to the aCommerce system after it has already been placed. The aCommerce system will match this DELETE request against an shipping order with the same shipOrderId. This API will reject the DELETE request if the order is in a state where it cannot be cancelled (e.g. the package is already out for delivery to the destination). In such cases, this endpoint will return a will return a "409 Conflict" error with a JSON document providing more detail about the error condition.
A call using this verb does not require a JSON document to be present in the request.
Shipping Order Creation
Shipping Order Schema
Attribute | Description | Type | Example | Mandatory |
|---|---|---|---|---|
| shipCreatedTime | The time and date that the order was created in ISO8601 format. If this is not provided in a PUT verb, then the current time will be captured and attached if the object is being created or be left unchanged if the current document is being modified. | Datetime | 2015-06-24T04:47:00Z | No |
| shipPartnerSalesOrderId | This is used if a partner needs to tie multiple shipping orders together under a single sales order. In general, aCommerce will ignore this field except within the shipping-order-status APIs where a shipping partner may search for all shipping orders related to this identifier. This field can also be used by a shopper in the aCommerce tracking page to locate all of the related shipment orders. | String | "3456789" | No |
| shipServiceType | This field identifies which service type to be used for this order. Current available service type are "DROP_SHIP", "DELIVERY", and "SMARTSHIP_THAIPOST". If this attribute is omitted, default service type "DROP_SHIP" will be assumed. | Enum | "DROP_SHIP" | No |
| shipSender | Sender name and address information, which could be merchant or partner. For SMARTSHIP_THAIPOST service: aCommerce will use one of aCommerce Shipping Hub Location address (i.e., RAMA III) in the label, not this sender address If the order is rejected or failed to delivery to the shopper, the package will be returned to aCommerce Shipping Hub location by Thai Post, then aCommerce will return the package based on this sender information. | Address Detail object | See below | Yes |
| shipShipment | Receiver name and address information, which is the shipping order's (package's) destination. | Address Detail object | See below | Yes |
| shipPickup | Pickup information, which is the origin of packages and typically requires aCommerce to schedule a pickup service. It could be different from sender information. This object is interpreted differently based upon the shipServiceType. DROP_SHIP: This field represents the address where the package(s) are picked up. If this pickup address and shipSenderare the same, this field can be omitted. If the order is rejected or failed to delivery, the package will be returned to this address. If this address is not present, then the package will be returned to the shipSender. DELIVERY: This field represents the aCommerce Shipping Hub where the package will be prepared. SMARTSHIP_THAIPOST: This field is not required and will be ignored. | Address Detail object | See below | No |
| shipShippingType | Type of shipping which may indicate how fast of shipping. | Enum | NEXT_DAY | Yes |
| shipPaymentType | Payment type | Enum | NON_COD | Yes |
| shipCurrency | Currency use in this order, formatted in ISO 4217 | Enum | THB | No |
| shipGrossTotal | Gross total of this order, this field will be used if payment type is "COD" or "CCOD" | Number | 1024.00 | Required when shipPaymentType is COD or CCOD |
| shipInsurance | Order insurance, default value is false. | Boolean | True | No |
| shipTotalDeclareValue | Amount of order declare value use for calculate insurance. When this is present withpackageDeclaredValue, this attribute should be sum ofpackageDeclaredValue. | Number | 1500.00 | Required when shipInsurance is True. |
| shipOrderNote | Specific command of the order as agreed with aCommerce. | String | Some Text | No |
| shipPickingList[] | Items to be Picked from inventory and packed. When this is present, an email will be issued to the shipPickup.addressEmail containing this list of items to pack along with any printing labels needed to prepare the package for pickup. If this object is populated, shipPackages should not be present. | Array of Ship Item object | See below | Required when shipPackages object is not present |
| shipPackages[] | Details of boxes (and items if any) that have been prepared for shipment. If this object is populated, then shipPickingList should not be present. | Array of Package Detail object | See below | Required when shipPickingList is not present |
Address Detail Schema
Address detail of a person, organization or collection point.
| Attribute | Description | Type | Example | Mandatory |
|---|---|---|---|---|
| addressee | Name of person, organization, or one of the Shipping Hub Location codes. | String | "Dan Happiness" or "BKKRAMAIII" | Yes |
| address1 | Address line 1 | String | Dusit Thani Hotel | Yes, if the addressee is not one of the Shipping Hub location codes. |
| address2 | Address line 2 | String | 964 Rama 4 Road | No |
| subDistrict | Sub-district | String | Silom | No |
| district | District | String | Bangrak | No |
| city | City | String | Yes | |
| province | Province or State | String | Bangkok | Yes |
| postalCode | Postal code | String | 10100 | Yes, if the addressee is not one of the Shipping Hub location codes. |
| country | Country name | String | Thailand | Yes |
| phone | Phone number. All non-numeric characters will be removed. for shipShipment Validate if it’s a valid value for phone number in any countries. | String | 0800000000 | Required in shipPickup and shipShipment, Not required in shipSender |
| String | dan@happiness.bangkok | Yes, if the addressee is not one of the Shipping Hub location codes |
Package Detail Schema
Package detail includes information about the package, in particular the dimensions (height, width, depth), weight and pricing.
Attribute | Description | Type | Example | Mandatory |
|---|---|---|---|---|
| packageTrackingId | Package tracking ID, this field will be provided by aCommerce | String | AWB0000000000 | No |
| packageWeight | Weight of package in Kilogram | Number | 1.5 | No |
| packageHeight | Height of package in Centimeter | Number | 10 | No |
| packageWidth | Width of package in Centimeter | Number | 30 | No |
| packageDepth | Depth of package in Centimeter | Number | 30 | No |
| packageDeclaredValue | Declared value of single package, this value will be use for calculate insurance fee. | Number | 1500.00 | No |
| packagePriceDelivery | Price specify for delivering | Number | 60.00 | No |
| packagePriceInsurance | Price specify for Insurance fee | Number | 200.00 | No |
| packagePricePackaging | Price specify for packaging fee | Number | 30.00 | No |
| packagePriceRemoteArea | Price specify for remote area fee | Number | 100.00 | No |
| packagePriceService | Price specify for service fee | Number | 50.00 | No |
| packagePriceFuel | Price specify for fuel fee | Number | 10.00 | No |
| packageNote | Specific command of the package as agreed with aCommerce | String | No | |
| packageItems[] | An optional list of items included in the package. This is commonly required for international shipping. | Array of Ship Item object | See below | No |
Ship Item Schema
Ship item describe an item with a quantity of them.
Attribute | Description | Type | Example | Mandatory |
|---|---|---|---|---|
| itemDescription | A description of the item in the package | String | A widget that can be used for amazing things | Yes |
| itemQuantity | The quantity of item | Integer | 1 | Yes |
Payment Type Enum
Payment type for "shipPaymentType" should be enumerated as the following items.
- "NON_COD" for non cash on delivery (already paid to partner)
- "COD" for cash on delivery
- "CCOD" for credit card on delivery
Currency Type Enum
Currency type for "shipCurrency" should be enumerated follow the ISO 4217. The example is listed below.
- "THB" for Thai Baht
- "SGD" for Singapore dollar
- "IDR" for Indonesia rupiah
- "PHP" for Philippine peso
Shipping Type Enum
Payment type for "shipShippingType" should be enumerated as the following items, the shipping type will be add later if we have new shipping method.
- "SAME_DAY"
- "NEXT_DAY"
- "EXPRESS_1_2_DAYS"
- "STANDARD_2_4_DAYS"
- "NATIONWIDE_3_5_DAYS"
Shipping Hub Code
The Shipping Hub code is a unique value representing a shipping distribution center. Currently, these locations are the same as our Fulfillment center. However, we plan to have more locations outside of our Fulfillment center.
Shipping Order Creation Example
Placing an order with picking list
When a shipping partner without stock sold an item, they will need to send a picking list to their merchant to let them pick an item, packing and wait for picking up. This process will be done automatically thought aCommerce by giving a shipPickingList, the pickup address and email.
PUT https://shipping.api.acommerce.asia/partner/147/order/MYORDER0500004
{
"shipCreatedTime":"2015-06-24T04:47:00Z",
"shipSender":{
"addressee":"Best Seller Company",
"address1":"Dusit Thani Hotel",
"address2":"964 Rama 4 Road",
"subDistrict":"Silom",
"district":"Bangrak",
"city":"",
"province":"Bangkok",
"postalCode":"10100",
"country":"Thailand",
"phone":"0888888888",
"email ":"one@a.com"
},
"shipShipment":{
"addressee":"Smith Happiness",
"address1":"111 Rama 4 rd.",
"address2":"",
"subDistrict":"Silom",
"district":"Bangrak",
"city":"",
"province":"Bangkok",
"postalCode":"10500",
"country":"Thailand",
"phone":"0111111111",
"email":"two@a.com"
},
"shipPickup":{
"addressee":"Wonderful Merchant",
"address1":"Victory Monument",
"address2":"",
"subDistrict":"Thanon Phaya Thai",
"district":"Ratchathewi",
"city":"",
"province":"Bangkok",
"postalCode":"10400",
"country":"Thailand",
"phone":"022202200",
"email":"order@wonderful-merchant.asia"
},
"shipInsurance":false,
"shipCurrency":"THB",
"shipShippingType":"NEXT_DAY",
"shipPaymentType":"NON_COD",
"shipPickingList":[
{
"itemDescription":"A flagship smartphone",
"itemQuantity":1
},
{
"itemDescription":"Gadgets for a flagship smartphone",
"itemQuantity":4
}
]
}
With the request above, when aCommerce received an order, aCommerce will generate a list of picking items and send out an email to merchant to let them know they have to pack the items, and aCommerce will go to pickup.
The message body for placing an order will be looks like the following code, this call will create a shipping order, with one package to be picked up.
Placing an order with one package to be shipped
PUT https://shipping.api.acommerce.asia/partner/147/order/MYORDER0500001
{
"shipCreatedTime":"2015-06-30T03:00:00Z",
"shipSender":{
"addressee":"Dan Happiness",
"address1":"Dusit Thani Hotel",
"address2":"964 Rama 4 Road",
"subDistrict":"Silom",
"district":"Bangrak",
"city":"",
"province":"Bangkok",
"postalCode":"10100",
"country":"Thailand",
"phone":"0888888888",
"email ":"one@a.com"
},
"shipShipment":{
"addressee":"Smith Happiness",
"address1":"111 Rama 4 rd.",
"address2":"",
"subDistrict":"Silom",
"district":"Bangrak",
"city":"",
"province":"Bangkok",
"postalCode":"10500",
"country":"Thailand",
"phone":"0111111111",
"email":"two@a.com"
},
"shipPickup":{
"addressee":"BTS Kiosk",
"address1":"BTS Victory Monument",
"address2":"",
"subDistrict":"Thanon Phaya Thai",
"district":"Ratchathewi",
"city":"",
"province":"Bangkok",
"postalCode":"10400",
"country":"Thailand",
"phone":"022655800",
"email":""
},
"shipInsurance":false,
"shipShippingType":"NEXT_DAY",
"shipPaymentType":"NON_COD",
"shipPackages":[
{}
]
}
Placing an order with number of packages to be picked up
To have aCommerce picking up the packages, a set of shipPackages must be provided, since all fields in Package Detail are optional, API user can omitted all fields and use an empty body. From the example above, the shipping partner would like to ship a single package, then the value of shipPackages will be
"shipPackages":[
{}
]
And if shipping partner would like to ship 3 packages, the value of shipPackages will be
"shipPackages":[
{},
{},
{}
]
The code above put 3 empty Package Detail, that's mean API user don't want to declare anything in any packages.
Placing an order with package declaration
Shipping partner can declare a package to let aCommerce know some information, it could be weight, dimensions or any fields listed in the Package Detail
"shipPackages":[
{
"packageWeight":5,
"packageHeight":15,
"packageWidth":20,
"packageDepth":30
}
]
The code above contains weight and volume detail, which can be used by aCommerce to select a suitable pick up service.
Shipping partner can declare all packages, or just some packages, the example code shown below show the shipping order with 3 packages, where only one of them has details.
"shipPackages":[
{
"packageWeight":12,
"packageItems":[
{
"itemDescription":"A fragile items",
"itemQuantity":5
}
]
},
{},
{}
]
And a full message body and request URI are displayed below
PUT https://shipping.api.acommerce.asia/partner/147/order/MYORDER0500002
{
"shipCreatedTime":"2015-06-30T03:00:00Z",
"shipSender":{
"addressee":"Dan Happiness",
"address1":"Dusit Thani Hotel",
"address2":"964 Rama 4 Road",
"subDistrict":"Silom",
"district":"Bangrak",
"city":"",
"province":"Bangkok",
"postalCode":"10100",
"country":"Thailand",
"phone":"0888888888",
"email":"one@a.com"
},
"shipShipment":{
"addressee":"Smith Happiness",
"address1":"111 Rama 4 rd.",
"address2":"",
"subDistrict":"Silom",
"district":"Bangrak",
"city":"",
"province":"Bangkok",
"postalCode":"10500",
"country":"Thailand",
"phone":"0111111111",
"email":"two@a.com"
},
"shipPickup":{
"addressee":"BTS Kiosk",
"address1":"BTS Victory Monument",
"address2":"",
"subDistrict":"Thanon Phaya Thai",
"district":"Ratchathewi",
"city":"",
"province":"Bangkok",
"postalCode":"10400",
"country":"Thailand",
"phone":"022655800",
"email":""
},
"shipInsurance":false,
"shipCurrency":"THB",
"shipShippingType":"NEXT_DAY",
"shipPaymentType":"NON_COD",
"shipPackages":[
{
"packageWeight":12,
"packageItems":[
{
"itemDescription":"A fragile items",
"itemQuantity":5
}
]
},
{},
{}
]
}
Place an order with package items declaration
When shipping partner is going to place an international shipping order, package declaration must be provided for custom service.
Item declaration is also used for shipping insurance, by setting attribute shipInsurance to true, insurance is applied to the placed shipping order.
PUT https://shipping.api.acommerce.asia/partner/147/order/MYORDER0500003
{
"shipCreatedTime":"2015-06-24T04:47:00Z",
"shipSender":{
"addressee":"Dan Happiness",
"address1":"Dusit Thani Hotel",
"address2":"964 Rama 4 Road",
"subDistrict":"Silom",
"district":"Bangrak",
"city":"",
"province":"Bangkok",
"postalCode":"10100",
"country":"Thailand",
"phone":"0888888888",
"email ":"one@a.com"
},
"shipShipment":{
"addressee":"Smith Happiness",
"address1":"2-16-1 Konan Shinagawa East One Tower",
"address2":"",
"subDistrict":"",
"district":"Minato",
"city":"Tokyo",
"province":"",
"postalCode":"108-8282",
"country":"Japan",
"phone":"0111111111",
"email":"smith@japan.asia"
},
"shipPickup":{
"addressee":"Dan Happiness",
"address1":"Dusit Thani Hotel",
"address2":"964 Rama 4 Road",
"subDistrict":"Silom",
"district":"Bangrak",
"city":"",
"province":"Bangkok",
"postalCode":"10100",
"country":"Thailand",
"phone":"0888888888",
"email ":"one@a.com"
},
"shipInsurance":true,
"shipCurrency":"THB",
"shipShippingType":"NEXT_DAY",
"shipPaymentType":"NON_COD",
"shipPackages":[
{
"packageWeight":1.5,
"packageHeight":10,
"packageWidth":30,
"packageDepth":30,
"packageDeclaredValue":2500.00,
"packageItems":[
{
"itemDescription":"A widget that can be used for amazing things",
"itemQuantity":1
},
{
"itemDescription":"A much smaller widget that is not so useful",
"itemQuantity":10
}
]
}
]
}
Placing order with a specified payment method
aCommerce shipping service support cash on delivery or "COD", it is a transaction in which payment for a good is made at the time of delivery, if the purchaser does not make payment when the good is delivered, then the good will be returned to the seller. aCommerce also support "CCOD" or credit card on delivery, but the service areas are limited.
Example of an already paid good delivery.
... "shipPaymentType":"NON_COD", ...
Example of a shipping order with cash on delivery, API user have to put "shipGrossTotal" field to the message.
... "shipPaymentType":"COD", "shipGrossTotal":1000.00, ...
Example of a shipping order with credit card on delivery.
... "shipPaymentType":"CCOD", "shipGrossTotal":1000.00, ...
Response Message
Order Created
RESPONSE 201: Created
{
// an entity corresponding to the requested resource is sent in the response
}
Conflict Order
RESPONSE 409: Conflict
{
"error": {
"message": "Order ID is duplicated"
"errors":[
{
"reason":"already_exists",
"message":"Order ID MYORDER0500001 has already exists"
]
}
}
Missing Fields
RESPONSE 422: Unprocessable Entity
{
"error": {
"message": "Validation Failed",
"errors":[
{
"reason":"missing_field",
"message":"shipSender, this field is required"
},
{
"reason":"missing_field",
"message":"shipShippingType, this field is required"
}
]
}
}
Shipping Order Retrieval
Response Message
Order read successfully
RESPONSE 200: OK
{
// an entity corresponding to the requested resource is sent in the response
}
Order not found in system
RESPONSE 404: Not found
{
"error": {
"message": "Order ID is not found"
"errors":[
{
"reason":"missing",
"message":"Order MYORDER0599999 not found"
}
]
}
}
Shipping Order Modification
ORDER UPDATING IS NOT SUPPORTED RIGHT NOW, JUST REPLY WITH ERROR MESSAGE
RESPONSE 501: Not Implemented
{
"error": {
"message": "Order Modification is not yet implemented"
}
}
This endpoint is used to allow a partner to update an order to the aCommerce system after it has already been placed. The aCommerce system will match this PUT request against an order with the same orderId and shipCreatedTime value or the LATEST order placed with this orderId if the shipOrderCreated value is not present. This API will reject the PUT request if the order is in a state where it cannot be updated (e.g. a pickup was requested, the pickup location cannot be changed after the driver is in route). In such cases, this endpoint will return a will return a "409 Conflict" error with a JSON document providing more detail about the error condition.
Shipping Order Cancellation
ORDER CANCELING IS NOT SUPPORTED RIGHT NOW, JUST REPLY WITH ERROR MESSAGE
RESPONSE 501: Not Implemented
{
"error": {
"message": "Order Cancellation is not yet implemented"
}