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
externalIdfield (or pair withidempotencyKey). This ensures that retried order webhooks update the existing wallet pass idempotently rather than issuing duplicate cards.
Storefront-to-Wallet Architecture
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):
| Controller | Mounted Paths | Key Operations |
|---|---|---|
Shopware Onboarding API | /v1/integrations/shopware/registration, /v1/integrations/shopware/lifecycle/:action | Handles 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/webhooks | Processes 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 Topic | Passinstance Handler Behavior |
|---|---|
customers/create & customers/update | Provisions or updates a member loyalty pass matched by externalId: "shopify_customer_<id>". |
orders/paid | Calculates loyalty points from subtotal_price, increments stamp counters, or issues a purchased digital gift card (prepaid account). |
orders/cancelled & refunds/create | Reverses 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):
{
"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
In WordPress Admin, navigate to WooCommerce -> Settings -> Advanced -> Webhooks.
-
2
Create webhooks for Order updated (
order.updated), Order completed (order.completed), and Customer created (customer.created). -
3
Set the Delivery URL to
https://api.passinstance.com/webhooks/woocommerceand copy your workspace signing secret. -
4
When an order reaches
completed, Passinstance automatically issues or updates the customer's pass (keyed byexternalId) 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.
