Shopify Integration Overview & Setup

What the Integration Does

• Automated Order Sync — Capture all Shopify orders or only referred orders in Ambassador
• Referral Attribution — Automatically detect which advocate referred each customer (via discount code, referral link, or URL parameter)
• Discount Code Management — Auto-generate a Shopify discount code for every advocate's referral code
• Customer Enrollment — Convert Shopify customers into program advocates automatically
• Reward Automation — Create, approve, and fulfill rewards based on order status changes (paid, fulfilled, refunded)
• Loyalty Support — Track customer lifetime value and tier progression
• Real-time Updates — Webhooks deliver instant notifications when orders are created, paid, fulfilled, or refunded

Shopify Plan Requirements

Gift Card rewards via Shopify require Shopify Plus or a plan with gift card functionality enabled. Use other reward types (cash, points, custom) for non-Plus stores.

How to Connect Shopify to Ambassador

1. Go to Admin → Integrations → Shopify in your Ambassador admin.
2. Enter your Shopify subdomain — the part before .myshopify.com (e.g., if your store is mystore.myshopify.com, enter mystore).
3. Create a Private App in Shopify Admin (Settings → Apps → Develop apps) with the following API scopes:
   • read_customers
   • read_discounts, write_discounts
   • read_orders
   • read_price_rules, write_price_rules
   • read_gift_cards, write_gift_cards (if using Shopify gift card rewards)
4. Copy the Admin API Access Token from Shopify and paste it into Ambassador.
5. Click Test Connection to verify the token and scopes are correct.
6. Configure your Order Sync settings (see below).
7. Save your settings.

Order Sync Configuration

Sync All Orders (Recommended for Loyalty Programs)

Imports every order from your Shopify store. Creates a Prospect contact record for each customer, enabling post-purchase enrollment campaigns. Use this when running a loyalty program or when you want to invite all customers to become advocates.

Sync Referred Orders Only

Imports only orders with referral attribution (discount code, referral link, or URL parameter). Reduces contact usage in Ambassador. Use this for pure referral programs without a loyalty component.

Tip: Enable "Create Prospects for Non-Referred Customers" alongside "Sync Referred Orders Only" to build a prospect pool for recruitment campaigns — without creating full order records for non-referred purchases.

Referral Attribution — How It Works

When a Shopify order is created, Ambassador attempts to identify the referring advocate using these methods in priority order:

1. Shopify Discount Code — Order used a discount code matching an advocate's referral code (highest reliability)
2. Referral Code from Customer Journey — Shopify's server-side tracking of a ?ref= URL parameter (takes 3–5 minutes to populate)
3. Landing Page URL Parsing — Ambassador parses the ref= parameter from the customer's landing page URL
4. First Visit Referral Code — Captures the first time a customer clicked a referral link (useful for multi-visit journeys)
5. Existing Attribution — If the customer already has a referral attribution from a prior order, new orders are attributed to the same advocate
6. Coupon Code Lookup — Custom mapping from a coupon code to a specific advocate UID

Discount Code Setup

When Create Discount Codes from Referral Codes is enabled, Ambassador automatically creates a matching Shopify discount code whenever a new advocate referral code is generated. The discount rules (percentage off, minimum order, etc.) are defined by a Campaign Price Rule Mapping — a link between an Ambassador campaign and a Shopify Price Rule.

To configure this:

1. Create the desired Price Rules in Shopify Admin first and test them manually.
2. In Ambassador, enable "Create Discount Codes from Referral Codes."
3. Add a Campaign Price Rule Mapping for each campaign, linking it to the appropriate Shopify Price Rule ID.

Order Status Sync

Ambassador syncs Shopify order status changes to the external_status field on the Order record. This lets your Automations fire based on order status — for example, approving a reward when an order is fulfilled, or denying it when an order is refunded.

Key Shopify statuses and their Ambassador mappings:

Common Reward Automation Scenarios

• First-time referred purchase — Automation trigger: Order Created + first order filter → Create pending reward for advocate
• Status-based reward approval — Automation trigger: Order Updated + status = "fulfilled" → Approve pending reward
• Refund-based reward denial — Automation trigger: Order Updated + status = "refunded" → Deny pending reward
• Post-purchase enrollment — Automation trigger: Order Created (first order) → Enroll customer as advocate or send enrollment invite

Frequently Asked Questions

Can I sync orders from before the integration was connected?
Yes — use the Historical Order Sync feature to backfill past orders. We recommend starting with a 90-day lookback to avoid overwhelming the system.

How quickly do orders appear in Ambassador?
With webhooks enabled, orders appear within 5–10 seconds. Without webhooks, orders sync every 15 minutes via scheduled job.

Do I need Shopify Plus for this integration?
No — the integration works on all Shopify plans. Gift card rewards require Shopify Plus.

What happens if an advocate's referral code changes?
The integration automatically updates the discount code in Shopify. Historical orders that used the old code are preserved.

What happens if Shopify refunds an order after a reward was already paid?
Pending rewards are automatically denied if a refund is detected. Already-paid rewards require manual clawback.

Good to Know

• Always test the connection using the Test Connection button after initial setup and after any credential changes.
• Shopify's customer journey data (used for URL-based attribution) takes 3–5 minutes to populate — Ambassador accounts for this with a built-in delay.
• For Basic plan stores, ask your Ambassador team about the Custom Pixel setup to capture email at checkout without upgrading your Shopify plan.
• Related articles: Orders Overview, Automations Overview, Referral Attribution Overview, Fulfillment Methods Overview