Fruugo Get Orders

Summary of Changes: (The purpose of this table is to keep traceability and Product team to highlight the things that were changed into the scope, based on comments or discussions)

The Fruugo Retailer REST API allows Retailers to perform the following:

• To query for orders
• To update the status of an order

Again we will have to use Web-hooks. When submitting the request, we can provide a X-Correlation-ID which is an identifier used for tracking the request. The X-Correlation-ID is used to tie the response back to the original request. If we provide a correlation id when making a request, Fruugo will use that and include it in the webhook response. If we don’t provide one, Fruugo will auto-generate one for us, which should be included in the initial response to our request, then it will also be included in the web-hook response. We want to use the X-Correlation-ID as it will be easier to identify requests.

The webhook endpoint is : TBA

Useful information : https://fruugo.atlassian.net/wiki/spaces/RR/pages/66158670/Order+API

API Docs : https://developer.fruugo.com/#tag/orders-v3 API Call : POST https://order-api.fruugo.com/v3/orders

Example request :

{
  "dateFrom": "2019-08-24T14:15:22Z",
  "dateTo": "2019-08-24T14:15:22Z",
  "orderId": "string",
  "productId": "string",
  "skuId": "string",
  "statuses": [
    "PENDING"
  ],
  "customerCountries": [
    "AE"
  ],
  "paymentAmountMin": 0,
  "paymentAmountMax": 0
}

As you can see, we have filters dateFrom and dateTo so we can easily filter only orders that are new. Please note the only required node is the dateFrom so we want to send all other nodes as blank. In order to filter new orders we will use the last_date_run table where we will store a record each time the get orders cron has run successfully. Then we want to be looking for orders that are within 60 minutes of the last time we have ran the cron. So it will be dateFrom = last_date_run - 60 minutes. When the get orders is run for the first time, we want to be looking for orders since 6 months back.

Example responses :

202 Request has been accepted for processing, and update will be performed asynchronously.

This is the successful request. We should then expect a response from Fruugo via the web-hook endpoint that we have provided.

400 Bad Request

We should prepare to have this response as a notification in the new UI via the systems handling.

429 Request has been rejected due to exceeding rate limit. Retry after delay specified in "Retry-After" response header.

Incase we receive this we should just retry the request after the specified “Retry-After” in the header.

Callback payload samples

This will be when Fruugo will provide us with the actual order(s) information and details. This will be via a POST call done by them to our web-hook endpoint URI.

Example response :

{
  "value": {
    "type": "OrdersResponseList",
    "merchantId": 444,
    "correlationId": "c3145570-0731-45db-9c9a-33f97d588400",
    "payload": "{ 'orders': [{ 'orderId': '9164666001000444' 'customerOrderId': '9164666' 'orderDate': '2021-12-02 T14: 45:47 +02:00[Europe / Helsinki]' 'orderReleaseDate': '2021-12-02 T14: 45:58.307 +02:00[Europe / Helsinki]' 'orderStatus': 'PROCESSED' 'customerLanguageCode': 'EN' 'customerCurrency': 'GBP' 'customerTotalProductPriceIncVat': 208.0 'shippingAddress': { 'firstName': 'Dave' 'lastName': 'Willis' 'streetAddress': 'West HillCHANGE' 'city': 'Ottery St Mary' 'province': null 'postalCode': 'EX11 1 UTCH' 'countryCode': 'GB' 'phoneNumber': 07738150000 'emailAddress': null } 'shippingMethod': 'Standard Shipping' 'shippingCostInclVAT': 1.99 'shippingCostVAT': 1.66 'fruugoTax': false 'fruugoTaxId': 'GB929353206' 'fruugoEORI': 'GB929353206000' 'orderLines': [{ 'productId': 'DISC001 - ProdId' 'skuId': 'DISC - IS - 50 - WITHV20 - DISC - 10 % -Sku' 'skuName': 'DISC - IS - 50 - WITHV20 - DISC - 10 % -Title' 'attributes': {} 'currencyCode': 'GBP' 'itemPriceInclVAT': 120.0 'itemVAT': 20.0 'totalPriceInclVAT': 120.0 'totalVAT': 20.0 'customerPricing': { 'customerItemPriceExcVat': 100.0 'customerItemVat': 20.0 'totalCustomerPriceExcVat': 100.0 'totalCustomerVat': 20.0 'customerCurrency': GBP } 'vatPercentage': 20.0 'totalNumberOfItems': 1 'pendingItems': 0 'confirmedItems': 0 'shippedItems': 1 'cancelledItems': 0 'returnAnnouncedItems': 0 'returnedItems': 0 'itemsWithException': 0 'releaseDate: '2021 - 12 - 02 T14: 45: 58.307 + 02: 00[Europe / Helsinki]' 'personalised': false }] 'shipments': [{ 'shipmentId': '1' 'shippingDate': 2021 - 12 - 21 T16: 34: 42 + 02: 00[Europe / Helsinki] 'shipmentLines': [{ 'productId': 'DISC001 - ProdId' 'skuId': 'DISC - IS - 50 - WITHV20 - DISC - 10 % -Sku' 'skuName': 'DISC - IS - 50 - WITHV20 - DISC - 10 % -Title' 'quantity': 1 }] }] }] }"
  }
}

