Order Creation

Upload your orders into Best system, only one order can be uploaded in single request.

• URL: {API root URL}/orders
• Method: POST

Request

Attribute List

Element Name	Required	Data Type	Description
customerCode	Y	String	Your unique customer code assigned by Best system.
orderNumber	Y	String	An unique number to identify your order. Up to 30 characters.
warehouseCode		String	Indicate the warehouse that you want Best to ship your product from. Leave empty if your inventory is only located in one location or you want Best system to choose proper warehouse for you.
warehouseNotes		String	Special instructions for warehouse operation, up to 4000 characters.
giftNotes		String	The gift message you want Best operation team to include in your package, up to 1000 characters.
giftWrapRequired		String	Indicate if your order requires gift wrapping, available value is None or Required. Default value is None.
scheduledReleaseDate		String	Scheduled release date for orders. Submit orders to be created but not released until a future date as specified. Accepted format: MM-DD-YYYY.
poNumber		String	An unique number to identify the purchase order if available, up to 30 characters.
reference1		String	Reference number 1.
reference2		String	Reference number 2.
maximumPalletHeight		String	Specify the maximum height allowed for orders. Measurement in inches, accepts any positive integer value greater than 1.
invoiceNumber		String	Invoice number of the order.
shipToName	*	String	Recipient name. This field is required if ShipToCompany has no value.
shipToCompany	*	String	Recipient company name. This field is required if ShipToName has no value.
shipToStreetLine1	Y	String	Identify the destination address of shipment
shipToStreetLine2		String	Additional address info
shipToStreetLine3		String	Additional address info
shipToCity	Y	String	The city name of the ship to address.
shipToState	*	String	For US domestic orders, it’s required and value has to be the 2 letters of the state code. For international orders, put the actual state or province name, leave empty if the destination aderess doesn’t have state or province.
shipToZip	Y	String	The zip code of the shipping address
shipToCountry	Y	String	The ISO 2 characters code for the country of the shipping address, refer to https://countrycode.org/ for the country code list. If you are shipping your items to international countries out of United States, refer to International Orders page for more details.
shipToPhone		String	The phone number of the order recipient.
shipToEmail		String	The email address of the order recipient.
customerOrderType	Y	String	Indicate the type of the order, check Customer Order Type Reference page regarding the detail and how to provide the right value.
carrierBillingType	Y	String	Indicate the billing method for the shipping cost of the order, below values are expected: • Owner • Sender • ThirdParty • Receiver Check Carrier & Service Reference page regarding the detail and how to provide the right value.
carrierServiceLevel	Y	String	Indicate the shipment service level for the order, below values are expected: • Ground • NextDay • SecondDay • ThreeDay • LTL • WillCall • ShipDoc Important! For international parcel shipping, Only Ground is accepted. Check Carrier & Service Reference page regarding the detail and how to provide the right value.
carrier	*	String	The name of the carrier who will deliver the order, below values are expected: • USPS • FedEx • UPS • LANDMARK • DHL Refer to Carrier & Service Reference page for more details.
carrierService	*	String	The service code that pre-defined by carrier. Value is various for different carrier. Refer to Carrier & Service Reference page for more details.
shipperCarrierAccount	*	String	The number of shipper’s carrier account that will use to fulfill the order. Refer to Carrier & Service Reference page for more details.
carrierAccountNumber	*	String	The carrier account that will be billed for the order. Refer to Carrier & Service Reference page for more details.
carrierAccountZip	*	String	The zip code of the carrier account owner. Refer to Carrier & Service Reference page for more details.
optionSignature		String	Indicate if your order package requires a signature when delivery, available value is None or Required. Default value is None.
shipInsurance		String	Indicate if your order package requires carrier insurance. Available value is True or False. Default value is False.
currencyCode	*	String	The 3 characters currency code to indicate which currency the Price is based on. Please always provide the right currency code for your international orders, the default value is USD (US Dollar) if you don’t provide. Refer to International Orders page for more details.
orderDate		DateTime	The date & time when the order is originally placed by your customer. Value is always based on UTC time zone by format YYYY-MM-DDThh:mm:ss or  YYYY-MM-DDThh:mm:ssTZD with 24-hour clock time. For example: 2020-02-11T19:13:00 or  2020-02-11T11:13:00-08:00
salesChannel		String	The retailer name where the order comes from. Refer to Order Sales Channel page for more details.
storeNumber		String	The store number of the sales channel for the order. Refer to Order Sales Channel page for more details.
shipFromName	*	String	The name of the sender. It will be printed on the shipping from section of the shipping label with shipping from address together once value is provided.
shipFromCompany	*	String	The name of the sender company. It will be printed on the shipping from section of the shipping label with shipping from address together once value is provided.
shipFromStreetLine1	*	String	Address line 1 of the shipping from address. Your shipping from address will be printed on the shipping from section of the shipping label once value is provided.
shipFromStreetLine2		String	Additional address info
shipFromStreetLine3		String	Additional address info
shipFromCity	*	String	The city name of the shipping from address.
shipFromState	*	String	For US domestic shipping from address, it has to be the 2 letters of the state code.
shipFromZip	*	String	The zip code of the shipping from address
shipFromCountry		String	The ISO 2 characters code for the country of the shipping from address, refer to https://countrycode.org/ for the country code list. Default value “US” will be applied if value is not provided.
shipFromPhone		String	The phone number of the order sender. It will be printed on the shipping from section of the shipping label with shipping from address together once value is provided.
shipFromEmail		String	The email address of the order sender.
tariffPaymentParty		String	Applicable for international orders, indicate who will be responsible to pay the duty & tax. The following values are available: • Sender Default value if value is not provided. • Receiver • ThirdParty When value is Receiver or ThirdParty, the payer’s carrier account number and zip code are required to be provided in field CarrierAccountNumber and  CarrierAccountZip.
exportReason		String	Applicable for international orders, indicate the reason of exporting the products in the order. The following values are available: • Sale. Default value if value is not provided. • Gift • Sample • Return • Repair
deliveryIncoterms		String	Applicable for international orders, indicate the incoterms of the customs clearance. The following values are available: • DDP. Delivered Duty Paid. Default value if value is not provided. • DDU. Delivered Duty Unpaid.
details	Y	Array<Object>	The SKU list in the order.
details/sku	Y	String	The number of the item.
details/quantity	Y	Integer	The quantity of the item.
details/price		Decimal	Required for international order. The unit price of the item. Refer to International Orders page for more details.
details/countryOfOrigin		String	Required for international order. The ISO 2 characters code of the originally produced country for current item in the order. Refer to International Orders page for more details.
details/hsCode		String	Required for international order. The International tariff code of the item. Refer to International Orders page for more details.
details/boxCode		String	Indicate the packing material or options for this order. Leave empty if you want Best operation team to decide the packing option. Available values: • OEM. Item will be shipped in its original package. • OVERPACK. Item will be shipped within an outer box. Warehouse operation will decide what box to use. • WHdecide. Short for Warehouse will Decide. This is the default value if no option was provided. Warehouse operation will decide the packing option, OEM or OVERPACK for orders.  • Box Code. The SKU # of the packing material you previously created in our system. Follow below steps if you want to use your own material: 1. Create that material as a SKU first 2. Send them into Best warehouse 3. Put the SKU # of the material SKU into this field when create your orders.
details/retailSKU		String	The SKU number from the retailer. You don’t need to provide this value unless the order is a purchase order from a retailer, and the retailer requires to print their SKU number on the carton label or product label.
details/retailDescription		String	The SKU description from the retailer. If the order is a purchase order from a retailer, you may provide this field for a reference in Best system.
details/unitCost		String	The unit cost of the SKU. The amount you wish to insure for current item.
documents		Array<Object>	The order documents you want to attach after order is created. Refer to Order Documents page for more details.
documents/documentType	Y	String	The type of the order document. The following values are available: • SHIPPING_LABEL • BILL_OF_LADING • PRODUCT_LABEL • CARTON_LABEL • PALLET_LABEL • PACKING_LIST • COMMERCIAL_INVOICE • OTHER
documents/fileName	Y	String	The file name of the document, extension name should be included such as “.pdf”, “.png”. File name can’t be duplicated in all documents in same order.
documents/description		String	Any comment text for current document.
documents/	Y	String	This is to specify whether the encoded bytecode or the Label URL to be uploaded. Available values: • data– Indicates request is for encoded Base64. • url- Indicates the file download URL location.
requiredDocuments	Y (for Customer Order Type as VAS only)	Array<String>	Specify the required document(s) associated with current order. It is required if Customer Order Type is VAS. Available values: • PRODUCT_LABEL • CARTON_LABEL • PALLET_LABEL • PACKING_LIST • COMMERCIAL_INVOICE • OTHER

