# Supplier History

Review supplier products, purchase evidence, saved arrangements, and current cost context.

Canonical HTML: https://developer.shelfcycle.com/guides/supplier-history

Read the products connected to selected suppliers, together with supplier-specific names, purchase evidence, ship-from locations, Cost Book arrangements, and latest saved costs.

## Access

`GET /supplier-history` requires both `cost-book-entries:read` and `suppliers:read`, plus the acting person's current Cost Book and Supplier access. The request is accepted only when every selected supplier is available to the caller.

```text
GET /supplier-history?supplierIds=supplier-id
```

## Choose suppliers and a useful scope

`supplierIds` accepts 1 to 25 comma-separated supplier IDs. A supplier's history includes active products connected through any of these relationships:

- the product is linked to the supplier;
- the product appears on a completed or confirmed purchase order from the supplier; or
- the product has a Cost Book arrangement with the supplier.

Each product includes `admittedBy` so a workflow can see which relationship brought it into the response.

Use either optional filter when the supplier's complete history is broader than the current job:

- `nameQueries` accepts up to 50 comma-separated names and searches product codes, product names, family names, and that supplier's own names for the product.
- `productIds` accepts up to 200 comma-separated product IDs when the workflow already selected exact products.

Both filters may be used together. The response reports whether it is complete for the selected supplier, names, products, or combined scope.

```bash
curl "$SHELFCYCLE_API_BASE_URL/supplier-history?supplierIds=supplier-id&nameQueries=EM440CT,TOFA%20L-1" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "X-ShelfCycle-Client: Supplier price review"
```

## Read product and purchase context

Each product includes its code, family, package, supplier-specific names, and matching submitted names. Purchase context includes:

- `lastCompletedPurchase` for the latest completed purchase evidence;
- `latestOnOrderPurchase` for the latest confirmed purchase evidence; and
- material and landed amounts with their `currencyCode`, `uom`, and `comparisonBasis`.

Keep those three labels together whenever amounts are compared. The API returns stored amounts in their stated currency and unit.

## Read Cost Book context

`arrangements` lists the selected supplier's saved ways to buy each product. Every arrangement includes its kind and place context, plus `latestCost` when a saved cost is available. Latest cost details separate the starting amount, additional costs, and total amount and include the saved effective window and state.

Use arrangement identity and returned amount basis when preparing a connected Cost Book workflow. Purchase evidence and Cost Book context are separate facts, so show each with its own source date and label.

## Use coverage and name results

Each supplier result includes:

- `coverage.complete` and `coverage.scope` for the selected request;
- counts for returned products, arrangements, and saved costs;
- `nameQueryCounts` for every submitted name;
- `unmatchedQueries` for submitted names with no match; and
- `matchedQueries` on every matching product.

Treat an unmatched name as a complete result only when `coverage.complete` is true for the name scope. When `coverage.complete` is false, narrow the request with `nameQueries` or `productIds` and review the returned coverage again.

## Choose Product Directory when supplier context is not needed

Use [Product Directory](/guides/product-directory) for organization-wide name and regulatory lookup. Use Supplier History when the job also needs supplier-specific names, product relationships, purchasing context, or saved Cost Book context.