Response mapping :

PENDING: New order that hasn't been processed PROCESSED: At least part of the order has been processed EXCEPTION: There's an error or manual correction related to the order and it cannot be processed through the Order API. | | | | customerLanguageCode | Language of the Customer. | Orders Fruugo > Customer Language Default | | | | | customerCurrency | The currency of the order for the customer | Orders > Order Currency | | | | | customerTotalProductPriceIncVat | Total price including VAT in the customer currency | Orders > Order Total Amount AND Orders > Order Subtotal Amount | For the Order Subtotal Amount we need to deduct any shipping cost and then store it. | | | shippingAddress | | | | | | | | firstName | | Orders > Shipping Buyer Name AND Orders > Billing Name | We need to combine both firstName and lastName and fill all the information in the Shipping Buyer Name and Billing Name | | | | lastName | | Orders > Shipping Buyer Name AND Orders > Billing Name | We need to combine both firstName and lastName and fill all the information in the Shipping Buyer Name and Billing Name | | | | streetAddress | | Orders > Shipping Street 1 AND Orders > Billing Street 1 | | | | | city | | Orders > Shipping City AND Orders > Billing City Name | | | | | province | | Orders > Shipping State Province AND Orders > Billing State Province | | | | | postalCode | | Orders > Shipping Postal Code AND Orders > Billing Billing Postal Code | | | | | countryCode | | Orders > Shipping Country Code AND Orders > Billing Country Code | | | | | phoneNumber | | Orders > Shipping Phone AND Orders > Billing Phone | | | | | emailAddress | | Orders > Buyer mail | | | | | shippingMethod | | Orders > Shipping Service | | | | | shippingCostInclVAT | | Orders > Shipping Service Cost | | | | | shippingCostVAT | | Orders > Total Shipping VAT | | | | fruugoTax | | Identifies whether Fruugo is responsible for collecting and has collected tax on the order | N/A | | | | fruugoTaxId | | The relevant Fruugo tax ID for the order and customs declaration. If Fruugo has collected the tax on the order. | Orders Fruugo > Fruugo Tax ID | | | | fruugoEORI | | The Fruugo EORI (Economic Operators Registration and Identification number) for customs declaration. If Fruugo has collected the tax on the order. | Orders Fruugo > Fruugo EORI | | | | orderLines | | | | | | | | productId | Product id from retailers product information feed. | Product on Order > Item Order Line ID | | | | | skuId | SKU id from retailers product information feed (if retailer didn't provide SKU id , this is the same as product id). | Product in Order > SKU | | | | | skuName | SKU name from retailers product information feed. | Product in Order > Item Title | | | | | attributes | SKU attributes from retailers product information feed. | Product In Order > Item Variations | We need to store the Name and the Value as Item Specific Name and Item Specific Value Example : attributeName = Colour attributeValue = Green | | | | currencyCode | Fruugo's internal Product id. | N/A | | | | | itemPriceInclVAT | Price of a single item in retailer's currency. | N/A | | | | | itemVAT | Amount of VAT for a single item in retailer's currency. | N/A | | | | | totalPriceInclVAT | Total price charged from the customer in retailer's currency. | Product In Order > Item Price | | | | | totalVAT | Total VAT amount charged from the customer in retailer's currency. | Product In Order > Vat Item Price | | | | customerPricing | | | | | | | | customerItemPriceExcVat | Price excluding VAT for a single item in the customer currency | Fruugo Order Items > Item Price Excluding VAT | | | | | customerItemVat | VAT amount for a single item in the customer currency | Fruugo Order Items > Item VAT | | | | | totalCustomerPriceExcVat | Total price excluding VAT in the customer currency | N/A | | | | | totalCustomerVat | Total VAT amount charged in the customer currency | N/A | | | | | customerCurrency | The currency of the order for the customer | Fruugo Order Items > VAT Currency | | | | | totalNumberOfItems | Total number of items ordered of this Sku. | Product In Order > Quantity | | | | | pendingItems | | N/A | | | | | confirmedItems | | N/A | | | | | shippedItems | | N/A | | | | | cancelledItems | | N/A | | | | | returnAnnouncedItems | | N/A | | | | | returnedItems | | N/A | | | | | itemsWithException | | N/A | | | | | releaseDate | | N/A | | | | | personalised | | N/A | | | | shipments | | | | | | | | shipmentId | | Order Shipment > External Id | | | | shipmentLines | | | | | | | | productId | | N/A | We need to map with Product In Order > Item Order Line ID to get the needed information about the product, and then create Order Shipment Row for the shipped product(s) | | | | skuName | | N/A | | | | | quantity | | Order Shipment Row > Quantity | |

Order statuses mapping :

OR Shipped | We need to check if there is a shipping info in the order we need to mark the Hemi status as Shipped. Otherwise it should be on a Ready for Shipping status. | | EXCEPTION | N/A | If we receive such status we should not be storing the order. |

Everything else is as per the order management abstraction Order management general requirements