How do I assign or change a distribution template on a master SKU via the External API?

Managing distribution template assignments via the External API

Feature availability: The distribution template endpoints are gated by the Run Distribution feature. If your account does not have this feature enabled, these routes return 404. Contact your Luminous account team to enable it.

A distribution template (also called a size-curve template) defines how a total production quantity is split across variant SKUs. You can now manage these assignments on individual master SKUs through the External V1 API.

---

1. See which templates are compatible with a master SKU

GET /external/api/v1/products/{productId}/distribution-template/candidates

Returns all active distribution templates whose variant axes are compatible with the given master SKU. Only master SKUs (with variant axes defined) return results.

Example response:

{
  "data": [
    { "id": 3, "name": "Standard Size Curve", "description": "XS–2XL equal split", "is_default": true },
    { "id": 7, "name": "Tall Size Curve",     "description": "S–XL tall fit",       "is_default": false }
  ]
}

---

2. Assign a template to a product

PUT /external/api/v1/products/{productId}/distribution-template

Request body:

{ "distribution_template_id": 3 }

Example response:

{
  "data": { "id": 3, "name": "Standard Size Curve", "source": "assigned" },
  "message": "Distribution template assigned."
}

If the template is incompatible with the product's variant axes the API returns a 400 with an explanatory message.

---

3. Clear the template assignment

DELETE /external/api/v1/products/{productId}/distribution-template

Removes the directly assigned template. After clearing, the product will fall back to the tenant default template (if one is set) when a production run is resolved.

Example response:

{ "message": "Distribution template cleared." }

---

4. Bulk-assign one template to many products

POST /external/api/v1/distribution-templates/{templateId}/assign

Request body:

{ "sku_ids": [101, 102, 103] }

Example response:

{
  "data": {
    "template_id": 3,
    "template_name": "Standard Size Curve",
    "total": 3,
    "succeeded": 2,
    "failed": 1,
    "results": [
      { "sku_id": 101, "status": "assigned" },
      { "sku_id": 102, "status": "assigned" },
      { "sku_id": 103, "status": "error", "message": "Incompatible variant axes." }
    ]
  }
}

---

5. Reading the assignment on a product record

The product object returned by GET /external/api/v1/products/{productId} (and the list endpoint) now includes a distribution_template field:

{
  "distribution_template": {
    "id": 3,
    "name": "Standard Size Curve",
    "source": "assigned"
  }
}

source is always "assigned" when a template is explicitly set on the product. null means no template is directly assigned (the tenant default may still apply at resolve time).

---

Setting a template via product create or update

You can also pass distribution_template_id directly in a POST /products or PUT /products/{id} body to set the template during create/update:

{ "sku": "SHIRT-MASTER", "distribution_template_id": 3 }