--- title: "Shopify integration: getting started" description: "How to connect a Shopify store to Sapera: the Shopify app, setup and settings, choosing products, the first sync, orders, gift cards and troubleshooting." url: https://support.sapera.io/en/articles/765-shopify-integration-getting-started collection: "WebShop (guides)" updated: 2026-11-08 language: en alternates: [da] --- # Shopify integration: getting started How to connect a Shopify store to Sapera: the Shopify app, setup and settings, choosing products, the first sync, orders, gift cards and troubleshooting. ### In short Sapera can be connected directly to a Shopify store, so you maintain your products in one place only. The integration works both ways: - **From Sapera to Shopify:** products, variants, prices, images, tags, webshop categories (as collections, if turned on) and stock are sent to Shopify. - **From Shopify to Sapera:** paid orders are imported and become sales orders. Sapera is the master for products, prices and stock. Changes you make to these fields directly in Shopify are overwritten by the next sync.

What	Direction	How often
Products, variants, prices, images and tags	Sapera → Shopify	When you synchronize, and about 20 seconds after a change when automatic sync is on
Webshop categories as Shopify collections (if Sync categories as collections is on)	Sapera → Shopify	With every product sync
Available stock	Sapera → Shopify	With every product sync, and when stock changes
Paid orders	Shopify → Sapera (as sales orders)	Every 3 minutes
Fulfillment of orders	Sapera → Shopify	When the sales order is completed in Sapera
Gift cards and their balances	Both ways	When a gift card changes in Sapera, and every 10 minutes from Shopify

* * * ### How to access the setup From the hamburger menu in the top left corner, open **Financial**, and in the left menu choose **Webshop**. Here you find **Webshops** (the connection itself), **Webshop categories** (which products to sell) and, under **Shopify**, the **Synchronization operations** screen where you follow the sync. If you cannot see the menu item, you probably do not have permission to it. Contact support. * * * ### Before you start - A Shopify store on a plan that allows custom apps. To sell or sync gift cards, the plan must include gift cards; development stores do not. - The Shopify store must show prices **including VAT**. Orders from stores with prices without VAT are not imported. - In Sapera: the products you want to sell, an organizational unit that will own the sales orders, and (optional) a category with your shipping products. #### Create the Shopify app Sapera can connect to Shopify in two ways, chosen in the **Shopify app type** field on the webshop. New webshops use **Dev Dashboard app (Client ID and secret)**. Since 2026 Shopify no longer allows creating new custom apps in the store admin, so only use **Legacy custom app (Admin API access token)** if you already have such an app. **Dev Dashboard app (recommended)** 1\. Create an app in the Shopify Dev Dashboard under the organization that owns the store, for example named "Sapera". The app must be created by the organization that owns the store. If the app was created as a custom app in the store admin, Shopify rejects the request. 2\. Select the same access scopes as listed below, and release a version of the app. 3\. Also give the app access to **protected customer data** (name, email, phone and address), because the order import uses the customer's details. 4\. Install the app on the store. 5\. Copy the **Client ID** and **Client secret** from the app's settings. The secret is entered in Sapera. Sapera fetches access tokens itself and renews them automatically, so you do not need to store a token. **Access scopes** Both app types use these access scopes: - **write\_products** – create and update products, variants, images and collections - **write\_inventory** – set available stock - **write\_publications** – publish products to a sales channel - **write\_files** – upload product images - **read\_locations** – read the store's stock locations - **read\_orders** – import orders - **write\_merchant\_managed\_fulfillment\_orders** – fulfill orders - **write\_gift\_cards** and **write\_gift\_card\_transactions** – sync gift cards **Legacy custom app (Admin API access token)** 1\. In Shopify admin open **Settings → Apps**, click **Develop apps**, then **Create an app**, for example "Sapera". 2\. Under **Configuration → Admin API integration** select the same access scopes as listed above. 3\. Order import needs the customer's name, email and address, so also request access to **protected customer data** (name, email, phone, address) for the app. 4\. Install the app and copy the **Admin API access token** and the **API secret key**. > Shopify shows the Admin API access token only once. Keep the token and the API secret key somewhere safe until you have entered them in Sapera. * * * ### Connect the store in Sapera Open **Webshops**, click **New Webshop** and fill in:

