Shopify Integration

Shopify is the leading e-commerce platform with built-in subscription support through Shopify Subscriptions and third-party apps like ReCharge, Bold Subscriptions, and Loop. LostChurn connects to Shopify via OAuth and processes failed recurring payment events to recover subscription revenue.

Prerequisites

• An active Shopify store on any paid plan (Basic Shopify or higher)
• A subscription app installed on your store (Shopify Subscriptions, ReCharge, Bold Subscriptions, or Loop)
• Store owner or staff permissions with access to Apps and Settings
• A LostChurn account with at least one workspace created

Connection Steps

LostChurn connects to Shopify using OAuth, which means you install LostChurn as a Shopify app directly from your Shopify admin.

1. In your LostChurn dashboard, go to Settings > Integrations and click Connect Shopify.
2. Enter your Shopify store URL (e.g., your-store.myshopify.com) and click Continue.
3. You will be redirected to Shopify's app authorization page. Review the requested permissions:
   • Orders: Read access
   • Customers: Read access
   • Billing: Read access (for subscription data)
   • Webhooks: Read and Write access
4. Click Install app.
5. You are redirected back to LostChurn with the OAuth tokens automatically configured.
6. LostChurn registers the required webhook subscriptions with Shopify. No manual webhook configuration is needed.

Webhook Configuration

When you connect via OAuth, LostChurn automatically registers webhook subscriptions with Shopify. The following webhooks are created:

• Endpoint URL format:

  https://webhooks.lostchurn.com/v1/shopify

• Webhook topics:
  • orders/cancelled
  • orders/paid
  • orders/partially_fulfilled
  • subscription_contracts/create
  • subscription_contracts/update
  • subscription_billing_attempts/success
  • subscription_billing_attempts/failure
  • subscription_billing_attempts/challenged
  • customers/update

If you need to verify or modify the registered webhooks, go to your Shopify admin at Settings > Notifications > Webhooks. You will see the LostChurn webhooks listed there. Do not delete these webhooks or the integration will stop receiving events.

HMAC Verification

Shopify signs every webhook payload with an HMAC-SHA256 signature using your app's shared secret. The base64-encoded signature is sent in the X-Shopify-Hmac-Sha256 HTTP header. LostChurn computes HMAC-SHA256 of the raw request body, base64-encodes the result, and compares it against the header value using a timing-safe comparison. Shopify also sends an X-Shopify-Topic header identifying the event type and an X-Shopify-Webhook-Id header used for deduplication. Requests with missing or invalid signatures are rejected with a 401 response.

Verify Connection

1. After connecting, go to your LostChurn dashboard Events page.
2. LostChurn automatically sends a verification ping during the OAuth flow. You should see a connection_verified event for Shopify.
3. To test with a real event, go to your Shopify admin and create a test order using Shopify's Bogus Gateway:
   • Enable the Bogus Gateway in Settings > Payments > Additional payment methods.
   • Create a subscription order using your subscription app and the bogus gateway.
   • Simulate a payment failure by entering 3 in the credit card number field when using the Bogus Gateway.
4. Confirm the failure event appears in your LostChurn Events feed.

Supported Events

Provider-Specific Notes

Subscription App Compatibility

Shopify's subscription functionality comes from subscription apps rather than Shopify itself. LostChurn is compatible with:

• Shopify Subscriptions (native): Full support via Shopify's Subscription APIs.
• ReCharge: Supported via Shopify's unified subscription webhooks. ReCharge v2024-01+ required.
• Bold Subscriptions: Supported via Shopify's unified subscription webhooks.
• Loop Subscriptions: Supported via Shopify's unified subscription webhooks.

If you use a subscription app not listed above, contact LostChurn support to check compatibility.

Shopify Payments vs. Third-Party Gateways

Shopify supports multiple payment gateways. LostChurn receives subscription billing failure events regardless of which gateway processed the payment, because the webhook events come from Shopify's subscription billing system rather than the gateway directly.

However, retry capabilities vary by gateway:

• Shopify Payments (Stripe-powered): Full retry support. LostChurn can schedule and execute retries.
• Third-party gateways: Retry support depends on the gateway's API capabilities. LostChurn will attempt retries where the gateway supports programmatic charge creation.

Development Stores

Shopify provides free development stores for testing. You can connect a development store to LostChurn to test the integration before deploying to your production store. Development store events are labeled with a development badge in the Events feed.

Shopify API Version

LostChurn targets Shopify API version 2024-10 or later. Shopify requires apps to use an API version released within the last 12 months. LostChurn automatically updates its API version as new stable releases become available.

Rate Limits

Shopify uses a leaky bucket algorithm for rate limiting:

• REST API: 40 requests per app per store, refilling at 2 per second.
• GraphQL API: 1,000 cost points per second.

LostChurn uses the GraphQL Admin API for most operations to maximize throughput. Retry attempts are distributed to stay within the rate limit. If your store has Shopify Plus, higher rate limits are automatically applied.

Multi-Store Support

If you operate multiple Shopify stores, you can connect each store separately in your LostChurn dashboard. Each store appears as a distinct integration with its own events, recovery campaigns, and analytics. Cross-store reporting is available in the LostChurn analytics dashboard.