# Shopify

Shopify can be connected to The Wallet Crew through two complementary paths. One path focuses on **in-store enrolment** and customer creation/update in Shopify. The other path focuses on adding an **“Add to Wallet” button** to the online storefront.

<figure><img src="https://3566051324-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWLc8AHXW4tdrAXUBfrYF%2Fuploads%2FISvK0SaulvpXEPYVB9Yw%2Fimage.png?alt=media&#x26;token=de1e929f-91da-41da-99d8-3d9bb0fc354e" alt=""><figcaption></figcaption></figure>

The Shopify integration is different from SFCC / Adobe Commerce (Magento) / PrestaShop integrations. Those platforms typically rely on a custom storefront implementation of the cinto SDK. Shopify offers a maintained integration surface through a dedicated connector and app, which reduces custom code and long-term maintenance.

* **In-store QR registration (The Wallet Crew hosted flow).** A QR code opens a The Wallet Crew registration layout. The flow can create or update the Shopify customer, then issue a wallet pass.
* **Online store “Add to Wallet” button (The Wallet Crew Shopify app).** The Shopify app exposes a theme block that renders an “Add to Wallet” CTA on selected pages.

<details>

<summary><strong>Real-world examples</strong></summary>

* A retail Brand places a QR code near checkout. The flow creates the Shopify customer and issues a loyalty pass.
* A DTC Brand adds an “Add to Wallet” CTA in the account area after login.
* A gift card program shows an “Add to Wallet” CTA on the gift card page after purchase.
* A store uses a QR-driven form to capture consent in-store, then pushes the first pass immediately.

</details>

{% hint style="info" %}
When only the storefront button is needed, jump to [Online store “Add to Wallet” button](#online-store-add-to-wallet-button-shopify-app).
{% endhint %}

### In-store QR registration (The Wallet Crew hosted flow)

This setup connects The Wallet Crew enrolment flow to Shopify’s Admin API. It is typically used when the in-store journey should create or update a Shopify customer record while issuing a wallet pass in the same scan.

#### Summary

* Create a Shopify **custom app** and generate an **Admin API access token**.
* Configure the **Shop URL + token** in The Wallet Crew.
* Add a `shopify` step in `server/flows.yml`.
* Generate a **Redirect** QR code and display it in-store.

#### Prerequisites

* Admin access to your Shopify store.
* Access to The Wallet Crew admin console.
* A pass template already configured in The Wallet Crew.
* A registration **layout** (the page shown after scanning the QR code).

{% stepper %}
{% step %}

### Create a Shopify Admin API token (custom app)

1. In Shopify Admin, go to `Settings` → `Apps and sales channels`.
2. Click `Develop apps` → `Create an app`.
3. Open `Configuration` → `Admin API integration`.
4. Add scopes:
   * `read_customers`
   * `write_customers`
5. Install the app in your store.
6. Copy the **Admin API access token**.

{% hint style="warning" %}
Treat the token like a password. Rotate it if exposed.
{% endhint %}
{% endstep %}

{% step %}

### Configure Shopify in The Wallet Crew

1. In The Wallet Crew backoffice, go to `Integration` → `CRM` → `Shopify`.
2. Paste:
   * **Shop URL** (example: `https://your-shop.myshopify.com`)
   * **Admin API access token**
3. Save.
   {% endstep %}

{% step %}

### Enable Shopify in `server/flows.yml`

In The Wallet Crew backoffice, go to `Settings` → `Advanced Configuration`.

Edit `server/flows.yml` and ensure:

* The provider is enabled in `customerProviders`.
* The `shopify` step runs **before** the `pass` step.

{% code title="server/flows.yml" %}

```yaml
flows:
  - type: userRegistration
    name: user
    steps:
      - type: shopify
      - type: pass
        passType: {{ passType }}
      - type: mail
        mailTemplate: downloadPass

customerProviders:
  - type: shopify
```

{% endcode %}

{% hint style="info" %}
YAML indentation must be exact. One wrong indent can break the whole flow.
{% endhint %}
{% endstep %}

{% step %}

### Create the in-store QR code (Redirect)

1. In The Wallet Crew backoffice, go to `Layouts` → `Redirects`.
2. Create a redirect pointing to your registration layout.
3. Copy the URL or render the QR code.
4. Display it in-store.
   {% endstep %}
   {% endstepper %}

#### Validate the integration

Validation should cover both Shopify customer sync and pass delivery.

1. Scan the QR code from a phone.
2. Complete the registration.
3. Confirm the customer exists (or is updated) in Shopify.
4. Confirm the pass is created and can be added to Apple Wallet / Google Wallet.

#### Troubleshooting

**401 / 403 from Shopify**

* Re-check the app scopes. You need `read_customers` and `write_customers`.
* Re-install the custom app after changing scopes.
* Ensure you pasted an **Admin API access token** (not a storefront token).

**The flow runs, but no Shopify customer is created**

* Ensure `- type: shopify` is in the `userRegistration` flow.
* Ensure `customerProviders` includes `- type: shopify`.
* Validate YAML indentation.

### Online store “Add to Wallet” button (Shopify app)

The Wallet Crew Shopify app exposes an “Add to Wallet” block in the theme editor. This path is often used when an “Add to Wallet” entry point is needed without building a custom module or cartridge, as in SFCC / Magento / PrestaShop projects.

#### Prerequisites

* The Wallet Crew Shopify app installed and enabled.
* A working pass issuance setup in The Wallet Crew (so the button has something to deliver).

{% stepper %}
{% step %}

### Enable the theme block

1. Go to Shopify Admin → `Online Store` → `Themes`.
2. Click `Customize` for the theme you want to edit.
3. Navigate to the page/template where the button should appear.
4. Click `Add section` or `Add block`.
5. Under `Apps`, select **Add to Wallet Button - The Wallet Crew**.
6. Save.
   {% endstep %}

{% step %}

### Test

* On desktop, scan the QR code with your phone.
* On mobile, tap **Add to Apple Wallet** or **Add to Google Wallet**.
  {% endstep %}
  {% endstepper %}

#### Troubleshooting

**The theme block does not appear**

* Ensure the app is installed and enabled.
* Try adding the block on a different template (product vs page vs account).
* Check the theme editor’s `Apps` section (not `Sections`).

### FAQ

<details>

<summary><strong>Can both the in-store QR flow and the online button be used together?</strong></summary>

Yes. The in-store flow is typically used for enrolment and customer creation/update. The storefront button is typically used as an additional entry point in the online journey, often in the account area or post-purchase pages.

</details>

<details>

<summary><strong>Is the Shopify app required for the in-store QR registration flow?</strong></summary>

No. The in-store QR flow relies on a The Wallet Crew hosted layout and the Shopify Admin API token configured in the connector settings. The Shopify app is only required for the theme block (“Add to Wallet” button) scenario.

</details>

<details>

<summary><strong>Which Shopify token is required?</strong></summary>

The connector requires an **Admin API access token** issued by a Shopify **custom app** with `read_customers` and `write_customers` scopes. A storefront token does not work for customer create/update operations.

</details>

<details>

<summary><strong>What’s the main difference compared to SFCC / Magento / PrestaShop integrations?</strong></summary>

Shopify supports a maintained connector and a Shopify app that covers common wallet entry points with minimal custom storefront work. SFCC / Magento / PrestaShop integrations usually require implementing and maintaining the cinto SDK integration in the storefront codebase.

</details>