Back to top

Sales

Sales

List all sales

List all sales
GET/sales{?start_time,end_time,order,limit,job_reference}

Get a list of individual sales for a specified time period.

Because some reports take many seconds to run, requesting a list of sales may start a background job to generate the report. In this case the response will be 202 Accepted. Use the returned Location header to get the URL of the results of the job. While the job is running the API will return 204 No Content, and once the job completes you will receive a 200 OK with the body containing the requested sales.

See the asynchronous workflow for more background on implementation details.

Example URI

GET /sales?start_time=2014-08-04T00:00:00+00:00&end_time=2014-08-05T00:00:00+00:00&order=asc&limit=10&job_reference=jobS7UNg6k28OP8tg8a0VDnMS8fw
URI Parameters
HideShow
start_time
date-time (optional) Example: 2014-08-04T00:00:00+00:00

The starting date and time for the date range, inclusive.

If omitted then start_time defaults to the time of the first sale.

end_time
date-time (optional) Example: 2014-08-05T00:00:00+00:00

The ending date and time for the date range, exclusive.

If omitted then end_time defaults to the current date and time.

order
string (optional) Default: asc Example: asc

The time order that results are returned in, either asc or desc.

Choices: asc desc

limit
integer (optional) Example: 10

Limit the number of results to return.

Maximum of 1000. If omitted all results in the period are returned. If the total number of results exceeds 1000, an HTTP 400 error is returned.

job_reference
string (optional) Example: jobS7UNg6k28OP8tg8a0VDnMS8fw

The job reference which was returned if the API needed to start a background process to retrieve the sales.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "sales": [
    {
      "sale_id": "00003d938d46bc2ab3e6ca8f31f59c0980baa72b",
      "device_id": "123456",
      "valid_time": "2014-07-05T18:34:08.015987+00:00",
      "transaction_time": "2014-07-05T18:34:28.779150+00:00",
      "product_id": "MTN50",
      "voucher": {
        "voucher_id": "a5bb12d4f505f40503b071c79a35fe3b4abcb098",
        "serial": "1234567890"
      },
      "cost_price_in_cents": 4500,
      "sales_in_cents": 5000,
      "is_reversed": false,
      "location": {
        "latitude": -33.916451,
        "longitude": 18.423379
      }
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "sales": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "sale_id": {
            "type": "string"
          },
          "device_id": {
            "type": "string",
            "pattern": "^[0-9]{6}$"
          },
          "valid_time": {
            "type": "string",
            "format": "date-time"
          },
          "transaction_time": {
            "type": "string",
            "format": "date-time"
          },
          "product_id": {
            "type": "string"
          },
          "voucher": {
            "type": "object",
            "properties": {
              "voucher_id": {
                "type": "string"
              },
              "serial": {
                "type": "string"
              }
            }
          },
          "cost_price_in_cents": {
            "type": "integer"
          },
          "sales_in_cents": {
            "type": "integer"
          },
          "is_reversed": {
            "type": "boolean"
          },
          "location": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "latitude": {
                "type": "number",
                "minimum": -90,
                "maximum": 90
              },
              "longitude": {
                "type": "number",
                "minimum": -180,
                "maximum": 180
              }
            },
            "required": [
              "latitude",
              "longitude"
            ]
          }
        },
        "required": [
          "sale_id",
          "device_id",
          "valid_time",
          "transaction_time",
          "product_id",
          "voucher",
          "cost_price_in_cents",
          "sales_in_cents",
          "location"
        ]
      }
    }
  },
  "required": [
    "sales"
  ]
}
Response  202
HideShow
Headers
Location: https://api.nomanini.com/sales?job_reference=jobS7UNg6k28OP8tg8a0VDnMS8fw
Response  204

Get a sale by sale ID

Get a sale by sale ID
GET/sales/{sale_id}

Get the details of a specific sale.

Example URI

GET /sales/00003d938d46bc2ab3e6ca8f31f59c0980baa72b
URI Parameters
HideShow
sale_id
string (required) Example: 00003d938d46bc2ab3e6ca8f31f59c0980baa72b

