BOSS Reporting API

Back of Store System Reporting API

Report on and manage the real world handling of products.

This API receives the final decision taken by a user of the BOSS Recommendation API to power reporting provided by SmarterX via Tableau on various business and ESG related metrics around diversion paths and weights by location.

Unless otherwise noted, the following limits apply to fields in POST/PUT bodies, URL path and query params:

  • Date/time strings must be provided in ISO 8601 format. All values converted to UTC, no time zone info will be retained.
  • All string fields, path and query parameters are limited to 127 characters or fewer
  • All floating-point numeric values are limited to approximately 6 decimal places of precision, with a range from approximately 1E-37 to 1E+37
  • All integer numeric values are limited to ±2<sup>32</sup>
  • All UUIDs are UUIDv4. These will be generated initially by SmarterX, and used in subsequent reporting requests.
BASE URL
https://boss-test.smarterx.com

status

ENDPOINTS
GET/v1/reporting/health

Check status of service

Retrieve the status of the service. Use to check that api key authentication is working.

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

x-request-id

string

Unique request id for tracing purposes that can be provided in the header of any request

GET
/v1/reporting/health
1

Retrieve records at this location

Retrieve BOSS handling records for a location.

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Query Parameters

option_id

string

start_date

string

end_date

string

page

integer

page_size

integer

order

optional, string enum

Set this param to determine the order of records returned. If none provided, defaults to handled_asc: record handled_at in ascending order.

Possible Enum Values

handled_asc

handled_desc

updated_desc

updated_asc

created_desc

created_asc

Path Parameters

location_external_id

required, string

Customer provided unique id for a location. This location id must be previously registered with SmarterX.

GET
/v1/boss/reporting/:location_external_id/records
1

Create new handling record

Create a new BOSS handling record for a location.

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

location_external_id

required, string

Customer provided unique id for a location. This location id must be previously registered with SmarterX.

Request Body

New or updated BOSS handling record. May include multiple items, but only for one product.

product_id

required, string

SmarterX id of the product that was handled

option_id

required, string

SmarterX id of the handling option that was selected

recommendation_id

optional, string

SmarterX id of the BOSS recommendation shown to the user, if available

handled_at

required, string

The time at which the product was handled

weight

optional, number

Real world measured weight of a single unit of the product. Precision: at least 6 decimal places supported. If this value is missing, it will be calculated from the item_weight times quantity. Negative weights may be used if the item is being removed from the container

weight_measured_in

optional, string enum

Unit of measure for weight. Required anytime a weight is present.

Possible Enum Values

lbs

g

kg

quantity

required, number

Quantity of the product handled. Must not be zero. Negative quantities are allowed to represent removing the items from a container.

quantity_type

optional, string enum

Type of quantity. sku = entire item associated with identifier. component = individual component of an item. Default is sku.

Possible Enum Values

sku

component

metadata

optional, object

Object containing additional string metadata about a product as key value pairs.

Examples of information that can be tracked:

  • Where did the item come from?
  • What was the condition of the item?
  • What department handled the item?

user

optional, string

Name or identifier of the user who handled the product

container_id

optional, string

SmarterX id of the container that the product is placed in.

POST
/v1/boss/reporting/:location_external_id/records
1
EXAMPLE BODY
{
  "product_id": "0d012afa-f885-4e65-aeca-37e27701e2d1",
  "option_id": "ab22e710-5ce4-4e7e-a3db-bd6fdad8fe36",
  "recommendation_id": "ddb15214-abd6-4c83-931f-eaff12e7f260",
  "handled_at": "2019-08-24T14:15:22Z",
  "weight": 0.5,
  "weight_measured_in": "lbs",
  "quantity": 1,
  "metadata": {
    "source": "Customer Return",
    "item_condition": "Damaged and Leaking"
  },
  "user": "John Doe"
}

Retrieve existing handling record

Retrieve information on an existing BOSS handling record.

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

location_external_id

required, string

Customer provided unique id for a location. This location id must be previously registered with SmarterX.

record_id

required, string

SmarterX uuid for a handling record

GET
/v1/boss/reporting/:location_external_id/records/:record_id
1

Edit existing handling record

