ShopSense provides advanced inventory and sales reporting.

ShopSense Inventory

With ShopSense inventory, brands can view inventory levels at stores, prices, and inventory changes over time.

Report Index

The main "Report Index" page provides you with a list of "splits" (stores) in your report, and how many pages each split contains. To load the main "Report Index" page, call the following URL:

GET https://www.locally.com/api/v2/reports/json/{{uuid}}

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

Sample Response:

{
    "version": 2,
    "status": true,
    "properties": {
        "uuid": "127hyb-t5ad-4cbj5-a2a1-0zbay914d170",
        "report_date": "2025-02-15"
    },
    "content": [
        {
            "split_name": "458758",
            "first_page": "https://www.locally.com/api/v2/reports/json/3eb76cae-c2ad-4be5-ada1-0ba91d111d40/458758/0",
            "total_pages": 1
         }
    ]
}

In this example, the report ran on February 15th, 2025, and it consists of one split (one store), and that split has one page. A direct link to the first page of each split is provided in the "Content" section. Your report will likely contain many stores, and each store's splits will be of varying lengths (stores that carry a larger assortment will have multiple pages of inventory, etc.).

Retrieving inventory for a specific store

With ShopSense Inventory, each "split" in your report corresponds to an individual store. To load inventory details for a specific store, you'll call the following URL, which is also provided in the main Report Index results:

GET https://www.locally.com/api/v2/reports/json/{{uuid}}/{{split_id}}/0

Request:

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

Thesplit_id is the locally store_id, and the first page of each split is always 0 .

Sample Response:

{
    "version": 2,
    "status": true,
    "properties": {
        "uuid": "127hyb-t5ad-4cbj5-a2a1-0zbay914d170",
        "current_page": 0,
        "split_id": "sample-shopsense-inventory-report-20250221012345-458758",
        "split_name": "458758",
        "total_pages": 1,
        "total": 1,
        "per_page": 100,
        "report_date": "2025-02-21"
    },
    "content": [
        {
            "store_name": "Locally Test Store #1",          
						"store_company_name": "Locally Test Retailer",
            "vendor_id": "13579",
            "company_name": "Locally Test Brand",
            "product_category": "Guitars",
            "product_name": "Keith Richards Signature Telecaster",
            "upc": "848426073865",
            "gender": "Unisex",
            "size_1": "One Size",
            "color_name": "Butterscotch Blonde",
            "store_inventory_refreshed_at": "2025-10-27 09:05:22",
            "msrp": "5735 USD",
            "retailer_price": "5545 ",
            "updated": "2025-02-15",
            "inventory_change": "-1",
            "quantity_on_hand": "2"
        },
	  ]
}

In this example, the store has one UPC in-stock. The current quantity is 2, and there was one inventory depletion since the prior report. The item MSRP is $5,735 USD, and the store is selling it for $5,545.

Your report will likely contain numerous entries in the "content" section, for each item (UPC) that's in-stock at each store.

Response Explanation [Properties]

Definitions of the Properties section of the response:

Field	Definition
`version`	Locally API version
`status`	`true` if request was a success, `false` if not
`uuid`	UUID of the report
`current page`	The page number you are currently viewing
`split_id`	The unique id of the current split being viewed
`split_name`	The name of the split being viewed (this is the Locally store_id for the given store)
`total_pages`	The number of pages for that split
`total`	The total number of content items in the current split (i.e. number of individual UPCs in the store's inventory)
`per_page`	The number of content items per page
`report_date`	Date the report was generated

Response Explanation [Content]

The Content section of the response contains the store's inventory data and some associated product details. The specific parameters here are illustrative of a typical report, but parameters can be removed or added based on your specific needs, so your report may be slightly different.

Field	Definition
`store_name`	The name of the retail store
`store_company_name`	The company or business name of the retailer
`store_address`	The street address of the retail store
`store_city`	The city the retail store is located in
`store_state`	The state the retail store is located in
`store_country`	The country the retail store is located in
`store_phone`	The phone number of the retail store
`vendor_id`	The brand's unique identifier for store (if available)
`company_name`	The name of the brand or manufacturer of the product
`product_category`	The Locally category
`product_name`	The name of the specific product model or item
`upc`	The Universal Product Code (UPC) for the item
`style_number`	The Locally Style Number assigned to the product
`brand_product_no`	Your unique product id (SKU, MPN), if using
`gender`	The gender category for the product
`size_1`	The size of the product, if applicable (e.g., One Size, Medium).
`color_name`	The color of the product
`msrp`	The Manufacturer’s Suggested Retail Price (MSRP) for the product, typically including the currency.
`retailer_price`	The price at which the retailer is selling the item.
`updated`	The date when the report last ran
`inventory_change`	The quantity change since the last report.
`quantity_on_hand`	The total number of units currently available in the store's inventory.
`store_inventory_refreshed_at`	The date and timestamp of the last inventory file received for this store. NOTE: this is the overall store feed. This is not the last time the particular UPC updated.

ShopSense Inventory + Sales

Our ShopSense Inventory + Sales report includes parameters that show sales and sales prices.

Field	Definition
`msrp`	The Manufacturer’s Suggested Retail Price (MSRP) for the product, typically including the currency.
`retailer_price`	The price at which the retailer is selling the item.
`valuation_price_usd`	A summary field that provides the USD selling price of the item. Helpful for calculating sales amounts.
`sales`	Units sold since last report