Skip to content
Help Center Guide · Pass Distribution
4 min readVerified 2026-11-16

Selling Subscriptions

Sell recurring digital memberships, synchronizing Stripe Billing or PayPal Subscriptions with pass expiration dates and status changes.

In This Guide

Recurring Membership & Subscription Architecture

For fitness clubs, coworking spaces, transit networks, subscription boxes, and professional associations, digital wallet passes act as dynamic, real-time membership credentials. Unlike static cards, a subscription pass in Apple Wallet and Google Wallet can update its expiration date, membership status, and barcode validity automatically as recurring billing cycles succeed, fail, or cancel.

Passinstance synchronizes subscription billing agreements (from Stripe Billing, PayPal Subscriptions, or custom subscription backends) with the pass lifecycle using automated webhook handlers and silent push notifications:

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
RECURRING SUBSCRIPTION LIFECYCLE SYNC
STAGE 01 CUSTOMER BILLING SUBSCRIPTION ENGINE
Stripe Billing | PayPal Subscriptions | Custom Recurring Engine
STAGE 02 PASSINSTANCE WEBHOOK LISTENER (/webhooks/billing)
Matches incoming subscription ID or customer email to Pass.externalId
STAGE 03 (Renewal Success) | (Payment Failed) | (Cancelled)
1
EXTEND EXPIRATION
Update expirationDate to new period end
Push silent APNs
Push Google update
2
GRACE PERIOD ALERT
Update field:
"Payment Overdue"
Push lockscreen alert
Allow scanner grace
3
EXPIRE OR VOID PASS
Set status: EXPIRED or voided: true
Barcode crossed out
Scanner rejects scan

Linking Payment Subscriptions to Pass Records

To ensure seamless recurring lifecycle synchronization, each pass must be bound to the customer's subscription record using the externalId field:

  1. 1
    When Customer Subscribes: When an initial subscription is created in Stripe or PayPal, your backend or Passinstance's checkout integration captures the subscription ID (e.g. sub_1Q8xYz2e...) or customer ID (e.g. cus_987654...).
  2. 2
    Binding to externalId: Passinstance stores this ID in Pass.externalId.
  3. 3
    Setting Initial Expiration: The pass's initial expirationDate is set to the Unix timestamp of current_period_end from the billing provider.

Webhook Lifecycle Events & Automated Actions

Passinstance listens to recurring billing webhooks and triggers corresponding pass state updates:

1. Subscription Renewed (invoice.payment_succeeded / BILLING.SUBSCRIPTION.RENEWED)

When a monthly or annual subscription payment succeeds:

  • Action: Passinstance locates the pass matching externalId and extends pass.expirationDate to the new billing cycle end date.
  • Field Update: Any dynamic field displaying {validUntil} or {membershipExpiry} updates to the new date.
  • Push Notification: Apple Wallet receives a silent APNs update; Google Wallet updates the object via REST. The lockscreen may display a subtle update banner (e.g. "Membership renewed through March 31").

2. Payment Failed / Past Due (invoice.payment_failed / INVOICE.PAYMENT_FAILED)

If a recurring charge fails due to an expired credit card or insufficient funds:

  • Action: The pass remains active during your configured grace period (e.g. 7 days).
  • Field Update: An auxiliary or secondary field updates from "ACTIVE" to "PAYMENT PAST DUE".
  • Alert Notification: A push notification is sent to the customer's device: "Please update your payment method to keep your membership active."

3. Subscription Cancelled or Terminated (customer.subscription.deleted / BILLING.SUBSCRIPTION.CANCELLED)

When a customer terminates their subscription:

  • Action: At the conclusion of the paid billing period, Passinstance updates the pass status to EXPIRED or sets pass.voided = true.
  • Visual Deactivation: Apple Wallet crosses out the check-in barcode and displays a "Pass Voided" badge. Google Wallet marks the card as expired.
  • Scanner Rejection: Physical validation at gym turnstiles or front desks via Passinstance Scanner immediately displays a red screen with EXPIRED or VOIDED.

Step-by-Step Setup: Connecting Stripe Billing to Passinstance

Step 1: Connect Stripe in Workspace Settings

  1. 1
    Navigate to Settings -> Integrations -> Payments in the Passinstance dashboard.
  2. 2
    Connect your Stripe account.

Step 2: Register the Stripe Webhook Endpoint

In your Stripe Dashboard -> Developers -> Webhooks, add an endpoint pointing to Passinstance:

TEXT
https://api.passinstance.com/api/v1/webhooks/stripe-billing

Select the following events:

  • invoice.payment_succeeded
  • invoice.payment_failed
  • customer.subscription.created
  • customer.subscription.updated
  • customer.subscription.deleted

Step 3: Configure Subscription Pass Expiration Rules

In your Pass Template settings:

  1. 1
    Open Functionalities -> Expiration & Validity.
  2. 2
    Select Dynamic Subscription Expiration.
  3. 3
    Choose the post-cancellation behavior: Expire Pass (remains in wallet history) or Void Pass (crosses out barcode immediately).

Managing Subscription Status with Passinstance Scanner

When gym staff or venue hosts scan a member's pass using the Passinstance Scanner App (Passinstance Scanner):

Subscription StateScanner ScreenScanner ResponseResult
Active & PaidGreen ScreenVALIDMember admitted. Displays customer name and active tier.
Payment Past Due (Grace Period)Amber ScreenWARNINGStaff alerted: "Grace period active. Prompt member to update card."
Cancelled / ExpiredRed ScreenEXPIREDTurnstile remains locked. Displays "Membership expired on [Date]".
Revoked / VoidedRed ScreenVOIDEDCheck-in blocked. Displays "Card has been voided by issuer".

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.