Shopify integration

Connect your Shopify store to IncentIA so every order auto-creates a member (if missing) and earns points per your programme rules.

Case: ecommerce that wants to reward customers with points per purchase, with no custom development.

Time: ~15 min · Level: intermediate (requires Shopify admin access).

Prerequisites

• A loyalty programme already created in IncentIA with at least one OnPurchase earning rule (see points tutorial).
• Admin access to the Shopify store.
• IncentIA public URL reachable from the internet.

1. Create the integration in IncentIA

1. Admin → Integrations → New → type Shopify.
2. Name: My Shopify store.
3. On save, IncentIA generates:
   • Webhook URL: https://your-domain.app/api/webhooks/shopify/{integrationId}
   • HMAC Secret: random string Shopify uses to sign webhooks.
4. Copy both.

2. Field mapping

In the Mapping tab of the integration:

Shopify field	IncentIA field	Required
email	Member.Email	yes
total_price	purchase amount	yes
customer.first_name	Member.FirstName	no
customer.last_name	Member.LastName	no
customer.phone	Member.Phone	no
order_number	Transaction.ExternalId	no (for dedup)
line_items	detail (optional)	no

Mapping determines what data reaches IncentIA and how it becomes Member and Transaction.

3. Configure member auto-creation

Options:

• Auto-create if missing → the customer's first order auto-registers them in the programme (no OTP, no manual sign-up).
• Match existing email only → if email exists in Members, the purchase is associated; otherwise ignored.

For smooth onboarding, Auto-create is usually best.

4. Configure the webhook in Shopify

In your Shopify admin:

1. Settings → Notifications → Webhooks section.
2. Create webhook:
   • Event: Order paid
   • Format: JSON
   • URL: the IncentIA URL from step 1.
3. Save.

(Optional) Also add Customer updated if you want to sync profile changes.

5. Configure HMAC signing

Shopify signs every webhook. In IncentIA, the integration verifies the signature with the secret from step 1.

If the secret is different, webhooks arrive but are rejected with 401. Check logs at Admin → Integrations → {your integration} → Logs tab.

6. Test with a real (or sandbox) order

1. Create a test order in Shopify (or use the development store).
2. On payment, Shopify sends the webhook.
3. In IncentIA → Integrations → Logs: see the entry with 200 and the summary.
4. Admin → Members: the customer appears (if new).
5. Admin → Transactions: the transaction is logged.
6. The member has points per your earning rules.

7. Member notification

If the customer is new, typically send:

• Welcome email to the programme (template welcome_email + flow trigger).
• Include link to their portal to see points: https://your-domain.app/member.

Existing members get only the "you earned X points" notification if your config allows.

8. Reprocess historical orders (optional)

To import historical data:

1. Export Shopify paid orders from the last year.
2. Admin → Integrations → Reprocess → upload the JSON.
3. IncentIA ingests each order as if it just arrived (with is_backfill flag to skip emails).

Common issues

Symptom	Cause	Fix
Webhooks arrive but 401	HMAC secret copied wrong	Reset from Shopify, update in IncentIA
Duplicate members	Same email across stores	Enable MatchByEmail and disable Auto-create
Duplicate points	Order received twice (Shopify retry)	Enable ExternalId dedup in mapping
Member not created	Empty email in Shopify	Webhook rejected (email is required)

What you built

• Shopify sends webhook to IncentIA on every paid order.
• IncentIA auto-creates members in the programme.
• Points accumulate per existing earning rules.
• Transaction history synced.

Next steps

• Integrate WooCommerce or Stripe with the same pattern.
• Configure a communications flow for post-purchase email → communications tutorial.
• Launch a cashback campaign requiring Shopify evidence for an extra → cashback tutorial.