Skip to content
Help Center Guide · Third-Party Integrations
3 min readVerified 2026-11-16

E-Commerce Integrations

Connect online storefronts via our native Shopware 6 integration or webhook-triggered REST issuance for custom e-commerce stacks.

In This Guide

Overview

Passinstance bridges online e-commerce storefronts and physical retail Point-of-Sale (POS) checkouts so customers can earn loyalty points, redeem promotional vouchers, and spend prepaid gift card balances seamlessly across web and in-store channels. You can connect storefronts using our native Shopware 6 controller suite (/settings/workspace/integrations/shopware in the Dashboard), dedicated Shopify (POST /webhooks/shopify or /v1/automations/webhooks/shopify/:customerId) and WooCommerce (POST /webhooks/woocommerce or /v1/automations/webhooks/woocommerce/:customerId) webhook receivers, or idempotent REST upserts (POST /api/v1/passes/upsert-by-external-id).

Important: Always map your e-commerce platform's immutable Customer ID or Order ID to the pass's externalId field (or pair with idempotencyKey). This ensures that retried order webhooks update the existing wallet pass idempotently rather than issuing duplicate cards.

Storefront-to-Wallet Architecture

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
E-COMMERCE ORDER & LOYALTY SYNCHRONIZATION
PARTICIPATING SYSTEM ACTORS
P1 Online Storefront
P2 Passinstance E-Commerce Layer
P3 Wallet & In-Store POS
STEP CTX CONTEXT Shopware 6 App
STEP 1a REQUEST / ACTION Handshake & Config
›
/v1/integrations/shopware/*
›
(ShopwareRegistration & Admin)
STEP 1b REQUEST / ACTION Order / Cart Hook
›
POST/v1/integrations/shopware/
›
webhooks
STEP 1c REQUEST / ACTION Storefront Pass Widget
›
Shopware Storefront Widget
STEP CTX CONTEXT Shopify / WooCommerce
STEP 2 REQUEST / ACTION POST/webhooks/shopify
›
Verify HMACUpsert Pass|-- 3. Issue / Update Pass
›
or /v1/automations/webhooks/..
›
(externalId = shopify_cust_id)
›
& Push to Wallet
STEP 4 REQUEST / ACTION Redeem In-Store via
STEP 5 RESPONSE Sync In-Store Scan via Webhook
›
<----------------------------------| POST/v1/pos/redeem

1. Native Shopware 6 Integration Suite

Passinstance includes a dedicated backend module and Dashboard console (/settings/workspace/integrations/shopware) for Shopware 6 (/shopware) orchestrated by four specialized controllers and tracked via ShopwareInstallationStatus (PENDING | REGISTERED | CONNECTED | DEACTIVATED | UNINSTALLED):

ControllerMounted PathsKey Operations
Shopware Onboarding API/v1/integrations/shopware/registration, /v1/integrations/shopware/lifecycle/:actionHandles Shopware App System handshake, signature verification, secret rotation, and uninstall transitions (UNINSTALLED).
Shopware Admin API/api/v1/integrations/shopware/admin/*Connects a Shopware sales channel to a Passinstance workspace, maps templates (PassKind) to customer groups, and manages automation rules.
Shopware Storefront Widget/api/v1/integrations/shopware/storefront/*Serves personalized Add to Apple Wallet / Save to Google Wallet badges, guest/order passes, and reservation redemptions (reserve-redemption / capture-redemption).
Shopware Webhook Handler/v1/integrations/shopware/webhooksProcesses checkout.order.placed, order_transaction.state.paid, customer.written, and cancellation/refund hooks to award points or void vouchers.

2. Shopify Integration (POST /webhooks/shopify & Universal Automations)

Connect your Shopify or Shopify Plus store by pointing Shopify webhook subscriptions to https://api.passinstance.com/webhooks/shopify — or configure workspace automation rules via /v1/automations/webhooks/shopify/:customerId (authenticated via X-Shopify-Hmac-Sha256):

Shopify TopicPassinstance Handler Behavior
customers/create & customers/updateProvisions or updates a member loyalty pass matched by externalId: "shopify_customer_<id>".
orders/paidCalculates loyalty points from subtotal_price, increments stamp counters, or issues a purchased digital gift card (prepaid account).
orders/cancelled & refunds/createReverses unearned points from the pass balance or transitions single-use promotional coupons to VOIDED.

Example Shopify Order Webhook Mapping (POST /api/v1/passes/upsert-by-external-id)

When building a custom Shopify middleware or Checkout UI Extension, call the idempotent upsert endpoint directly (the resulting .pkpass automatically inherits the template's configured bundleId certificate):

JSON
{
  "templateId": "tmpl_shopify_vip_loyalty",
  "externalId": "shopify_cust_74920184",
  "attributes": {
    "holderName": "Lukas Weber",
    "email": "lukas.weber@example.com",
    "points": 450,
    "tier": "SILVER",
    "lastOrderNumber": "#1049"
  }
}

3. WooCommerce Integration (POST /webhooks/woocommerce & Universal Automations)

WooCommerce stores connect via https://api.passinstance.com/webhooks/woocommerce or /v1/automations/webhooks/woocommerce/:customerId (verified via the X-WC-Webhook-Signature HMAC-SHA256 header):

  1. 1
    In WordPress Admin, navigate to WooCommerce -> Settings -> Advanced -> Webhooks.
  2. 2
    Create webhooks for Order updated (order.updated), Order completed (order.completed), and Customer created (customer.created).
  3. 3
    Set the Delivery URL to https://api.passinstance.com/webhooks/woocommerce and copy your workspace signing secret.
  4. 4
    When an order reaches completed, Passinstance automatically issues or updates the customer's pass (keyed by externalId) and returns the smart download URL (/s/:token) for inclusion in WooCommerce transactional emails.

Explore additional connectors in Available Integrations, payment providers at /settings/workspace/integrations/payment-providers, and the Shopware Integration Overview.

Related Product & Developer Documentation

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.