Square

The Square integration connects Square subscription memberships to RemyPass wallet passes.

Use this integration when customers buy or manage memberships through Square subscriptions and you want RemyPass to issue, update, and end digital passes automatically.

Square support is subscription-focused. RemyPass listens for Square subscription and customer events, applies your plan-to-pass mappings, and keeps the linked wallet pass aligned with the customer's subscription state.

What RemyPass Does

• Reads Square customers and subscription plan variations from your connected Square account.
• Matches a Square customer to an existing RemyPass member or creates a new member from the Square customer record.
• Issues the RemyPass pass template mapped to the customer's Square subscription plan.
• Optionally emails the issued pass to the customer. If email delivery is off, the pass can still be shared using the pass link.
• Updates the linked pass when the Square subscription becomes active, pauses, is cancelled, or is completed.
• Stores Square subscription metadata on the pass, including subscription ID, status, start date, plan variation ID, and calculated expiry date.
• Supports Square-specific pass fields such as subscription status, subscription start date, customer ID, plan name, and plan variation name.
• Updates a linked RemyPass member's name or email when Square sends a customer update for a customer whose reference_id matches the RemyPass barcode value.
• Refreshes passes that use a mapped subscription plan name when Square sends a catalog update after the seller renames the plan.
• Marks the integration as disconnected and requiring reauthorization when Square reports OAuth access has been revoked.
• Records processed Square events so repeated webhook deliveries do not create duplicate passes.

Data RemyPass Uses

RemyPass requests Square access for customers, catalog items, and subscriptions. That lets RemyPass:

• Read Square customers so it can create or match RemyPass members.
• Read subscription plan variations so you can map Square plans to RemyPass pass templates.
• Read subscription events so RemyPass knows when to issue, reactivate, deactivate, expire, or revoke a pass.
• Write the Square customer reference_id to the RemyPass barcode value. This helps link future Square customer updates back to the correct RemyPass member and pass.

Square access and refresh tokens are encrypted before storage.

Before You Connect

Make sure you have:

• Administrator access in RemyPass.
• A Square account with subscription plans configured.
• Customer records in Square with usable contact details, especially email addresses if you want RemyPass to email passes.
• A RemyPass pass template for each subscription membership you want to issue.
• Dynamic pass fields if you want Square data, such as the subscription status or start date, to appear on the wallet pass.

Setup Overview

1. Open Integrations in RemyPass.
2. Choose Square and connect your Square account.
3. Open Configure Square.
4. Enable Handle Square subscriptions.
5. Map each Square subscription plan variation to the RemyPass pass template that should be issued.
6. Choose whether passes issued from active subscriptions should be emailed automatically.
7. Add field mappings if pass fields should be filled from Square customer or subscription data.
8. Save the settings and test with one subscription before using the integration broadly.

Subscribe your Square webhook endpoint to subscription.created, subscription.updated, customer.updated, catalog.version.updated, and oauth.authorization.revoked.

Webhook Events

RemyPass handles these Square webhook events:

Square event	What RemyPass does
subscription.created	Checks the subscription plan mapping and issues the mapped pass when the subscription is active.
subscription.updated	Updates the linked pass when the subscription changes state, renews, pauses, cancels, or completes.
customer.updated	Updates linked member details when the Square customer can be matched to a RemyPass pass.
catalog.version.updated	Refreshes mapped Square plan names if plan names are used on passes.
oauth.authorization.revoked	Marks Square as disconnected and requires the integration to be reauthorized.

Every Square event is recorded. Events that are duplicated, missing required data, or not matched to a configured mapping are retained as ignored or failed events so you can audit what happened.

Subscription Lifecycle

When Square sends a subscription event, RemyPass checks your mappings before changing a member or pass.

Square subscription state	RemyPass behavior
Active	Creates or updates the member, issues or reactivates the mapped pass, stores Square subscription fields, and updates wallet passes already added to a device.
Paused	Applies the cancellation action configured for the mapping. The common setup is to deactivate the linked pass so it can no longer be used.
Cancelled	Applies the configured cancellation action, such as deactivating, expiring, revoking, or doing nothing.
Completed	Ends the linked pass according to the configured cancellation action.

