Find records by business identifiers

Find products, shipments, invoices, suppliers, and related records by the identifiers you already have

Set your API key and brand. Use exact lookups for identifiers from your ERP or PIM, then use the returned UUID for detail and relationship reads. All paths below start at /api/public/v1/brands/{brand}.

You know	Request
Parent Product code	/products?code=TEE-001
Part of a product name or code	/products?q=cotton
Product Option name and parent	/product-options?productId={id}&name=Ocean
SKU code or UPC	/skus?code=TEE-001-M or /skus?upc=012345678901
Purchase-order number	/orders?orderNumber=PO-2026-0042
Your external order reference	/orders?externalOrderCode=ERP-42
Quotes for a product and supplier	/quotes?productId={id}&supplierId={id}
Quote number	/quotes?quoteNumber=RFQ-2026-0081
Shipment code	/shipments?shipmentCode=SHP-2026-0042
Tracking number and carrier	/shipments?trackingNumber=JD0146000123456789&carrierSlug=dhl
Container number	/shipments?containerNumber=MSCU1234567
Forwarder’s reference	/shipments?source=manual&externalShipmentId=EXT-42
Booking reference	/bookings?externalBookingReference=BOOK-42&source=manual
Packing-list reference	/packing-lists?reference=PL-42
Goods-receipt number	/goods-receipts?receiptNumber=GR-42
Invoice number and issuer	/invoices?invoiceNumber=INV-42&issuerPartnerId={id}
Payment reference	/payment-receipts?paymentReference=BANK-42
Supplier slug	/suppliers?slug=textile-co
Contact email	/contacts?email=orders%40textile.example
Sample code	/samples?code=SAMPLE-42
Material code	/materials?code=FAB-001
Color code	/colors?code=NAVY
Port code	/locations?unLocode=USLAX
Document filename	/documents?fileName=invoice-42.pdf

Exact filters are case-sensitive. Product q search is case-insensitive and matches a literal substring, including % and _ as ordinary characters. Combine filters with AND; for example, code=TEE-001&status=active. Product Option names and external references can match several records, so every lookup returns the standard page envelope. Zero matches is an empty page. Unknown or invalid parameters return 400 instead of silently broadening a read. See filters by entity for the complete collection selector list.

curl --fail-with-body --get \
  -H "Authorization: Bearer $AMBER_API_KEY" \
  --data-urlencode "code=TEE-001" \
  "https://app.amber.ai/api/public/v1/brands/$AMBER_BRAND/products"

Save amber-client.mjs, then run this with Node.js 22 or later and PRODUCT_CODE set to a known code:

find-product.mjs

import { apiUrl, records, productGraph } from "./amber-client.mjs";

const code = process.env.PRODUCT_CODE;
if (!code) throw new Error("Set PRODUCT_CODE");
for await (const product of records(apiUrl("products", { code }))) {
  const packet = await productGraph(product.id, "versions,boms,bomComponents,measurementTables,productOptions,skus");
  console.log(JSON.stringify(packet));
}

Keep IDs as your local join keys. Product codes and names can change; the UUID identifies the same record across those edits. When paginating, preserve the brand, resource and filters. Reusing a cursor for a different lookup returns 400.

Find one shipment and read its contents

Use shipmentCode when you have Amber’s code. For carrier events, combine trackingNumber and carrierSlug; for imported shipments, combine externalShipmentId and source. A containerNumber lookup matches membership in the shipment’s containerNumbers array.

curl --fail-with-body --get \
  -H "Authorization: Bearer $AMBER_API_KEY" \
  --data-urlencode "shipmentCode=SHP-2026-0042" \
  --data-urlencode "limit=2" \
  "https://app.amber.ai/api/public/v1/brands/$AMBER_BRAND/shipments"

If you expect exactly one match, check totalItems before choosing it. Do not silently take items[0] when several records share a reference. This script fails on ambiguity and fetches only the selected shipment’s lines and cartons:

find-shipment.mjs

import { apiUrl, readJson, records } from "./amber-client.mjs";

const shipmentCode = process.env.SHIPMENT_CODE;
if (!shipmentCode) throw new Error("Set SHIPMENT_CODE");
const page = await readJson(apiUrl("shipments", { shipmentCode, limit: 2 }));
if (page.totalItems !== 1 || page.items.length !== 1) {
  throw new Error(`Expected one shipment; found ${page.totalItems}`);
}
const shipment = page.items[0];
const items = [];
const cartons = [];
for await (const item of records(apiUrl("shipment-items", { shipmentId: shipment.id }))) {
  items.push(item);
}
for await (const carton of records(apiUrl("shipment-cartons", { shipmentId: shipment.id }))) {
  cartons.push(carton);
}
console.log(JSON.stringify({ shipment, items, cartons }, null, 2));

Disambiguate repeated references

Identifiers often belong to a parent or an issuing organization. Use both parts when you know them:

Record	Selectors to combine
Supplier invoice	invoiceNumber + issuerPartnerId; supplierId identifies the order supplier and can differ from the issuer
Carton	packingListId + cartonNumber
Product version	productId + versionNumber
Quote revision	rfqId + round; rfqId is the parent Quote ID returned by /quotes
Quote price band	quoteItemId + bandNumber
Production run	orderId + runNumber
Payment obligation	sourceKind + sourceKey, with scopeKey if needed
Dimension curve cell	curveId + rowIndex + colIndex

These combinations narrow a read; they do not promise that every source has a unique business reference. Use the matching record’s stable ID for future reads.

Look up reference values before joining

Resolve /colors?code=NAVY or /materials?code=FAB-001 once, then use the returned IDs in relationship filters. For example, /material-variants accepts componentId, colorId, and supplierMaterialVariantCode. A child without its own business code is still addressable by its parent and related IDs: use /shipment-carton-items?shipmentCartonId={id}&skuId={id} to read one carton’s matching SKU rows.

Boolean selectors use true or false. Integer selectors use ordinary whole numbers without leading zeros, such as versionNumber=0 or rowIndex=0. Always URL-encode values, especially email addresses, spaces, +, &, and #.