The unique identifier of the sale you want to retrieve.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "sales": [
    {
      "sale_id": "00003d938d46bc2ab3e6ca8f31f59c0980baa72b",
      "device_id": "123456",
      "valid_time": "2014-07-05T18:34:08.015987+00:00",
      "transaction_time": "2014-07-05T18:34:28.779150+00:00",
      "product_id": "MTN50",
      "voucher": {
        "voucher_id": "a5bb12d4f505f40503b071c79a35fe3b4abcb098",
        "serial": "1234567890"
      },
      "cost_price_in_cents": 4500,
      "sales_in_cents": 5000,
      "is_reversed": false,
      "location": {
        "latitude": -33.916451,
        "longitude": 18.423379
      }
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "sales": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "sale_id": {
            "type": "string"
          },
          "device_id": {
            "type": "string",
            "pattern": "^[0-9]{6}$"
          },
          "valid_time": {
            "type": "string",
            "format": "date-time"
          },
          "transaction_time": {
            "type": "string",
            "format": "date-time"
          },
          "product_id": {
            "type": "string"
          },
          "voucher": {
            "type": "object",
            "properties": {
              "voucher_id": {
                "type": "string"
              },
              "serial": {
                "type": "string"
              }
            }
          },
          "cost_price_in_cents": {
            "type": "integer"
          },
          "sales_in_cents": {
            "type": "integer"
          },
          "is_reversed": {
            "type": "boolean"
          },
          "location": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "latitude": {
                "type": "number",
                "minimum": -90,
                "maximum": 90
              },
              "longitude": {
                "type": "number",
                "minimum": -180,
                "maximum": 180
              }
            },
            "required": [
              "latitude",
              "longitude"
            ]
          }
        },
        "required": [
          "sale_id",
          "device_id",
          "valid_time",
          "transaction_time",
          "product_id",
          "voucher",
          "cost_price_in_cents",
          "sales_in_cents",
          "location"
        ]
      }
    }
  },
  "required": [
    "sales"
  ]
}

Reverse a sale by sale ID
PATCH/sales/{sale_id}

The patch method can be used to reverse a sale that was made in error Setting the is_reversed parameter to true will

  • Make the previously sold voucher available for re-sale

  • Refund the value of the sale to the device that initiated the sale

  • Add an adjustment to the sales reports A sale reversal cannot be undone.

Permissions: reverse_transactions

Example URI

PATCH /sales/00003d938d46bc2ab3e6ca8f31f59c0980baa72b
URI Parameters
HideShow
sale_id
string (required) Example: 00003d938d46bc2ab3e6ca8f31f59c0980baa72b

The unique identifier of the sale you want to retrieve.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "is_reversed": true
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "is_reversed": {
      "type": "boolean",
      "enum": [
        true
      ],
      "description": "Reverse the effects of this sale"
    }
  },
  "required": [
    "is_reversed"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "sales": [
    {
      "sale_id": "00003d938d46bc2ab3e6ca8f31f59c0980baa72b",
      "device_id": "123456",
      "valid_time": "2014-07-05T18:34:08.015987+00:00",
      "transaction_time": "2014-07-05T18:34:28.779150+00:00",
      "product_id": "MTN50",
      "voucher": {
        "voucher_id": "a5bb12d4f505f40503b071c79a35fe3b4abcb098",
        "serial": "1234567890"
      },
      "cost_price_in_cents": 4500,
      "sales_in_cents": 5000,
      "is_reversed": false,
      "location": {
        "latitude": -33.916451,
        "longitude": 18.423379
      }
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "sales": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "sale_id": {
            "type": "string"
          },
          "device_id": {
            "type": "string",
            "pattern": "^[0-9]{6}$"
          },
          "valid_time": {
            "type": "string",
            "format": "date-time"
          },
          "transaction_time": {
            "type": "string",
            "format": "date-time"
          },
          "product_id": {
            "type": "string"
          },
          "voucher": {
            "type": "object",
            "properties": {
              "voucher_id": {
                "type": "string"
              },
              "serial": {
                "type": "string"
              }
            }
          },
          "cost_price_in_cents": {
            "type": "integer"
          },
          "sales_in_cents": {
            "type": "integer"
          },
          "is_reversed": {
            "type": "boolean"
          },
          "location": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "latitude": {
                "type": "number",
                "minimum": -90,
                "maximum": 90
              },
              "longitude": {
                "type": "number",
                "minimum": -180,
                "maximum": 180
              }
            },
            "required": [
              "latitude",
              "longitude"
            ]
          }
        },
        "required": [
          "sale_id",
          "device_id",
          "valid_time",
          "transaction_time",
          "product_id",
          "voucher",
          "cost_price_in_cents",
          "sales_in_cents",
          "location"
        ]
      }
    }
  },
  "required": [
    "sales"
  ]
}

