Shopify integration: getting started

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 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.

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 and get the 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 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

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 somewhere safe until you have entered them in Sapera.

Connect the store in Sapera

Open Webshops, click New Webshop and fill in:

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

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.

Each webshop category 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 its collections; it is not deleted.

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:

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

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.