You are here:
Set Up Product Bundle Data Feed for Point of Sale
Upload bundle details to the CMS with the Product Bundle feed, an NDJSON file that defines each bundle's price, contents, and images.
Before you begin, confirm that every variant group referenced in the feed already exists in the product catalog under the same merchant, locale, and region. A feed line with a non-blank variantGroupId passes initial validation even if that variant group doesn't exist. A typo in this field won't surface until associates see the bundle behave incorrectly in the app.
The Product Bundle feed is a newline-delimited JSON (NDJSON) file. Each line is one complete JSON object that defines a single bundle — its price, product class, tax class, and the variant groups it includes. Each feed run fully refreshes the bundles that the feed manages for a merchant, locale, and region. If you leave a bundle out of a run, the feed removes it from the feed-managed set. The feed doesn't touch bundles you manage separately in CMS.
-
Build the feed file with one JSON object per line, using the field names and casing in the schema reference.
Use the .ndjson file extension and UTF-8 encoding, and don't include a header row. You can include blank lines. The feed skips them during processing. Send only the fields the schema defines. Don't include other properties. See Product Bundle Feed Object Schema.
- In CMS, go to . Expand Products and turn on Enable Product Bundles V2.
-
Set the feed source's file type to NDJSON. Upload the feed manually, or schedule it to run automatically.
A scheduled run can include multiple files. Together, the files in that run form one complete refresh, and the feed processes them in sequence.
The feed validates each bundle line independently. It logs a rejected line but keeps processing the rest of the file. Check the log for MISSING_ID (a missing or blank bundleId) or INVALID_ENTRY (most other validation failures, including malformed JSON on that line). Fix the source file before you resubmit it. If the feed rejects every bundle in a run, or the file is empty, it doesn't replace the existing bundle set.
After the feed finishes processing, confirm that the bundles appear with the correct ID, description, and variant groups.
Point of Sale Product Bundle Feed Object Schema
Field definitions, filtering rules, and JSON examples for the Product Bundle feed's bundle object. Each non-blank line in the feed contains one JSON object with these top-level fields.
| Field | Required | Description |
|---|---|---|
| bundleId | Yes | Unique, non-blank identifier for the bundle within the merchant, locale, and region. Up to 128 characters. |
| bundlePrice | Yes | Regular bundle price, as a decimal number in the merchant's configured currency. Enter only the numeric amount, up to 10 total digits with no more than 2 decimal places. |
| productClass | Yes | Merchant-defined product class for the bundle, such as FURNITURE or APPAREL. Non-blank, up to 64 characters. |
| taxClass | Yes | Merchant-defined tax class for the bundle, such as STANDARD or EXEMPT. Non-blank, up to 64 characters. If the products in a bundle belong to different tax classes, set the tax class you want at the bundle level. The feed doesn't calculate tax from individual child products. |
| bundledProductVariants | Yes | Non-empty ordered array of the variant groups the bundle includes. Array order sets the component order associates see. See the variant group fields next. |
| title | No | Bundle title that appears in the POS app. Up to 128 characters. |
| description | No | Bundle description that appears in the POS app. |
| imageUrl | No | URL of the image that represents the bundle. Up to 256 characters. |
| isActive | No | Whether the bundle is available for use. If you omit this field, it defaults to true. |
| scanCode | No | Code that an associate scans or enters to look up the bundle. Up to 64 characters. It can match bundleId, or use a different value. |
| bundleSalePrice | No | Sale price, as a decimal number, up to 10 total digits with no more than 2 decimal places. When this value is greater than zero, it becomes the effective bundle price instead of bundlePrice. The feed doesn't compare the two prices, so send a sale price lower than the regular price. |
Variant group fields
Each object in bundledProductVariants defines one component slot in the bundle.
| Field | Required | Description |
|---|---|---|
| variantGroupId | Yes | Identifier of an existing product variant group. Must match the VariantGroupID value that the product catalog exposes. Non-blank. |
| quantity | No | Number of units this component slot includes. Defaults to 1. The feed rejects a value less than 1. |
| filter | No | Filters that limit which products in the variant group are eligible for this component. Omit it, or send null or an empty array, for no filter. |
Filtering products within a variant group
Each object in a filter array has two parts: a fieldName (the product attribute to filter, case-sensitive) and a non-empty fieldValues array (the values it accepts). Always send fieldValues as an array, even for a single value.
- All filter objects for one component must match (AND behavior). Any value within one fieldValues array can match (OR behavior).
- The same fieldName can't appear more than once for the same component.
- Filter order isn't significant.
- Filter values can't contain ;, =, ,, or |.
- A product matches a filter only when it has the attribute the filter requests.
Supported fieldName values:
- Core product attributes: MerchantCategory, Brand, Color, Size, Material, Pattern, Gender, AgeGroup, ProductClass, ProductType, Manufacturer
- Catalog and inventory state: IsOnSale, Availability, ProductCondition
- Custom attributes: CustomString0 through CustomString12, CustomInt0, CustomInt1
- Product identity: lowercase id (the merchant product ID or SKU) and uppercase GTIN (the product barcode)
A fieldName outside this list causes the feed to reject the entire bundle line.
This example includes every optional field and filters two of the bundle's components—one by color and size, the other by material.
{"bundleId":"BND-002","title":"Weekend Layer Set","description":"Two-piece layering set with a shirt and cardigan.","imageUrl":"https://cdn.example.com/bundles/BND-002.jpg","isActive":true,"scanCode":"BND-002","bundlePrice":249.00,"bundleSalePrice":199.00,"productClass":"APPAREL","taxClass":"STANDARD","bundledProductVariants":[{"variantGroupId":"VG-2001","quantity":1,"filter":[{"fieldName":"Color","fieldValues":["Blue","Navy"]},{"fieldName":"Size","fieldValues":["M"]}]},{"variantGroupId":"VG-2002","quantity":1,"filter":[{"fieldName":"Material","fieldValues":["Wool"]}]}]}A minimal bundle needs only the required fields, plus one variant group:
{"bundleId":"BND-MIN-001","bundlePrice":49.99,"productClass":"ACCESSORY","taxClass":"STANDARD","bundledProductVariants":[{"variantGroupId":"VG-5001"}]}