Get a sale by voucher ID

Get a sale by voucher ID
GET/sales/voucher/{voucher_id}

Get the details of a specific sale referenced by its voucher ID.

Example URI

GET /sales/voucher/d92e52cf4cb5728ca686165dfe460074
URI Parameters
HideShow
voucher_id
string (required) Example: d92e52cf4cb5728ca686165dfe460074

The unique identifier of the voucher. Unique across all vouchers within the Nomanini platform.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "sales": [
    {
      "sale_id": "00003d938d46bc2ab3e6ca8f31f59c0980baa72b",
      "device_id": "123456",
      "valid_time": "2014-07-05T18:34:08.015987+00:00",
      "transaction_time": "2014-07-05T18:34:28.779150+00:00",
      "product_id": "MTN50",
      "voucher": {
        "voucher_id": "a5bb12d4f505f40503b071c79a35fe3b4abcb098",
        "serial": "1234567890"
      },
      "cost_price_in_cents": 4500,
      "sales_in_cents": 5000,
      "is_reversed": false,
      "location": {
        "latitude": -33.916451,
        "longitude": 18.423379
      }
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "sales": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "sale_id": {
            "type": "string"
          },
          "device_id": {
            "type": "string",
            "pattern": "^[0-9]{6}$"
          },
          "valid_time": {
            "type": "string",
            "format": "date-time"
          },
          "transaction_time": {
            "type": "string",
            "format": "date-time"
          },
          "product_id": {
            "type": "string"
          },
          "voucher": {
            "type": "object",
            "properties": {
              "voucher_id": {
                "type": "string"
              },
              "serial": {
                "type": "string"
              }
            }
          },
          "cost_price_in_cents": {
            "type": "integer"
          },
          "sales_in_cents": {
            "type": "integer"
          },
          "is_reversed": {
            "type": "boolean"
          },
          "location": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "latitude": {
                "type": "number",
                "minimum": -90,
                "maximum": 90
              },
              "longitude": {
                "type": "number",
                "minimum": -180,
                "maximum": 180
              }
            },
            "required": [
              "latitude",
              "longitude"
            ]
          }
        },
        "required": [
          "sale_id",
          "device_id",
          "valid_time",
          "transaction_time",
          "product_id",
          "voucher",
          "cost_price_in_cents",
          "sales_in_cents",
          "location"
        ]
      }
    }
  },
  "required": [
    "sales"
  ]
}

List sales by a device

List sales by a device
GET/sales/device/{device_id}{?start_time,end_time,order,limit}

Get a list of all sales made by a particular device.

Use the returned Location header to get the URL of the results of the job.

Example URI

GET /sales/device/123456?start_time=2014-08-04T00:00:00+00:00&end_time=2014-08-05T00:00:00+00:00&order=asc&limit=10
URI Parameters
HideShow
device_id
string (required) Example: 123456

The device for which you want to get all the sales for.

start_time
date-time (optional) Example: 2014-08-04T00:00:00+00:00

The starting date and time for the date range, inclusive. If omitted then start_time defaults to the time of the first sale for this device.

end_time
date-time (optional) Example: 2014-08-05T00:00:00+00:00

