> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.quivo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Product Bundles

A bundle is a product definition that groups multiple articles together into a single offering. Each bundle has its own SKU (stock keeping unit) that you can use in orders. When you use a bundle SKU in an order, the system processes the bundle during the fulfillment process.

Bundles enable you to:

* Sell sets of products together as a single item
* Manage complex product combinations

A bundle contains:

* A unique SKU that identifies the bundle
* A list of bundle items, where each item references an article and specifies a quantity
* Optional metadata such as name, weight, and customs value

This guide shows you how to create product bundles and use bundles in fulfillment orders.

## Prerequisites

Before you start, make sure you have:

* **Session token:** A valid session token. See the [Authentication guide](/api-reference/authentication) to learn how to obtain one.
* **Seller ID:** Use the [`GET /sellers endpoint`](/api-reference/#tag/sellers) to find it.
* **Existing articles:** Create the articles that you want to include in bundles. See the [Create Products guide](/docs/quivo-guides/create-products) if you have not created articles yet.

<Note>
  All API examples in this guide use `${BASE_URL}` as a placeholder. Replace it with the correct base URL configured for the correct environment. For more information see [Environments page](/api-reference/environments).
</Note>

## Create a bundle

Create a bundle using the [`POST /bundles/{sellerId} endpoint`](/api-reference/#tag/bundles). You must provide a SKU, and you can optionally include bundle items and other metadata. Use `articleId` values that reference articles in your catalog.

The following example shows how to create a bundle with bundle items:

<Tabs>
  <Tab title="Request">
    Use this request to create a new bundle:

    ```bash theme={null}
    curl -X POST "${BASE_URL}/bundles/<YOUR_SELLER_ID>" \
      -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
      -H "Authorization: <YOUR_SESSION_TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
        "sku": "<BUNDLE_SKU>",
        "name": {
          "value": "<BUNDLE_NAME>",
          "language": "EN"
        },
        "bundleItems": [
          {
            "articleId": <ARTICLE_ID_1>,
            "quantity": 2
          },
          {
            "articleId": <ARTICLE_ID_2>,
            "quantity": 1
          }
        ],
        "grossWeight": {
          "value": 1.5,
          "unit": "KG"
        },
        "customsValue": {
          "value": 29.99,
          "currencyCode": "EUR"
        }
      }'
    ```
  </Tab>

  <Tab title="Response">
    A successful request returns a `200 OK` status code with a `BundleGetDetail` object:

    ```json theme={null}
    {
      "id": <BUNDLE_ID>,
      "sellerId": <YOUR_SELLER_ID>,
      "sku": "<BUNDLE_SKU>",
      "name": {
        "value": "<BUNDLE_NAME>",
        "language": "EN"
      },
      "bundleItems": [
        {
          "id": <BUNDLE_ITEM_ID_1>,
          "articleId": <ARTICLE_ID_1>,
          "articleSku": "<ARTICLE_SKU_1>",
          "quantity": 2
        },
        {
          "id": <BUNDLE_ITEM_ID_2>,
          "articleId": <ARTICLE_ID_2>,
          "articleSku": "<ARTICLE_SKU_2>",
          "quantity": 1
        }
      ],
      "grossWeight": {
        "value": 1.5,
        "unit": "KG"
      },
      "customsValue": {
        "value": 29.99,
        "currencyCode": "EUR"
      },
      "created": "<YYYY-MM-DDTHH:mm:ssZ>",
      "lastModified": "<YYYY-MM-DDTHH:mm:ssZ>"
    }
    ```

    Save the `id` from the response. You need this ID to retrieve, update, or delete the bundle later. Timestamps use the ISO 8601 format YYYY-MM-DDTHH:mm:ssZ.
  </Tab>
</Tabs>

The following table describes the key fields you can include when creating a bundle. For complete field definitions, see the [API Reference](/api-reference/#tag/bundles):

| Field                      | Type                     | Description                                                                                                                                                                  |
| -------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sku`                      | String (1-50 characters) | The SKU that identifies this bundle.                                                                                                                                         |
| `bundleItems`              | Array of objects         | Each item includes `articleId` (integer, required) and `quantity` (integer, minimum 1, required). Optionally includes `articleSku` (string) and `unitCustomsValue` (number). |
| `name`                     | Object                   | Object with `value` (string) and `language` (string).                                                                                                                        |
| `grossWeight`              | Object                   | Object with `value` (number) and `unit` (string).                                                                                                                            |
| `netWeight`                | Object                   | Object with `value` (number) and `unit` (string).                                                                                                                            |
| `customsValue`             | Object                   | Object with `value` (number) and `currencyCode` (string).                                                                                                                    |
| `alternativeSkus`          | Array of strings         | Array of string values.                                                                                                                                                      |
| `alternativeNames`         | Array of objects         | Array of name objects (same structure as `name`).                                                                                                                            |
| `alternativeCustomsValues` | Array of objects         | Array of customs value objects (same structure as `customsValue`).                                                                                                           |

## Search bundles

Search for bundles using the [`GET /bundles endpoint`](/api-reference/#tag/bundles). This endpoint supports query, sorting, and pagination parameters. Use the `query` parameter to filter results, `sort` to order them, and `pageSize` to limit the number of results.

<Tabs>
  <Tab title="Request">
    Use this request to search for bundles using query parameters:

    ```bash theme={null}
    curl -X GET "${BASE_URL}/bundles?query=sku:<BUNDLE_SKU>&sort=created:desc&pageSize=50" \
      -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
      -H "Authorization: <YOUR_SESSION_TOKEN>"
    ```
  </Tab>

  <Tab title="Response">
    A successful request returns a `200 OK` status code with an array of `BundleGetSummary` objects:

    ```json theme={null}
    [
      {
        "id": <BUNDLE_ID>,
        "sellerId": <YOUR_SELLER_ID>,
        "sku": "<BUNDLE_SKU>",
        "name": {
          "value": "<BUNDLE_NAME>",
          "language": "EN"
        }
      }
    ]
    ```
  </Tab>
</Tabs>

## Retrieve bundle details

Retrieve bundle details using the bundle ID. Use the [`GET /bundles/{sellerId}/{bundleId} endpoint`](/api-reference/#tag/bundles) to get details by bundle ID:

<Tabs>
  <Tab title="Request">
    Use this request to retrieve the full details of a bundle by its ID:

    ```bash theme={null}
    curl -X GET "${BASE_URL}/bundles/<YOUR_SELLER_ID>/<BUNDLE_ID>" \
      -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
      -H "Authorization: <YOUR_SESSION_TOKEN>"
    ```
  </Tab>

  <Tab title="Response">
    A successful request returns a `200 OK` status code with the full bundle details as a `BundleGetDetail` object, including all bundle items and metadata.
  </Tab>
</Tabs>

## Update a bundle

Update an existing bundle using the [`PUT /bundles/{sellerId}/{bundleId} endpoint`](/api-reference/#tag/bundles). Send a JSON object with the bundle data you want to update, using the same structure as the `BundlePost` schema used for creating bundles.

The following example shows how to update a bundle:

<Tabs>
  <Tab title="Request">
    Use this request to update an existing bundle:

    ```bash theme={null}
    curl -X PUT "${BASE_URL}/bundles/<YOUR_SELLER_ID>/<BUNDLE_ID>" \
      -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
      -H "Authorization: <YOUR_SESSION_TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
        "sku": "<BUNDLE_SKU>",
        "name": {
          "value": "<BUNDLE_NAME>",
          "language": "EN"
        },
        "bundleItems": [
          {
            "articleId": <ARTICLE_ID_1>,
            "quantity": 2
          },
          {
            "articleId": <ARTICLE_ID_2>,
            "quantity": 1
          }
        ],
        "grossWeight": {
          "value": 1.5,
          "unit": "KG"
        },
        "customsValue": {
          "value": 29.99,
          "currencyCode": "EUR"
        }
      }'
    ```
  </Tab>

  <Tab title="Response">
    A successful request returns a `200 OK` status code with a `BundleGetDetail` object:

    ```json theme={null}
    {
      "id": <BUNDLE_ID>,
      "sellerId": <YOUR_SELLER_ID>,
      "sku": "<BUNDLE_SKU>",
      "name": {
        "value": "<BUNDLE_NAME>",
        "language": "EN"
      },
      "bundleItems": [
        {
          "id": <BUNDLE_ITEM_ID_1>,
          "articleId": <ARTICLE_ID_1>,
          "articleSku": "<ARTICLE_SKU_1>",
          "quantity": 2
        },
        {
          "id": <BUNDLE_ITEM_ID_2>,
          "articleId": <ARTICLE_ID_2>,
          "articleSku": "<ARTICLE_SKU_2>",
          "quantity": 1
        }
      ],
      "grossWeight": {
        "value": 1.5,
        "unit": "KG"
      },
      "customsValue": {
        "value": 29.99,
        "currencyCode": "EUR"
      },
      "created": "<YYYY-MM-DDTHH:mm:ssZ>",
      "lastModified": "<YYYY-MM-DDTHH:mm:ssZ>"
    }
    ```
  </Tab>
</Tabs>

## Delete a bundle

Delete a bundle using the [`DELETE /bundles/{sellerId}/{bundleId} endpoint`](/api-reference/#tag/bundles):

<Tabs>
  <Tab title="Request">
    Use this request to delete a bundle:

    ```bash theme={null}
    curl -X DELETE "${BASE_URL}/bundles/<YOUR_SELLER_ID>/<BUNDLE_ID>" \
      -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
      -H "Authorization: <YOUR_SESSION_TOKEN>"
    ```
  </Tab>

  <Tab title="Response">
    A successful deletion returns a `200 OK` status code with a `BundleGetDetail` object.
  </Tab>
</Tabs>

## Use bundles in orders

To use a bundle in a fulfillment order, include the bundle's SKU in the order position's `sku` field when creating an order. The system processes the bundle during the fulfillment process.

The following example shows how to use a bundle SKU in an order:

<Tabs>
  <Tab title="Request">
    Use this request to create an order that includes a bundle:

    ```bash theme={null}
    curl -X POST "${BASE_URL}/orders" \
      -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
      -H "Authorization: <YOUR_SESSION_TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
        "sellerId": <YOUR_SELLER_ID>,
        "orderIdentifier": "<YOUR_ORDER_IDENTIFIER>",
        "orderReference": "<YOUR_ORDER_REFERENCE>",
        "deliveryAddress": {
          "name": "<RECIPIENT_NAME>",
          "street": "<STREET_ADDRESS>",
          "city": "<CITY>",
          "zip": "<ZIP_CODE>",
          "countryIso2": "<COUNTRY_CODE>"
        },
        "positions": [
          {
            "sku": "<BUNDLE_SKU>",
            "name": "<BUNDLE_NAME>",
            "quantity": 1
          }
        ]
      }'
    ```
  </Tab>

  <Tab title="Response">
    A successful request returns a `200 OK` status code with an `OrderPostResult` object:

    ```json theme={null}
    {
      "status": "OK",
      "message": "Order created successfully",
      "orderId": <YOUR_ORDER_ID>
    }
    ```

    When you retrieve order details, the `FulfillmentOrderPositionSummary` includes a `bundleSku` field. The `sku` field shows the final SKU selected for fulfillment after considering bundles and maps, as described in the API specification.
  </Tab>
</Tabs>

For complete details on creating orders, see the [Create a Fulfillment Order guide](/docs/quickstart/create-order).

## Where to go next

Now that you can manage bundles, continue with these guides:

<CardGroup cols={2}>
  <Card title="Create Products" icon="plus" href="/docs/quivo-guides/create-products">
    Learn how to create articles that you can include in bundles.
  </Card>

  <Card title="Create a Fulfillment Order" icon="shopping-cart" href="/docs/quickstart/create-order">
    Learn how to create orders and use bundles in fulfillment requests.
  </Card>
</CardGroup>