Request Example

{
    "customerCode": "USSAND",
    "orderNumber": "API-test-001",
    "warehouseCode": "USCA01",
    "warehouseNotes": "Testing order",
    "giftNotes": "",
    "poNumber": "P233677",
    "shipToName": "John Doe",
    "shipToCompany": "Best Inc.",
    "shipToStreetLine1": "5125 Schaefer Ave",
    "shipToStreetLine2": "STE 101",
    "shipToStreetLine3": "",
    "shipToCity": "Chino",
    "shipToState": "CA",
    "shipToZip": "91710",
    "shipToCountry": "US",
    "shipToPhone": "626-626-7665",
    "shipToEmail": "johnD@testemail.com",
    "customerOrderType": "VAS",
    "carrierBillingType": "Sender",
    "carrierServiceLevel": "Ground",
    "carrier": "UPS",
    "carrierService": "03",
    "carrierAccountNumber": "",
    "carrierAccountZip": "",
    "optionSignature": "Required",
    "currencyCode": "USD",
    "orderDate": "2021-09-28",
    "salesChannel": "",
    "storeNumber": "",
    "details": [
        {
            "sku": "A001",
            "quantity": 2,
            "price": 15.99,
            "countryOfOrigin": "US",
            "hsCode": "457733",
            "boxCode": "OEM"
        },
        {
            "sku": "A002",
            "quantity": 1,
            "price": 25.99,
            "countryOfOrigin": "US",
            "hsCode": "496693",
            "boxCode": "OEM"
        }
    ],
    "documents": [
    {
      "documentType": "PACKING_LIST",
      "fileName": "pl.pdf",
      "description": "Packing Slip File",
      "data": "{actual base64 content for your file}"
    }
    {
      "documentType": "CARTON_LABEL",
      "fileName": "p2.pdf",
      "description": "Carton Label File",
      "data": "{actual base64 content for your file}"
    }
  ],
    "requiredDocuments": [
        "PACKING_LIST",
		"CARTON_LABEL"
    ],
}