Field	What to enter
Name	Any name for the webshop.
Webshop type	Shopify.
Organizational unit	The unit that owns the sales orders. Its prices are sent to Shopify, and its stock is used when no stock organizational units are selected.
Automatic sync	Turn on to send changes automatically and to import orders every 3 minutes. Turn it on after the first sync has been checked.
Stock organizational units	The units whose stock is offered in Shopify. Leave empty to use the organizational unit above.
Shipping Category	The Sapera category that holds your shipping products. Order shipping lines are matched to these products (see "Orders").
Shopify store URL	The store address, for example https://your-store.myshopify.com.
Shopify app type	Dev Dashboard app (Client ID and secret) (default) or Legacy custom app (Admin API access token). The fields below change with the choice.
Client ID	Dev Dashboard app only: the Client ID from the app.
Client secret	Dev Dashboard app only: the Client secret from the app.
Admin API access token	Legacy custom app only: the token from the Shopify app.
API secret key	Legacy custom app only: the API secret key from the Shopify app. It is not used yet, but fill it in: Shopify shows it only once, and it will be needed if Shopify is later set up to notify Sapera about changes directly. Today Sapera checks Shopify at regular intervals, which is more stable.
API version	Pick the newest stable version. The button next to the field loads the versions Shopify supports.

Then click **Load Shopify info** to load the store's locations and sales channels, choose the settings described below, and click **Test configuration**. The test shows the store, its currency and time zone, and whether the API version, the access scopes, the location, the sales channel and (when enabled) gift cards are in order. Fix anything marked as missing before the first sync. * * * ### Settings

Setting	What it does	Default
Sales channel	Products are published to this Shopify sales channel, usually the Online Store.	Empty
Brand handling	Vendor field: the product's brand search tag is sent as the Shopify vendor. Do not sync: no vendor is sent. Collection: not supported yet, and the product sync fails if it is selected. Do not select it.	Vendor field
Sync categories as collections	When on, each webshop category becomes a Shopify collection with the same name, and the products are put in the collections they match. Turn it off if you build your own collections in Shopify, for example as automated collections on tags or vendor.	Off
Stock location handling	Sum all units into one location: the stock of all stock organizational units is added up and sent to the chosen Shopify location. Map each organizational unit to a location: pick a Shopify location for each unit; units without a location are not sent.	Sum all units into one location
Allow update of product descriptions	When off, descriptions are only sent when a product is created, so you can edit them in Shopify.	On
Allow update of product images	When off, images are only sent when a product is created.	On
Allow update of product other properties	When off, title, tags and vendor are only sent when a product is created.	On
Create products in draft state	When on, new products are created as drafts and Sapera never changes their status, so you publish them in Shopify yourself. When off, every sync sets synced products to Active.	Off
Continue selling when out of stock	Not used yet. Set the inventory policy in Shopify.	Off
Sync gift cards	Syncs gift cards and allows selling gift card products in Shopify (see "Gift cards").	Off

* * * ### Choose which products to sell Products are chosen through **Webshop categories** (select the webshop at the top). A product is sent to Shopify when it matches any category of the webshop through one of its mappings: - it is in a mapped Sapera category, - it is one of the products picked in a mapping, - it has one of the mapped search tags, or - its manufacturer is one of the mapped manufacturers. Which products are sent to Shopify is decided by the webshop categories. If **Sync categories as collections** is on, each webshop category also becomes a Shopify collection with the same name, holding the products that match it. When a product stops matching every category, it is set to Draft in Shopify and removed from the collections Sapera has put it in. It is not deleted in Shopify, and if it later matches again, it is linked by SKU and updated again. #### How a product looks in Shopify - **Title and description:** the web display name and web description, or the normal ones when these are empty. - **SKU and barcode:** the product or variant number and the GTIN. - **Price:** the current sales price of the organizational unit, converted to the store currency with the Sapera exchange rate. When the product is on sale, the regular price is shown as the compare-at price. - **Variants:** the visible fields of the variant template become Shopify options. Shopify allows at most 3 options. - **Tags:** the product's search tags whose tag type is marked for the web. - **Images:** product images first, then variant images. Images you add directly in Shopify are kept. Products that already exist in Shopify are linked by SKU instead of being created again. * * * ### First synchronization 1\. Open **Webshop categories** and select the webshop. 2\. Click **Synchronize**. The message "Shopify synchronization has been initiated" confirms it is queued. 3\. Follow the progress in **Shopify → Synchronization operations**, tab **Product sync**. When it completes, read the **Summary** for skipped or failed products. 4\. Check a few products in Shopify, then turn on **Automatic sync** for the webshop. **Synchronize** sends the products changed since the last successful sync (all of them the first time). **Force full resynchronization**, available to administrators, sends every product again and also deletes images in Shopify that no product uses any more. > Order import starts from the moment the first product was synced, so older Shopify orders are not imported. * * * ### Automatic sync With **Automatic sync** on, and after the first sync has completed: - product, variant and stock changes are sent to Shopify about 20 seconds after they happen, - when a search tag changes, the products with that tag are updated, - paid orders are imported every 3 minutes, - completed sales orders are fulfilled in Shopify, - gift cards are synced (when enabled). While a manual synchronization runs, automatic updates wait until it finishes. * * * ### Following the synchronization **Shopify → Synchronization operations** shows everything the integration does, one tab per kind of work:

Tab	Shows	Actions
Product sync	Manual synchronizations, with kind (Full / Changes), synced products, times and a summary.	Copy summary, Copy error
Product updates	Automatic product and stock updates.	Re-enqueue failed, Open product, Copy error
Search tag updates	Search tag changes and how many product updates they queued.	Re-enqueue failed, Copy error
Gift card updates	Gift card syncs.	Export gift cards, Re-enqueue failed, Copy error
Order imports	Imported Shopify orders and the sales orders created from them.	Import orders, Reimport order, Show replaced, Copy error
Order exports	Fulfillments sent to Shopify.	Re-enqueue failed, Copy error

* * * ### Orders Every 3 minutes Sapera imports Shopify orders that are **paid and not cancelled**. **Import orders** on the Order imports tab checks right away. Each order becomes a sales order in the webshop's organizational unit: - **Customer:** an existing customer is reused when the email, the name and phone, or the company name match; otherwise a new customer is created from the billing details. - **Lines:** matched to the synced products; products created outside Sapera are matched by SKU and marked "please check correctness". Discounts are kept as line discounts. - **Shipping:** matched to a product in the Shipping Category by its number (the Shopify shipping code) or its name (the shipping title); otherwise the first product in that category is used. Without a Shipping Category, shipping is not imported. - **Stock:** when stock organizational units are set, the line is taken from a unit that has enough stock. - **Reference and notes:** the Shopify order name becomes the customer reference; the order note, payment method and shipping method go to the public note. - **Currency:** the order currency must exist in Sapera and, if it is not the default currency, have an exchange rate for the order date. If some lines cannot be found, the sales order is still created and its internal note lists what is missing. No payment is registered on the sales order. #### Reimporting an order To import an order again, discard its sales order in Sapera, then select it on the **Order imports** tab and click **Reimport order**. The order is read from Shopify again. A failed import is also retried automatically when the order is changed in Shopify. #### Fulfillment When the sales order is **Completed** in Sapera, the order is marked as fulfilled in Shopify (Order exports tab). Shopify does not send the customer a shipping notification for it. > Orders with more than 100 lines: only the first 100 are imported, with a note on the sales order. Refunds and cancellations made in Shopify after an order was imported are not reflected in Sapera. * * * ### Gift cards Turn on **Sync gift cards** in the webshop settings. It also needs: - a Shopify plan that includes gift cards (Test configuration reports "This Shopify plan doesn't include gift cards" otherwise), - **Generate Gift Card Web codes** turned on in the gift card settings, because the web code becomes the Shopify gift card code. The settings show a warning when no organizational unit generates web codes, - Automatic sync. #### Gift cards sold in Sapera - A sold gift card is created in Shopify with the same code and balance. Gift card types that allow only one withdrawal are not synced, because Shopify cannot enforce that. - Withdrawals and discards in Sapera change the Shopify balance. - Money spent in Shopify comes back to Sapera as a withdrawal ("Used in Shopify webshop …"), checked every 10 minutes. - To send existing gift cards once, click **Export gift cards** on the Gift card updates tab. #### Selling gift cards in Shopify The product of a Sapera gift card type is sent to Shopify as a Shopify gift card product when the type has a **fixed amount** and allows multiple withdrawals. When a customer buys it, Shopify issues the gift card and emails it to the customer; the order import registers a matching gift card in Sapera, and its balance is synced from then on. > Gift cards issued by Shopify can be used in Shopify only: Shopify does not reveal their code, so they cannot be redeemed at the POS by web code. If the store does not fulfill gift cards automatically, the order import waits for them: fulfill the gift card lines in Shopify, then reimport the order. * * * ### Troubleshooting

