Shopify Integration

Connect your Shopify store to automatically award points for purchases, handle refunds, and generate discount codes as rewards.

Features

Points for Purchases: Automatic points based on order value
Refund Handling: Proportional point deduction on refunds
Discount Codes: Generate unique coupon codes as rewards
Product Multipliers: Bonus points for specific products/collections
Guest Exclusion: Option to exclude guest checkout
Multiplier Events: Double/triple points during promotions

Setup

1. Connect Your Store

Navigate to Settings → Integrations → Shopify
Click Connect Shopify Store
Enter your shop domain (e.g., mystore.myshopify.com)
Authorize the app in Shopify

2. OAuth Permissions

The app requests these permissions:

Scope	Purpose
`read_orders`	Process orders for points
`write_orders`	Update order metadata
`read_customers`	Identify customers
`write_customers`	Create customer records
`read_products`	Product multipliers
`write_discounts`	Generate reward coupons
`read_price_rules`	Discount management
`write_price_rules`	Create price rules

3. Configure Points Settings

Setting	Default	Description
Points per Dollar	1	Points earned per $1 spent
Rounding Mode	FLOOR	How to round points (FLOOR, CEIL, ROUND)
Min Order Amount	None	Minimum order to earn points
Exclude Shipping	Yes	Don't count shipping in points
Exclude Tax	Yes	Don't count tax in points
Exclude Guest	Yes	Require customer account

Webhook Events

The integration automatically registers these webhooks:

Event	Action
`orders/paid`	Award points to customer
`orders/cancelled`	Refund all points
`refunds/create`	Proportional point refund
`customers/create`	Create member record
`customers/update`	Update member info
`app/uninstalled`	Deactivate connection

Points Calculation

Formula

Eligible Amount = Subtotal [- Shipping] [- Tax]
Points = Eligible Amount × Points per Dollar × Multiplier

Example

Order Total: $150.00
Shipping: $10.00
Tax: $12.00
Points per Dollar: 1

Eligible Amount = $150 - $10 - $12 = $128
Points Earned = 128 × 1 = 128 points

With Multiplier Event

Base Points: 128
Active Multiplier: 2x ("Double Points Weekend")
Final Points: 128 × 2 = 256 points

Product Multipliers

Set higher earning rates for specific products:

By Product

{
  "productOverrides": {
    "gid://shopify/Product/12345": {
      "multiplier": 2.0
    },
    "gid://shopify/Product/67890": {
      "multiplier": 1.5
    }
  }
}

By Collection

{
  "collectionOverrides": {
    "gid://shopify/Collection/premium": {
      "multiplier": 2.0
    },
    "gid://shopify/Collection/sale": {
      "multiplier": 0.5
    }
  }
}

Priority Order

Product-specific multiplier (highest priority)
Collection multiplier (if multiple, use highest)
Default multiplier (1.0)

Refund Handling

Full Cancellation

When an order is cancelled:

All points earned from the order are refunded
Transaction status set to REFUNDED

Partial Refund

Points are refunded proportionally:

Refund Ratio = Refund Amount / Original Order Total
Points Refunded = Original Points × Refund Ratio

Example:

Original Order: $100 → 100 points earned
Refund Amount: $30
Refund Ratio: 30 / 100 = 0.30
Points Refunded: 100 × 0.30 = 30 points
Remaining Points: 70 points

Discount Code Rewards

Create rewards that generate Shopify discount codes:

Percentage Discount

{
  "name": "10% Off Reward",
  "type": "COUPON",
  "pointsCost": 500,
  "discountConfig": {
    "type": "PERCENTAGE",
    "value": 10
  }
}

Fixed Amount Discount

{
  "name": "$20 Off Reward",
  "type": "COUPON",
  "pointsCost": 1000,
  "discountConfig": {
    "type": "FIXED_AMOUNT",
    "value": 20
  }
}

Free Shipping

{
  "name": "Free Shipping Reward",
  "type": "COUPON",
  "pointsCost": 300,
  "discountConfig": {
    "type": "FREE_SHIPPING"
  }
}

Generated Code Format

USELOYALTY-ABC123XY

Prefix: USELOYALTY-
Random: 8 characters
Usage: 1 per customer, 1 total

API Endpoints

List Stores

GET /api/shopify/stores

Returns all connected Shopify stores with stats.

Get Store Settings

GET /api/shopify/stores/:storeId/settings

Returns points configuration for a store.

Update Settings

PATCH /api/shopify/stores/:storeId/settings

{
  "pointsPerDollar": 2,
  "roundingMode": "FLOOR",
  "excludeShipping": true,
  "excludeTax": true,
  "excludeGuestCheckout": true,
  "minOrderAmount": 25.0,
  "productOverrides": {
    "gid://shopify/Product/123": { "multiplier": 2.0 }
  }
}

Embed the loyalty widget in your Shopify theme:

{% if customer %}
<script src="https://cdn.useloyalty.app/widget/useloyalty-widget.iife.js"></script>
<script>
  // Fetch auth from your app proxy
  fetch('/apps/useloyalty/widget-auth')
    .then(r => r.json())
    .then(auth => {
      UseLoyaltyWidget.init({
        ...auth,
        member: {
          email: '{{ customer.email }}',
          name: '{{ customer.name }}'
        }
      });
    });
</script>
{% endif %}

2. App Proxy Setup

Configure Shopify app proxy to route /apps/useloyalty/* to your widget auth endpoint.

Troubleshooting

Points Not Awarded

Check order is paid (not pending)
Verify customer has an account (if guest excluded)
Check minimum order amount
Review webhook delivery in Shopify admin

Webhook Errors

GET /api/shopify/webhooks/logs

Check recent webhook deliveries and errors.

Duplicate Points

The system uses idempotency keys to prevent duplicates:

Each order can only award points once
Check ShopifyOrderTransaction table for existing record

Data Model

ShopifyStore

{
  id: string;
  projectId: string;
  shopDomain: string;
  shopName: string;
  accessToken: string; // Encrypted
  isActive: boolean;
  connectedAt: Date;
}

ShopifyOrderTransaction

{
  id: string;
  storeId: string;
  memberId: string;
  shopifyOrderId: string;
  orderNumber: string;
  customerEmail: string;
  orderTotal: Decimal;
  eligibleAmount: Decimal;
  pointsEarned: number;
  status: "PENDING" | "PROCESSED" | "REFUNDED" | "PARTIALLY_REFUNDED";
  refundedAmount: Decimal;
  pointsRefunded: number;
}

Best Practices

1. Set Appropriate Points Rate

Low value (1 point = $1): Easy to earn, high redemption
High value (1 point = $10): Harder to earn, lower redemption

2. Use Collection Multipliers

Boost slow-moving inventory:

{
  "clearance-collection": { "multiplier": 2.0 }
}

3. Run Multiplier Events

Create urgency with time-limited bonuses:

"Double Points Weekend" - 2x multiplier, Fri-Sun

4. Test Webhook Delivery

Use Shopify's webhook testing to verify integration:

Go to Settings → Notifications → Webhooks
Click "Send test notification"
Verify receipt in useLoyalty logs

Shopify Integration

On this page