Get Started

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.

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.

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 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.