The following reference guide will allow you to create orders and retrieve their status within the FORT Warehouse Management System (WMS).
The RESTful Order API is intended to be used by an external system that would like to fulfill orders within WMS. The RESTful Order API allows a system to create and view the status of orders securely over HTTPS.
After WMS has supplied your company with a username, password, and remote api key, you will have access to create and view your orders within WMS. Initially, when an order creation request is received, it will be validated, placed in your company’s order upload queue, and then processed in sequence. The request will be validated for required fields and data, as outlined in Appendix A. If the request is accepted, you will receive a 202 (Accepted) response from WMS with a unique request_key. This request_key will be used as the primary identifier for the request.
Once WMS has processed your order upload, you will receive a postback to the postback_url provided in the request with the request_key, as well as the results of the upload. If everything was uploaded into WMS smoothly, then the response will contain a success message for each order that was uploaded. If any orders failed to upload, then the errors and warnings will be provided in the response, as defined by the Error Handling section.
Once an order has been created successfully, you may view the status and attributes of the order, as outlined in the Retrieve section. This retrieve will bring back all the information about the order, as well as information about the sub-resources within the order, including the individual recipients, packages, and products.
All requests can be either JSON or XML formatted. To inform WMS which content type you are providing, you must provide the following header in the request:
| Request Data Representation | Header |
|---|---|
| JSON | Content-Type: “application/json” |
| --- | --- |
| XML | Content-Type: “application/xml” |
To designate whether you would like the response from WMS formatted as JSON or XML, you either append a MIME Extension to the end of the resource identifier, or send an Accept header in the request, as shown below:
| Response Data Representation | Header | MIME Extension |
|---|---|---|
| JSON | Accept: “application/json” | .json |
| --- | --- | --- |
| XML | Accept: “application/xml” | .xml |
A single request may contain many orders. Each order can contain 1 to many recipients. Each recipient can contain 1 to many packages. Each package can contain 1 to many products. This nested structure results in the schema shown below: Note: The auth block is provided on request but _is _never returned in** the response. Each section has either a primary identifier or set of identifiers, as shown in the table below:
| Request section | Identifier(s) |
|---|---|
| orders | order_number & seller_code |
| --- | --- |
| recipients | recipient_id_3p |
| packages | package_id_3p |
| products | product_id |
These identifier fields are required to identify the resource in the case of an error.
All requests are required to use HTTPS and are authenticated with the following 3 fields:
| Field | Description |
|---|---|
| username | A username provided by WMS |
| --- | --- |
| password | A password provided by WMS |
| remote_api_key | A unique key provided by WMS that is associated with your company |
For GET requests, authentication credentials are provided in the query string. For example, the following URL would both authenticate the user, and retrieve information about an order: https:// **[Your WMS Domain]/rest/v1/orders/[order_number]/?seller_code=[Your Seller Code]&username=[Your Username]&password=[Your_ _Password]&remote_api_key=[_Your _Remote API Key] *Note: Do not include the_ _square brackets,_ _“[” or “]”,_ in the GET request_* For POST requests, the authentication credentials are embedded in a top level auth block within the body of the request, JSON snippet below:
All dates and times are represented using the ISO 8601 format and expected to be UTC (Universal Coordinated Time). Any field that has a suffix of _date is a date, while any field with a suffix of _datetime is considered to be a datetime. Date formats listed below:
| Type | Suffix | Format | Example |
|---|---|---|---|
| Date | _date | YY-MM-DD | 1/1/2016 |
| --- | --- | --- | --- |
| Datetime | _datetime | YY-MM-DDThh:mm:ssZ | 2016-01-01T08:00:00Z |
Each of the supported order actions are associated with a particular HTTP Verb, as described below:
| Product Action | HTTP Verb | Url | Description |
|---|---|---|---|
| Create | POST | /rest/v1/orders/ | Create an order within WMS |
| --- | --- | --- | --- |
| Retrieve | GET | /rest/v1/orders/[order_number]/?seller_code=[Your Seller Code] | Retrieve all attributes of an order and its nested sub resources. |
When one or more orders are uploaded into the WMS, the batch of orders is placed into a queue and executed sequentially per company. This means that the original request to create one or more orders is merely a request to place the order(s) into a queue. You will know the initial request to place the order(s) into the queue was successful when you receive a 202 (Accepted) response back from WMS, along with a request_key***. The request_key ***represents the entire request and will be used to identify the results of the upload later. Any validation error will invalidate the entire batch and prevent the batch from entering the queue. Validation errors will return a status code of 400 (Bad Request) and will give more information about the problem, as defined in the Error Handling section. When the queue processes the batch, the results are then posted back to the URL provided in the postback_url field in the settings block. This response will contain the same request_key from the initial response, as well as one or more of the following arrays: errors, warnings and information. These arrays will contain all the upload results from the upload, and will follow the same schema as defined in the Error Handling section. Each successful order upload will result in one information entry with the order instance URL and a status of 200 (OK). For more information, please see the Create example in the Examples section.
To retrieve the attributes of an order, you will need the order_number and seller_code of the order, as well the correct credentials to access the order. Once these are obtained, the request is as simple as a normal GET request to the orders API endpoint, using the order_number as the primary resource identifier as well as the seller_code within the query string. The GET request will also retrieve the attributes for the sub-resources, including: recipients, packages, and products. The sub-resources are contained within arrays by their respective names. Url format below: _https:// _[Your WMS Domain]/rest/v1/orders/[order_number]/?seller_code=[Your Seller Code]&username=[Your Username]&password=[Your_ Password_]&remote_api_key=[Your Remote API Key]** For more information, please see the Retrieve example in the Examples section. ** **
There are three levels of error handling supported by WMS: error, warning, and information. These different types of errors are included at the top level of the FORT API response within arrays by their respective names: errors, warnings, and information. These arrays can contain 0 to many instances of the specific type of problem within the response. These will follow the schema defined below:
| Field Name | Required? | Type | Description |
|---|---|---|---|
| title | Yes | String | A generic title for the error |
| --- | --- | --- | --- |
| status | Yes | Integer | A status code that represents the type of error |
| detail | Yes | String | More information about the type of error and, where appropriate, how to fix it |
| instance | No | String | Included where appropriate, this will identify the offending resource. Format: /rest/v1/orders/[order_number]?seller_code=[Your Seller Code]. |
| request_key | No | Guid | In the case of an exception, the request key will be included in the error message to assist support. This key is the unique identifier for the request. |
For example, an authentication error would look like: xx
In addition to the error handling above, an HTTP status code will also be returned with the response. The currently supported HTTP status codes are shown below:
| HTTP Status Code | Description |
|---|---|
| 200 | Status OK |
| --- | --- |
| 201 | Created |
| 202 | Accepted |
| 400 | Bad Request |
| 404 | Not Found |
| 405 | Method Not Allowed |
| 500 | Internal Server Error |
If an error has occurred, the orders*** array will not be returned in a request and the errors*** array will be present instead. If the request encountered a non-fatal problem and the request was successful, then the orders array will be present, along with any warnings*** ***or information that might be of use to the API client.
The following examples are complete, except for authentication credentials.
**Request URL: **/rest/v1/orders/ **HTTP Verb: **POST **Example ****Request ****JSON ****Payload: **
{
"auth": {
"username": "*[**Your Username**]*",
"password": "*[**Your Password**]*",
"remote_api_key": "*[**Your Remote API Key**]*"
},
"settings": {
"postback_url": "*[**Your Postback URL**]*"
},
"orders": [{
"order_number": "TEST_ORDER_01",
"seller_code": "TESTCOMP01",
"order_type": "Club",
"order_date": "01/01/2016",
"billing_first_name": "John",
"billing_last_name": "Smith",
"billing_company_name": "Test Company",
"billing_street_address_1": "700 Larkspur Landing",
"billing_street_address_2": "Ste 125",
"billing_city": "Larkspur",
"billing_state": "CA",
"billing_zip": "94939",
"billing_country": "USA",
"recipients": [{
"recipient_id_3p": "56562229-3CD7-4DDD-A52C-987B4B6B5DEA",
"shipping_first_name": "John",
"shipping_last_name": "Smith",
"shipping_street_address_1": "700 Larkspur Landing",
"shipping_street_address_2": "Ste 125",
"shipping_city": "Larkspur",
"shipping_state": "CA",
"shipping_zip": "94939",
"shipping_country": "USA",
"packages": [{
"shipment_method": "GSC",
"package_id_3p": "TEST_ORDER_01_1",
"total_product_amount": "162.00",
"products": [{
"product_id": "AE81A654-A113-AFED-E4E5-49255567225D",
"quantity": "6",
"product_sale_amount": "15.00"
}, {
"product_id": "C27FB19A-02E4-7B5A-4928-ADD06932E49B",
"quantity": "6",
"product_sale_amount": "12.00"
}
}]]
}]
}]
}
Request_key**: 7F412D02-71CF-4451-BF92-887375841BD8 Requested Order Number: TEST_ORDER_01 Requested **Order Seller Code: TESTSELLERCODE01 Response Endpoint: https://[Your Domain]/[Your API Endpoint] **HTTP Verb: **POST Response MIME Type: JSON Successful_ __Order Upload _JSON Postback:
{
"warnings": [{
"request_key": "A06F1A0E-F55C-91D9-397E-27EE89182A11",
"status": 200,
"instance": "/rest/v1/orders/TEST_ORDER_01/",
"title": "Import Warning",
"detail": "There is not enough inventory for Product \"Test Product 01\". If you have specified an inventory location, make sure there is enough inventory on hand."
}],
"information": [{
"request_key": "A06F1A0E-F55C-91D9-397E-27EE89182A11",
"status": 200,
"instance": "/rest/v1/orders/TEST_ORDER_01/",
"title": "Order Upload Success",
"detail": "Order with Order Number: (TEST_ORDER_01) has been uploaded successfully."
}]
}
{
"errors": [{
"request_key": "A06F1A0E-F55C-91D9-397E-27EE89182A11",
"status": 400,
"instance": "/rest/v1/orders/TEST_ORDER_01/",
"title": "Import Error",
"detail": "The zip code 99999 is not in our system."
}...
Order Number**: TEST_ORDER_01 Seller Code: TESTSELLERCODE01 Example Request URL: https://[Your WMS Domain]/rest/v1/orders/ TEST_ORDER_01/?seller_code= TESTSELLERCODE01&username=[Your Username]&password=[Your_ _Password]&remote_api_key=[Your Remote API Key]****&includeArchived=**[0|1] **HTTP Verb: **Get
{
"orders": [{
"billing_age_confirm": null,
"seller_branding_code": null,
"sub_type": null,
"recipients": [{
"shipping_city": "Larkspur",
"shipping_birth_date": null,
"shipping_zip": 94939,
"shipping_state": "CA",
"packages": [{
"is_gift": 0,
"package_status_comment": null,
"handling_fees_amount": 0,
"seller_branding_code": null,
"delivery_instructions": null,
"package_id_3p": "TEST_ORDER_01_1",
"freight_amount": 0,
"depletion_datetime": null,
"special_instructions": null,
"pod_invoice_datetime": null,
"shipment_tracking_datetime": null,
"invoice_date": null,
"discount_product_amount": 0,
"crossdock_sent_datetime": null,
"is_adult_signature_required": null,
"shipment_method": "GSC",
"payment_date": null,
"recipient_message": null,
"package_status_code": null,
"fulfiller": "TESTWAREHOUSE01",
"pod_invoice_numbers": null,
"package_shipping_status_flag": 0,
"gift_wrap": null,
"gift_card": null,
"requested_ship_date": null,
"crossdock_received_datetime": null,
"surcharges": null,
"total_product_amount": 162,
"insurance_amount": 0,
"requested_delivery_date": null,
"products": [{
"product_sku": "TESTPROD01",
"quantity": 6,
"product_alc": 13.5,
"product_id": "AE81A654-A113-AFED-E4E5-49255567225D",
"product_name": "Test Wine 01",
"supplier_code": "TESTSUPPLIERCODE01",
"product_sale_amount": 15.00
}, {
"product_sku": "TESTPROD02",
"quantity": 6,
"product_alc": 13.5,
"product_id": "C27FB19A-02E4-7B5A-4928-ADD06932E49B",
"product_name": " Test Wine 02",
"supplier_code": " TESTSUPPLIERCODE02",
"product_sale_amount": 12.00
}],
"discount_freight_amount": 0,
"tracking_number": null,
"discount_amount": 0,
"package_id": 9990032,
"compliance_id": null,
"manifest_number": null
}],
"shipping_phone_1": null,
"shipping_last_name": "Smith",
"shipping_company_name": "Test Company",
"shipping_age_confirm": null,
"shipping_street_address_2": "Ste 125",
"shipping_phone_2": null,
"age_verification_id": null,
"shipping_first_name": "John",
"shipping_street_address_1": "700 Larkspur Landing",
"shipping_mobile_phone": null,
"shipping_email": null,
"recipient_type": null,
"recipient_id": null,
"shipping_country": "US",
"recipient_id_3p": "56562229-3CD7-4DDD-A52C-987B4B6B5DEA"
}],
"billing_city": "Larkspur",
"actual_ship_datetime": null,
"billing_birth_date": null,
"billing_last_name": "Smith",
"billing_id": null,
"seller_code": "TESTCOMP01",
"billing_first_name": "John",
"order_source_3p": null,
"purchase_order_number": null,
"billing_id_3p": null,
"order_date": "2016-01-01",
"billing_country": "US",
"invoice_number": null,
"order_type": "Club",
"billing_company_name": "Test Company",
"billing_street_address_2": "Ste 125",
"billing_street_address_1": "700 Larkspur Landing",
"billing_email": null,
"billing_mobile_phone": null,
"order_number": "TEST_ORDER_01",
"billing_zip": 94939,
"billing_phone_2": null,
"billing_state": "CA",
"billing_phone_1": null
}]
}
| Field Name | POST Active? | POST Required? | GET Active? | FORT 209 Column Name (Position) |
|---|---|---|---|---|
| actual_ship_datetime | No | No | Yes | Ship Date (34) |
| --- | --- | --- | --- | --- |
| billing_first_name | Yes | Yes | Yes | Billing First Name (60) |
| billing_last_name | Yes | Yes | Yes | Billing Last Name (61) |
| billing_state | Yes | Yes | Yes | Billing State (67) |
| billing_street_address_1 | Yes | Yes | Yes | Billing Address (64) |
| billing_zip | Yes | Yes | Yes | Billing Postal Code (68) |
| order_date | Yes | Yes | Yes | Order Date (21) |
| order_number | Yes | Yes | Yes | Order No (4) |
| billing_age_confirm | Yes | No | Yes | Customer Age Confirm (75) |
| billing_city | Yes | No | Yes | Billing City (66) |
| billing_company_name | Yes | No | Yes | Billing Company Name (63) |
| billing_country | Yes | No | Yes | Billing Country (69) |
| billing_birth_date | Yes | No | Yes | Billing DOB (74) |
| billing_email | Yes | No | Yes | Billing Email (73) |
| billing_id | Yes | No | Yes | Customer ID (58) |
| billing_id_3p | Yes | No | Yes | Customer ID 3P (59) |
| billing_mobile_phone | Yes | No | Yes | Billing Mobile Phone (72) |
| billing_phone_1 | Yes | No | Yes | Billing Phone 1 (70) |
| billing_phone_2 | Yes | No | Yes | Billing Phone 2 (71) |
| billing_street_address_2 | Yes | No | Yes | Billing Address 2 (65) |
| force_3_tier | Yes | No | No | Force 3 Tier (15) |
| invoice_date | Yes | No | Yes | Invoice Date (22) |
| invoice_number | Yes | No | Yes | Invoice No (6) |
| is_archived | No | No | Yes | N/A |
| is_license_to_license | Yes | No | No | License to License (12) |
| is_onsite | Yes | No | No | Onsite (11) |
| order_number_3p | Yes | No | Yes | Order No 3P (5) |
| order_source_3p | Yes | No | Yes | Order Source 3P (17) |
| order_type | Yes | No | Yes | Order Type (18) |
| purchase_order_number | Yes | No | Yes | PO No (9) |
| sub_type | Yes | No | Yes | Sub Type (19) |
| Field Name | POST Active? | POST Required? | GET Active? | FORT 209 Column Name (Position) |
|---|---|---|---|---|
| recipient_id_3p | Yes | Yes | Yes | Recipient ID 3P (41) |
| --- | --- | --- | --- | --- |
| shipping_first_name | Yes | Yes | Yes | Recipient First Name (43) |
| shipping_last_name | Yes | Yes | Yes | Recipient Last Name (44) |
| shipping_state | Yes | Yes | Yes | Recipient State (49) |
| shipping_street_address_1 | Yes | Yes | Yes | Recipient Street Address (46) |
| shipping_zip | Yes | Yes | Yes | Recipient Zip (50) |
| age_verification_id | Yes | No | Yes | Age Verification ID (39) |
| recipient_id | Yes | No | Yes | Recipient ID (40) |
| recipient_type | Yes | No | Yes | Recipient Type (42) |
| shipping_age_confirm | Yes | No | Yes | Recipient Age Confirm (57) |
| shipping_city | Yes | No | Yes | Recipient City (48) |
| shipping_company_name | Yes | No | Yes | Recipient Company Name (45) |
| shipping_country | Yes | No | Yes | Recipient Country (51) |
| shipping_birth_date | Yes | No | Yes | Recipient DOB (56) |
| shipping_email | Yes | No | Yes | Recipient Email (55) |
| shipping_mobile_phone | Yes | No | Yes | Recipient Mobile Phone (54) |
| shipping_phone_1 | Yes | No | Yes | Recipient Phone (52) |
| shipping_phone_2 | Yes | No | Yes | Recipient Phone 2 (53) |
| shipping_street_address_2 | Yes | No | Yes | Recipient Address Line 2 (47) |
| Field Name | POST Active? | POST Required? | GET Active? | FORT 209 Column Name (Position) |
|---|---|---|---|---|
| package_id_3p | Yes | Yes | Yes | Package ID 3P (7) |
| --- | --- | --- | --- | --- |
| shipment_method | Yes | Yes | Yes | Courier (24) |
| compliance_id | Yes | No | Yes | Compliance ID (38) |
| delivery_instructions | Yes | No | Yes | Delivery Instructions (85) |
| delivery_datetime | No | No | Yes | N/A |
| discount_amount | Yes | No | Yes | Discount Amount (101) |
| discount_freight_amount | Yes | No | Yes | Discount Amount Freight (103) |
| discount_product_amount | Yes | No | Yes | Discount Amount Product (102) |
| freight_amount | Yes | No | Yes | Freight (92) |
| freight_tax_amount | Yes | No | Yes | Freight Tax Amount (98) |
| gift_card | Yes | No | Yes | Gift Card (88) |
| gift_wrap | Yes | No | Yes | Gift Wrap (89) |
| handling_fees_amount | Yes | No | Yes | Handling Fees (93) |
| handling_tax_amount | Yes | No | Yes | Handling Tax Amount (99) |
| insurance_amount | Yes | No | Yes | Insurance Amount (104) |
| is_allocated | No | No | Yes | N/A |
| is_gift | Yes | No | Yes | Is Gift (86) |
| Is_packed | No | No | Yes | N/A |
| is_archived | No | No | Yes | N/A |
| package_excise_tax_amount | Yes | No | Yes | Excise Tax (100) |
| package_id | Yes | No | Yes | Package ID (8) |
| pod_invoice_datetime | No | No | Yes | N/A |
| product_tax_amount | Yes | No | Yes | Product Tax Amount (97) |
| recipient_message | Yes | No | Yes | Recipient Message (87) |
| requested_delivery_date | Yes | No | Yes | Requested Delivery Date (31) |
| requested_ship_date | Yes | No | Yes | Requested Ship Date (30) |
| seller_branding_code | Yes | No | Yes | Brand Company Code (3) |
| special_instructions | Yes | No | Yes | Special Instructions (84) |
| surcharges | Yes | No | Yes | Special Packaging (91) |
| total_product_amount | Yes | No | Yes | Total Product Amount (106) |
| total_tax_collected_amount | Yes | No | Yes | Total Tax Collected (96) |
| tracking_number | Yes | No | Yes | Courier Tracking No (26) |
| licensee_company_code_x_tier | Yes | No | No | Licensee Company Code xTier (16) |
| crossdock_received_datetime | No | No | Yes | Crossdock Received Date (33) |
| crossdock_sent_datetime | No | No | Yes | Crossdock Sent Date (32) |
| is_adult_signature_required | No | No | Yes | ASR (25) |
| package_shipping_status_flag | No | No | Yes | Package Shipping Status Flag (36) |
| shipping_status | No | No | Yes | N/A |
| package_status_code | No | No | Yes | Package Status (35) |
| package_status_comment | No | No | Yes | Package Comment (37) |
| depletion_datetime | No | No | Yes | N/A |
| fulfiller | No | No | Yes | Fulfiller (27) |
| manifest_number | No | No | Yes | Manifest No (10) |
| package_type | No | No | Yes | Package Type (14) |
| pod_invoice_datetime | No | No | Yes | N/A |
| pod_invoice_numbers | No | No | Yes | N/A |
| shipment_tracking_datetime | No | No | Yes | N/A |
| weight_amount | No | No | Yes | N/A |
| Field Name | POST Active? | POST Required? | GET Active? | FORT 209 Column Name (Position) |
|---|---|---|---|---|
| product_name | Yes | Yes | Yes | Prod Name (110 + P*14) |
| --- | --- | --- | --- | --- |
| quantity | Yes | Yes | Yes | Prod Qty (109 + P*14) |
| product_sale_amount | Yes | No | Yes | Prod Sale Amount (117 + P*14) |
| product_sku | Yes | No | Yes | Prod ID (108 + P*14) |
| supplier_code | Yes | No | Yes | Prod Supplier Code (107 + P*14) |
| product_alc | No | No | Yes | Prod Alc (118 + P*14) |
| product_excise_tax_amount | Yes | No | Yes | Prod Alc (114 + P*14) |
| product_sale_amount | Yes | No | Yes | Prod Alc (112 + P*14) |
Please refer to the FORT 209 Excel document for column descriptions and value options, where appropriate. Changelog V1.01 to v1.02
- Moved request_key within the errors, warnings and information*** ***JSON objects. This is to provide support for orders which consist of products from more than one self-fulfilling suppliers.
V1.02 to v1.03
- Added support for querying archived orders and packages
V1.03 to v1.04
- Various column additions for GET requests