Skip to main content
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, 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.
This results in faster, more accurate resolutions because both you and the customer know exactly which part of the order is affected.

​
Where to find it

1

Open Claims settings

From the dashboard, go to Settings → Claims.
2

Find the Product Taxonomy card

Scroll to the Product Taxonomy card. Here you’ll find the Download Template and Upload Catalog buttons.Product Taxonomy card in Claims settings

​
How to upload your taxonomy

1

Download the template

Click Download Template on the Product Taxonomy card. This generates a product_taxonomy.csv file pre-populated with all of your existing top-level products, so you have the correct product IDs to work from.
2

Edit the relationship columns

Open the CSV in your spreadsheet tool of choice. For each product that is a component or a bundle item, fill in the parent_source_product_id and relationship_type columns to point it at its parent product. (See CSV structure below.)
3

Upload the catalog

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 were updated, any new products that were created, and any rows that were skipped.

​
CSV structure

Each row in the CSV represents one product. A product becomes a component or bundle item by pointing it at a parent product using the last two columns.
ColumnRequiredDescription
source_product_idYesThe unique product ID for this row’s product (matches the ID in your store/platform).
skuNoThe product’s SKU.
nameYesThe product’s display name.
priceYesThe product’s price.
statusYesThe product’s status (e.g., ACTIVE, ARCHIVED, DRAFT).
product_imageNoURL to the product’s image.
parent_source_product_idNoThe source_product_id of the parent product this item rolls up to. Leave blank for a top-level/parent product.
relationship_typeNoEither COMPONENT or BUNDLE. 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 or bundle items attach to.
  • Relationship rows — A row with a relationship_type of COMPONENT or BUNDLE must also include a valid parent_source_product_id. This is what links the child product to its parent.
If a source_product_id or parent_source_product_id in your CSV doesn’t yet exist in your catalog, it is created automatically as a new product using the name, sku, price, status, and product_image values from the row.

​
Example

source_product_idnameparent_source_product_idrelationship_type
1001Modern Bed Frame
1002Headboard1001COMPONENT
1003Side Rails1001COMPONENT
2001Skincare Bundle
2002Gentle Cleanser2001BUNDLE
2003Hydrating Toner2001BUNDLE
In this example, the Bed Frame has two components (Headboard, Side Rails), and the Skincare Bundle contains two bundle items (Cleanser, Toner). A customer could file a claim against just the Headboard or just the Toner.

Sample CSV

Download a filled-in product_taxonomy.csv showing both a component relationship (Sterling Chain Necklace) and a bundle relationship (Skincare Bundle) 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.
  • 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. 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.
  • CSV format only. The upload accepts .csv files up to the platform’s file-size limit. Invalid rows (e.g., a relationship_type other than COMPONENT or BUNDLE, or a relationship row missing its parent) are skipped and reported back in the upload summary.

​
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.
Customer selecting an affected part during claim filing 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. Filed claim showing the affected part 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”). Claim detail showing the affected part under Item Issues If you have questions about setting up your product taxonomy, reach out to your Customer Success Manager or your shared Slack channel.