Custom reports

This page explains the two types of custom reports we have:

• Tabs to be used for rebates and billing
• Order exporter to be used for accounting system and data warehouse sync

Tabs

A tab is a collection of Events (see here for an explanation of Events).

A tab can be created like this:

curl {baseURL}/tabs  
-H "Authorization:your-api-key"  
-H "Content-type: application/json"  
-X POST  
-d '{  
  "name": "Jones & Sons rebate",
  "tabFilter": "#order.sellerId == 'supplier-trader-id' and #order.status == 'COMPLETED'",
  "tabFormula": "#order.orderAmountInCents * 0.02",  
  "type": "REBATE",
  "currency": "GBP" 
}'

This particular tab calculates a 1% rebate on all payments to a particular supplier.

You can give the tab any name and type you want.

The tabFilter specifies which Events are included in the tab. In this case the filter specifies the supplier and order status. You can include any field of the order or event using #order or #event followed by the field name.

The tabFormula specifies what value to calculate. Just as for the tabFilter, you can use any field of the order or event. You can also use the + - * and / mathematical operators and brackets.

The response will look like this:

{
  "name": "Jones & Sons rebate",
  "tabFilter": "#order.sellerId == 'supplier-trader-id' and #order.status == 'COMPLETED'",
  "tabFormula": "#order.orderAmountInCents * 0.02",  
  "type": "REBATE",
  "status": "OPEN",
  "traderId": "your-trader-id",
  "results": [
    {
      "currency": "GBP",
      "currencyComponent": 2,
      "amountInCents": 8964338,
      "formulaAmountInCents": 25000,
      "events": [
        {
          "orderId": "order-id",
          "eventId": "event-id"
        }
     ]
   }
}

Let's break that down. The first few fields are what you provided plus a status and traderId:

"name": "Jones & Sons rebate",
  "tabFilter": "#order.sellerId == 'supplier-trader-id' and #order.status == 'COMPLETED'",
  "tabFormula": "#order.orderAmountInCents * 0.02",  
  "type": "REBATE",
  "status": "OPEN",
  "traderId": "your-trader-id",

The status can either be FILLING (we are still filling the tab), OPEN or CLOSED.

The results include all events and our calculations:

"results": [
    {
      "currency": "GBP",
      "currencyComponent": 2,
      "amountInCents": 8964338,
      "formulaAmountInCents": 25000,
      "events": [
        {
          "orderId": "order-id",
          "eventId": "event-id"
        }
     ]
   }

When a tab is OPEN we will constantly add new events to the tab and recalculate the values and list of events in the results.

The amountInCents is the sum of the payments for all events. The formulaAmountInCents is the result of the formula you provided which in this example was 1% of the total value of all payments to this supplier.

To get a list of tabs, you can call the following API:

curl {baseURL}/tabs?type=REBATE
-H "Authorization:your-api-key"
-X GET

You can also call this API without the type filter in which case you get a list of all tabs

To get an individual tab, you can call this API:

curl {baseURL}/tabs/tab-id
-H "Authorization:your-api-key"
-X GET

Order exporter

The order exporter exports all orders in CSV file with the columns and values your accounting system or data warehouse needs.

You can call this API to get this file:

curl {baseURL}/orders/export?format=STANDARD_FORMAT&startDate=2021-02-01&endDate=2021-02-28&buyerTagValues=PO&buyerAccountingSynced=false
-H "Authorization:your-api-key"  
-X GET

The file will be emailed to the user whose key is used to call this API.

The following filters can be provided

• format : is the format of the export file as defined by you. You can have multiple formats. We can set up the formats for you or you can create new formats by API. To learn how, please get in touch with your support manager. STANDARD_FORMAT is available for all customers
• startDate and endDate : the date range of the orders you want to receive
• buyerTagValues : values of the tags defined for the order. They are a logical OR so if any of the tag values match, the order will be returned
• buyerAccountingSynced indicates if the order has already been synced with the accounting system or not