> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orderprotection.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Product Taxonomy (Components & Bundles)
> Map product components and bundle items so customers can file a claim against a single part instead of the whole product.
Product Taxonomy lets you describe the relationships between your products so customers can file a claim against a **single part of a product** (a component) or a **single item within a bundle** -- rather than the entire purchase. You define these relationships by downloading a CSV template, filling in the relationship columns (by hand or with an AI assistant), and re-uploading it.
## Why use Product Taxonomy
By default, a claim is filed against a product as a whole. Taxonomy adds structure so customers can be more specific about what went wrong:
* **Components** -- Parts that make up a single product. For example, a bed frame might have a *headboard*, *side rails*, and *hardware kit* as components. If only the headboard arrives damaged, the customer can file a claim against just that part.
* **Bundles** -- Separate products sold together as a set or kit. For example, a *skincare bundle* might contain a cleanser, toner, and moisturizer. If only the toner leaks in transit, the customer can file a claim against just that item.
Taxonomy can also describe **variants** -- versions of the same product, like sizes or colors. Variants from Shopify sync automatically, so you only need to add variants that your platform doesn't sync.
### Why granular claims matter
When a customer can claim against a single part instead of the entire purchase, both sides of the claim get better outcomes:
* **Faster, more accurate resolutions.** When the customer tells you exactly which part failed, there's no back-and-forth to figure out what's wrong. Your team can approve and fulfill the right replacement immediately.
* **Less waste and fewer unnecessary refunds.** A single failed part no longer forces a full-product refund or a duplicate reshipment of items the customer already has.
* **Better product insight.** Claims tagged to specific components or bundle items show you *which* parts fail most often -- so you can fix a recurring issue at the source (a supplier, a packaging problem, a fragile clasp) instead of just eating the cost.
* **A clearer customer experience.** Customers feel understood when the claim form reflects the real problem. Picking "the clasp broke" is far more intuitive than filing a vague claim against the whole necklace.
In the example above, a customer with a **Sterling Chain Necklace** can pinpoint the **Lobster Clasp** as the part that failed -- rather than claiming the entire necklace -- so you can reship just the clasp.
## Before you start: sync your product catalog
The taxonomy template is built from the product catalog Order Protection has for your store, so your products need to be in the dashboard before you download it. Open the **Products** page. If it shows **No products found**, sync your catalog first:
Ask your Customer Success Manager or your shared Slack channel to turn on the **Product Sync** capability for your store -- an Order Protection admin can turn it on for you. Once your store is live, Product Sync also refreshes your catalog automatically twice a day.
On the **Products** page, click **Sync Products** to pull in your catalog now instead of waiting for the next automatic sync. When the sync finishes, your products appear in the list and the time of the last sync shows next to the button.
**Sync Products** pulls your catalog from Shopify, and you need permission to edit products to see it. If the button doesn't appear after Product Sync is turned on, or your store is on another platform, ask your Customer Success Manager to get your catalog loaded.
## Where to find it
From the dashboard, go to **Settings → Claims**.
Scroll to the **Product Taxonomy** card. Here you'll find the **Download Template** and **Upload Catalog** buttons.
Don't see the **Product Taxonomy** card? It only appears for team members with permission to edit products. If you have that permission and still don't see it, ask your Customer Success Manager to turn on Product Taxonomy for your store.
## How to upload your taxonomy
Click **Download Template** on the Product Taxonomy card. This downloads a `Product Taxonomy.csv` file with a row for every product in your catalog, plus a row for each of its variants, so you have the correct IDs to work from. Any relationships you've uploaded before are already filled in.
Export your full catalog from your ecommerce platform. The template only has each product's name, SKU, price, status, and image. Your platform's export adds the descriptions, product types, tags, and options that show which products are bundles and what they include.
In Shopify, go to **Products → Export**, choose **All products** and **Plain CSV file**, then click **Export products**. Shopify emails you the file.
For each product that is a component, bundle item, or variant, fill in the **`parent_source_product_id`** and **`relationship_type`** columns to point it at its parent product. The fastest way is to [have an AI assistant map them](#map-relationships-with-an-ai-assistant) from both files. You can also edit the template by hand in a spreadsheet. (See [CSV structure](#csv-structure) below.)
Back on the Product Taxonomy card, click **Upload Catalog** and select your edited CSV. You'll see a confirmation summarizing how many relationships were mapped, how many parent products they cover, any new products that were created, and any rows that were skipped.
Product IDs are long numbers. When Excel saves a CSV, it can turn them into scientific notation (like `7.05046E+12`), which breaks them. If you edit the file by hand, use Google Sheets or Numbers -- or don't save it from Excel.
## Map relationships with an AI assistant
Mapping relationships by hand is slow for a big catalog. An AI assistant that can read and create files, such as Claude or ChatGPT, can do the first pass for you from the template and your catalog export. You review what it sends back, then upload it.
Start a new chat and attach your `Product Taxonomy.csv` template and your catalog export.
Paste the [base prompt](#base-prompt), then paste the [goal prompt](#goal-prompts) for what you're setting up -- bundles, components, or variants -- below it. To set up more than one at a time, add each goal prompt you need.
The assistant sends back a CSV file, a summary of the relationships it added, and a list of anything it wasn't sure about. Before you upload, check that:
* Every parent has **all** of its parts or items. The upload replaces each parent's relationships with the ones in the file.
* The IDs match the template exactly.
* Part names read the way a customer would describe them. Customers see these names when they file a claim.
* Everything on the "not sure" list is resolved. Fix it in the file, or ask the assistant to.
Upload the file with **Upload Catalog** on the Product Taxonomy card. Then open the **Products** page and check the **Relationship** column to confirm each parent shows its parts or items.
Setting up bundles and components in separate chats? Download a fresh template before each one. The fresh template includes what you've already uploaded, so the assistant keeps it and your next upload doesn't overwrite it.
Both files contain product information only -- no customer or order data. If your export includes columns you'd rather not share, like **Cost per item**, delete them before you attach the file. For a very large catalog, export and map one product type or collection at a time.
### Base prompt
Start every chat with this prompt. It tells the assistant how the template works and what to send back. Replace anything in \[square brackets] with your own details.
```text theme={null}
I've attached two files:
1. Product Taxonomy.csv: my Order Protection product taxonomy template. Each row is one product or one variant from my catalog.
2. [File name]: my full product catalog export from [Shopify / your platform].
Improve the taxonomy file by mapping how my products relate to each other. Follow these rules exactly.
IDS AND MATCHING
- Treat every value as text. Copy IDs exactly as they appear in the template, with no ".0", no scientific notation, and no added or removed characters.
- Use my catalog export only for context: titles, descriptions, product types, tags, and options. It may not include the template's IDs, so match products to template rows by SKU first, then by exact name.
- Don't guess. If you can't match something with confidence, leave it out and list it for me.
HOW RELATIONSHIPS WORK
- A child row points to its parent: set parent_source_product_id to the parent's source_product_id, and set relationship_type to COMPONENT, BUNDLE, or VARIANT.
- Parent rows and standalone rows leave parent_source_product_id and relationship_type blank.
- Always leave parent_source_variant_id blank.
- One level only: a product can be a parent or a child, never both.
- A row can have only one parent.
- No ID can contain "::".
- Every new row needs a source_product_id that isn't already in the template. The only exception is a VARIANT row, which reuses its product's source_product_id.
- Don't change any other values on rows that already exist in the template.
WHAT TO SEND BACK
1. A downloadable .csv file (not a table in the chat) with exactly the same header row as the template. Include only:
- rows from the template that already have a relationship_type, unchanged unless I ask you to change them, and
- rows you added or changed.
2. A table of every relationship you added: parent name, child name, relationship_type.
3. A list of anything you skipped or weren't sure about, and why.
```
### Goal prompts
Paste the prompt for each thing you're setting up below the base prompt.
```text theme={null}
GOAL: SET UP BUNDLES
A bundle is a single product that's sold as a set of other items, like a kit, gift set, or multi-pack.
1. Map these bundles: [list your bundles, for example: Skincare Bundle, 13-Piece Pan Set]. If I haven't listed any, find likely bundles using titles, product types, tags (like "bundle", "kit", "set", or "pack"), and descriptions that list what's included. Then show me the list and wait for me to confirm.
2. For each bundle, work out which items it includes from its description in my catalog export.
3. If an included item has its own row in the template, set that row's parent_source_product_id to the bundle's source_product_id and its relationship_type to BUNDLE. If the bundle includes one specific size or color of the item, use that variant's row instead.
4. If an included item doesn't have a row in the template, add a new row for it:
- source_product_id: the bundle's source_product_id, a hyphen, then the item's name in capitals with hyphens (for example, 7050531884494-TRAVEL-POUCH)
- source_variant_id: blank
- name: the item's name, the way a customer would say it
- price: 0
- status: ACTIVE
- parent_source_product_id: the bundle's source_product_id
- relationship_type: BUNDLE
5. If an item is in more than one bundle, map it to the first bundle only and list the others for me.
6. Leave each bundle's own row with a blank parent_source_product_id and relationship_type.
```
```text theme={null}
GOAL: SET UP COMPONENTS
A component is one part of a single product that can break or arrive damaged on its own, like a lid, clasp, strap, cushion, or hardware kit.
1. Add these components:
- [Product name]: [part], [part], [part]
- [Product name]: [part], [part]
If I haven't listed any, suggest parts for products whose descriptions mention separate pieces. Then show me the list and wait for me to confirm.
2. For each part, add a new row:
- source_product_id: the product's source_product_id, a hyphen, then the part's name in capitals with hyphens (for example, 7050460138846-LOBSTER-CLASP)
- source_variant_id: blank
- name: the part's name, the way a customer would say it (customers see this name when they file a claim)
- price: 0
- status: ACTIVE
- parent_source_product_id: the product's source_product_id
- relationship_type: COMPONENT
3. If a part is also sold on its own and fits only this one product, link its existing row instead: set its parent_source_product_id to the product's source_product_id and its relationship_type to COMPONENT.
4. Only add parts I've listed or confirmed. Don't invent parts.
```
Shopify variants sync automatically, so Shopify stores usually don't need this prompt. Use it if your platform doesn't sync variants to Order Protection, and only if your catalog export includes variant IDs.
```text theme={null}
GOAL: SET UP VARIANTS
A variant is a version of one product, like a size, color, or material. A variant row uses its product's source_product_id and has its own source_variant_id.
1. Find the products in my catalog export that have variants. [Optional: only map variants for these products: ...]
2. Skip any variant that already has a row in the template with the same source_product_id and source_variant_id.
3. For each remaining variant, add a row:
- source_product_id: the product's source_product_id
- source_variant_id: the variant's ID from my catalog export
- sku: the variant's SKU
- name: the product name and the variant, for example "Adventure Water Bottle Sling - Black"
- price: the variant's price
- status: ACTIVE, ARCHIVED, or DRAFT, matching the variant
- product_image: the variant's image URL, if it has one
- parent_source_product_id: the same source_product_id as the product
- relationship_type: VARIANT
This doesn't break the one-level rule: the variant rows are the children, and the product's own row is the parent.
4. Only add variants for products that already have their own row in the template (the row with a blank source_variant_id).
5. Every VARIANT row needs a real source_variant_id from my catalog export. Never make one up. If a variant has no ID in my export, list it for me instead.
6. Don't add variants for a product that's a component or bundle item in this file. List those products for me instead.
```
### Example prompt script
Here's a complete prompt for a Shopify store that's adding components to a necklace and mapping two bundles. It's the base prompt followed by the Components and Bundles goal prompts, with the details filled in.
```text theme={null}
I've attached two files:
1. Product Taxonomy.csv: my Order Protection product taxonomy template. Each row is one product or one variant from my catalog.
2. products_export_1.csv: my full product catalog export from Shopify.
Improve the taxonomy file by mapping how my products relate to each other. Follow these rules exactly.
IDS AND MATCHING
- Treat every value as text. Copy IDs exactly as they appear in the template, with no ".0", no scientific notation, and no added or removed characters.
- Use my catalog export only for context: titles, descriptions, product types, tags, and options. It may not include the template's IDs, so match products to template rows by SKU first, then by exact name.
- Don't guess. If you can't match something with confidence, leave it out and list it for me.
HOW RELATIONSHIPS WORK
- A child row points to its parent: set parent_source_product_id to the parent's source_product_id, and set relationship_type to COMPONENT, BUNDLE, or VARIANT.
- Parent rows and standalone rows leave parent_source_product_id and relationship_type blank.
- Always leave parent_source_variant_id blank.
- One level only: a product can be a parent or a child, never both.
- A row can have only one parent.
- No ID can contain "::".
- Every new row needs a source_product_id that isn't already in the template. The only exception is a VARIANT row, which reuses its product's source_product_id.
- Don't change any other values on rows that already exist in the template.
WHAT TO SEND BACK
1. A downloadable .csv file (not a table in the chat) with exactly the same header row as the template. Include only:
- rows from the template that already have a relationship_type, unchanged unless I ask you to change them, and
- rows you added or changed.
2. A table of every relationship you added: parent name, child name, relationship_type.
3. A list of anything you skipped or weren't sure about, and why.
GOAL: SET UP COMPONENTS
A component is one part of a single product that can break or arrive damaged on its own, like a lid, clasp, strap, cushion, or hardware kit.
1. Add these components:
- Sterling Chain Necklace: Rope Chain, Lobster Clasp, Pendant
2. For each part, add a new row:
- source_product_id: the product's source_product_id, a hyphen, then the part's name in capitals with hyphens (for example, 7050460138846-LOBSTER-CLASP)
- source_variant_id: blank
- name: the part's name, the way a customer would say it (customers see this name when they file a claim)
- price: 0
- status: ACTIVE
- parent_source_product_id: the product's source_product_id
- relationship_type: COMPONENT
3. If a part is also sold on its own and fits only this one product, link its existing row instead: set its parent_source_product_id to the product's source_product_id and its relationship_type to COMPONENT.
4. Only add parts I've listed or confirmed. Don't invent parts.
GOAL: SET UP BUNDLES
A bundle is a single product that's sold as a set of other items, like a kit, gift set, or multi-pack.
1. Map these bundles: Skincare Bundle, 13-Piece Pan Set.
2. For each bundle, work out which items it includes from its description in my catalog export.
3. If an included item has its own row in the template, set that row's parent_source_product_id to the bundle's source_product_id and its relationship_type to BUNDLE. If the bundle includes one specific size or color of the item, use that variant's row instead.
4. If an included item doesn't have a row in the template, add a new row for it:
- source_product_id: the bundle's source_product_id, a hyphen, then the item's name in capitals with hyphens (for example, 7050531884494-TRAVEL-POUCH)
- source_variant_id: blank
- name: the item's name, the way a customer would say it
- price: 0
- status: ACTIVE
- parent_source_product_id: the bundle's source_product_id
- relationship_type: BUNDLE
5. If an item is in more than one bundle, map it to the first bundle only and list the others for me.
6. Leave each bundle's own row with a blank parent_source_product_id and relationship_type.
```
The assistant sends back a file like the one below, along with its summary and its "not sure" list -- for example, a note that the 13-Piece Pan Set's description doesn't say which pans it includes. The file doesn't need rows for the parent products themselves; they're already in your catalog.
```csv theme={null}
source_product_id,source_variant_id,sku,name,price,status,product_image,parent_source_product_id,parent_source_variant_id,relationship_type
7050460138846-ROPE-CHAIN,,,Rope Chain,0,ACTIVE,,7050460138846,,COMPONENT
7050460138846-LOBSTER-CLASP,,,Lobster Clasp,0,ACTIVE,,7050460138846,,COMPONENT
7050460138846-PENDANT,,,Pendant,0,ACTIVE,,7050460138846,,COMPONENT
7050531900001,,CLN-01,Gentle Cleanser,32.00,ACTIVE,,7050531884494,,BUNDLE
7050531900002,,TNR-01,Hydrating Toner,28.00,ACTIVE,,7050531884494,,BUNDLE
7050531900003,,MST-01,Daily Moisturizer,38.00,ACTIVE,,7050531884494,,BUNDLE
```
## CSV structure
Each row in the CSV represents one product or one variant. A row becomes a **component**, **bundle item**, or **variant** by pointing it at a parent product using the last columns. The template has the columns below, in this order. Don't delete or rename any of them -- the upload needs the `source_product_id`, `parent_source_product_id`, and `relationship_type` columns even when most of their values are blank.
| Column | Required | Description |
| - | - | - |
| `source_product_id` | **Yes** | The unique product ID for this row's product (matches the ID in your store/platform). A product's variant rows share its ID. |
| `source_variant_id` | No | The variant's ID. Blank on a product's own row. |
| `sku` | No | The product's SKU. |
| `name` | For new products | The product's display name. For a new part or bundle item, this is the label customers see when they file a claim. |
| `price` | No | The product's price. Used for new products; defaults to `0`. |
| `status` | No | The product's status: `ACTIVE`, `ARCHIVED`, or `DRAFT`. Used for new products; defaults to `ACTIVE`. |
| `product_image` | No | URL to the product's image. |
| `parent_source_product_id` | Relationship rows | The `source_product_id` of the **parent** product this item rolls up to. Leave blank for a top-level/parent product. |
| `parent_source_variant_id` | No | Leave blank. Relationships should point to the parent product itself, not one of its variants. |
| `relationship_type` | Relationship rows | `COMPONENT`, `BUNDLE`, or `VARIANT`. Must be blank for a top-level/parent product. |
### How rows are interpreted
* **Parent / top-level rows** -- Leave `parent_source_product_id` and `relationship_type` blank. These rows simply describe a product and act as the parent that components, bundle items, or variants attach to.
* **Relationship rows** -- A row with a `relationship_type` **must** also include a valid `parent_source_product_id`. This is what links the child to its parent:
* `COMPONENT` -- The row is a part of the parent product.
* `BUNDLE` -- The row is an item included in the parent bundle.
* `VARIANT` -- The row is a version of the parent product, like a size or color. Use the product's own ID as both the `source_product_id` and the `parent_source_product_id`, and fill in the variant's `source_variant_id`.
* **Variant rows** -- Rows that share a `source_product_id` and have a `source_variant_id` are that product's variants. To make one specific variant a component or bundle item (say, only the 8 oz size of a toner), put the relationship on that variant's row.
If a `source_product_id` in your CSV isn't in your catalog yet -- like a part that isn't sold on its own -- it's created automatically as a new product using the `name`, `sku`, `price`, `status`, and `product_image` values from the row. A `VARIANT` row does the same for the variant it names, as long as its product already exists. A parent must already be in your catalog or have its own row in the file.
### Example
| source\_product\_id | source\_variant\_id | name | parent\_source\_product\_id | relationship\_type |
| - | - | - | - | - |
| `1001` | | Modern Bed Frame | | |
| `1001-HEADBOARD` | | Headboard | `1001` | `COMPONENT` |
| `1001-SIDE-RAILS` | | Side Rails | `1001` | `COMPONENT` |
| `2001` | | Skincare Bundle | | |
| `2002` | | Gentle Cleanser | `2001` | `BUNDLE` |
| `2003` | | Hydrating Toner | `2001` | `BUNDLE` |
| `3001` | | Water Bottle Sling | | |
| `3001` | `3101` | Water Bottle Sling - Black | `3001` | `VARIANT` |
| `3001` | `3102` | Water Bottle Sling - Tan | `3001` | `VARIANT` |
In this example, the Bed Frame has two components (Headboard, Side Rails) that aren't sold on their own, so they get new IDs. The Skincare Bundle contains two products you already sell (Cleanser, Toner), and the Water Bottle Sling has two variants (Black, Tan). A customer could file a claim against just the Headboard or just the Toner.
Download a filled-in sample showing a component relationship (Sterling Chain Necklace), a bundle relationship (Skincare Bundle), and variants (Adventure Water Bottle Sling) to use as a starting point.
## Rules & limitations
Keep these constraints in mind to avoid skipped rows or unexpected results.
* **One level of nesting only.** A product can be a parent *or* a child, but not both. A component or bundle item cannot itself have its own components. If a file lists the same product as both, the whole upload is rejected.
* **A child has one parent.** Each product can be linked to a single parent product.
* **Uploads replace each parent's relationships.** When you upload a CSV, the components/bundle items listed for a given parent **replace** that parent's existing links, and a product you list under a new parent is moved off its old one. To make a change, re-download the current template, edit it, and re-upload.
* **Blanking out rows does not remove links.** Removing all of a parent's relationship rows from the CSV will *not* clear its existing components or bundle items. To remove a relationship entirely, contact your Customer Success Manager.
* **Synced variants aren't affected.** Variants that sync from Shopify don't show up as relationships in the template, and uploads never change them.
* **Some errors reject the whole file.** Nothing is saved if the file is missing the `source_product_id`, `parent_source_product_id`, or `relationship_type` column, if a `relationship_type` is anything other than `COMPONENT`, `BUNDLE`, or `VARIANT`, if a relationship row is missing its `source_product_id` or `parent_source_product_id`, or if an ID contains `::`. The error message names the row to fix -- Row 1 is the first row under the header.
* **Rows that can't be matched are skipped.** If a row's product or parent can't be found -- for example, a `parent_source_product_id` that isn't in your catalog and doesn't have a row of its own -- that row is skipped, the rest of the file is saved, and the upload summary shows how many rows were skipped.
* **CSV format only.** The upload accepts `.csv` files up to 5 MB. The file name must end in `.csv`.
## Keeping your taxonomy up to date
Your taxonomy is only as valuable as it is accurate. Your catalog changes over time -- you launch new products, redesign a bundle, rename a part, or discontinue an item -- and each of those changes should be reflected in your taxonomy so customers always see the right parts to claim against.
You can review each product's relationships on the **Products** page, where the **Relationship** column shows whether a product is a parent (e.g., *Parent · 3 Parts*), a component, or a set of variants. With Product Sync on, a live store's catalog refreshes twice a day, and **Sync Products** pulls in the latest changes on demand.
Keeping your taxonomy current matters because:
* **New products default to whole-item claims.** Until a newly launched product's components or bundle items are mapped, customers can only claim against the entire product -- which means higher-cost resolutions on exactly the products you know least about.
* **Stale mappings confuse customers.** A renamed or removed part that still appears (or a new part that's missing) makes the claim form inaccurate and erodes trust.
* **Your failure data stays meaningful.** Accurate component mapping is what lets you trust the "which parts fail most often" insight -- outdated taxonomy skews it.
Make updating your taxonomy part of your product-launch and catalog-cleanup routine. Whenever you add or restructure products, sync your catalog, download a fresh template, and map the new products -- by hand or with the [AI prompts](#map-relationships-with-an-ai-assistant) -- so granular claims work from day one.
## The customer experience
Once your taxonomy is uploaded, customers filing a claim will see a **Which part is affected?** dropdown when describing their issue. It defaults to **Whole item**, with each mapped component or bundle item listed as an option. This lets the customer pinpoint exactly which part has the issue.
The **Which part is affected?** selector appears when the issue type is **Damaged** or **Defective**. **Missing** is also available for **bundle items** -- a bundle can arrive with one of its items missing -- but not for components, since a component is part of a single product and can't go missing on its own. For all other issue types, the claim is filed against the whole item.
After the claim is filed, the selected part is carried through to the claim itself. The affected component or bundle item appears under **Includes:** on the line item, so your team can see exactly which part the customer is claiming against.
In the claim detail view, the affected part is listed under **Item Issue(s)** with its issue type and the customer's description -- in this example, the *Lobster Clasp* component is flagged as **Damaged** ("Lobster clasp won't lock").
If you have questions about setting up your product taxonomy, reach out to your Customer Success Manager or your shared Slack channel.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.