If a Square event does not match a configured plan mapping, RemyPass records it as ignored and does not issue a pass.

Field Mapping

Field mappings let you copy Square customer or subscription values into RemyPass pass fields. Use them when a pass should display Square data or when you want Square data stored as pass custom fields.

Common Square sources include:

• Customer ID, name, email, phone number, and reference ID.
• Subscription ID, status, start date, and timezone.
• Subscription plan variation ID, plan variation name, and plan name.

Common pass fields include:

• Member name and member email.
• Square customer ID and Square customer reference ID.
• Square subscription ID, status, and start date.
• Square plan name, plan variation name, and plan variation ID.

RemyPass also stores core Square subscription fields automatically on Square-issued passes, even if you do not add field mappings for every field.

If a pass uses the subscription plan name as a mapped dynamic field, Square plan renames are applied after RemyPass receives catalog.version.updated.

Pass Delivery

When a Square subscription becomes active, RemyPass can email the issued pass automatically. This is controlled by Email passes issued from active subscriptions in Configure Square.

If automatic email delivery is disabled, RemyPass can still issue the pass. You can share the Apple Wallet or Google Wallet pass link separately.

Recommended Test Plan

Before enabling Square for all plans:

1. Create a test Square subscription plan variation.
2. Map that variation to a test RemyPass pass template.
3. Add any dynamic Square fields you expect to show on the pass.
4. Create or update one Square subscription and confirm the event appears in View Events.
5. Confirm the member, pass status, expiry behavior, and wallet field values in RemyPass.
6. Add the pass to Apple Wallet or Google Wallet and confirm updates are pushed after a subscription change.

Troubleshooting

Use Configure Square -> View Events in RemyPass to review Square events that RemyPass has processed.

If a pass was not issued:

• Check that Handle Square subscriptions is enabled.
• Check that the Square subscription plan variation is mapped to a valid pass template.
• Confirm the Square customer has enough contact data to create or match a RemyPass member.
• Review the event log to see whether the event was processed, ignored, or failed.
• Contact RemyPass support with the Square customer ID, subscription ID, and expected pass behavior.

FAQ

Does the Square integration support one-off Square purchases?

Square support is currently focused on Square subscriptions. Pass issuance is driven by Square subscription events and plan variation mappings.

What happens if Handle Square subscriptions is turned off?

RemyPass keeps the Square connection, but subscription handling is disabled. Subscription mappings and subscription delivery settings are not applied until handling is turned back on.

Does RemyPass create duplicate passes if Square retries a webhook?

No. RemyPass records processed Square event and subscription IDs so repeated webhook deliveries do not issue duplicate passes.

What if a Square subscription plan is not mapped?

The event is recorded as ignored. RemyPass does not create a member or issue a pass until that Square plan variation is mapped to a RemyPass pass template.

What happens when a subscription is paused or cancelled?

That depends on the cancellation action configured for the mapping. You can configure RemyPass to do nothing, deactivate the pass, expire the pass, or revoke the pass.

Can passes still be issued if automatic email delivery is disabled?

Yes. Email delivery only controls whether RemyPass sends the pass email automatically. The pass can still be issued and shared using the pass link.

Can Square data appear on the Apple Wallet or Google Wallet pass?

Yes. Add Square data fields to the pass design, such as subscription status, subscription start date, plan name, or subscription ID. RemyPass resolves those fields when generating and updating wallet passes.

What happens if a Square plan name changes?

When RemyPass receives catalog.version.updated, it refreshes mapped plan names and updates linked passes that use those plan-name fields.

What happens if Square access is revoked?

RemyPass marks the Square integration as disconnected and requiring reauthorization. Reconnect Square from the Integrations page to resume subscription updates.

How do I investigate a missing pass?

Open Configure Square -> View Events and find the relevant Square event. The event log shows whether it was processed, ignored, or failed, and usually explains missing customer data, duplicate delivery, or missing plan mappings.