Update (full or partial) information on an existing BOSS handling record (identical to PATCH)

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

location_external_id

required, string

Customer provided unique id for a location. This location id must be previously registered with SmarterX.

record_id

required, string

SmarterX uuid for a handling record

Request Body

Full or partial update for a handling record

product_id

required, string

SmarterX id of the product that was handled

option_id

required, string

SmarterX id of the handling option that was selected

recommendation_id

optional, string

SmarterX id of the BOSS recommendation shown to the user, if available

handled_at

required, string

The time at which the product was handled

weight

optional, number

Real world measured weight of a single unit of the product. Precision: at least 6 decimal places supported. If this value is missing, it will be calculated from the item_weight times quantity. Negative weights may be used if the item is being removed from the container

weight_measured_in

optional, string enum

Unit of measure for weight. Required anytime a weight is present.

Possible Enum Values

lbs

g

kg

quantity

required, number

Quantity of the product handled. Must not be zero. Negative quantities are allowed to represent removing the items from a container.

quantity_type

optional, string enum

Type of quantity. sku = entire item associated with identifier. component = individual component of an item. Default is sku.

Possible Enum Values

sku

component

metadata

optional, object

Object containing additional string metadata about a product as key value pairs.

Examples of information that can be tracked:

  • Where did the item come from?
  • What was the condition of the item?
  • What department handled the item?

user

optional, string

Name or identifier of the user who handled the product

container_id

optional, string

SmarterX id of the container that the product is placed in.

PUT
/v1/boss/reporting/:location_external_id/records/:record_id
1
EXAMPLE BODY
{
  "product_id": "0d012afa-f885-4e65-aeca-37e27701e2d1",
  "option_id": "ab22e710-5ce4-4e7e-a3db-bd6fdad8fe36",
  "recommendation_id": "ddb15214-abd6-4c83-931f-eaff12e7f260",
  "handled_at": "2019-08-24T14:15:22Z",
  "weight": 0.5,
  "weight_measured_in": "lbs",
  "quantity": 1,
  "metadata": {
    "source": "Customer Return",
    "item_condition": "Damaged and Leaking"
  },
  "user": "John Doe"
}

Edit existing handling record (same as PUT)

Update (full or partial) information on an existing BOSS handling record (identical to PUT)

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

location_external_id

required, string

Customer provided unique id for a location. This location id must be previously registered with SmarterX.

record_id

required, string

SmarterX uuid for a handling record

Request Body

Full or partial update for a handling record

product_id

required, string

SmarterX id of the product that was handled

option_id

required, string

SmarterX id of the handling option that was selected

recommendation_id

optional, string

SmarterX id of the BOSS recommendation shown to the user, if available

handled_at

required, string

The time at which the product was handled

weight

optional, number

Real world measured weight of a single unit of the product. Precision: at least 6 decimal places supported. If this value is missing, it will be calculated from the item_weight times quantity. Negative weights may be used if the item is being removed from the container

weight_measured_in

optional, string enum

Unit of measure for weight. Required anytime a weight is present.

Possible Enum Values

lbs

g

kg

quantity

required, number

Quantity of the product handled. Must not be zero. Negative quantities are allowed to represent removing the items from a container.

quantity_type

optional, string enum

Type of quantity. sku = entire item associated with identifier. component = individual component of an item. Default is sku.

Possible Enum Values

sku

component

metadata

optional, object

Object containing additional string metadata about a product as key value pairs.

Examples of information that can be tracked:

  • Where did the item come from?
  • What was the condition of the item?
  • What department handled the item?

user

optional, string

Name or identifier of the user who handled the product

container_id

optional, string

SmarterX id of the container that the product is placed in.

PATCH
/v1/boss/reporting/:location_external_id/records/:record_id
1
EXAMPLE BODY
{
  "product_id": "0d012afa-f885-4e65-aeca-37e27701e2d1",
  "option_id": "ab22e710-5ce4-4e7e-a3db-bd6fdad8fe36",
  "recommendation_id": "ddb15214-abd6-4c83-931f-eaff12e7f260",
  "handled_at": "2019-08-24T14:15:22Z",
  "weight": 0.5,
  "weight_measured_in": "lbs",
  "quantity": 1,
  "metadata": {
    "source": "Customer Return",
    "item_condition": "Damaged and Leaking"
  },
  "user": "John Doe"
}

