> For the complete documentation index, see [llms.txt](https://docs.giftcardfactory.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.giftcardfactory.app/misc/recipients-selector.md). # Recipients Selector The recipients selector lets you choose who should receive gift cards, discount codes, or store credit. There are **five input methods**, each suited to a different scenario.
> Used by: [Gift Card Bulk Send](/bulk-operations/bulk-send.md), [Discount Codes Bulk Send](/bulk-operations/discount-codes-bulk-send.md), [Store Credit Bulk Add](/bulk-operations/store-credit-bulk-add.md), and several campaigns. **Method 1: Manual List of Emails (Default)** **How it works:** Type or paste a list of email addresses or customer IDs directly into the text field. **Format:** * Separate entries with commas OR new lines * Mix of emails and customer IDs is allowed * Extra spaces are automatically removed **Examples:** Comma-separated: ``` john@example.com, jane@example.com, bob@example.com ``` New line separated: ``` john@example.com jane@example.com bob@example.com ``` Mixed format: ``` john@example.com, jane@example.com bob@example.com ``` Using customer IDs: ``` 123456789 987654321 ``` **When to use:** * You have a specific list of customers * You're copying emails from a spreadsheet * You have 50 or fewer customers * You need precise control over recipients **Tips:** * Copy from Excel/Google Sheets directly - the app handles formatting * If you have customer IDs from Shopify exports, you can use those * The app will create new customer records if emails don't exist yet * Always double-check for typos in email addresses *** **Method 2: Select Customers** **How it works:** Click a button to open a customer selector where you can browse and choose specific customers from your store. **Steps:** 1. Click **"Select customers"** button 2. Browse or search for customers in the modal 3. Check the boxes next to customers you want to include 4. Click **"Confirm"** to apply your selection **Features:** * Search by name, email, or customer details * See customer information before selecting * Multi-select - choose as many as needed * Change selection anytime before creating the operation * Clear all selections with one click **When to use:** * You want to browse your customer list * You need to verify customer details before selection * You're not sure of exact email addresses * You want a visual selection process * You have 10-200 customers to select **Display:** After selection, you'll see a green banner showing: * "X customers selected" * Buttons to change or clear your selection *** **Method 3: Select Customer Segment** **How it works:** Choose an entire customer segment that you've already created in Shopify, and all members of that segment will receive gift card, discount code or store credit. **Steps:** 1. Click **"Select segment"** button 2. Browse available segments from your Shopify store 3. Select the segment you want 4. Click **"Confirm"** to apply **Features:** * Uses your existing Shopify customer segments * Automatically includes all segment members * Shows member count before confirmation * Perfect for large groups * Updates dynamically if segment membership changes before execution **What are Shopify Segments?** Customer segments are groups of customers in Shopify based on criteria like: * Purchase history (e.g., "Customers who spent $500+") * Location (e.g., "Customers in California") * Engagement (e.g., "Subscribed to marketing") * Custom tags or attributes **Creating Segments:** If you haven't created segments yet: 1. Go to Shopify Admin → Customers 2. Click "Segments" or "Create segment" 3. Set your criteria 4. Save the segment 5. Return to Gift Card Factory and select it **When to use:** * You have existing segments in Shopify * You're targeting large groups (100+ customers) * You want dynamic membership (segment updates automatically) * You run regular campaigns to the same groups * You need consistent targeting across operations **Display:** After selection, you'll see a green banner showing: * "Segment: \[Segment Name] (X members)" * Buttons to change or clear your selection **Important:** The segment members are evaluated at the time the operation runs, not when you create it. If you schedule the operation for the future, the segment membership may change between now and then. *** **Method 4: Customers Query** **How it works:** Enter a Shopify customer search query (e.g. `tag:vip`, `orders_count:>5`, or a Liquid expression like `tag:birthday-{{ "now" | date: "%m-%d" }}`). The recipient list is **resolved at execution time** — every customer matching the query when the operation runs becomes a recipient. **Steps:** 1. Switch to the **Customers query** tab. 2. Enter your query in the input field. 3. Use the **Test Query** button to preview the matching customers. 4. The query is saved with the operation; the actual list is computed when the operation executes. **Features:** * **Dynamic recipients** — the same query produces different recipients on different days (e.g. `tag:birthday-{{ "now" | date: "%m-%d" }}` matches today's birthdays each time it runs). * Uses [Shopify's customer search syntax](https://shopify.dev/docs/api/usage/search-syntax), supporting `AND` / `OR` / `NOT`, wildcards, and many fields (tags, location, orders count, marketing consent, etc.). * Supports [Liquid templating](/misc/customers-query-selector.md#understanding-liquid-templating) for date-based queries. * No upfront list — recipients can be added/removed by tagging or untagging customers in Shopify. **When to use:** * **Recurring or scheduled campaigns** where the audience changes over time (birthday campaigns, anniversary campaigns, "customers tagged X this month"). * **Tag-driven workflows** where you (or another system) maintain audience membership via Shopify tags. * **Targeting by attribute** (location, marketing consent, order count) without manually building a list. * **Pairing with the** [**Customers Query Selector docs**](/misc/customers-query-selector.md) for in-depth syntax reference and examples. **Limitations:** * Operations resolving more than **3000 matching customers** are paused. If your query matches more, narrow it (more specific tags, additional `AND` conditions). * You won't see the actual recipient list until the operation runs (use **Test Query** to preview, but remember the test runs against today's date — scheduled runs will use the date at execution time). **See also:** [Customers Query Selector](/misc/customers-query-selector.md) for the full query syntax, Liquid filters, and worked examples. *** **Method 5: Customer Segment Query** **How it works:** Enter a query in **Shopify's segment language** — the same one used in Customers → Segments — such as `customer_tags CONTAINS 'vip' AND amount_spent >= 500` or `anniversary(date: 'metafields.facts.birth_date') = today`. Unlike Method 3 you don't need to save a segment first, and unlike Method 4 you get the full power of segment filters (spend, order dates, metafields, store credit balances, products purchased). The recipient list is **resolved at execution time**. **Steps:** 1. Switch to the **Customer segment query** tab. 2. Type your query, or click an **Example** button to start from a template. 3. The app validates the query as you type and shows how many customers match right now (syntax errors show Shopify's own message). 4. Save — the query is stored with the operation and re-evaluated whenever it runs. **Examples:** ``` customer_tags CONTAINS 'vip' AND email_subscription_status = 'SUBSCRIBED' ``` ``` last_order_date > -30d AND number_of_orders >= 2 ``` ``` store_credit_accounts MATCHES (balance > 0) ``` ``` anniversary(date: 'metafields.facts.birth_date') = today ``` **When to use:** * You already think in Shopify segments, or want to reuse a query from the Shopify segment editor without saving it. * You need filters the search syntax can't express (lifetime spend, last order date, metafields, store credit balance, products purchased). * Recurring / scheduled campaigns with a dynamic audience. **Limitations:** * Operations resolving more than **3000 customers** are paused — the live count warns you before you save. * Metafield filters need a customer **metafield definition**; functions take named parameters (`anniversary(date: '…')`). **See also:** [Segment Query Selector](/misc/segment-query-selector.md) for the syntax, field reference and worked examples. *** #### Comparing Recipient Methods | Feature | Manual List | Select Customers | Select Segment | Customers Query | Customer Segment Query | | -------------------------- | ----------------------- | ----------------------- | ---------------------------------- | ---------------------------------- | ----------------------------------------------- | | **Best for** | Small, specific lists | Medium-sized selections | Large groups | Recurring / dynamic campaigns | Recurring / dynamic campaigns with rich filters | | **Size limit** | Any | 50–200 practical | Unlimited | Up to 3000 per execution | Up to 3000 per execution | | **Requires preparation** | List of emails | No | Segment must exist | Tags / attributes set on customers | Knowing Shopify's segment language | | **Visual selection** | No | Yes | Yes | No (live count preview) | No (live count preview) | | **Dynamic at run time?** | No (static list) | No (snapshot) | Yes (segment members re-evaluated) | Yes (query re-runs) | Yes (query re-runs) | | **Supports Liquid dates?** | No | No | No | Yes | Yes (built-in relative dates preferred) | | **Speed to set up** | Fast for small lists | Moderate | Very fast | Moderate (query authoring) | Moderate (query authoring) | | **Accuracy** | Requires careful typing | High | High | High (assuming correct query) | High (validated as you type) | **Recommendation:** * **One-off, small list (1–50)** → Manual list, if you have the emails. * **One-off, medium browse-and-pick** → Select customers. * **One-off, large pre-defined group** → Select segment. * **Recurring / scheduled with changing audience** → Customers query. * **Date-driven (birthdays, anniversaries)** → Customers query with Liquid, or a segment query with `anniversary(date: …)` on a birthday metafield. * **Spend / order-history / store-credit targeting** → Customer segment query.