Quill Create Orders

The orders are created with a simple POST call to Quill with very little information provided by us to them.

API Call : POST https://easyapiqa.staples.com/quill-omnia/api/v1/order

Doc is in the main page but I am adding it here for ease -

Quill Reseller Order API Specification.xlsx

We need to send the Bearer token and Ocp-Apim-Subscription-Key as headers. The token we pick from cache and the Ocp-Apim-Subscription-Key we pick from Quill Connector > Subscription Key

It is a simple order export but due to client’s requirements we need to create a few additional logics.

Since this is a client who works on a dropship model, he gets send supplier prices every Wednesday by the manufacturers and he wants to keep the most up to date price AND the previous price in Hemi for a certain product. For this we have decided to use the Product Account > Original Price and Product Account > Original RRP (we might need to rename the labels of these field for ease of use). So in other words we will keep always the latest price in Original Price and the previous week’s price in Original RRP. We then need to do a comparison between those two prices and act as follows :

• IF we have Original Price which is lower than the Original RRP price we want to stop the export of the order until the next first Sunday at 11:59AM Eastern Time (ET). Example : We receive an order on Thursday which has Original Price < Original RRP , we need to hold it and only action the export on Sunday after 11:59AM Eastern Time (ET). (from dev point of view we can use America/New_York as timezone)
• IF we have Original Price which is higher than the Original RRP we export the order as normal.
• IF we have Original Price equal to Original RRP we export the order as normal.
• IF we have Original Price and missing Original RRP We don’t export the order immediately.We block it until the next first Sunday 11:59AM Eastern Time (ET) and we export it after that time even if we still dont have Original RRP
• If we have missing Original Price we don’t export the order regardless if we have Original RRP or not.

A second logic we need to create is if an order has passed X amount of days since it was created in our system and if we still haven’t sent it, this means that there is something wrong with it and we don’t want to send it at all. We want to control this with the flag in Account Quill Connector > Dont send order older than X days

And the third logic is that the client wants to have a block for orders export on product account level which he wants to control. There will be two types of blocks : date inflicted and flag inflicted.

The date inflicted will be basically the customer will input a date into Product Account Quill > Date (in a format (MM/DD/YYYY)) and this date will act as a blocker showing up until when an order containing the product should not be exported to Quill. Example : We have an order with SKU 123 which has Product Account > Date of 30th September 2024 in a format (MM/DD/YYYY) and this will mean we should not export the order until the 30th. If the date is not imported in this format and if we are in the case of a date inflicted blocker, we want to store an error in Orders > Order Error stating that the SKU is with a wrong date format.

The flag inflicted block will be a Yes/No field in Product Account Quill called Block Item that is just pure block and that’s it. If Yes then we block orders containing this product disregarding any other logic, if No then we follow the previous logics.

There is no hierarchy on the blockers, but if one of them is active we want to block the order export.

We want to create order in Quill when we have the following statuses/flags :

Orders > Splitted Shipping Cost = Yes Product in Order > Check For Bundle = Yes

Order > Order Status = Ready For Shipping Order > Connector Order ID = ‘’ Product in Order > Connector Order ID = ‘’ Product in Order > Connector Exported = No Order > Connector Error = ‘’

Product in Order > Seller != ''

Product Account Quill > Block Item = No

The request will be in a JSON format so we need to use the content-type = application/json header.

TBA - To check with Quill if we have to sent single order per request or we can send many orders in a single request

Sample request (please note that all fields are mandatory except just 3 which if we are missing information for, can be sent as null) :

{
  "correlation_id": "Amazon Order ID",
  "agency_order_number": "Amazon Order ID",
  "supplier_agency_id": "(Quill to provide)", 
  "created_date": "2024-07-25T17:38:06.6282911Z",
  "modified_date": "2024-07-25T17:38:07.2638099Z",
  "line_items": [
    {
      "sku": "901-163147",
      "quantity": 2,
      "name": "Quill Brand 8.5 x 11 Multipurpose Copy Paper 20 lbs. 94 Brightness 500 Sheets/Ream 10 Reams/Carton",
      "price": 45.5
    }
  ],
  "shipping_method_id": "Standard Shipping",
  "shipping_address": {
    "line1": "300 Tri State",
    "line2": "Suite 300",  // or null
    "city": "Lincolnshire",
    "country": "USA", 
    "country_code": "US",
    "province_code": "IL",
    "postal_code": "60069",
    "first_name": "customer firstName",
    "last_name": "customer lastName",
    "company": "Acme Co",  // or null
    "comment": "(Gets put on shipping label)"  // or null
  }
}

Response Mapping :

Needs to be in ISO 8601 format 2024-07-25T17:38:06.6282911Z | | line_items | | Array | | | | | sku | String | Product In Order > SKU | | | | quantity | Integer | Product In Order > Quantity | | | | name | String | Product In Order > Item Title | | | | price | Decimal | Product In Order > Original Price | | | shipping_method_id | | String | | Hardcoded as “Standard Shipping” | | shipping_address | | Object | | | | | line1 | String | Orders > Shipping Street 1 | | | | line2 | String or null | Orders > Shipping Street 2 | If empty we send it as null | | | city | String | Orders > Shipping City | | | | country | String | | Hardcoded as “USA” for the moment | | | country_code | String | | Hardcoded as “US” for the moment | | | province_code | String | Orders > Shipping State Province | | | | postal_code | String | Orders > Shipping Postal Code | | | | first_name | String | Orders > Shipping Buyer Name | We need only the first name and we get everything before the first space character Trim leading white spaces if any | | | last_name | String | Orders > Shipping Buyer Name | We get everything after the first space character Trim leading white spaces if any | | | company | String or null | Orders > Company Name | If empty we need to send it as null | | | comment | String or null | Orders > Note | If empty we need to send it as null |

Sample success response :

{
  "correlation_id": "Order ID",
  "status": "Confirmed Reseller Order",
  "line_items": [
    {
      "sku": "901-163147",
      "quantity": 2,
      "name": "Quill Brand 8.5 x 11 Multipurpose Copy Paper 20 lbs. 94 Brightness 500 Sheets/Ream 10 Reams/Carton",
      "price": 45.5
    }
  ]
}

If we receive a success response we need to mark the order as exported by storing the correlation_id and in Orders > Connector Order ID AND Product In Order > Connector ID and update Product In Order > Connector Exported = Yes.

Sample error response :

{
    "error": "Order with the same correlation identifier already exists"
}           

This error means that the order was already created in Quill. We don’t want to take any action on it. We just want to store the error into Order Error with type Connector and Orders > Connector Error

We have other possible errors which is a status 500 . This error we want to display in the terminal when the cron is run with DEVMODETRUE and store Order Error with type Connector and Orders > Connector Error