Product Bus and Product Detail Page Delivery

The product bus facility allows you easily manage product information in an easy to use API using JSON inspired by https://schema.org/Product

The API consists of a simple PUT with a single product as the payload and a bulk API that allows the update of a batch of products.

The Product Bus also produces Indexes and feeds for sitemap.xml or Google Merchant Center.

The Product Detail Page (PDP) Delivery dynamically creates standard markup, including JSON-LD schema.org information ready to be decorated with regular block developers. Changes that are made to product data, are immediately reflected on the PDP without going through a preview and publish lifecycle.

API

One component of the product bus is the API.

The most common use case for the product bus API is inserting one or more products. To use ingestion APIs, you’ll need a `sitekey` which is provided to the API as a bearer authorization token. Each sitekey allows access to an org/site pair. It can be used to ingest (and fetch) data from any store and view within that org/site. In Edge Delivery terms, org/site is treated the same as owner/repo.

To get a sitekey, reach out to us on Slack.

A simple example

curl -sS -X PUT \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  "https://api.adobecommerce.live/$ORG/$SITE/catalog/$STORE/$VIEW/products/test-sku.json" \
  --data-binary @- <<'JSON'
{
  "sku": "test-sku",
  "name": "Test Product",
  "urlKey": "test-product",
  "url": "https://www.example.com/products/test-product"
}

There are many more options, including the ability to include custom data not conforming to the expected schema. All data provided in the product entry will be served on GETs to the product-bus pipeline. The location where it appears (JSON-LD, HTML head meta, HTML body) will depend on the property.

A more complete example

curl -sS -X PUT \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  "https://api.adobecommerce.live/$ORG/$SITE/catalog/$STORE/$VIEW/products/sku-123.json" \
  --data-binary @- <<'JSON'
{
  "sku": "sku-123",
  "urlKey": "product-url-key",
  "description": "Long product description...",
  "name": "Product Name",
  "metaTitle": "Product Name | Brand",
  "metaDescription": "Short SEO description...",
  "gtin": "0123456789012",
  "url": "https://www.example.com/products/product-url-key",
  "brand": "ExampleBrand",
  "availability": "InStock",
  "price": {
    "currency": "USD",
    "regular": "129.99",
    "final": "99.99"
  },
  "itemCondition": "NewCondition",
  "metadata": {
    "color": "black",
    "size": "M"
  },
  "options": [
    {
      "id": "finish",
      "label": "Finish",
      "position": 1,
      "values": [
        { "value": "Matte" },
        { "value": "Glossy" }
      ]
    }
  ],
  "aggregateRating": {
    "ratingValue": "4.3",
    "reviewCount": "12",
    "bestRating": "5",
    "worstRating": "1"
  },
  "specifications": "<ul><li>Spec A</li><li>Spec B</li></ul>",
  "images": [
    {
      "url": "https://cdn.example.com/images/sku-123/main.jpg",
      "label": "main",
      "roles": ["small", "thumbnail"],
      "video": "https://cdn.example.com/videos/sku-123/overview.mp4"
    }
  ],
  "variants": [
    {
      "sku": "sku-123-RED",
      "name": "Product Name - Red",
      "price": {
        "currency": "USD",
        "regular": "129.99",
        "final": "99.99"
      },
      "url": "https://www.example.com/products/product-url-key?color=red",
      "images": [
        { "url": "https://cdn.example.com/images/sku-123/red.jpg", "label": "red" }
      ],
      "gtin": "0123456789013",
      "description": "Red variant description",
      "availability": "InStock",
      "options": [ { "value": "Red", "id": "color", "uid": "opt-1" } ],
      "itemCondition": "NewCondition",
      "custom": { "material": "aluminum" }
    }
  ],
  "jsonld": "{\n  \"@context\": \"https://schema.org\",\n  \"@type\": \"Product\",\n  \"name\": \"Product Name\"\n}",
  "custom": {
    "warranty": "2 years",
    "countryOfOrigin": "USA"
  }
}

Note that all the properties expect strings as the type, this is to ensure consistency for the renderer/clients. For more details on the schema specifics, check out the README or TypeScript types.

A bulk example

We also provide an API for bulk updates, using a POST with an array of products as the body.

curl -sS -X POST \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  "https://api.adobecommerce.live/$ORG/$SITE/catalog/$STORE/$VIEW/products/*" \
  --data-binary @- <<'JSON'
[
  {
    "sku": "bulk-001",
    "name": "Bulk Product 1",
    "urlKey": "bulk-product-1",
    "url": "https://www.example.com/products/bulk-product-1"
  },
  {
    "sku": "bulk-002",
    "name": "Bulk Product 2",
    "urlKey": "bulk-product-2",
    "url": "https://www.example.com/products/bulk-product-2"
  }
]

Note that the limit for the number of products allowed in a single POST is subject to change. If you send too many (or an invalid product), the API will respond with 400 and a body including `errors` explaining the issues.

If many images are provided in a single POST, we may also process the images asynchronously. The product in product bus will point to the URLs provided in the POST until that processing completes, at which point the URLs will be relative paths, like `./media_xyz.png`.

For more details, check out the API README.

Rendering

Another component of the product bus is the product pipeline, which renders markup including JSON-LD from product data. If you’re familiar with Edge Delivery Services, this functions similarly to the helix-pipeline. Direct access to the pipeline endpoints is not usually required.

Delivery

A service related to the product bus is the Helix Mixer, which provides CDN routing through a declarative configuration in Edge Delivery Services’ site config. Note that this is an experimental technology and configurations not applied by the AEM engineering team may break at any time.