The ending date and time for the date range, exclusive. If omitted then end_time defaults to the current date and time.

order
string (optional) Example: asc

The time order that results are returned in, either asc or desc. If omitted defaults to asc.

Choices: asc desc

limit
integer (optional) Example: 10

Maximum of 1000. Limit the number of results to return. If omitted all results in the period are returned.

Response  202
HideShow
Headers
Location: https://api.nomanini.com/sales?job_reference=jobS7UNg6k28OP8tg8a0VDnMS8fw

List sales for a product

List sales for a product
GET/sales/product/{product_id}{?start_time,end_time,order,limit}

Get a list of all sales made for a particular product.

Use the returned Location header to get the URL of the results of the job.

Example URI

GET /sales/product/MTN10?start_time=2014-08-04T00:00:00+00:00&end_time=2014-08-05T00:00:00+00:00&order=asc&limit=10
URI Parameters
HideShow
product_id
string (required) Example: MTN10

The product for which you want to retrieve all sales for.

start_time
date-time (optional) Example: 2014-08-04T00:00:00+00:00

The starting date and time for the date range, inclusive. If omitted then start_time defaults to the time of the first sale for this product.

end_time
date-time (optional) Example: 2014-08-05T00:00:00+00:00

The ending date and time for the date range, exclusive. If omitted then end_time defaults to the current date and time.

order
string (optional) Example: asc

The time order that results are returned in, either asc or desc. If omitted defaults to asc.

Choices: asc desc

limit
integer (optional) Example: 10

Maximum of 1000. Limit the number of results to return. If omitted all results in the period are returned. If the total number of results exceeds 1000, an HTTP 400 error is returned.

Response  202
HideShow
Headers
Location: https://api.nomanini.com/sales?job_reference=jobS7UNg6k28OP8tg8a0VDnMS8fw

List sales by a merchant

List sales by a merchant
GET/sales/merchant/{person_id}{?start_time,end_time,order,limit}

Get a list of all sales made by a particular merchant.

Use the returned Location header to get the URL of the results of the job.

Example URI

GET /sales/merchant/5668655375319040?start_time=2014-08-04T00:00:00+00:00&end_time=2014-08-05T00:00:00+00:00&order=asc&limit=10
URI Parameters
HideShow
person_id
string (required) Example: 5668655375319040

The merchant for which you want to retrieve all sales.

start_time
date-time (optional) Example: 2014-08-04T00:00:00+00:00

The starting date and time for the date range, inclusive. If omitted then start_time defaults to the time of the first sale for this merchant.

end_time
date-time (optional) Example: 2014-08-05T00:00:00+00:00

The ending date and time for the date range, exclusive. If omitted then end_time defaults to the current date and time.

order
string (optional) Example: asc

The time order that results are returned in, either asc or desc. If omitted defaults to asc.

Choices: asc desc

limit
integer (optional) Example: 10

Maximum of 1000. Limit the number of results to return. If omitted all results in the period are returned. If the total number of results exceeds 1000, an HTTP 400 error is returned.

Response  202
HideShow
Headers
Location: https://api.nomanini.com/sales?job_reference=jobS7UNg6k28OP8tg8a0VDnMS8fw

Sales summary

Sales summaries give the total sales over a time period, grouped in to buckets by hours, days or months, and allows you to show trends in sales without having to download all the individual sales over that time frame.

Sales summary

Summarise all sales
GET/sales/summary{?group_by,limit,job_reference}

Get the total sales in each hour or day or month (as specified in the group_by parameter) for all devices. This looks backwards over the hours, days or months up to the limit specified.

For example, to get the total sales each day for the last week (7 days):

GET /sales/summary?group_by=day&limit=7

To get the total sales each month for the last year (12 months):

GET /sales/summary?group_by=month&limit=12

Example URI

GET /sales/summary?group_by=day&limit=7&job_reference=jobS7UNg6k28OP8tg8a0VDnMS8fw
URI Parameters
HideShow
group_by
string (optional) Example: day

