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:
https://boss-test.smarterx.com
Retrieve the status of the service. Use to check that api key authentication is working.
Authorization
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
Unique request id for tracing purposes that can be provided in the header of any request
1
Retrieve BOSS handling records for a location.
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
option_id
start_date
end_date
page
page_size
order
Set this param to determine the order of records returned. If none provided, defaults to handled_asc: record handled_at in ascending order.
handled_asc
handled_desc
updated_desc
updated_asc
created_desc
created_asc
location_external_id
Customer provided unique id for a location. This location id must be previously registered with SmarterX.
1
Create a new BOSS handling record for a location.
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
location_external_id
Customer provided unique id for a location. This location id must be previously registered with SmarterX.
New or updated BOSS handling record. May include multiple items, but only for one product.
product_id
SmarterX id of the product that was handled
option_id
SmarterX id of the handling option that was selected
recommendation_id
SmarterX id of the BOSS recommendation shown to the user, if available
handled_at
The time at which the product was handled
weight
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
Unit of measure for weight. Required anytime a weight is present.
lbs
g
kg
quantity
Quantity of the product handled. Must not be zero. Negative quantities are allowed to represent removing the items from a container.
quantity_type
Type of quantity. sku = entire item associated with identifier. component = individual component of an item. Default is sku.
sku
component
metadata
Object containing additional string metadata about a product as key value pairs.
Examples of information that can be tracked:
user
Name or identifier of the user who handled the product
container_id
SmarterX id of the container that the product is placed in.
1
{
"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 information on an existing BOSS handling record.
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
location_external_id
Customer provided unique id for a location. This location id must be previously registered with SmarterX.
record_id
SmarterX uuid for a handling record
1
Update (full or partial) information on an existing BOSS handling record (identical to PATCH)
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
location_external_id
Customer provided unique id for a location. This location id must be previously registered with SmarterX.
record_id
SmarterX uuid for a handling record
Full or partial update for a handling record
product_id
SmarterX id of the product that was handled
option_id
SmarterX id of the handling option that was selected
recommendation_id
SmarterX id of the BOSS recommendation shown to the user, if available
handled_at
The time at which the product was handled
weight
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
Unit of measure for weight. Required anytime a weight is present.
lbs
g
kg
quantity
Quantity of the product handled. Must not be zero. Negative quantities are allowed to represent removing the items from a container.
quantity_type
Type of quantity. sku = entire item associated with identifier. component = individual component of an item. Default is sku.
sku
component
metadata
Object containing additional string metadata about a product as key value pairs.
Examples of information that can be tracked:
user
Name or identifier of the user who handled the product
container_id
SmarterX id of the container that the product is placed in.
1
{
"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"
}
Update (full or partial) information on an existing BOSS handling record (identical to PUT)
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
location_external_id
Customer provided unique id for a location. This location id must be previously registered with SmarterX.
record_id
SmarterX uuid for a handling record
Full or partial update for a handling record
product_id
SmarterX id of the product that was handled
option_id
SmarterX id of the handling option that was selected
recommendation_id
SmarterX id of the BOSS recommendation shown to the user, if available
handled_at
The time at which the product was handled
weight
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
Unit of measure for weight. Required anytime a weight is present.
lbs
g
kg
quantity
Quantity of the product handled. Must not be zero. Negative quantities are allowed to represent removing the items from a container.
quantity_type
Type of quantity. sku = entire item associated with identifier. component = individual component of an item. Default is sku.
sku
component
metadata
Object containing additional string metadata about a product as key value pairs.
Examples of information that can be tracked:
user
Name or identifier of the user who handled the product
container_id
SmarterX id of the container that the product is placed in.
1
{
"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 an existing BOSS handling record.
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
location_external_id
Customer provided unique id for a location. This location id must be previously registered with SmarterX.
record_id
SmarterX uuid for a handling record
1
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.
Use state query param to limit results to containers with one of these states:
Use start_date and end_date query params to retrieve historical records. Returned containers must intersect with this range if both are provided.
Use page and page_size query params to page through chunks of results.
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 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.
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
option.id
SmarterX ID of the option to filter by
state
Container state to filter by
open
closed
picked_up
page
page_size
start_date
Set this to match containers with a finish_datetime on or after this date, or without a finish_datimetime value
end_date
Set this to match containers with a start_datetime on or before this date
order
Set this param to determine the order of containers returned. If none provided, defaults to name_asc: container name in ascending order.
name_asc
name_desc
updated_desc
updated_asc
created_desc
created_asc
location_external_id
Customer provided unique id for a location. This location id must be previously registered with SmarterX.
1
Create a new container
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
location_external_id
Customer provided unique id for a location. This location id must be previously registered with SmarterX.
Container (request body)
Container in the back-of-store that holds sorted items
1
{
"option_id": "ab22e710-5ce4-4e7e-a3db-bd6fdad8fe36",
"total_weight_measured_in": "lbs",
"start_datetime": "2019-08-24T14:15:22Z",
"state": "open"
}
Get information about a specific container
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
location_external_id
Customer provided unique id for a location. This location id must be previously registered with SmarterX.
container_id
SmarterX ID for the container
1
Update information about a specific container
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
location_external_id
Customer provided unique id for a location. This location id must be previously registered with SmarterX.
container_id
SmarterX ID for the container
option_id
UUID of the sorting option that the container is for
total_weight_measured_in
Unit of measure for weight. Required anytime a weight is present.
lbs
g
kg
state
State of the container. Closed containers cannot have more items added. Picked up containers are no longer in the back-of-store.
open
closed
picked_up
start_datetime
UTC date-time when the container was started
finish_datetime
UTC date-time when the container was closed
1
{
"state": "closed"
}
Get all records of sorted products from a container
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
start_date
records must be handled on/after this date
end_date
records must be handled on/before this date
page
results page number (1-indexed, default 1)
page_size
results page size (default 10), accepted range 1-1000
order
Set this param to determine the order of records returned. If none provided, defaults to handled_asc: record handled_at in ascending order.
handled_asc
handled_desc
updated_desc
updated_asc
created_desc
created_asc
page
location_external_id
Customer provided unique id for a location. This location id must be previously registered with SmarterX.
container_id
SmarterX ID for the container
1
Add a product to a container
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
start_date
records must be handled on/after this date
end_date
records must be handled on/before this date
page
results page number (1-indexed, default 1)
page_size
results page size (default 10), accepted range 1-1000
order
Set this param to determine the order of records returned. If none provided, defaults to handled_asc: record handled_at in ascending order.
handled_asc
handled_desc
updated_desc
updated_asc
created_desc
created_asc
location_external_id
Customer provided unique id for a location. This location id must be previously registered with SmarterX.
container_id
SmarterX ID for the container
New or updated BOSS handling record. May include multiple items, but only for one product.
product_id
SmarterX id of the product that was handled
option_id
SmarterX id of the handling option that was selected
recommendation_id
SmarterX id of the BOSS recommendation shown to the user, if available
handled_at
The time at which the product was handled
weight
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
Unit of measure for weight. Required anytime a weight is present.
lbs
g
kg
quantity
Quantity of the product handled. Must not be zero. Negative quantities are allowed to represent removing the items from a container.
quantity_type
Type of quantity. sku = entire item associated with identifier. component = individual component of an item. Default is sku.
sku
component
metadata
Object containing additional string metadata about a product as key value pairs.
Examples of information that can be tracked:
user
Name or identifier of the user who handled the product
container_id
SmarterX id of the container that the product is placed in.
1
{
"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"
}