ShopSense Suggested Orders

Overview

The Suggested Orders report provides brands with UPC-level restock recommendations for each of their retail partners. Recommendations are driven by recent sales velocity and current on-hand inventory, surfacing products and sizes that have recently sold our or are at risk of stocking out. Suggested Orders reports can be provided at the retailer account-level or at at the store-level, depending on your preference.

The report is accessed in two steps:

1. Fetch the Index — retrieves the list of retailer “splits” available for your report
2. Fetch a Split — retrieves the paginated suggested order line items for a specific retailer company or store

Authentication

To access your report, you’ll be provided with an API key that authenticates your access to your report only.

Endpoints

1. Get Report Index

Retrieves the list of retailer splits available for a given report.

curl --request GET \
  --url 'https://www.locally.com/api/v2/reports/json/{{uuid}}' \
  --header 'Locally-Api-Token: {{API_TOKEN}}'

PATH PARAMETERS

EXAMPLE REQUEST

EXAMPLE RESPONSE

{
  "version": 2,
  "status": true,
  "properties": {
    "uuid": "c8e3465e-c13d-453a-b09c-81h3pb1777d9",
    "report_date": "2026-02-18"
  },
  "content": [
    {
      "split_name": "919",
      "first_page": "https://www.locally.com/api/v2/reports/json/{uuid}/919/0",
      "total_pages": 1
    },
    {
      "split_name": "127",
      "first_page": "https://www.locally.com/api/v2/reports/json/{uuid}/127/0",
      "total_pages": 3
    },
    ...
  ]
}

RESPONSE FIELDS — TOP LEVEL

RESPONSE FIELDS — PROPERTIES OBJECT

RESPONSE FIELDS — CONTENT ITEMS (SPLITS)

2. Get Retailer Split (Suggested Orders)

Retrieves a paginated list of suggested restock orders for a specific retailer. Can be company or store-level, depending on your report.

PATH PARAMETERS

EXAMPLE REQUEST

EXAMPLE RESPONSE

{
  "version": 2,
  "status": true,
  "properties": {
    "uuid": "{uuid}",
    "current_page": 0,
    "split_id": "shopsense-suggested-orders-{brand-name}-20260218110118-919",
    "split_name": "919",
    "total_pages": 1,
    "total": 75,
    "per_page": 100,
    "report_date": "2026-02-18"
  },
  "content": [
    {
            "retailer_name": "Trailside Depot",
            "store_name": "Trailside Depot",
            "store_id": "919",
            "vendor_id": "13579",
            "product_id": "2359528",
            "upc": "120076326375",
            "product_name": "Wavebound Shorts",
            "product_vertical": "Apparel & Accessories",
            "product_category": "Outerwear Bottoms",
            "season": "Spring 26",
            "brand_product_no": "BKD457",
            "gender": "Mens",
            "color": "Bright Blue",
            "size": "L",
            "size_2": "",
            "stores_carrying_product": "3",
            "stores_in_stock": "3",
            "total_quantity_on_hand": "5",
            "total_expected_28_day_sales": "116",
            "total_expected_quantity_28d": "0",
            "suggested_order_qty": "111",
            "suggested_order_value": "72039",
            "msrp_usd": "649",
            "msrp_local": "649",
            "local_currency": "USD",
            "sales_last_7_days": "19",
            "sales_last_14_days": "39",
            "sales_last_21_days": "81",
            "sales_last_28_days": "116",
            "sales_last_365_days": "206"
        },
       … 
  ]
}

RESPONSE FIELDS — TOP LEVEL

RESPONSE FIELDS — PROPERTIES OBJECT

Each item in content represents a single suggested restock recommendation at the UPC level (product + color + size combination).

CONTENT ITEMS — PRODUCT IDENTIFICATION

CONTENT ITEMS — INVENTORY & DISTRIBUTION

CONTENT ITEMS — SALES VELOCITY

CONTENT ITEMS — RECOMMENDATION

CONTENT ITEMS — PRICING

Report Levels: Retailer-Level vs. Store-Level

Suggested Orders reports are delivered at one of two levels, which determines how splits are keyed and how line items are scoped:

• Retailer-level (default): Splits are keyed on the Locally store_company_id, so each split represents an entire retail company. Line items are aggregated across the company's locations, and the store_id field identifies the individual store a given line item belongs to. Because vendor_id is scoped per store, a single retailer-level split may contain multiple vendor_id values.
• Store-level: Splits are keyed on the Locally store_id, so each split represents a single retail location. The split_name matches the store_id of every line item in that split.

Pagination

Splits with total_pages > 1 require multiple requests to retrieve all line items. Pages are zero-indexed. To retrieve all pages for a given split:

1. Fetch first_page from the Index response.
2. Note total_pages from the split's properties.
3. Increment the trailing page number in the URL from 0 through total_pages − 1.

EXAMPLE — SPLIT WITH 3 PAGES

GET /reports/json/{uuid}/{split_name}/0
GET /reports/json/{uuid}/{split_name}/1
GET /reports/json/{uuid}/{split_name}/2

Known Edge Cases & Notes

• Numeric values are returned as strings. All quantity, sales, and price fields use the string type despite containing numeric data. Parse accordingly.
• MSRP may be missing. When unavailable, msrp_usd will be an empty string, msrp_local will be "-1", and suggested_order_value will also be empty.
• product_id is Locally's style number and is not a unique SKU key. Multiple records can share a product_id because it represents the style, not the individual size/color. Use upc or your brand_product_no as the unique identifier.
• vendor_id is scoped per store. In retailer-level reports (keyed on store_company_id), different stores within the same split may have different vendor_id values, and a store may list multiple vendor_id's.