Order API

Created by Darren Stretch
Last updated: Feb 10, 2020

The Fruugo Product Order API is an interface for retailers to process Fruugo orders within their own system.

Introduction

The main functionalities in the API are:

- Download orders from Fruugo (HTTP/XML)
- Confirm, ship, cancel and return items (HTTP)
- Download packing slips for printing (HTTP/PDF)

The normal process flow for receiving an order and shipping is quite simple:

  1. The retailer's system downloads order information using the API.
  2. The retailer's system calls the API to confirm the order.
  3. When the products are ready for shipping the retailer's system calls the API to change status to shipped
  4. The retailer's system downloads packing slip using the API
  5. The retailer prints out the packing slip and includes it to the shipment

Each section of the Order API is permitted to be used independently of all other sections. It provides the option of using the XML interface to only download orders, and then use the Fruugo Retailer Portal to carry out order status updates and the printing of packing slips. Authentication is handled with HTTP Basic - method.

Order Data Feed Semantics

The retailer’s system sends a HTTP request to Fruugo to request order information. The request parameters specify the time of the earliest and latest orders to retrieve as well as the authentication credentials of the retailer. The response from Fruugo contains the requested orders in XML format.

The API is stateless, i.e. it doesn’t track which orders the retailer system has already downloaded.

Depending on the payment method, order value and other additional factors, Fruugo checks the payment status with the payment service provider (PSP) and evaluates the fraud risk of each order. These checks are done before Fruugo releases the order to the retailer through the API (or in the Retailer Portal).

Some payment methods (PSPs) have occasional delays in their processing and that, combined with the stateless nature of the service, has an effect on how Fruugo can process and forward the orders. Therefore the start date and end date of the Order Data Feed used to select orders is based upon the time the order successfully passes the Fraud Checks, not the time that the customer places the order.

Benefits of the chosen approach are:

- The API gives only “checked and paid” complete orders. Once an order has been release no extra lines will appear in a later download.
- The API provides full view to the current order data including the status of each order and each of it’s lines. For example Monday morning orders can be retrieved on Monday as well as on Thursday. The XML that is generated on Monday contains new unprocessed lines (status pending). If the same orders are retrieved on Thursday the same line items probably have status “confirmed” or “shipped”.
- If the retailer system succeeds in downloading the XML but then fails to process it, the API can be called again as many times as needed.

The downside is:

- The API doesn't provide a service to "get only the new orders that have not been transferred before".

For example:
- Customer places order 108 at 1:30pm.
- API is called at 3 pm to get orders between 1 pm and 2 pm -> the result is orders 100, 105 and 110.
- At 3:30 pm Fruugo releases order 108 to the retailer.
- API is called at 4 pm with the same time parameters -> the  result is orders 100, 105 and 110.
- API is called at 5 pm to get orders between 3 pm and 5pm -> the result is orders 108.

Simple logic for a basic integration

Here is an example logic for a simple integration. First some assumed business rules:

  1. A retailer wants to get the orders every four hours.
  2. The retailer's system processes the orders and “owns” the order after it is retrieved from Fruugo. The Retailer does not update the orders using the Fruugo Retailer Portal.

Every four hours the retailer system runs a batch job that downloads the orders for the previous 4 hour period.

The retailer's system processes the orders in the XML data and:

- Skips all orders that have a status other than ‘PENDING’ (the other ones have already been processed fully or partially and thus they must already exist in the retailer system)

- Checks if an order with ‘PENDING' status in the XML already exists in the retailer system. If it doesn’t then it is stored in the retailer system. Otherwise it can be skipped.

Common data formats used in the API

  1. Dates are in ISO 8601 format, with or without time of day. Example: 2011-01-01 or 2011-01-01T01:00:00
  2. Currencies are in ISO 4217 format (EUR, GBP, USD)
  3. Languages are in ISO 639-2 codes (en, fi, se)
  4. Countries are in ISO 3166 two letter format (GB, FI, SE)
  5. Item-based operations take arbitrary number of items-parameters in comma separated