> ## Documentation Index
> Fetch the complete documentation index at: https://docs.komerza.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup Shopify

> Configure Shopify payments on your Komerza store

Accept payments through Shopify on your Komerza store. Komerza creates draft orders on your Shopify store and redirects customers to Shopify's hosted checkout to complete payment.

## Prerequisites

* A [Shopify store](https://www.shopify.com/) with an active plan
* Access to the [Shopify Dev Dashboard](https://dev.shopify.com/dashboard/)

<Steps>
  <Step title="Create an app in the Shopify Dev Dashboard">
    1. Go to the [Shopify Dev Dashboard](https://dev.shopify.com/dashboard/)

    2. Click **Create an app** and give it a name (e.g. "Komerza Integration")

    3. Set the **App URL** to `https://dashboard.komerza.com`

    4. Add this **Allowed redirection URL** - exactly as written, with no trailing slash:

       ```
       https://dashboard.komerza.com/shopify/callback
       ```

    5. In **Access scopes**, paste:

       ```
       write_draft_orders,read_draft_orders,read_orders,write_orders
       ```

    6. Set the **Webhook version** to `2026-04`

    7. Click **Create app**

    <Warning>
      The allowed redirection URL is the step people miss. Shopify requires the
      exact callback URL to be registered on the app before it will show the
      install screen, so without it authorization fails no matter how correct
      your credentials are.
    </Warning>

    <Note>
      All four scopes are required. Missing any of them will cause connection
      errors later.
    </Note>
  </Step>

  <Step title="Copy your credentials">
    Open the app's **Settings** and copy the **Client ID** and **Client secret**.

    <Note>
      Keep these secure - they grant access to your Shopify store's order data.
    </Note>
  </Step>

  <Step title="Connect Shopify to Komerza">
    1. In your Komerza dashboard, go to **Settings** → **Payment Methods** → **Shopify**
    2. Enter your **Shop URL**: your `myshopify.com` domain only, e.g. `mystore.myshopify.com`
    3. Paste the **Client ID** and **Secret** from the previous step
    4. Click **Connect Shopify**

    <Warning>
      The Shop URL must be the bare `mystore.myshopify.com` domain. Do not
      include `https://`, do not add a trailing slash, and do not use your
      custom storefront domain or the `admin.shopify.com/store/...` address from
      your browser's address bar - none of those work for authorization or for
      creating orders.
    </Warning>
  </Step>

  <Step title="Authorize the connection">
    1. You'll be redirected to Shopify to approve the app's permissions
    2. Click **Install app** on the Shopify authorization screen
    3. You'll be redirected back to your Komerza dashboard - the connection is now active

    <Warning>
      Finish this step. Saving your credentials makes Shopify available at your
      checkout, but orders cannot be created until authorization completes - so
      an abandoned connection leaves customers unable to pay.
    </Warning>

    The status will show:

    * **Active** - Everything is connected and working
    * **Inactive** - Authorization has not completed, or the credentials are wrong
  </Step>
</Steps>

## How It Works

1. A customer selects Shopify at checkout
2. Komerza creates a draft order on your Shopify store
3. The customer is redirected to Shopify's hosted checkout to complete payment
4. Once payment is confirmed, Komerza automatically marks the order as delivered

## Managing Payments

* **Refunds** - You can issue refunds through Komerza. The refund is processed via the Shopify Orders API and reflected in both platforms.
* **Webhooks** - Komerza listens for order and refund events from Shopify to keep everything in sync.

## Disconnecting Shopify

Go to **Settings** → **Payment Methods** → **Shopify** and click **Disconnect**. Your existing orders are not affected - only new checkouts will no longer offer Shopify.

## Troubleshooting

| Problem                                                      | Fix                                                                                                                                                                     |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization fails, or Shopify rejects the redirect         | Add `https://dashboard.komerza.com/shopify/callback` to your app's **Allowed redirection URL(s)**. It must match exactly, with no trailing slash                        |
| "Missing required permissions" error                         | Make sure all four access scopes are set on the app, then reconnect                                                                                                     |
| Customers see "This store's payment method is misconfigured" | Your Shop URL is not a bare `mystore.myshopify.com` domain. Re-enter it without `https://`, without a trailing slash, and without a custom domain                       |
| Shopify appears at checkout but orders fail                  | Authorization was never completed. Reconnect and finish the **Install app** step on Shopify                                                                             |
| Webhooks not firing                                          | Verify your app has the `read_orders` scope - Shopify requires it for order and refund webhook subscriptions. Webhooks are only registered once authorization completes |
| "Please configure your Shopify app credentials first"        | Save your Client ID and Secret before clicking Connect                                                                                                                  |