> For the complete documentation index, see [llms.txt](https://merchant-help.violet.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://merchant-help.violet.io/platform-guides/shopify.md). # Shopify ## Prerequisites You must have a minimum Shopify plan of `Basic` to be able to connect with Violet. {% hint style="success" %} **Shopify Plan Changes** Shopify subscription plan upgrades and downgrades can happen in place without any interruptions, so long as a minimum plan of `Basic` is maintained. {% endhint %} {% hint style="info" %} **API Version Change Notices from Shopify** If you receive a notice from Shopify about future changes to the Shopify API that may impact Violet's connection to your store, you can ignore those. Shopify sends these out well in advance of deprecations and Violet will always ensure that the connection to your store remains in a healthy state. {% endhint %} *** {% hint style="warning" %} **Important: Channel Pre-Registration Now Available** As of January 2026, Shopify requires all new merchant connections to use single-merchant custom apps. Many channel partners now **pre-register** merchants, which means: * **If you received a Violet Connect link from your channel partner**: Your app is likely already created! Click the link and follow the simple authorization process (2 minutes). * **If you haven't received a link**: Contact your channel partner first - they may need to pre-register you. * **Only follow the manual setup below if**: Your channel partner specifically instructed you to create your own app. [Learn more about the pre-registration process →](https://github.com/violetio/docs/blob/main/channel-docs/ecom-platforms/shopify/merchant-onboarding.md) {% endhint %} {% hint style="warning" %} **Using Global-E for International Orders?** If your store uses Global-E (or Shopify's Managed Markets powered by Global-E) as the Merchant of Record for international orders, please notify your channel partner while onboarding. Orders placed through Violet bypass Global-E's checkout, which means Global-E cannot act as the Merchant of Record for those transactions. Your channel partner will need to configure your integration accordingly to avoid tax compliance gaps. [Learn more about Global-E and Shopify →](https://github.com/violetio/docs/blob/main/channel-docs/ecom-platforms/shopify/global-e.md) {% endhint %} ## Quick Start: Pre-Registered Merchants If your channel partner has pre-registered your store, onboarding takes just 2 minutes: 1. **Click the Violet Connect link** provided by your channel partner 2. **Verify your email** with the verification code sent to you ![Violet Connect Login](/files/QhMU1YepLMN2e0N8uSnv) ![Violet Connect 6-digit Code Authentication](/files/XLjQ2BbbBsim8oHBQdaC) 3. **Confirm your store URL** is correct ![Violet Connect Pre-registration Detected](/files/2uXPQA9CTbsFZk1zsxRI) 4. **Click "Connect to Shopify"** and authorize the app ![Shopify Install App OAuth Handshake](/files/bx0YiVmQIkAUthU3Svgb) ![Shopify OAuth Handshake Redirect to Violet Connect](/files/4lcRoC9IxywNf3AnQMFR) 5. **Complete payout setup** if required That's it! Your store is now connected. The manual setup below is only needed if not pre-registered. *** ## Manual Setup Guide (Advanced) This guide is for merchants who need to manually create a Custom App in their Shopify dashboard. **Most merchants should use the pre-registration method above instead.** During this process, you will create a Custom App in your Shopify dashboard and then provide the generated credentials to Violet through the Violet Connect onboarding tool. You will retain full control of the created Custom App and can modify or remove it at any time from within your Shopify dashboard. *Total time for completion is around 5 minutes.* {% embed url="" %} *** ### Step 1: Creating the Custom App 1. From your Shopify dashboard navigate to Settings → Apps and sales channels → Develop Apps. 2. Click the green Create an app button. 3. In the modal that appears, enter an app name (ex. Violet) and select the user in your system who should be the owner of this app. Typically this is the default selected user. *** ### Step 2: Configuring Scopes From the `App development` view click on the **Configuration** tab. {% hint style="info" %} Any topics with a `write_*` scope will automatically include the equivalent `read_*` scope. This is by design from Shopify. {% endhint %} #### Admin API Scopes Click **Configure** or **Edit** in the `Admin API integration` section. The following Admin access scopes are the minimum required for Violet to perform all necessary functions against your store. If any additional scopes are required by certain channels within Violet, these will be communicated to you when you enable the channel. Violet uses these permissions to do three things: (1) sync your product catalog and inventory so channel partners can accurately display your products, (2) submit orders placed on those channels into your store so they appear alongside your other orders, and (3) report fulfillment and refund status back to the channel so shoppers stay informed. {% hint style="success" %} **Only 5 of these scopes involve write access:** four are used exclusively for orders and customer records created through Violet, and one (`write_publications`) publishes your products to the sales channels you connect through Violet. Violet never modifies your existing product data, prices, inventory, discounts, store settings, or theme. {% endhint %} **Products & Inventory (read-only)** | Scope | Why Violet needs it | | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `read_products` | Syncs your product titles, descriptions, images, variants, and prices so channel partners can display and sell them. | | `read_inventory` | Keeps stock levels in sync so channels stop selling an item the moment you run out — preventing oversells. | | `read_locations` | Shopify tracks inventory per location; this lets Violet total available stock across all of your locations. | | `read_metaobject_definitions`, `read_metaobjects` | Products can reference custom data ("metaobjects") such as size charts or material details; this lets that content appear on channel listings. | | `read_locales`, `read_translations` | For multi-language stores, ensures products display in the correct language on each channel. | **Publications** | Scope | Why Violet needs it | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `read_publications` | Reads which sales channels (publications) your products are published to. | | `write_publications` | Publishes your products to the sales channels you connect through Violet, so channel partners can list them. This is the only product-related scope that involves write access. | **Orders & Checkout (used only for orders placed through your connected channels)** | Scope | Why Violet needs it | | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `write_draft_orders`, `read_draft_orders` | Draft orders are how Violet calculates shipping and taxes and places an order in your store — the same mechanism as manually creating an order in your admin. | | `write_orders`, `read_orders` | After an order is placed, Violet marks it as paid, records cancellations and refunds, and keeps its status in sync with the channel. Violet only writes to orders it created. | | `write_merchant_managed_fulfillment_orders` | Lets Violet place a **fulfillment hold** on an order it created when the order needs your review (e.g., suspected fraud) — so it isn't shipped before you've checked it. Never used on orders from your other sales channels. | **Customers** | Scope | Why Violet needs it | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `write_customers`, `read_customers` | When a shopper checks out on a channel, Violet creates (or matches by email, to avoid duplicates) the customer record so the order appears in your admin like any other. Violet does not export or sync your customer list. | **Shipping & Fulfillment (read-only)** | Scope | Why Violet needs it | | ------------------- | ------------------------------------------------------------------------------------------------------ | | `read_shipping` | Reads your shipping zones and rates so shoppers see your real shipping options and prices at checkout. | | `read_markets` | Reads the countries and regions you sell to, so checkout only accepts addresses you actually ship to. | | `read_fulfillments` | Reads tracking numbers and fulfillment status so shoppers receive shipping updates from the channel. | **Discounts (read-only)** | Scope | Why Violet needs it | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `read_discounts`, `read_price_rules` | When a shopper enters one of your discount codes at checkout, Violet validates it against your discount rules and applies the correct amount. Violet never creates or edits your discounts. | **Optional Admin API Scopes** | Scope | Why Violet needs it | | --------------------- | -------------------------------------------------------------------------------------------------------- | | `read_legal_policies` | Lets your refund and return policies be shown to shoppers at checkout. | | `read_returns` | Detects when an order placed through Violet is returned, so the channel can process the matching refund. | {% hint style="info" %} Webhook subscriptions should be left in the default state with the latest version being selected. {% endhint %} #### Storefront API Scopes (Optional) Click **Configure** or **Edit** in the `Storefront API integration` section. The Storefront API is the same public API your online store's theme uses — it only exposes data already visible to any shopper on your site. Violet uses it for high-volume cart operations because it scales better than the Admin API. | Scope | Why Violet needs it | | ---------------------------------------- | --------------------------------------------------------- | | `unauthenticated_write_checkouts` | Creates shopping carts as shoppers browse on the channel. | | `unauthenticated_read_product_listings` | Reads public product data while building carts. | | `unauthenticated_read_product_inventory` | Checks stock availability while building carts. | **Summary of access** * All inventory, shipping, and discount scopes are **read-only**, and Violet never edits your existing product data. * Write access is limited to orders and customer records **created through Violet**, plus publishing your products to the sales channels you connect (`write_publications`). * You retain full control: the app can be uninstalled from your Shopify admin at any time, immediately revoking all access. *** ### Step 3: API Credentials From the app view click **API credentials** then click **Install App** **Access Token** This token is used to authenticate requests made by Violet when interacting with your store. Important: this value can only be viewed once. It’s recommended that you copy and paste it into a temporary location until you finish the Violet onboarding process. If you lose this value before completing the Violet onboarding process you must uninstall the create app and start over. **API Key** This key is used in combination with the API Secret Key to verify and authenticate certain actions or events. **API Secret Key** This key is used in combination with the API Key to verify and authenticate certain actions or events. **Storefront API Access Token (Optional)** {% embed url="" %} An optional key used for authenticating requests to the Storefront API once you've enabled Storefront API access. Pass the `Private access token` generated into Violet Connect's `Storefront API Access Token` field *** ### Step 4: Provide Configured App Credentials to Violet Once your app is fully configured, it’s time to return to the Violet Connect onboarding tool and enter the following credentials created in the previous steps: * Access Token * API Key * API Secret Key Once entered, click the **Next** button to validate the credentials and complete the connection between your store and Violet. If the credentials are invalid you should check for any spaces or other copy/paste errors and try again. Upon success you will be redirected back to the channel who first sent you to Violet. *** --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://merchant-help.violet.io/platform-guides/shopify.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.