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

# Shopify

> Read and write Shopify store data — products, orders, customers, and inventory — through Archie's GraphQL API.

The Shopify integration connects your Archie app to a Shopify store. Once configured, you can read and update products, orders, customers, and inventory through namespaced GraphQL operations and react to store events via webhooks.

<Note>
  A typed TypeScript SDK for integrations is coming with the next archie-app release. This page documents the GraphQL operation surface available today.
</Note>

## Enable the integration

Open **Integrations** in the left sidebar and pick Shopify.

You'll need a Shopify Partner app or a custom app installed on your store (Shopify Admin → **Apps and sales channels → Develop apps**). From the app's settings:

* **API Key** — under **API credentials**.
* **API Secret** — same place. Used to authenticate API calls and verify webhook signatures.
* **Store URL** — your shop's `.myshopify.com` domain (e.g. `acme.myshopify.com`).
* **Environment** — `Development` or `Production`, so credentials route to the right environment.

Optional:

* **Access Token** — set this if you want to skip the OAuth handshake and use a direct admin token from a private app.
* **Webhook Secret** — separate from the API secret; used specifically to verify Shopify webhook payloads.

Secrets are encrypted with AES-256-GCM at rest.

## What you can do

The integration covers the most common Shopify Admin API surfaces:

* **Products** — list, get, create, update, delete; manage variants and metafields
* **Orders** — list, get, create, update, fulfill, refund, cancel
* **Customers** — list, get, create, update, search
* **Inventory** — read and adjust stock levels per location
* **Webhooks** — subscribe to store events from your Archie app

## Reading and writing data

### List products

```graphql theme={null}
query {
  shopify_products(first: 25) {
    edges {
      node {
        id
        title
        status
        totalInventory
        priceRange {
          minVariantPrice { amount currency }
          maxVariantPrice { amount currency }
        }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}
```

### Create an order draft

```graphql theme={null}
mutation {
  shopify_createDraftOrder(input: {
    customerId: "gid://shopify/Customer/12345"
    lineItems: [
      { variantId: "gid://shopify/ProductVariant/67890", quantity: 2 }
    ]
    note: "Manual order from internal CRM"
  }) {
    id
    invoiceUrl
  }
}
```

### Update inventory

```graphql theme={null}
mutation {
  shopify_adjustInventory(input: {
    inventoryItemId: "gid://shopify/InventoryItem/...."
    locationId: "gid://shopify/Location/...."
    delta: -1
  }) {
    available
  }
}
```

### Search customers

```graphql theme={null}
query {
  shopify_searchCustomers(query: "email:ada@example.com") {
    edges {
      node {
        id
        firstName
        lastName
        email
        ordersCount
        totalSpent
      }
    }
  }
}
```

## Webhooks

In Shopify Admin, go to **Settings → Notifications → Webhooks** and add the events you want, pointing each at the Archie-generated Shopify webhook URL for your project. Archie verifies the HMAC signature using your webhook secret before storing or dispatching the event.

Common events to subscribe to:

* `orders/create`, `orders/paid`, `orders/cancelled`, `orders/fulfilled`
* `products/create`, `products/update`, `products/delete`
* `customers/create`, `customers/update`
* `inventory_levels/update`
* `app/uninstalled` (so you can clean up if your app is removed)

See [Webhooks](/features/backend/integrations/webhooks) for receiving events in custom functions.

## FAQ

<AccordionGroup>
  <Accordion title="Custom app vs. Partner app — which should I use?">
    For a single store, a custom app inside Shopify Admin is simpler. For multi-store distribution or a public app on the Shopify App Store, you need a Partner app with OAuth. Both work with this integration; the credentials are the same shape.
  </Accordion>

  <Accordion title="Why are IDs in the format `gid://shopify/...`?">
    Shopify's GraphQL Admin API uses Global IDs. The legacy REST IDs (numeric) and GraphQL IDs are interchangeable — Archie accepts either format, but the GraphQL form is what comes back in responses.
  </Accordion>

  <Accordion title="How do I sync product changes from Shopify into my Archie data model?">
    Subscribe to `products/update` and `products/create` webhooks. In the handler, upsert into your Archie data model. For initial sync, paginate `shopify_products` until `hasNextPage` is false.
  </Accordion>

  <Accordion title="What about rate limits?">
    Shopify rate-limits the Admin API on a leaky-bucket model — roughly 2 requests per second on standard plans, more on Shopify Plus. If you need to do bulk reads, use Shopify's Bulk Operation API rather than paginating manually; the integration exposes `shopify_bulkOperationRunQuery` for it.
  </Accordion>

  <Accordion title="Can I run the integration against a development store?">
    Yes. Development stores work the same as live stores. Use the development store's `.myshopify.com` URL and a custom app installed there, with your integration environment set to `Development`.
  </Accordion>
</AccordionGroup>