Return the total sales in each hour, day or month. If omitted defaults to day.

Choices: hour day month

limit
integer (optional) Example: 7

The number of periods to return. The latest period will be now (this hour, today or this month) and look backward up to the limit specified. If omitted defaults to 7.

job_reference
string (optional) Example: jobS7UNg6k28OP8tg8a0VDnMS8fw

The job reference which was returned if the API needed to start a background process to retrieve the sales.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "summary": [
    {
      "start_time": "2015-10-01T00:00:00+00:00",
      "end_time": "2015-10-02T00:00:00+00:00",
      "total_sales_in_cents": 12345600,
      "total_transactions": 1000,
      "total_active_devices": 30
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "summary": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "start_time": {
            "type": "string",
            "format": "date-time",
            "description": "The start time (inclusive) of the period for the total sales."
          },
          "end_time": {
            "type": "string",
            "format": "date-time",
            "description": "The end time (exclusive) over which the sales are totaled."
          },
          "total_sales_in_cents": {
            "type": "integer",
            "minimum": 0,
            "description": "The sum of the face value of all the sales between the start and end time."
          },
          "total_transactions": {
            "type": "integer",
            "minimum": 0,
            "description": "The count of all transactions that took place between the start and end times."
          },
          "total_active_devices": {
            "type": "integer",
            "minimum": 0,
            "description": "The number of devices that made at least one sale in the period."
          }
        },
        "required": [
          "start_time",
          "end_time",
          "total_sales_in_cents",
          "total_transactions",
          "total_active_devices"
        ]
      }
    }
  },
  "required": [
    "summary"
  ]
}
Response  202
HideShow
Headers
Location: https://api.nomanini.com/sales/summary?job_reference=jobS7UNg6k28OP8tg8a0VDnMS8fw
Response  204

Top selling devices

Top selling devices
GET/sales/summary/devices{?start_time,end_time,order,limit}

Get the top or bottom selling devices over a specified period.

For example, to get the top 10 selling devices (devices that made the most sales) for Oct, 2015:

GET /sales/summary/devices?start_time=2015-10-01T00:00:00+00:00&end_time=2015-10-31T00:00:00+00:00&limit=10&order=desc

Example URI

GET /sales/summary/devices?start_time=2015-10-01T00:00:00+00:00&end_time=2015-10-31T00:00:00+00:00&order=asc&limit=10
URI Parameters
HideShow
start_time
date-time (optional) Example: 2015-10-01T00:00:00+00:00

The starting date and time for the date range, inclusive. If omitted then start_time defaults to the time of the first sale.

end_time
date-time (optional) Example: 2015-10-31T00:00:00+00:00

The ending date and time for the date range, exclusive. If omitted then end_time defaults to the current date and time.

order
string (optional) Example: asc

The order that results are returned in, either asc or desc. If desc then the device with the highest sales is at the top. If omitted defaults to asc (devices with lowest to highest sales.)

Choices: asc desc

limit
integer (optional) Example: 10

The number of devices to return. If omitted all devices that made sales in the period are returned.

Response  200
HideShow
Body
{
  "devices": [
    {
      "device_id": "123456",
      "total_sales_in_cents": 11199900,
      "total_transactions": 1000
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "devices": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "device_id": {
            "type": "string",
            "pattern": "^[0-9]{6}$"
          },
          "total_sales_in_cents": {
            "type": "integer",
            "minimum": 0,
            "description": "The sum of the face value of all sales between the start and end time."
          },
          "total_transactions": {
            "type": "integer",
            "minimum": 0,
            "description": "The number of transactions that took place between the start and end time."
          }
        },
        "required": [
          "device_id",
          "total_sales_in_cents",
          "total_transactions"
        ]
      }
    }
  },
  "required": [
    "devices"
  ]
}

Summarise a devices sales

Summarise a devices sales
GET/sales/summary/devices/{device_id}{?group_by,limit}

Get a devices’ sales in each hour or day or month (as specified in the group_by parameter.) This looks backwards over the last hour, day or month up to the limit specified.

