Find records by business identifiers

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

Get started

Tutorials

Read your data

Find records by business identifiers

Find one shipment and read its contents

Disambiguate repeated references

Look up reference values before joining

​Find one shipment and read its contents

​Disambiguate repeated references

​Look up reference values before joining

Find one shipment and read its contents

Disambiguate repeated references

Look up reference values before joining