Delete existing handling record

Delete an existing BOSS handling record.

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

location_external_id

required, string

Customer provided unique id for a location. This location id must be previously registered with SmarterX.

record_id

required, string

SmarterX uuid for a handling record

DELETE
/v1/boss/reporting/:location_external_id/records/:record_id
1

Retrieve container inventory

Retrieves containers at a location. By default, returns the full inventory of containers at the location.

Use the order sort the resulting containers returned with 6 options: name_asc (default), name_desc, updated_asc, updated_desc, created_desc, created_asc.

Query Params

Use state query param to limit results to containers with one of these states:

  • open
  • closed
  • picked_up

Use start_date and end_date query params to retrieve historical records. Returned containers must intersect with this range if both are provided.

  • start_date: matches any container with a finish_datetime on or after this date, or containers without a finish_datetime
  • end_date: matches any container with a start_datetime on or before this date

Use page and page_size query params to page through chunks of results.

Use option.id query param to filter by a specific sorting option.

Use category query param to filter by a specific binning category, e.g. disposal, recycle, etc.

Use cases

Searching Closed or Picked Up Containers

Use state=closed to return containers that are finished and ready for pickup. Use state=picked_up to return containers that have been collected by the disposal partner.

The number of closed/picked up containers will naturally increase over time, and a query for these states may eventually return a large number of results. Since all of these containers are expected to have a finish_datetime value, we can use start_date and end_date to limit the results to the desired time range.

  • Use start_date and end_date together to limit the results to containers that intersect with this time range, e.g. start_date=2023-02-01&end_date=2023-02-28 to return containers that had items added in the month of Februrary
  • Use start_date alone to limit the results to containers that have finish_datetime after this date, e.g. start_date=2023-03-01 to return containers that had items added after March 1st
  • Use end_date alone to limit the results to containers that have start_datetime prior this date, e.g. end_date=2023-01-01 to return containers that had items added prior to 2023

Searching Open Containers

Use state=open to return only open containers. These are containers that are available for adding additional items.

Because the count of open containers on-site at a retail location tends to be a manageable number during a relatively short window of time, filtering by date range on these statuses is usually unnecessary, although still supported. Note that since these containers typically don't have a finish_datetime, they'll match any query where only start_date is provided.

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Query Parameters

option.id

string

SmarterX ID of the option to filter by

state

string enum, default: open

Container state to filter by

Possible Enum Values

open

closed

picked_up

page

integer

page_size

integer

start_date

string

Set this to match containers with a finish_datetime on or after this date, or without a finish_datimetime value

end_date

string

Set this to match containers with a start_datetime on or before this date

order

string enum

Set this param to determine the order of containers returned. If none provided, defaults to name_asc: container name in ascending order.

Possible Enum Values

name_asc

name_desc

updated_desc

updated_asc

created_desc

created_asc

category

optional, string enum

Filter by disposal category. If none provided, defaults to all categories.

Possible Enum Values

disposal

recycle

donation

organics

vendor_managed

Path Parameters

location_external_id

required, string

Customer provided unique id for a location. This location id must be previously registered with SmarterX.

GET
/v1/boss/reporting/:location_external_id/containers
1

Create new container

Create a new container

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

location_external_id

required, string

Customer provided unique id for a location. This location id must be previously registered with SmarterX.

Request Body

Container (request body)

object

Container in the back-of-store that holds sorted items

POST
/v1/boss/reporting/:location_external_id/containers
1
EXAMPLE BODY
{
  "option_id": "ab22e710-5ce4-4e7e-a3db-bd6fdad8fe36",
  "total_weight_measured_in": "lbs",
  "start_datetime": "2019-08-24T14:15:22Z",
  "state": "open"
}

Retrieve existing container

Get information about a specific container

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

location_external_id

required, string

Customer provided unique id for a location. This location id must be previously registered with SmarterX.

container_id

required, string

SmarterX ID for the container

GET
/v1/boss/reporting/:location_external_id/containers/:container_id
1

Update existing container

Update information about a specific container

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

