• PXM Products/
    PXM Bundles/
    PXM Bundles API/
    Create a Bundle

    Create a Bundle

    POST Create a Bundle

    https://api.moltin.com/pcm/products
    

    Creates a product bundle. A bundle is a purchasable product that is composed of a combination of two or more products that you want to sell together. You can create multiple components within a bundle. Each component can have one or more options. Each option is a product and a quantity.

    Dynamic Bundles

    You can configure minimum and/or maximum values for each product option in a component that your shoppers can select. For example, you can enable a shopper to select 1 or more product options from a list of 10, giving your shoppers greater flexibility when selecting products in your store front. These are called dynamic bundles.

    If you do not specify any minimum or maximum values for the product options in your components, your shoppers can select any number of product options.

    Your shoppers cannot modify the quantities of a product. They must purchase the quantity of products that you have specified when you created your components and options.

    Bundles of Bundles

    Your bundle can consist of child bundles. This is useful if you have a base product that comprises of child products and the pricing of the base product changes, depending on the child products a customer chooses. This can be represented by creating a parent bundle that comprises of child bundles. To create a bundle of bundles, add a child bundle as an option to a component in a parent bundle.

    • You cannot have more than one level of child bundles. In other words, a child bundle cannot have a child bundle as a component.
    • A parent bundle can contain both bundle and product components.
    • Both parent and child bundles can be either fixed or dynamic in a bundle of bundles.

    Bundle Configuration

    You must configure:

    • A component key: The component key is a unique identifier that is used to identify a component. In the following example, games is a component key. See components object.
    • A component name: The component name is the name that is displayed in your storefront. In the following example, GamesOptions is a component name. See options object.

    Bundles have a bundle_configuration which describe the options selected. You can use Get a product in a catalog release to check a bundle_configuration. The bundle_configuration forms the body of a request when using the configure a shopper bundle endpoint. This endpoint allows your shoppers to select product options within a bundle. The response from the configure a shopper bundle endpoint updates the bundle_configuration with the product options a shopper selects. In your storefront, you can display this as a summary of the product options a shopper has selected.

    For example, you may have the following components and product options.

    "components": {
                    "games": {
                        "name": "GamesOptions",
                        "max": 1,
                        "min": 1,
                        "options": [
                            {
                                "id": "d7b79eb8-19d8-45ea-86ed-2324a604dd9c",
                                "quantity": 1,
                                "type": "product",
                                "sort_order": 1
                            },
                            {
                                "id": "baaebdd6-490e-4834-a4a5-307602f70ea0",
                                "quantity": 2,
                                "type": "product",
                                "sort_order": 12
                            }
                        ]
                    },
                    "toys": {
                        "name": "ToysOptions",
                        "max": 2,
                        "min": 2,
                        "sort_order": 1,
                        "options": [
                            {
                                "id": "1aea6f97-f0d9-452c-b3c1-7fb5629ead82",
                                "quantity": 1,
                                "type": "product",
                                "sort_order": 3
                            },
                            {
                                "id": "0192ccdd-6d33-4898-87d7-c4d87f2bf8ea",
                                "quantity": 1,
                                "type": "product",
                                "sort_order": 2
                            },
                            {
                                "id": "de691397-2320-48fb-af7b-8b17d27a34a4",
                                "quantity": 1,
                                "type": "product",
                                "sort_order": 1
                            }
                        ]
                    }
              }
    

    In this example, a shopper can select product options from the games and toys components.

    • In the games component, either product option 1 or 2.
    • In the toys component, 2 product options from a list of 3.

    This is shown in the bundle_configuration.

    "bundle_configuration": {
                    "selected_options": {
                        "games": {
                            "d7b79eb8-19d8-45ea-86ed-2324a604dd9c": 1
                        },
                        "toys": {
                            "0192ccdd-6d33-4898-87d7-c4d87f2bf8ea": 1,
                            "1aea6f97-f0d9-452c-b3c1-7fb5629ead82": 1
                        }
                    }
             }
    

    The sort_order Attribute

    You can add a sort_order to the body of your request and specify a sort_order value. A sort_order value must be a number. You can specify any numbers that you want. For example, 1, 2, 3, or 100, 90, 80, and so on.

    The sort order value is visible when you add the products to your catalogs. You can then use the sort_order value to program your storefront to display the bundle components and component options in the order that you want.

    The create a bundle endpoint does not sort components and component options. You must program your storefront to sort the components and component options in the order that you want.

    Parameters

    Headers

    NameRequiredTypeDescription
    AuthorizationRequiredstringThe Bearer token required to get access to the API.

    Body

    NameRequiredTypeDescription
    typeRequiredstringSpecifies the type of resource. You must use product.
    attributes.nameRequiredstringSpecifies the product name to display to customers.
    attributes.commodity_typeRequiredstringSpecifies the type of commodity, such as physical or digital.
    attributes.skuOptionalstringSpecifies the unique SKU of the product.
    attributes.slugOptionalstringSpecifies a label for the product that is used in the URL paths. A slug can contain any combination of letters, numbers, periods, hyphens, and underscores. No spaces or other characters are allowed. By default, product name is used as the slug.
    attributes.descriptionOptionalstringSpecifies the product description to display to customers.
    attributes.mpnOptionalstringSpecifies MPN of the product.
    attributes.statusOptionalstringSpecifies the status of the bundle, such as draft or live. The default status is draft.
    attributes.upc_eanOptionalstringSpecifies the UPC or EAN used to scan a product in a Point Of Sale (POS) system.
    attributes.localesOptionalobjectSpecifies the product details localized in the supported languages. For example, product names or descriptions. See locales object.
    attributes.componentsRequiredobjectSpecifies the categories of the products included in the bundle. See components object.
    attributes.optionsRequiredobjectSpecifies the product options that comprise a component. This can be the bundle ID of another bundle. See Bundles of Bundles. You cannot have more than 1500 options in a bundle. See options object.
    custom_inputsOptionalobjectThe custom text that can be added to a product. See Personalized EP PXM Products.

    In the following example, the name of the bundle is Favourite games bundle and this bundle consists of products from the components Consoles and Games. Each component consists of a product from that component with details, such as the product name, product id, and quantity.

    Request Examples

    SKU-based bundles

    curl -X POST https://api.moltin.com/pcm/products \
         -H "Authorization: Bearer XXXX" \
         -H "Content-Type: application/json" \
         -d $'{
      "data": {
        "type": "product",
        "attributes": {
          "name": "Favourite games bundle",
          "description": "All of your favourite DOOM games in one bundle",
          "sku": "doom-franchise",
          "mpn": "1234-5678-ABCD",
          "upc_ean": "123456",
          "commodity_type": "digital",
          "status": "live",
          "components": {
            "games": {
                "name": "Game 1",
                "max": 1,
                "min": 1,
                "sort_order": 5,
                "options": [
                  {
                    "id": "7c0aa6df-0bd3-4d1f-b6f9-fd9358868869",
                    "type": "product",
                    "quantity": 1
                  }
               ]
            },
            "posters": {
               "name": "Game 2",
                "max": 1,
                "min": 1,
                "sort_order": 4,
                "options": [
                  {
                     "id": "f0ec8088-13e1-4a53-8b5d-3f4d973e05c9",
                     "type": "product",
                     "quantity": 1
                  }
                ]
             }
          }
        }
      }
    }'
    

    SKU-less bundles

    curl -X POST https://api.moltin.com/pcm/products \
         -H "Authorization: Bearer XXXX" \
         -H "Content-Type: application/json" \
         -d $'{
      "data": {
        "type": "product",
        "attributes": {
          "name": "Shower bundle",
          "description": "A bundle of shower products",
          "commodity_type": "physical",
          "status": "live",
          "components": {
            "shampoo": {
                "name": "Shampoo",
                "max": 1,
                "min": 1,
                 "sort_order": 1,
              "options": [
                {
                  "id": "shampooProductID",
                  "type": "product",
                  "quantity": 1
                }
              ]
            },
            "conditioner": {
                "name": "Conditioner",
                "max": 1,
                "min": 1,
                "sort_order": 2,
              "options": [
                {
                  "id": "conditionerProductID",
                  "type": "product",
                  "quantity": 1
                }
              ]
            }
          }
        }
      }
    }'
    

    Response example

    201 Created

    {
        "data": {
            "type": "product",
            "id": "cc0a5d66-59cb-4a50-930b-9d1d42fc51b9",
            "attributes": {
                "commodity_type": "digital",
                "components": {
                    "games": {
                        "name": "Game 1",
                        "options": [
                            {
                                "id": "7c0aa6df-0bd3-4d1f-b6f9-fd9358868869",
                                "type": "product",
                                "quantity": 1
                            }
                        ],
                        "min": 1,
                        "max": 2,
                        "sort_order": 2,
                    },
                    "posters": {
                        "name": "Game 2",
                        "options": [
                            {
                                "id": "f0ec8088-13e1-4a53-8b5d-3f4d973e05c9",
                                "type": "product",
                                "quantity": 1
                            }
                        ],
                        "min": 1,
                        "max": 1,
                        "sort_order": 1,
                    }
                },
                "description": "All of your favourite DOOM games in one bundle",
                "mpn": "1234-5678-ABCD",
                "name": "Favourite games bundle",
                "sku": "doom-franchise",
                "status": "live",
                "upc_ean": "123456"
            },
            "relationships": {
                "children": {
                    "data": [],
                    "links": {
                        "self": "/products/cc0a5d66-59cb-4a50-930b-9d1d42fc51b9/children"
                    }
                },
                "component_products": {
                    "data": [],
                    "links": {
                        "self": "/products/cc0a5d66-59cb-4a50-930b-9d1d42fc51b9/relationships/component_products"
                    }
                },
                "files": {
                    "data": [],
                    "links": {
                        "self": "/products/cc0a5d66-59cb-4a50-930b-9d1d42fc51b9/relationships/files"
                    }
                },
                "main_image": {
                    "data": null
                },
                "templates": {
                    "data": [],
                    "links": {
                        "self": "/products/cc0a5d66-59cb-4a50-930b-9d1d42fc51b9/relationships/templates"
                    }
                },
                "variations": {
                    "data": [],
                    "links": {
                        "self": "/products/cc0a5d66-59cb-4a50-930b-9d1d42fc51b9/relationships/variations"
                    }
                }
            },
            "meta": {
                "created_at": "2022-02-03T19:11:25.307Z",
                "owner": "store",
                "updated_at": "2022-02-03T19:11:25.307Z"
            }
        }
    }
    

    Was this helpful?

    Previous
    Get Bundle Component Products Relationships