Brands API: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. This can be a helpful jumping off point as you plan your implementation.

Create a product with a new brand

To create a product and assign a new brand with a single API call: Call Create Product and pass a new product.brand.name to the product.brand field.

Note: if you pass the brand.name of a brand you've already created, that brand will be assigned to the product.

Assign an existing brand to a product

The Brands API allows you to create, update, and manage multiple brands. You can then use and reuse these brands and assign them across multiple products.

To create and assign a brand to a product:

1. Call Create Brand.
2. Save the brand.id or brand.name from your newly created brand.
3. Call Create Product or Update Product, and pass either the brand.id or the brand.name to the product.brand field.

Consolidate two brands

This flow explains how to merge brand A into brand B. This process involves moving every product currently assigned to A onto B, then deleting A, so that no products are left with a dangling brand reference:

1. Call Search Products with a filter on brand.id equal to brand A's id to list every product currently assigned to brand A. Page through all results.
2. For each affected product, call Update Product (or Bulk Update Products for higher throughput) with product.brand.id set to brand B's id. Specify the product's current revision in the request.
3. For each updated product, call Get Product and confirm product.brand.id equals brand B's id. Use Get Product for this readback, not Search Products or ASSIGNED_PRODUCTS_COUNT on Query Brands — both are driven by the products search index and lag Update Product writes. Only Get Product is strongly consistent.
4. Once every readback confirms the new assignment, call Delete Brand on brand A.

Clean up brands with no assigned products

This flow explains how to delete every brand that no product currently references. For example, after a bulk reassignment or import. To do so:

1. Page through every product with Query Products or Search Products and collect every non-empty product.brand.id into a set of brand IDs that are still in use.
2. Page through every brand with Query Brands.
3. For each brand whose id isn't in the in-use set, call Delete Brand.

Don't gate this cleanup on ASSIGNED_PRODUCTS_COUNT from Query Brands immediately after a reassignment. The count is computed from the products search index and lags Update Product writes by a small but nonzero interval, so a brand that just received products may still show 0 and get incorrectly deleted. Collecting brand IDs directly from product records (step 1) reads from the product store and isn't affected by the lag.