Add Free Product to Upcoming Recharge Order on Customer Tag

When customer tags are updated in Shopify (tags added, removed, or modified through admin, bulk actions, or other workflows), this trigger activates the workflow and captures the customer ID and current tag state. The workflow runs for every customer tag change. No configuration is required—it's pre-connected to your Shopify store and monitors tag updates automatically.

Tag-based gift workflow: This approach lets you manage subscription gifts at scale—bulk tag customers from a segment, CSV upload, or manually tag VIP customers—and the workflow handles the Recharge complexity.

This step retrieves the full Shopify customer record using the customer ID. It returns complete customer data including all current tags as a comma-separated string. This comprehensive tag list is essential for the next step's filtering logic that checks for both the "add-free-product" trigger tag and the "recharge-workflow" processing marker.

This filter implements two critical checks using AND logic. The workflow proceeds only when BOTH conditions are true:

1. "recharge-workflow" NOT in customer tags: Ensures this workflow hasn't already processed this customer (preventing duplicate gifts)
2. "add-free-product" IN customer tags: Confirms the customer is tagged for a gift (the trigger condition)

Logic breakdown:

1. First check prevents re-running if someone modifies other tags after gift was added
2. Second check ensures only intentionally tagged customers receive gifts
3. Combined logic prevents edge cases like accidental duplicate processing

If either condition fails, the workflow stops without adding a gift.

This step queries Recharge's customer database using the Shopify customer ID as the external_customer_id parameter. It returns matching Recharge customer records with the Recharge customer ID needed for querying subscriptions. The first result (index 0) contains the customer's Recharge ID.

Shopify-Recharge connection: Recharge stores the Shopify customer ID as external_customer_id, enabling lookups that bridge the two systems. This is automatically set when customers create subscriptions through Shopify checkout.

This step queries Recharge for subscriptions belonging to the Recharge customer ID. It returns subscription details including address_id (shipping address), next_charge_scheduled_at (next order date), subscription product information, and billing details. The first subscription (index 0) is used for adding the gift—if customers have multiple subscriptions, the gift adds to the first subscription's order.

Multi-subscription consideration: Customers with multiple active subscriptions will receive the gift on their first subscription's next order. To add gifts to all subscriptions, you'd need to loop through all subscriptions and create multiple one-time products.

This step creates a Recharge "one-time" product—a product added to a single upcoming subscription order rather than recurring.

Configuration: You must set two values during setup:

1. Product title: The display name for the gift product (like "Free Sample - Thank You Gift" or "Loyalty Bonus Product")
2. Shopify Variant ID: The variant ID of the gift product in Shopify (found in product admin URL or using Shopify API)

The one-time product includes:

1. address_id: Shipping address from the subscription (ensures gift ships to correct location)
2. price: Set to "0" (makes it free)
3. next_charge_scheduled_at: Scheduled for the subscription's next charge date (adds to upcoming order)
4. product_title: Your configured gift product name
5. quantity: Set to "1" (one gift per customer)
6. external_variant_id: Your configured Shopify variant ID (connects to actual product)

One-time vs subscription: One-time products appear only on the next order, not every order. Perfect for gifts, promotions, or bonuses that shouldn't recur.

This step adds the "recharge-workflow" tag to the customer's Shopify record. This processing marker ensures the filter in step 3 will block future workflow runs for this customer, even if someone edits other tags or re-adds the "add-free-product" tag. The tag remains permanently unless manually removed.

Tag management strategy:

1. Keep "add-free-product" tag to track who received gifts
2. Add "recharge-workflow" tag to prevent duplicates
3. To send another gift later, remove both tags and re-tag with "add-free-product"