Product graphs

Parent Products, Product Options, SKUs, and complete specification data

Parent Products are returned by /products. Product Options are returned by /product-options; each has a productId pointing to its Parent Product. SKUs are returned by /skus, with productId and optional productOptionId. Library /options and /option-values define attributes such as color or material. They are distinct from Product Options.

Request an expanded Parent Product

curl --fail-with-body \
  -H "Authorization: Bearer $AMBER_API_KEY" \
  "https://app.amber.ai/api/public/v1/brands/$AMBER_BRAND/products/$PRODUCT_ID?include=all&includeLimit=100"

Use a comma-separated include to request less data:

include=productOptions,skus,versions,boms,bomComponents,measurementTables,materials

The API reference lists every supported include name. Unsupported names return 400. With no include, the detail retains its compact shape and existing variants and suppliers summaries.

Each distinct include costs one expansion credit. The per-key budget holds 62 credits, enough for two immediate include=all requests, and refills at 1,000 credits per hour by default. Duplicate names cost once. When the budget is exhausted, the API returns 429 with Retry-After; wait before retrying or request fewer collections. Continuation URLs use the regular request quota without expansion credits. See Authentication for rate limits.

Each requested collection appears under included:

{
  "included": {
    "boms": {
      "items": [],
      "nextCursor": null,
      "totalItems": 0,
      "url": "/api/public/v1/brands/acme/boms?productId=00000000-0000-4000-8000-000000000001&limit=100"
    }
  }
}

An empty items with totalItems: 0 means no visible records. An omitted collection was not requested. include=all returns up to 25 records in each of 31 collections by default. Add includeLimit=100 to retrieve up to 100 records per collection, with the same relationship-query credit cost. The API runs relationship reads in batches of at most 3. A non-null nextCursor means that collection has more records. Keep the parameters in its url and add cursor to continue. See the productGraph() helper to retrieve every page with one client call. includeLimit requires include; invalid values return 400.

Preserve versions and relationships

BOMs and measurement tables carry productVersionId. BOM component instances carry bomId; their componentId and componentVariantId point to the materials library. Keep these IDs when constructing your local graph: several versions can contain different BOMs or measurements for the same product.

Version technicalSpecs, packagingSpecs, labelingSpecs, and sizeSpecs, BOM construction annotations, and measurement table JSON retain their nested content. Historical versions remain accessible. Reading a product without a version does not create one.

Product Options expose their own scalar fields. Their values, dimensions, prices, collections, and SKU assignments have independent paginated endpoints. The expansion includes both assignments and referenced library records.

In the compatibility variants array, color uses the SKU’s legacy color name, or its Product Option name when no legacy color is available. It is null when neither label exists.

The images include covers attachments on the Parent Product, Product Options, SKUs, versions, measurement tables, Samples, Sample Rounds, BOM components, and Materials referenced by its BOMs. Historical versions and archived entities remain included. Soft-deleted parents and Materials are excluded. Each image appears once, even when several BOM lines reference its Material. Follow the page’s url and nextCursor to retrieve the remaining images. Use /images/{id}/content for a signed download URL.

The documents include returns Parent Product files. For files attached to a Product Option, version, SKU or Sample, query /documents with the corresponding subjectKind and subjectKey; see Entity relationships.