canonical: https://jentic.com/apis/gs1.org/gs1

# GS1 Inventory Report API

The GS1 Inventory Report API is an alpha-stage API from GS1 that exposes inventory data for products identified by Global Trade Item Number (GTIN) across locations identified by Global Location Number (GLN). It currently exposes three read endpoints: a query for inventory across all products and locations, a per-location query keyed by GLN, and a per-product query keyed by GTIN. Authentication is by an ApiKey header, and the dataset is intended for trading-partner inventory visibility scenarios where retailers and suppliers exchange real-time stock counts using standard GS1 identifiers.

## For AI agents

Query inventory data for GS1-identified products and locations using GTIN and GLN keys.

## Scope

Does not handle order placement, EDI documents, or barcode generation - use for GS1 inventory queries by GTIN and GLN only.

## Capabilities

- Retrieve inventory data for every GTIN across every GLN in one call for a full snapshot
- Look up inventory at a single location by Global Location Number (GLN) for store-level reporting
- Look up inventory for a single product by Global Trade Item Number (GTIN) across all locations
- Query stock levels using only GS1 standard identifiers, avoiding vendor-specific SKU mappings
- Drive trading-partner inventory visibility flows that need GS1-conformant data exchange

## Use cases

### Trading-partner inventory visibility

Share real-time inventory between a supplier and a retailer using GS1 standard identifiers rather than each party's internal SKU. The supplier exposes GET /products for a full snapshot or GET `/findProductById/{gtin}` for a single product, while the retailer can drill into a single store with GET `/findProductsByLocation/{gln}.` Because the keys are GTIN and GLN there is no SKU translation step, which is the point of using GS1 standards in the first place.

Example prompt: Call GET `/findProductById/{gtin}` for the supplier-side product reference and confirm stock is on hand before promising to the retailer.

### Out-of-stock detection across locations

Detect out-of-stock or low-stock conditions at trading partner locations by polling GET `/findProductsByLocation/{gln}` for each store and flagging products below threshold. The agent can then generate replenishment recommendations for the supply chain team. Because the API uses GS1 identifiers, the same logic works regardless of how many distinct retailer ERPs are in the trading network.

Example prompt: Iterate over each known GLN, call GET `/findProductsByLocation/{gln}`, and write a low-stock alert when inventory is below the configured threshold.

### Compliance-grade inventory snapshots

Capture daily inventory snapshots using GS1-standard identifiers for compliance reporting and audit. GET /products returns the full cross-location snapshot, which can be archived for later review. Because the dataset is keyed by GTIN and GLN, the snapshot is portable across retailer systems and remains meaningful even after vendor SKU changes.

Example prompt: Schedule a nightly call to GET /products and persist the response to the data warehouse with a date-stamped key.

### AI agent integration through Jentic

Let a supply-chain agent answer GS1-keyed inventory questions through Jentic without writing custom HTTP code. The agent searches Jentic for the relevant intent (for example 'look up inventory for a GTIN'), loads the operation schema, and executes the GS1 call. Jentic stores the GS1 ApiKey in its vault so the agent only sees a scoped Jentic agent key.

Example prompt: Through Jentic, search 'look up inventory by GTIN', load the operation, and execute it with the GTIN supplied in the user query.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/products` | Inventory snapshot across all products and locations |
| GET | `/findProductsByLocation/{gln}` | Inventory at a single GLN location |
| GET | `/findProductById/{gtin}` | Inventory for a single GTIN across all locations |

## Key resources

- **products** — Cross-location inventory snapshot for every product in the dataset
- **findProductsByLocation** — Inventory data for all products at a single GS1 GLN location
- **findProductById** — Inventory data for a single GTIN across all known locations

## Why Jentic

- **Setup:** Wiring the GS1 Inventory Report API by hand means setting the ApiKey header on every call to the dev.gs1.org inventory host and handling GTIN and GLN lookups and retries yourself. Through Jentic you install once, import GS1 Inventory from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** GS1 puts the GTIN and GLN in the URL path (`/findProductById/{gtin}`, `/findProductsByLocation/{gln}`), so a rule can pin your agent to one product or one location for reads. You choose the operations it may call, and since every endpoint here is a read, the agent only fetches the inventory records you allow.
- **Credential handling:** Your GS1 ApiKey is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'look up inventory by GTIN' or 'find products by location GLN', and Jentic returns the matching operation with its input schema, including the required GTIN or GLN, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Shopify Admin API** — Inventory and order management for Shopify storefronts
- **Walmart Inventory Management API** — Walmart marketplace inventory updates
- **eBay API** — Marketplace inventory and listing platform

## FAQ

### What authentication does the GS1 Inventory Report API use?

The API uses an ApiKey header on every request, named ApiKey. The key is issued by GS1 to participating trading-partner organisations. Through Jentic the ApiKey is stored encrypted in the vault, and the agent only authenticates to Jentic with a scoped agent key (ak_*).

### Can I look up inventory by GTIN?

Yes. GET `/findProductById/{gtin}` returns inventory data for the specified Global Trade Item Number across all available locations. This is the right endpoint when you have the product identifier and want to know where it is in stock.

### Can I look up inventory by store location?

Yes. GET `/findProductsByLocation/{gln}` returns inventory for all products at a single GS1 Global Location Number. This is the right endpoint for store-level reporting and per-DC stocktake views.

### What are the rate limits for the GS1 Inventory Report API?

The published spec does not document rate limits, and the dev.gs1.org host is the alpha environment used for early integration testing. Coordinate with your GS1 contact for production limits and base URL when promoting your integration.

### How do I pull a full inventory snapshot through Jentic?

Install Jentic with pip install jentic, search for 'list GS1 inventory across all products', load the matching operation, and execute it. Jentic resolves the call to GET /products and returns the full cross-location snapshot.

### Is this API the production environment?

The dev.gs1.org/inventory/v1 base URL is the alpha development environment for the Inventory Report API. Promote to the production endpoint with GS1 only after your integration passes their conformance checks; the path structure stays the same.

### Can I limit what my agent is allowed to do with the GS1 Inventory Report API?

Yes. Because you self-host Jentic One, your own rules decide which of the three read operations the agent may call, so you can allow only GET `/findProductById/{gtin}` or GET `/findProductsByLocation/{gln}` and withhold the full GET /products snapshot. Since GS1 puts the GTIN and GLN in the URL path, a rule can pin the agent to a single product or a single location, and because every endpoint here is read-only the agent can only fetch the inventory records you permit. Your GS1 ApiKey stays under your control and is injected at execution time rather than exposed to the agent.