For example, to get the total sales for device 123456 for each hour over the last 24 hours:

GET /sales/summary/device/123465?group_by=hour&limit=24

To get the total sales for device 123456 over the last 6 months:

GET /sales/summary/device/123456?group_by=month&limit=6

Example URI

GET /sales/summary/devices/123456?group_by=day&limit=7
URI Parameters
HideShow
device_id
string (required) Example: 123456

The device for which you want to get the sales summary for.

group_by
string (optional) Example: day

Return the total sales in eachhour, day or month. If omitted defaults to day.

Choices: hour day month

limit
integer (optional) Example: 7

The number of periods to return. The latest period will be now (this hour, today or this month) and look backward up to the limit specified. If omitted defaults to 7.

Response  202
HideShow
Headers
Location: https://api.nomanini.com/sales?job_reference=jobS7UNg6k28OP8tg8a0VDnMS8fw

Top selling merchants

Top selling merchants
GET/sales/summary/merchants{?start_time,end_time,order,limit}

Get the top or bottom selling merchants over a specified period.

For example, to get the total 10 selling merchants (merchants that made the most sales) for Oct, 2015:

GET /sales/summary/merchants?start_time=2015-10-01T00:00:00+00:00&end_time=2015-10-31T00:00:00+00:00&limit=10&order=desc

Example URI

GET /sales/summary/merchants?start_time=2015-10-01T00:00:00+00:00&end_time=2015-10-31T00:00:00+00:00&order=asc&limit=10
URI Parameters
HideShow
start_time
date-time (optional) Example: 2015-10-01T00:00:00+00:00

The starting date and time for the date range, inclusive. If omitted then start_time defaults to the time of the first sale.

end_time
date-time (optional) Example: 2015-10-31T00:00:00+00:00

The ending date and time for the date range, exclusive. If omitted then end_time defaults to the current date and time.

order
string (optional) Example: asc

The order that results are returned in, either asc or desc. If desc then the merchant with the highest sales is at the top. If omitted defaults to asc (merchants with lowest to highest sales.)

Choices: asc desc

limit
integer (optional) Example: 10

The number of merchants to return. If omitted all merchants that made sales in the period are returned.

Response  200
HideShow
Body
{
  "merchants": [
    {
      "merchant_id": "4505944845189120",
      "total_sales_in_cents": 11199900,
      "total_transactions": 1000,
      "total_active_devices": 3
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "devices": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "merchant_id": {
            "type": "string",
            "description": "The unique reference identifier for this merchant."
          },
          "total_sales_in_cents": {
            "type": "integer",
            "minimum": 0,
            "description": "The sum of the face value of all sales between the start and end time."
          },
          "total_transactions": {
            "type": "integer",
            "minimum": 0,
            "description": "The number of transactions that took place between the start and end times."
          },
          "total_active_devices": {
            "type": "integer",
            "minimum": 0,
            "description": "The number of devices that the merchant is registered to that made at least one sale between the start and end times."
          }
        },
        "required": [
          "merchant_id",
          "total_sales_in_cents",
          "total_transactions",
          "total_active_devices"
        ]
      }
    }
  },
  "required": [
    "merchants"
  ]
}

Summarise a merchants sales

Summarise a merchants sales
GET/sales/summary/merchants/{person_id}{?group_by,limit}

Get a merchants’ sales in each hour or day or month (as specified in the group_by parameter.) This looks backwards over the last hour, day or month up to the limit specified, totaling all sales across all a merchants devices.

For example, to get the total sales for a merchant for each hour over the last 24 hours:

GET /sales/summary/merchant/5668655375319040?group_by=hour&limit=24

To get the total sales for a merchant over the last 6 months:

GET /sales/summary/merchant/5668655375319040?group_by=month&limit=6

Example URI

GET /sales/summary/merchants/5668655375319040?group_by=day&limit=7
URI Parameters
HideShow
person_id
string (required) Example: 5668655375319040

The merchant for which you want to retrieve all sales.

group_by
string (optional) Example: day