location_external_id

required, string

Customer provided unique id for a location. This location id must be previously registered with SmarterX.

container_id

required, string

SmarterX ID for the container

Request Body

option_id

optional, string

UUID of the sorting option that the container is for

total_weight_measured_in

optional, string enum

Unit of measure for weight. Required anytime a weight is present.

Possible Enum Values

lbs

g

kg

state

optional, string enum

State of the container. Closed containers cannot have more items added. Picked up containers are no longer in the back-of-store.

Possible Enum Values

open

closed

picked_up

start_datetime

optional, string

UTC date-time when the container was started

finish_datetime

optional, string

UTC date-time when the container was closed

PATCH
/v1/boss/reporting/:location_external_id/containers/:container_id
1
EXAMPLE BODY
{
  "state": "closed"
}

Retrieve container contents

Get all records of sorted products from a container

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Query Parameters

start_date

string

records must be handled on/after this date

end_date

string

records must be handled on/before this date

page

integer

results page number (1-indexed, default 1)

page_size

integer

results page size (default 10), accepted range 1-1000

order

optional, string enum

Set this param to determine the order of records returned. If none provided, defaults to handled_asc: record handled_at in ascending order.

Possible Enum Values

handled_asc

handled_desc

updated_desc

updated_asc

created_desc

created_asc

page

integer

Path Parameters

location_external_id

required, string

Customer provided unique id for a location. This location id must be previously registered with SmarterX.

container_id

required, string

SmarterX ID for the container

GET
/v1/boss/reporting/:location_external_id/containers/:container_id/records
1

Add a product to a container

Add a product to a container

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Query Parameters

start_date

string

records must be handled on/after this date

end_date

string

records must be handled on/before this date

page

integer

results page number (1-indexed, default 1)

page_size

integer

results page size (default 10), accepted range 1-1000

order

optional, string enum

Set this param to determine the order of records returned. If none provided, defaults to handled_asc: record handled_at in ascending order.

Possible Enum Values

handled_asc

handled_desc

updated_desc

updated_asc

created_desc

created_asc

Path Parameters

location_external_id

required, string

Customer provided unique id for a location. This location id must be previously registered with SmarterX.

container_id

required, string

SmarterX ID for the container

Request Body

New or updated BOSS handling record. May include multiple items, but only for one product.

product_id

required, string

SmarterX id of the product that was handled

option_id

required, string

SmarterX id of the handling option that was selected

recommendation_id

optional, string

SmarterX id of the BOSS recommendation shown to the user, if available

handled_at

required, string

The time at which the product was handled

weight

optional, number

Real world measured weight of a single unit of the product. Precision: at least 6 decimal places supported. If this value is missing, it will be calculated from the item_weight times quantity. Negative weights may be used if the item is being removed from the container

weight_measured_in

optional, string enum

Unit of measure for weight. Required anytime a weight is present.

Possible Enum Values

lbs

g

kg

quantity

required, number

Quantity of the product handled. Must not be zero. Negative quantities are allowed to represent removing the items from a container.

quantity_type

optional, string enum

Type of quantity. sku = entire item associated with identifier. component = individual component of an item. Default is sku.

Possible Enum Values

sku

component

metadata

optional, object

Object containing additional string metadata about a product as key value pairs.

Examples of information that can be tracked:

  • Where did the item come from?
  • What was the condition of the item?
  • What department handled the item?

user

optional, string

Name or identifier of the user who handled the product

container_id

optional, string

SmarterX id of the container that the product is placed in.

POST
/v1/boss/reporting/:location_external_id/containers/:container_id/records
1
EXAMPLE BODY
{
  "product_id": "0d012afa-f885-4e65-aeca-37e27701e2d1",
  "option_id": "ab22e710-5ce4-4e7e-a3db-bd6fdad8fe36",
  "recommendation_id": "ddb15214-abd6-4c83-931f-eaff12e7f260",
  "handled_at": "2019-08-24T14:15:22Z",
  "weight": 0.5,
  "weight_measured_in": "lbs",
  "quantity": 1,
  "metadata": {
    "source": "Customer Return",
    "item_condition": "Damaged and Leaking"
  },
  "user": "John Doe"
}