Welcome to the BOSS API documentation!

The SmarterX Back of Store System (BOSS) helps you make compliant disposal for products leaving your store or warehouse. You can ingest your catalog, get smart recommendations, and record your disposal decisions with these APIs, while integrating with your existing platforms.

Product Lifecycle APIs

Use the following APIs to update product information, get disposal recommendations, and log your decisions:

  • Product Catalog - Tell SmarterX which products you sell and expect recommendations for.
  • Recommendation - Receive compliant, location specific handling paths for disposal, recycling, organics, donation, and more.
  • Unknown Items - Receive compliant disposal paths for items outside of your catalog with a UPC and photo.
  • Reporting - Power reporting for your business users on how locations managed unsaleable items, tracking historic diversion & ESG metrics. This endpoint also enables data sharing with trusted third parties for more efficient pickups.

Configuration APIs

The following APIs are used to manage your locations, disposal options, check product status, and get a status report for the APIs.

  • Location management - Set up store locations and available disposal paths including donation partners.
  • Product lookup (BETA) - Retrieve product registration status on the SmarterX platform
  • Health - Confirm availability of each API endpoint.

Authentication

The BOSS API uses API keys to authenticate requests. The key should be included in the Authorization header of each request. At present, keys are issued by SmarterX and are not available for self-service generation.

curl -H "Authorization: Bearer <your key here>" https://boss.smarterx.com/v1/health

Setup

Location Management

Before you can start using the BOSS APIs, you need to set up your locations and disposal options. Initial configuration of disposal options will be handled by SmarterX, but location setup, adding donation partners, and enabling/disabling disposal options can be done through the Location Management API.

Product Catalog

Next, you need to ingest your product catalog into the BOSS system. This will allow SmarterX to provide disposal recommendations for your products. For products with regulatory disposal requirements, the supplier will be asked provide additional information via the SmarterX Portal. Until the supplier registers the product, it won't be available for disposal recommendations.

Once the product is ingested, you can check on the status of the product registration using the Product Lookup API.

Disposal Workflow

The typical disposal workflow involves the following steps:

  1. Get a recommendation via the Recommendation API
  2. Choose the disposal path from the recommendations. The preferred options are listed first. For regulated products, only compliant disposal paths for the product and location will be presented.
  3. If a recommendation couldn't be provided, because the product isn't registered yet or isn't part of your catalog, use the Unknown Items API to get a recommendation between 10 minutes and 10 hours.
  4. Log the disposal decision using the Reporting API to track your diversion metrics and share data with disposal and donation partners.