Message	What to do
Test configuration: access scopes "missing …"	Add the scope to the Shopify app, reinstall it and update the token in Sapera if Shopify issued a new one.
"Shopify refused to issue an access token (shop_not_permitted)..."	The Client ID and Client secret must belong to an app created in the Dev Dashboard by the organization that owns the store, and the app must be installed on the store. A custom app created in the store admin cannot be used with this app type.
"Shopify did not accept the Client ID and Client secret, or the app is not installed on the store"	Check the Client ID and secret, and install the app on the store.
"[product] skipped: Product has N variant attributes, Shopify allows at most 3"	Reduce the visible fields of the product's variant template.
"[product] skipped: SKU … is used by N Shopify variants" / "its SKUs are spread over N Shopify products"	Clean up the duplicate SKUs in Shopify, then synchronize again.
"Stock is not synced: no Shopify location is configured"	Choose a Shopify location (or one per unit) in Stock location handling.
"… has prices without VAT, only shops with prices including VAT are supported"	Set the Shopify store to show prices including taxes.
Customer data missing (order import)	Give the Shopify app access to protected customer data.
"No exchange rate defined for …"	Add an exchange rate for the order currency and date, then reimport the order.
"Shopify order … is already imported as sales order …"	Discard that sales order first if the order really has to be imported again.
"… cannot be fulfilled while its fulfillment orders are …"	The order is on hold or already handled in Shopify; resolve it there, then Re-enqueue failed.
"Webshop … has not completed its first Shopify sync"	Run Synchronize once; automatic updates start after it completes.
"Shopify throttled …"	Nothing: Shopify asked Sapera to slow down and the work is retried automatically.

For any failed row, **Copy error** copies the full message for support. * * * _If you need help with the setup, you are always welcome to contact support._ * * * **Want to know more?** Read more in these related articles: [ Webshop categories Create and manage categories in your webshop, and link them with inventory categories and products from Sapera. ](https://support.sapera.io/en/articles/540.md)[ WooCommerce integration: what data is exchanged A complete, non-technical walkthrough of Sapera's WooCommerce integration: which product, stock and price data Sapera sends to the webshop, what comes back when an order is created, and all configuration options. ](https://support.sapera.io/en/articles/579.md)[ Sapera integration to Woo Webshop This guide explains how to create an API user, generate API keys, and synchronize Sapera with WooCommerce ](https://support.sapera.io/en/articles/253.md)[ WebShop settings An overview of the settings for Sapera's webshop integration and how to access them. ](https://support.sapera.io/en/articles/425.md)[ Integrations — webshop, payment and bank An overview of what Sapera can be connected to, and when to take it on. ](https://support.sapera.io/en/articles/674.md)[ Gift cards Manage gift cards in Financial: create, sell, redeem and cancel gift cards, and set up gift card types as templates. ](https://support.sapera.io/en/articles/133.md)[ Settings for gift cards Overview of the settings for gift cards in Sapera, including automatic creation on sale, restriction to the cash register and generation of web codes. ](https://support.sapera.io/en/articles/189.md) ## Related - [Sapera integration to Woo Webshop](https://support.sapera.io/en/articles/253-sapera-integration-to-woo-webshop.md) - [Return an order](https://support.sapera.io/en/articles/325-return-an-order.md) - [WooCommerce integration: what data is exchanged](https://support.sapera.io/en/articles/579-woocommerce-integration-what-data-is-exchanged.md) - [Video library](https://support.sapera.io/en/articles/1-video-library.md) - [Getting started - What do you need to know as a customer?](https://support.sapera.io/en/articles/317-getting-started-what-do-you-need-to-know-as-a-customer.md)