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 to learn how to obtain one.
Seller ID: Use the GET /sellers endpoint to find it.
Existing articles: Create the articles that you want to include in bundles. See the Create Products guide if you have not created articles yet.

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.

Create a bundle

Create a bundle using the POST /bundles/{sellerId} endpoint. 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:

Request
Response

Use this request to create a new bundle:

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"
    }
  }'

A successful request returns a 200 OK status code with a BundleGetDetail object:

{
  "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.

The following table describes the key fields you can include when creating a bundle. For complete field definitions, see the API Reference:

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. 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.

Request
Response

Use this request to search for bundles using query parameters:

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>"

A successful request returns a 200 OK status code with an array of BundleGetSummary objects:

[
  {
    "id": <BUNDLE_ID>,
    "sellerId": <YOUR_SELLER_ID>,
    "sku": "<BUNDLE_SKU>",
    "name": {
      "value": "<BUNDLE_NAME>",
      "language": "EN"
    }
  }
]

Retrieve bundle details

Retrieve bundle details using the bundle ID. Use the GET /bundles/{sellerId}/{bundleId} endpoint to get details by bundle ID:

Request
Response

Use this request to retrieve the full details of a bundle by its ID:

curl -X GET "${BASE_URL}/bundles/<YOUR_SELLER_ID>/<BUNDLE_ID>" \
  -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
  -H "Authorization: <YOUR_SESSION_TOKEN>"

A successful request returns a 200 OK status code with the full bundle details as a BundleGetDetail object, including all bundle items and metadata.

Update a bundle

Update an existing bundle using the PUT /bundles/{sellerId}/{bundleId} endpoint. 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:

Request
Response

Use this request to update an existing bundle:

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"
    }
  }'

A successful request returns a 200 OK status code with a BundleGetDetail object:

{
  "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>"
}

Delete a bundle

Delete a bundle using the DELETE /bundles/{sellerId}/{bundleId} endpoint:

Request
Response

Use this request to delete a bundle:

curl -X DELETE "${BASE_URL}/bundles/<YOUR_SELLER_ID>/<BUNDLE_ID>" \
  -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
  -H "Authorization: <YOUR_SESSION_TOKEN>"

A successful deletion returns a 200 OK status code with a BundleGetDetail object.

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:

Request
Response

Use this request to create an order that includes a bundle:

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
      }
    ]
  }'

A successful request returns a 200 OK status code with an OrderPostResult object:

{
  "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.

For complete details on creating orders, see the Create a Fulfillment Order guide.

Where to go next

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

Create Products

Learn how to create articles that you can include in bundles.

Create a Fulfillment Order

Learn how to create orders and use bundles in fulfillment requests.

Introduction

Quickstart

Quivo Flows

Webhooks

Manage Product Bundles

Prerequisites

Create a bundle

Search bundles

Retrieve bundle details

Update a bundle

Delete a bundle

Use bundles in orders

Where to go next

Create Products

Create a Fulfillment Order

Introduction

Quickstart

Quivo Flows

Webhooks

​Prerequisites

​Create a bundle

​Search bundles

​Retrieve bundle details

​Update a bundle

​Delete a bundle

​Use bundles in orders

​Where to go next

Create Products

Create a Fulfillment Order

Prerequisites

Create a bundle

Search bundles

Retrieve bundle details

Update a bundle

Delete a bundle

Use bundles in orders

Where to go next