Return the total sales in each hour, day or month. If omitted defaults to day.

Choices: hour day month

limit
integer (optional) Example: 7

The number of periods to return. The latest period will be now (this hour, today or this month) and look backward up to the limit specified. If omitted defaults to 7.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "summary": [
    {
      "start_time": "2015-10-01T00:00:00+00:00",
      "end_time": "2015-10-02T00:00:00+00:00",
      "total_sales_in_cents": 12345600,
      "total_transactions": 1000,
      "total_active_devices": 30
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "summary": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "start_time": {
            "type": "string",
            "format": "date-time",
            "description": "The start time (inclusive) of the period for the total sales."
          },
          "end_time": {
            "type": "string",
            "format": "date-time",
            "description": "The end time (exclusive) over which the sales are totaled."
          },
          "total_sales_in_cents": {
            "type": "integer",
            "minimum": 0,
            "description": "The sum of the face value of all the sales between the start and end time."
          },
          "total_transactions": {
            "type": "integer",
            "minimum": 0,
            "description": "The count of all transactions that took place between the start and end times."
          },
          "total_active_devices": {
            "type": "integer",
            "minimum": 0,
            "description": "The number of devices that made at least one sale in the period."
          }
        },
        "required": [
          "start_time",
          "end_time",
          "total_sales_in_cents",
          "total_transactions",
          "total_active_devices"
        ]
      }
    }
  },
  "required": [
    "summary"
  ]
}

Sales by location

Sales by location
GET/sales/summary/locations{?start_time,end_time,northwest_latitude,northwest_longitude,southeast_latitude,southeast_longitude,job_reference}

This endpoint is used for creating heatmaps of sales over a geographic region (bounding box) between the start and end times. Instead of sending potentially hundreds of thousands of sale objects back to the client, as GET /sales might, this endpoint aggregates sales in to small geographic buckets. In this way only a few thousand location objects are returned.

To display the correct heatmap colour intensity, use the totals returned for each location as the weight factor in the heatmap later.

For example, to get build a heatmap over all sales for 2015:

GET /sales/summary/locations?start_time=2015-01-01T00:00:00+00:00&end_time=2016-01-01T00:00:00+00:00&northwest_latitude=-33.9229995&northwest_longitude=18.4296167&southeast_latitude=-32.9229995&southeast_longitude=18.9616742

This starts a background job on the server to aggregate the sales by location. The API responds with 202 Accepted and the location of the results in the Location header.

Next, poll the URL specified in the Location header:

GET https://api.nomanini.com/sales/summary/locations?job_reference=jobS7UNg6k28OP8tg8a0VDnMS8fw

This will return 204 No Content until the job is completed, after which 200 Ok will be returned with the results in the body of the response.

To display a heatmap of

  • sales in an area: use total_sales_in_cents as the weight.

  • transactions in an area: use total_transactions as the weight.

  • number active devices: use total_active_devices as the weight.

  • average transaction value: use total_sales_in_cents / total_transactions as the weight.

Example URI

GET /sales/summary/locations?start_time=2015-01-01T00:00:00+00:00&end_time=2016-01-01T00:00:00+00:00&northwest_latitude=-33.9229995&northwest_longitude=18.4296167&southeast_latitude=-32.9229995&southeast_longitude=18.9616742&job_reference=jobS7UNg6k28OP8tg8a0VDnMS8fw
URI Parameters
HideShow
start_time
date-time (optional) Example: 2015-01-01T00:00:00+00:00

The starting date and time for the date range, inclusive. If omitted then start_time defaults to the time of the first sale with a location.

end_time
date-time (optional) Example: 2016-01-01T00:00:00+00:00

The ending date and time for the date range, exclusive. If omitted then end_time defaults to the current date and time.

northwest_latitude
number (required) Example: -33.9229995

The latitude of the north west corner of the bounding box. (Only sales in the north-west/south-east bounding box will be returned by the query.)

northwest_longitude
number (required) Example: 18.4296167

The longitude of the north west corner of the bounding box.

