Category-Collection Mapping Configuration

Category-Collection Mapping Configuration

For the Carta del Docente discount to function correctly, you need to associate ministerial categories with your Shopify store’s collections. This step is crucial as it determines which products in the cart are eligible for the discount when a customer uses a voucher.

How the mapping system works

The app uses an automatic system based on product metafields to check eligibility. Here’s the complete flow:

1. You configure the mappings in the app (e.g., “Books and texts” → “Books” Collection)
2. The app automatically synchronizes all products in the selected collections
3. Each product receives a metafield carta_docente.categoria with the corresponding value
4. The Discount Function (Shopify server-side) compares the voucher’s scope with the product’s metafield
5. The discount is applied only to products that match the voucher’s category

Important note: Eligibility checking occurs exclusively within Shopify’s Discount Function, not in the checkout widget. This means the widget will always show “Code verified” if the voucher is valid, but the final discount in the cart will only consider eligible products.

Configuring the mappings

Follow these steps to configure the associations between Carta del Docente categories and your Shopify collections:

1. Access your Carta del Docente app dashboard
2. Go to the “Options” section in the navigation menu
3. Scroll down to the “Category-Collection Mappings” section
4. For each ministerial category you want to support:
   • Select the Carta del Docente category from the dropdown menu (e.g., “Books and texts”, “Hardware and software”)
   • Select one or more collections from your store that contain products of that category
   • Click on “Add Mapping” to save the association
5. Repeat for all categories you wish to enable
6. Click on “Save Settings” at the bottom of the page

Note: When you save the settings, the app automatically starts synchronizing metafields for all products in the selected collections. This process may take a few seconds depending on the number of products.

Configuration example

Here’s a practical example of how to configure the mappings:

• Carta del Docente Category: “Books and texts”
• Shopify Collections: “Books”, “E-books”, “School textbooks”

With this configuration:

1. All products in the “Books”, “E-books”, and “School textbooks” collections will receive the metafield carta_docente.categoria = "libri-testi"
2. When a customer uses a Carta del Docente voucher with the scope “Books and texts”
3. The Discount Function will apply the discount only to products that have the corresponding metafield
4. Products from other collections (e.g., “Apparel”) will not receive the discount

Manual metafield synchronization

In some cases, it may be necessary to manually synchronize product metafields:

• You have added new products to an already mapped collection
• You have modified the mappings and want to apply the changes immediately
• You are experiencing issues with the eligibility of certain products

To synchronize manually:

1. Go to the “Options” section of the app
2. Click on the “Synchronize Product Metafields” button
3. Wait for the operation to complete (you will see a confirmation message)

Note: Manual synchronization updates metafields for all products based on current mappings. Products removed from mapped collections will retain the existing metafield but will no longer receive the discount on new orders.

Common troubleshooting

Problem: The discount is not applied to products even if the voucher is valid.

Solution: Verify that:

1. Category-collection mappings are configured correctly
2. Products are actually in the mapped collections
3. Metafield synchronization has been completed (you can force it manually)
4. The Discount Function is correctly installed and active in your store

Problem: Some products receive the discount even if they shouldn’t.

Solution: Check that products do not belong to multiple collections, some of which might be mapped to Carta del Docente categories. A product receives the discount if it belongs to at least one collection mapped for the category of the voucher used.

Best practices

• Keep collections organized: Create specific collections for eligible products (e.g., “CdD Books”, “CdD Hardware”)
• Check periodically: Ensure mappings are updated when you add new product categories
• Always test: After modifying mappings, place a test order with a valid voucher to verify that the discount is applied correctly
• Communicate clearly: Inform customers about which products can be purchased with Carta del Docente to avoid misunderstandings