> For the complete documentation index, see [llms.txt](https://docs.perkville.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.perkville.com/integrations/integration-reference/shopify.md).

# Shopify

## Purchase use cases

* **Purchase rules** — Filter by product, variant or payment type; configure refund handling with your Perkville representative.
* **Coupon support** — Shopify supports single-use coupons. This does not add code generation or redemption write access to the standard read-only connection.

## What the Shopify integration supports

The standard Shopify connection is designed to let Perkville read information from Shopify so it can be used as part of your loyalty program. The custom app setup below grants read-only Shopify Admin API scopes.

<details>

<summary>Read Shopify customers, orders, products, locations, and payout data — Yes</summary>

**Standard Shopify connection:** Yes. The setup below grants the corresponding `read_*` scopes.

</details>

<details>

<summary>Write data back to Shopify — No</summary>

**Standard Shopify connection:** No. The standard setup below does not grant Shopify write scopes.

</details>

<details>

<summary>Expose a Perkville Level or Tier to Shopify as a customer tag, metafield, segment, or other Shopify attribute — Not through the standard connection</summary>

**Standard Shopify connection:** Not through this standard read-only connection.

</details>

<details>

<summary>Award or adjust points based on Shopify purchases and refunds — Depends on configuration</summary>

**Standard Shopify connection:** The exact earning, refund, and timing behavior depends on how your Perkville program and integration are configured. Confirm the intended behavior with your Perkville representative when setting up the integration.

</details>

<details>

<summary>Redeem Perkville rewards directly inside Shopify — Not provided by the custom app setup alone</summary>

**Standard Shopify connection:** The custom app setup below does not provide a Shopify redemption experience by itself. Custom workflows may require additional integration work.

</details>

For custom or two-way workflows, see [Integrating Perkville](https://docs.perkville.com/integrations/integrating-perkville.md) and [Automating your program using Perkville's API](https://docs.perkville.com/integrations/integrating-perkville/automating-your-program-using-perkvilles-api.md). Perkville can also use Middle for custom integration workflows when appropriate.

## Integration Steps

Shopify stopped allowing new legacy custom apps on January 1, 2026. New apps are created in the **Dev Dashboard**. Existing legacy custom apps are unaffected by this change. See [Shopify's custom app guidance](https://help.shopify.com/en/manual/apps/managing-apps#manage-legacy-custom-apps).

### Before you begin

Use a Shopify account with permission to develop and install apps. Create the app in the **same Shopify organization as your store**; Shopify's client credentials authentication requires this.

Confirm the connection method with your Perkville representative. A new Dev Dashboard app requires a connection that can obtain and renew access tokens. A connection that only accepts a saved Admin API access token needs an updated authentication setup.

### Creating a custom app

1. From Shopify admin, open **Settings → Apps → Develop apps → Build apps in Dev Dashboard**, or sign in to the [Dev Dashboard](https://dev.shopify.com/dashboard) directly. Select your store's organization.
2. Choose **Apps → Create app → Start from Dev Dashboard**.
3. Name the app **Perkville Custom - YOUR STORE NAME**, then create it.
4. Open **Versions** and configure a version:
   * **App URL:** For this connection, which has no embedded Shopify interface, use `https://shopify.dev/apps/default-app-home`.
   * **Embed app in Shopify admin:** Turn this off if shown.
   * **Webhooks API version:** Select the latest stable version offered.
   * **Scopes:** Add the read-only permissions listed below.
5. Select **Release**. If prompted, add a version name or message and confirm **Release**.

See [Shopify's custom app setup guide](https://help.shopify.com/en/manual/apps/install-setup-apps#create-a-custom-app-using-the-dev-dashboard) and [guidance for apps without an embedded interface](https://community.shopify.dev/t/checking-my-understanding-of-a-headless-app-novice-starting-out-with-graphql/29218).

#### Required Admin API scopes

Keep the following scopes for the standard Perkville connection:

| Scope                           | Access                                            |
| ------------------------------- | ------------------------------------------------- |
| `read_products`                 | Products and variants                             |
| `read_orders`                   | Orders and transactions                           |
| `read_customers`                | Customers                                         |
| `read_locations`                | Store locations                                   |
| `read_shopify_payments_payouts` | Shopify Payments payouts and balance transactions |

These scopes grant read access. Your Perkville representative will confirm any additional permissions needed for a custom workflow. If Shopify displays a customer-data access requirement, share it with your representative so they can help confirm the required access.

By default, `read_orders` covers orders created within the last 60 days. If you need older purchases imported, ask your representative about `read_all_orders` before adding it. See [Shopify's access scope reference](https://shopify.dev/docs/api/usage/access-scopes).

### Install the app on your store

1. Open your app's overview and choose **Install app** in the **Installs** card.
2. Select the store you want to connect.
3. Review the permissions and approve the installation.

The app must have a released version before installation. If you change its scopes later, release the updated version and approve the new permissions in Shopify. See [Shopify's installation instructions](https://shopify.dev/docs/apps/build/dev-dashboard/create-apps-using-dev-dashboard#step-3-install-your-app).

### Share the connection details with Perkville

1. In the Dev Dashboard, open your app's **Settings**.
2. Find **Credentials** and copy the **Client ID** and **Client secret**.
3. Securely provide your Perkville representative with:
   * The **Client ID**.
   * The **Client secret**.
   * Your store's **`myshopify.com` domain**, such as `daisypetsupply.myshopify.com`.
   * Confirmation that the app is installed on that store.
4. Use a secure sharing method such as [OneTimeSecret](https://onetimesecret.com/) for the secret.
5. Your representative will coordinate the connection setup and verification.

Shopify also calls the Client ID an API key and the Client secret an API secret. See [Shopify's credential guide](https://shopify.dev/docs/apps/build/authentication-authorization/manage-credentials).

**New apps do not display a permanent Admin API access token to copy.** With Shopify's client credentials flow, the integration exchanges the Client ID and Client secret for an access token that expires after 24 hours, then requests another token when needed. Your Client secret is not an Admin API access token, and manually sharing a temporary token is not a lasting connection setup. See [Shopify's authentication guide](https://shopify.dev/docs/apps/build/authentication-authorization/client-credentials-grant).

For additional stores, coordinate the app installation and connection details for each store with your Perkville representative.

### Existing legacy custom apps

If your Perkville connection already uses a legacy custom app created before January 1, 2026, you do not need to recreate it because of this change. You can manage it in **Shopify admin → Settings → Apps → Legacy custom apps**. Coordinate any replacement with your Perkville representative to avoid interrupting the connection.

## Your Shopify store name

Typically your Shopify store name does not reflect your public-facing store URL. It will be the subdomain on your MyShopify URL. For example in `daisypetsupply.myshopify.com`, your store name would be `daisypetsupply`.

## FAQ

### Does coupon support allow Perkville to write to Shopify?

No. The standard connection above uses read scopes. Any workflow requiring write access needs separate review and setup.

See the [Shopify partner profile](https://partners.perkville.com/partners/shopify) for additional integration information.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.perkville.com/integrations/integration-reference/shopify.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