southeast_latitude
number (required) Example: -32.9229995

The latitude of the south east corner of the bounding box.

southeast_longitude
number (required) Example: 18.9616742

The longitude of the south east corner of the bounding box.

job_reference
string (optional) Example: jobS7UNg6k28OP8tg8a0VDnMS8fw

Poll the end point with the job_reference that was returned by the API call until while the locations are being sumarised in the background. Once a 200 Ok is returned the body will contain the summarised location information.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "locations": [
    {
      "latitude": -33.916451,
      "longitude": 18.423379,
      "total_sales_in_cents": 123400,
      "total_transactions": 1000,
      "total_active_devices": 12
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "locations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "latitude": {
            "type": "number",
            "minimum": -90,
            "maximum": 90
          },
          "longitude": {
            "type": "number",
            "minimum": -180,
            "maximum": 180
          },
          "total_sales_in_cents": {
            "type": "integer",
            "minimum": 0,
            "description": "The total value of all sales in the region of this `latitude` and `longitude`."
          },
          "total_transactions": {
            "type": "integer",
            "minimum": 0,
            "description": "The total number of sale transactions in the region of this `latitude` and `longitude`."
          },
          "total_active_devices": {
            "type": "integer",
            "minimum": 0,
            "description": "The number of unique devices making sales in the region of this `latitude` and `longitude`."
          }
        },
        "required": [
          "latitude",
          "longitude",
          "total_sales_in_cents",
          "total_transactions",
          "total_active_devices"
        ]
      }
    }
  },
  "required": [
    "locations"
  ]
}
Response  202
HideShow
Headers
Location: https://api.nomanini.com/sales/summary/locations?job_reference=jobS7UNg6k28OP8tg8a0VDnMS8fw
Response  204

Sales prediction

Predict sales

Predict how many sales you will have across all products in the next few hours or days.

Predict sales
GET/sales/prediction{?group_by,limit}

Get the predicted total sales for all products for each period specified in the group_by parameter.

Get the total predicted sales in each hour or day (as specified in the group_by parameter.) This looks ahead over the hours or days up to the limit specified.

For example, to get the total predicted sales per hour for the next 24 hours:

GET /sales/prediction?group_by=hour&limit=24

To get the total predicted sales per day for the next week:

GET /sales/prediction?group_by=day&limit=7

Example URI

GET /sales/prediction?group_by=hour&limit=24
URI Parameters
HideShow
group_by
string (optional) Example: hour

Return the prediction for the total sales in each hour or day. If omitted defaults to hour.

Choices: hour day

limit
integer (optional) Example: 24

The number of periods ahead to make sales predictions for. If omitted defaults to 24.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "prediction_start_time": "2015-10-01T00:00:00+00:00",
  "prediction_end_time": "2015-10-02T00:00:00+00:00",
  "summary": [
    {
      "start_time": "2015-10-01T00:00:00+00:00",
      "end_time": "2015-10-02T00:00:00+00:00",
      "total_sales_in_cents": 100000
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "prediction_start_time": {
      "type": "string",
      "format": "date-time",
      "description": "The start time for this prediction period. Typically the current time."
    },
    "prediction_end_time": {
      "type": "string",
      "format": "date-time",
      "description": "The end time for this prediction period. Typically the current time + group_by * limit supplied in the query."
    },
    "summary": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "start_time": {
            "type": "string",
            "format": "date-time",
            "description": "The start time (inclusive) of the period to predict total sales."
          },
          "end_time": {
            "type": "string",
            "format": "date-time",
            "description": "The end time (exclusive) over which the sales totals are predicted."
          },
          "total_sales_in_cents": {
            "type": "integer",
            "minimum": 0,
            "description": "The predicted total of all sales (face values) between the start and end time in this period."
          }
        },
        "required": [
          "start_time",
          "end_time",
          "total_sales_in_cents"
        ]
      }
    }
  },
  "required": [
    "prediction_start_time",
    "prediction_end_time",
    "summary"
  ]
}

Generated by aglio on 03 Oct 2016