Response

Attribute List

Element Name	Data Type	Description
Id	Integer	The internal ID of the order.
status	String	The order status, value will be always “Creating” in this order creation response.
uploadTime	DateTime	The date and time when the order is created into Best Inc. system. Value is based on UTC time zone.
customerCode	String	Your unique customer code assigned by Best system.
orderNumber	String	The order number specified in your request.
warehouseCode	String	Indicate the warehouse that will process current order.
warehouseNotes	String	Special instructions for warehouse operation specified in your request.
giftNotes	String	The gift message you want Best operation team to include in your package.
scheduledReleaseDate	String	Scheduled release date for orders.
poNumber	String	The purchase order number specified in your request.
sShipToName	String	Recipient name.
shipToCompany	String	Recipient company name.
shipToStreetLine1	String	The destination address of shipment.
shipToStreetLine2	String	Additional address info.
shipToStreetLine3	String	Additional address info.
shipToCity	String	The city name of the ship to address.
shipToState	String	The state name of the ship to address.
shipToZip	String	The zip code of the ship to address.
shipToCountry	String	The country code of the ship to address.
shipToPhone	String	The phone number of the order recipient.
shipToEmail	String	The email address of the order recipient.
customerOrderType	String	The type of the order specified in your request.
carrierBillingType	String	The billing method specified in your request.
carrierServiceLevel	String	The shipment service level specified in your request.
carrier	String	The name of the shipping carrier specified in your request.
carrierService	String	The shiping service code specified in your request.
carrierAccountNumber	String	The carrier account number that will be billed for all shipped packages, specified in your request.
carrierAccountZip	String	The zip code associated with the carrier account,specified in your request.
optionSignature	String	Indicate if your order package requires a signature when delivery.
currencyCode	String	The 3 characters currency code for the price specified in your request.
orderDate	DateTime	The original date & time when the order was placed, specified in your request.
salesChannel	String	The retailer name of current order, specified in your request.
storeNumber	String	The store number of the sales channel if specified in your request.
details	Array<Object>
details/sku	String	The item number of item.
details/quantity	Integer	The order quantity of current item.
details/price	Decimal	The item price if specified in your request.
details/countryOfOrigin	String	The originally produced country for current item in the order if specified in your request.
details/hsCode	String	The International tariff code of the item if specified in your request.
details/boxCode	String	The packing option/ or material specified in your request.

Response Example

{
    "orderDate": "2021-09-28T00:00:00+00:00",
    "warehouseNotes": "Testing order",
    "giftNotes": "",
    "customerOrderType": "Standard",
    "salesChannel": "",
    "importChannel": "API",
    "poNumber": "P233677",
    "shipToName": "John Doe",
    "shipToCompany": "Best Inc.",
    "shipToStreetLine1": "5125 Schaefer Ave",
    "shipToStreetLine2": "STE 101",
    "shipToStreetLine3": "",
    "shipToCity": "Chino",
    "shipToState": "CA",
    "shipToZip": "91710",
    "shipToCountry": "US",
    "shipToPhone": "626-626-7665",
    "shipToEmail": "johnD@testemail.com",
    "optionSignature": "Required",
    "carrierServiceLevel": "Ground",
    "carrier": "UPS",
    "carrierService": "03",
    "carrierBillingType": "Sender",
    "details": [
        {
            "sku": "A001",
            "quantity": 2,
            "price": 15.99,
            "boxCode": "OEM",
            "countryOfOrigin": "US",
            "hsCode": "457733"
        },
        {
            "sku": "A002",
            "quantity": 1,
            "price": 25.99,
            "boxCode": "OEM",
            "countryOfOrigin": "US",
            "hsCode": "496693"
        }
    ],
    "wmsOrders": [],
    "status": "Creating",
    "shipStatus": "None",
    "id": 64528,
    "customerCode": "USSAND",
    "orderNumber": "API-test-001",
    "warehouseCode": "USCA01",
    "uploadTime": "2021-09-28T22:57:58+00:00"
}