Add return reasons data and category mappings

[ricardotejedorsanz]

This PR introduces the foundational data structure for return reasons in the product taxonomy repository. It adds 359 curated return reasons (6 general + 353 product-specific) mapped to all taxonomy categories to help reduce the 68% of returns currently marked as "other" or "unknown".

What's included:

• data/return_reasons.yml: Central definition file with all 359 return reasons
• data/localizations/return_reasons/en.yml: English localization file
• All 26 category YAML files: Updated with return_reasons mappings to applicable categories

Data structure:
Each return reason has:

• id: Unique numeric identifier (1-359)
• name: Human-readable display name
• handle: Snake_case identifier for code
• friendly_id: URL-safe slug for category references
• description: Plain text explanation of when to use this reason

Design decisions:

• Uses gid://shopify/ReturnReasonDefinition/{id} format (see open discussion below)
• Special handling for ID 5 (Unknown) and ID 6 (Other) which always appear last
• Follows same pattern as attributes: centralized definition, referenced by categories

Context:
This is part of the Better Return Reasons project to provide category-specific return reasons automatically across Admin, POS, Self-Serve Returns, and public APIs. The return reasons are being integrated into the public taxonomy repository for discoverability, versioning, and localization alongside categories and attributes.

Open Discussion - GID Format:
There's an ongoing discussion about the GID naming convention:

• Current choice: gid://shopify/ReturnReasonDefinition/{id} - maintains consistency with Core DB and avoids breaking changes to existing API integrations
• Alternative consideration: gid://shopify/TaxonomyReturnReason/{id} - would align with other taxonomy GIDs (TaxonomyCategory, TaxonomyAttribute, TaxonomyValue)

Tradeoffs:

• ReturnReasonDefinition: Consistent with Core DB implementation, avoids significant rework in API schema/resolvers/integrations. Also maintains conceptual separation: return reasons are an add-on to taxonomy (distinct from its three core elements: categories, attributes, and values), so omitting the "Taxonomy" prefix reinforces this distinction.
• TaxonomyReturnReason: Consistent with taxonomy naming patterns (TaxonomyCategory, TaxonomyAttribute, TaxonomyValue), but would require breaking changes to Core DB and API integrations, potentially impacting delivery timeline. Also implies return reasons are core taxonomy entities rather than supplementary features.

Stakeholder input welcome on whether consistency with existing taxonomy naming patterns outweighs the implementation complexity and the conceptual model of return reasons as add-ons vs. core taxonomy entities.

How mappings were created:

• Return reasons and category mappings come from approved CSV curated by the Returns team
• A one-off Python script was used to map return reasons to categories (not checked in; served only to bootstrap initial data)
• 6 general return reasons mapped to applicable categories
• 353 product-specific return reasons mapped to relevant categories
• Alphabetical ordering with Unknown (ID 5) second-to-last, Other (ID 6) last

Review notes:

• Pure data PR - no code changes, only YAML files
• Subsequent PRs will add models, serializers, and CLI tools to work with this data
• GID format is used throughout the codebase, so stakeholder alignment on naming is important before merging
• Category files can be spot-checked; they all follow the same pattern

Prototype/Placeholder Status:

• Return reasons list: Temporary data to power the prototype. Only approved decisions are included; list may evolve before final merge.
• IDs: Currently placeholder values for prototype purposes. We recommend aligning these with existing ID assignments in Core DB before final merge, with the long-term vision of ID generation originating from the public repo.
• Descriptions: Currently placeholders (return reason name repeated). We suggest enhancing these similar to attribute descriptions—providing clear definitions of what each return reason means and when to use it—to help users distinguish between similar options.

Files to Include

• data/return_reasons.yml
• data/localizations/return_reasons/en.yml
• All 26 category files:
  • data/categories/aa_apparel_accessories.yml
  • data/categories/ae_arts_entertainment.yml
  • data/categories/ap_animals_pet_supplies.yml
  • data/categories/bi_business_industrial.yml
  • data/categories/bt_baby_toddler.yml
  • data/categories/bu_bundles.yml
  • data/categories/co_cameras_optics.yml
  • data/categories/el_electronics.yml
  • data/categories/fb_food_beverages_tobacco.yml
  • data/categories/fr_furniture.yml
  • data/categories/gc_gift_cards.yml
  • data/categories/ha_hardware.yml
  • data/categories/hb_health_beauty.yml
  • data/categories/hg_home_garden.yml
  • data/categories/lb_luggage_bags.yml
  • data/categories/ma_mature.yml
  • data/categories/me_media.yml
  • data/categories/na_uncategorized.yml
  • data/categories/os_office_supplies.yml
  • data/categories/pa_product_add_ons.yml
  • data/categories/rc_religious_ceremonial.yml
  • data/categories/se_services.yml
  • data/categories/sg_sporting_goods.yml
  • data/categories/so_software.yml
  • data/categories/tg_toys_games.yml
  • data/categories/vp_vehicles_parts.yml

Dependencies

• None (foundation PR)

Review Focus

• Return reasons data structure and schema
• Naming conventions
• Localization format
• Category mappings (spot-check a few categories for correctness)

[ricardotejedorsanz]

• Implement return reasons model and distribution pipeline #790 : 2 dependent PRs (#792 , #795 )
• Add return reasons data and category mappings #789 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.