> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/admin/products/bundle-chapters/create-a-bundle-chapter.md).

# Create a bundle chapter

Creates a new chapter under a bundle product.

See the **Validation Rules** in the **Bundle Chapters** section — in particular, `bundle_product` must be a Bundle product, `default_product`, when given, must be a Miscellaneous product, and `attributes` should be sent even when empty.

```json
{"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"tags":[{"name":"Bundle Chapters","description":"Administrative endpoints for **bundle chapters** — the configurable selection slots of a **Bundle** product (`product_type` `2`). Each chapter groups the attribute-set-driven set of choices a customer picks from when configuring the bundle on the storefront. A chapter belongs to exactly one bundle product and can be pre-populated with a default miscellaneous product (`product_type` `4`). See the **Products** section for the shared product-type table.\n\n## Core Capabilities\n\n**1. Chapter Listing & Filtering**\n* Retrieve a paginated list of chapters, ordered by their `order` value unless a different order is requested. `order` is a single global ordering key, not grouped by bundle product — filter by `bundle_product` to see one product's chapters in sequence.\n* Filter by the parent bundle product, or by a partial, case-insensitive match on slug.\n\n**2. Chapter Lifecycle Management**\n* Create a chapter under a bundle product, together with the attribute set and initial attribute values used to render its selection form.\n* Update a chapter's name, slug, position, active state, requirement flags, and default product (see the restrictions below — some fields cannot be changed after creation, and `default_product` can only be set or replaced, not cleared).\n* Permanently delete a chapter. This is a **hard delete** — unlike deactivating a product, the chapter record and its miscellaneous-product associations are removed from the database rather than merely deactivated.\n\n## Validation Rules\n\n* `bundle_product` must reference a product whose `product_type` is **Bundle** (`2`); a reference to a product of a different type (or to a non-existent id) is rejected as an invalid identifier, the same as any other bad foreign key — a standard `400` validation error, not a business-rule error.\n* `default_product`, when provided, must reference a product whose `product_type` is **Miscellaneous** (`4`), rejected the same way (`400`) if it isn't. On create, it is automatically added to the chapter's set of selectable miscellaneous products.\n* The combination of `bundle_product` and `slug` must be unique — a bundle product cannot have two chapters with the same slug. Violating this is also a standard `400` validation error.\n* **`bundle_product` cannot be changed after creation.** It is accepted by the update operations but has no effect — a chapter always keeps the bundle product it was created under, even if a different `bundle_product` is sent and passes validation.\n* **`default_product` can only be set or replaced, never cleared.** Sending `null` has no effect if a default product is already set — there is no way to remove it through these endpoints once set.\n* **The attribute set and the chapter's attribute values can only be set at creation.** `attribute_set`, `attributes`, and `attributes_kwargs` are accepted by the update operations but have no effect on the stored chapter — they cannot be changed once the chapter exists. `attributes_kwargs` has no effect at creation either; it is always derived automatically from `attributes`.\n* `attributes` must be included when creating a chapter (send an empty object if there are no values to set). It is not flagged as a required field, but omitting it causes the request to fail with a server error instead of a normal validation response.\n\n## Dynamic Settings & Environment Variables\n\nNo dynamic settings or environment variables affect these endpoints."}],"servers":[{"description":"Omnitron Remote Proxy (external access — recommended)","url":"https://{omnitron_url}/api/v1/remote/{channel_id}","variables":{"omnitron_url":{"default":"sandbox.akinon.com","description":"Omnitron server URL (e.g., {omnitron.akinon.com})"},"channel_id":{"default":"1","description":"The channel identifier the remote request is routed through"}}},{"description":"Commerce API Server (internal / direct access only)","url":"https://{commerce_url}/api/v1","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Internal commerce server URL, reachable only from within the Omnitron network"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Token credential sent in the Authorization header, in the form: `Token <your-token>`. Requires a staff (admin) account."}},"schemas":{"BundleChapterWriteRequest":{"type":"object","description":"The data used to create a bundle chapter, or to fully update one. On update, `bundle_product`, `attribute_set`, `attributes`, and `attributes_kwargs` are accepted and validated but have no effect — see the **Validation Rules** in the **Bundle Chapters** section.","required":["name","slug","bundle_product","attribute_set"],"properties":{"name":{"type":"string","maxLength":255,"description":"The chapter's display name."},"slug":{"type":"string","maxLength":128,"description":"The chapter's identifier within its bundle product. Must be unique per `bundle_product`."},"bundle_product":{"type":"integer","description":"The identifier of the parent product. Must reference a product whose `product_type` is Bundle (`2`). Only applied at creation — ignored when updating an existing chapter, which cannot be moved to a different bundle product."},"default_product":{"type":["integer","null"],"description":"The identifier of the miscellaneous product to pre-select for this chapter. Must reference a product whose `product_type` is Miscellaneous (`4`). On update, this can be used to set or replace the default product, but not to clear it — sending `null` has no effect if one is already set."},"attribute_set":{"type":"integer","description":"The identifier of the attribute set that defines this chapter's selectable attributes. Only applied at creation."},"order":{"type":"integer","default":0,"description":"The chapter's position among its bundle product's chapters."},"is_active":{"type":"boolean","default":true,"description":"Whether the chapter is active."},"is_required":{"type":"boolean","default":true,"description":"Whether the customer must make a selection for this chapter."},"is_form_required":{"type":"boolean","default":false,"description":"Whether this chapter renders a form requiring additional input, rather than a plain selection."},"attributes":{"type":"object","description":"The attribute values to set on the chapter, keyed by attribute name — applied only when creating a chapter. Not enforced as required by field validation, but creating a chapter without this field causes the request to fail with a server error instead of a normal validation response; send an empty object if there are no values to set. Ignored when updating an existing chapter. Keys that don't match an attribute of the chapter's `attribute_set` are silently ignored.","additionalProperties":true},"attributes_kwargs":{"type":"object","description":"Accepted for symmetry with the response representation, but has no effect — the server derives this value automatically from `attributes` when a chapter is created, and it cannot be set directly on creation or update.","additionalProperties":true}}},"BundleChapter":{"type":"object","description":"A configurable selection chapter of a bundle product.","properties":{"pk":{"type":"integer","description":"The unique identifier of the bundle chapter.","readOnly":true},"name":{"type":"string","maxLength":255,"description":"The chapter's display name."},"slug":{"type":"string","maxLength":128,"description":"The chapter's identifier within its bundle product. Must be unique per `bundle_product`."},"bundle_product":{"type":"integer","description":"The identifier of the parent product. Must reference a product whose `product_type` is Bundle (`2`). Fixed at creation — a chapter's bundle product cannot be changed afterwards."},"default_product":{"type":["integer","null"],"description":"The identifier of the miscellaneous product pre-selected for this chapter, when set. Must reference a product whose `product_type` is Miscellaneous (`4`). Can be set or replaced through an update, but not cleared back to `null` once set."},"attribute_set":{"type":"integer","description":"The identifier of the attribute set that defines this chapter's selectable attributes. Can only be set at creation — sending a different value on update has no effect."},"order":{"type":"integer","default":0,"description":"The chapter's position among its bundle product's chapters. Chapters are listed ordered by this value by default."},"is_active":{"type":"boolean","default":true,"description":"Whether the chapter is active."},"is_required":{"type":"boolean","default":true,"description":"Whether the customer must make a selection for this chapter."},"is_form_required":{"type":"boolean","default":false,"description":"Whether this chapter renders a form requiring additional input, rather than a plain selection."},"attributes":{"type":"object","readOnly":true,"description":"The chapter's attribute values, keyed by attribute name.","additionalProperties":true},"attributes_kwargs":{"type":"object","readOnly":true,"description":"Additional attribute metadata for the chapter.","additionalProperties":true},"attr_key":{"type":"array","readOnly":true,"description":"The attribute definitions relevant to this chapter: when `is_form_required` is `true`, the attributes required by the chapter's form; otherwise, the attribute set's variant-distinguishing attributes.","items":{"$ref":"#/components/schemas/Attribute"}}}},"Attribute":{"type":"object","description":"An attribute definition as returned by the API.","properties":{"pk":{"type":"integer","description":"The unique identifier of the attribute.","readOnly":true},"key":{"type":"string","maxLength":255,"description":"The unique machine key of the attribute. Matches `^[a-zA-Z_][a-zA-Z0-9_-]*$`."},"name":{"type":"string","maxLength":255,"description":"The human-readable, translatable name of the attribute."},"data_type":{"$ref":"#/components/schemas/AttributeDataType"},"default_value":{"type":["integer","null"],"description":"The identifier of the attribute value used as the default, when any."},"is_required":{"type":"boolean","description":"Whether the attribute must have a value on the product."},"is_visible":{"type":"boolean","description":"Whether the attribute is shown in management and storefront contexts."},"is_searchable":{"type":"boolean","description":"Whether the attribute is indexed for search."},"is_filterable":{"type":"boolean","description":"Whether the attribute can be used as a storefront filter."},"is_variant":{"type":"boolean","description":"Whether the attribute distinguishes variants of a product."},"is_variant_listable":{"type":"boolean","description":"Whether the attribute participates in choosing the listable variant."},"is_form_required":{"type":"boolean","description":"Whether the attribute is required in the product form."},"is_form_field_required":{"type":"boolean","description":"Whether the attribute's form field is required."}}},"AttributeDataType":{"type":"string","description":"The data type of an attribute, controlling how its value is entered and interpreted. See the **Data Types** table under **Attributes**.","enum":["text","email","area","date","datetime","bool","valuelabel","dropdown","multiple","price","nested","image","file","model","bundle"]},"ValidationError":{"type":"object","description":"Returned when the request contains invalid or missing data. Errors are grouped by the field they apply to: each key is the name of a field from the request and its value is a list of one or more messages describing what is wrong with that field. Messages that do not belong to any single field are grouped under `non_field_errors`.","properties":{"non_field_errors":{"type":"array","description":"Error messages that apply to the request as a whole rather than to a specific field.","items":{"type":"string"}}},"additionalProperties":{"type":"array","description":"The list of error messages for the field named by the key.","items":{"type":"string"}}},"Error":{"type":"object","description":"An error response.","properties":{"detail":{"type":"string","description":"A human-readable description of the error."}},"additionalProperties":true}},"responses":{"ValidationError":{"description":"The request contains invalid or missing data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"Unauthorized":{"description":"Authentication credentials were not provided or are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The authenticated user does not have administrator privileges.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/bundle_chapters/":{"post":{"tags":["Bundle Chapters"],"operationId":"createBundleChapter","summary":"Create a bundle chapter","description":"Creates a new chapter under a bundle product.\n\nSee the **Validation Rules** in the **Bundle Chapters** section — in particular, `bundle_product` must be a Bundle product, `default_product`, when given, must be a Miscellaneous product, and `attributes` should be sent even when empty.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BundleChapterWriteRequest"}}}},"responses":{"201":{"description":"The bundle chapter was created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BundleChapter"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://apidocs.akinon.com/commerce-openapis/admin/products/bundle-chapters/create-a-bundle-chapter.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
