> ## 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 your Shopify Admin dashboard

<Steps>
  <Step title="Create a Custom App in Shopify">
    1. Log in to your [Shopify Admin](https://admin.shopify.com)
    2. Go to **Settings** → **Apps and sales channels** → **Develop apps**
    3. Click **Create an app** and give it a name (e.g. "Komerza Integration")
    4. Under **Configuration** → **Admin API integration**, click **Configure** and enable the following scopes:
       * `write_draft_orders`
       * `read_draft_orders`
       * `read_orders`
       * `write_orders`
    5. Click **Save**

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

  <Step title="Copy Your API Credentials">
    1. In your Shopify app, go to the **API credentials** tab
    2. Copy the **API key** and **API secret key**

    <Note>
      Keep these credentials 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** (e.g. `mystore.myshopify.com`) 3. Paste
       the **API Key** and **API Secret** from the previous step 4. Click **Save**
  </Step>

  <Step title="Authorize the Connection">
    1. After saving your credentials, click **Connect to Shopify**
    2. You'll be redirected to Shopify to approve the app's permissions
    3. Click **Install app** on the Shopify authorization screen
    4. You'll be redirected back to your Komerza dashboard — the connection is now active

    The status will show:

    * **Active** — Everything is connected and working
    * **Inactive** — Check that your API credentials are correct
  </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                                                                                                                    |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| "Missing required permissions" error                  | Go back to your Shopify app settings and make sure all four API scopes are enabled, then reconnect                     |
| OAuth authorization fails                             | Double-check that your API Key and API Secret are correct — copy them again from the Shopify app's API credentials tab |
| Webhooks not firing                                   | Verify your app has the `read_orders` scope enabled — Shopify requires it for order and refund webhook subscriptions   |
| "Please configure your Shopify app credentials first" | You need to save your API Key and API Secret before clicking Connect                                                   |