Appearance
Shopify
The Shopify integration lets a Shopify store use Boxture as its warehouse. Orders placed in Shopify are fulfilled by Boxture, stock levels in Shopify follow Boxture's inventory, and when a parcel leaves the warehouse the customer receives the tracking number from Shopify.
Boxture connects to Shopify as a fulfillment service: in Shopify, Boxture appears as a location that fulfills orders. Shopify sends Boxture fulfillment requests for the items assigned to that location, and Boxture accepts or rejects each request.
Two ways to connect
There are two Shopify integration types. Both are found under Admin › Integration › Third party.
| ShopifyApp Shop | Shopify Shop | |
|---|---|---|
| What it is | The Boxture app, installed by the merchant from Shopify | A custom app that the merchant creates in their own Shopify admin |
| Setup | Mostly automatic once the app is installed | Manual: enter app credentials and switch on webhooks |
| How orders arrive | Boxture checks Shopify every 5 minutes | Shopify notifies Boxture through webhooks and fulfillment requests |
| How stock reaches Shopify | Boxture sends stock levels every 10 minutes | Shopify asks Boxture for stock levels; Sync Inventory pushes them on demand |
| Settings in Shopify | An App settings page inside Shopify admin | None; everything is set in Boxture |
New stores use the ShopifyApp Shop. Existing Shopify Shop integrations can be moved over with the Shopify migration.
What is synchronised
| Data | Direction | When |
|---|---|---|
| Orders (per fulfillment order) | Shopify → Boxture | App: every 5 minutes. Custom app: when Shopify sends a fulfillment request. |
| Cancellations | Shopify → Boxture | When the merchant requests cancellation of a fulfillment |
| Contact details (phone and e-mail) | Shopify → Boxture | When the order is updated in Shopify, as long as the order's contacts can still be edited |
| Products | Shopify → Boxture | App: every 10 minutes and on product webhooks. Custom app: Setup Products and product webhooks. |
| Stock levels | Boxture → Shopify | App: every 10 minutes for changed products, a full pass every 6 hours. Custom app: when Shopify asks, and on Sync Inventory. |
| Fulfillments with tracking | Boxture → Shopify | About a minute after a shipment is shipped |
| Closing fulfillment orders | Boxture → Shopify | When the Boxture order is completed or cancelled |
| Customer data requests and erasure (GDPR) | Shopify → Boxture | App only, when Shopify sends the request |
Refunds and returns are not synchronised.
How Shopify orders become Boxture orders
Shopify splits an order into fulfillment orders, one for each location that ships part of it. Boxture handles only the fulfillment orders assigned to its own fulfillment service location, and creates one Boxture sales order per fulfillment order. If one Shopify order produces several Boxture orders, they share the same customer reference and are linked as related orders.
Checks before an order is accepted
A fulfillment request is rejected in Shopify, with a message explaining why, when:
- the order already exists in Boxture;
- a product on the order cannot be found in Boxture, or no order lines remain;
- the fulfillment order is not assigned to one of Boxture's fulfillment service locations;
- the payment status is not accepted.
Payment status rules:
| Shopify payment status | Accepted? |
|---|---|
| Paid | Always |
| Partially paid | When Accept partially paid orders is on |
| Partially refunded | When Accept partially refunded orders is on |
| Voided | Never |
| Any other status (pending, authorized, unpaid, ...) | When Accept unpaid orders is on |
For the ShopifyApp Shop there is one more rule: unless Read orders older than 60 days is on, fulfillment orders whose order is older than 60 days are skipped.
How fields are mapped
| Boxture | Taken from Shopify |
|---|---|
| Order type and channel | Sales order on the channel "Shopify" |
| Customer reference number | The Shopify order name, for example #1001 |
| Notes | The order note |
| Delivery contact | The fulfillment order's destination, with e-mail and phone from the order when missing |
| Ship at | The fulfillment order's "fulfill by" date, but not earlier than the end of tomorrow |
| Prices and discounts | Per line, in the currency the customer paid in |
| Shipping method | The code of the order's first shipping line, matched against Boxture shipping method codes (see below) |
| Products | Matched per line (see below) |
No Boxture customer record is created for Shopify orders; the customer's details are stored as contacts on the order.
Shipping method. Boxture takes the shipping line's code in capitals and looks for a shipping method with that code. If there is none, it tries the part before " - ": a Shopify shipping rate "DHL - Worldwide" matches the Boxture shipping method with code DHL. The shipping method must be available to the account. When nothing matches, the default shipping method applies (see Shipping › Default shipping method), which can be set per channel.
Products. For the Shopify Shop, Boxture matches the Shopify variant it has linked to a product before, or else the variant's SKU against the product number or a product alias on the "Shopify" channel. For the ShopifyApp Shop, Boxture matches the linked variant, or else the SKU against the EAN/UPC or the product number, among the active products already linked to the integration.
Valid and invalid orders
A valid order is confirmed immediately and continues like any other sales order (see Sales orders). If the order has invalid details, for example an incomplete address, it is still created but put on hold with the reason "invalid order details", and Shopify receives the message "[ATTENTION: ACTION REQUIRED!] Order ... has been put on hold." Correct the order in Boxture and release the hold. See Holds.
Cancellations
When the merchant cancels a fulfillment in Shopify, Shopify sends Boxture a cancellation request:
- If Boxture does not have the order, or it is already cancelled, the request is accepted.
- If the order can still be cancelled, Boxture cancels it and accepts the request.
- If the order is too far along (for example already packed or shipped), Boxture rejects the request with "The order could not be fully cancelled." (custom app) or "Order cancellation failed." (Boxture app), and the warehouse continues.
When an order is cancelled in Boxture, the fulfillment order in Shopify is closed.
WARNING
Cancelling a Shopify order does not cancel it in Boxture by itself. Only a fulfillment cancellation request from Shopify does. If the merchant cancels an order without requesting cancellation of its fulfillment, cancel the order in Boxture too.
Products
Boxture imports products from Shopify per variant with a SKU:
- The product number is the SKU in capitals (for the Boxture app: the SKU, or the barcode if there is no SKU).
- The name is the product title, followed by the variant title when the product has several variants.
- Description, HS code, country of origin, EAN/UPC (if unique), vendor, weight, price and images are copied (custom app).
- Active Shopify products are published in Boxture; products that are no longer active in Shopify, or deleted, are expired.
Products that already exist in Boxture with the same number are linked rather than duplicated. A product alias on the "Shopify" channel can be used when the SKU in Shopify differs from the Boxture product number (custom app).
Kits from Shopify (custom app). A SKU that combines other SKUs with [+] is created as a kit whose components are the products with those SKUs. MUG-01[+]TEA-02 is a kit of one MUG-01 and one TEA-02; MUG-01[+2]TEA-02 is a kit of one MUG-01 and two TEA-02. The component products must already exist in Boxture.
Stock levels in Shopify
Boxture reports the quantity that can be sold. Which inventory counts is set per integration with Inventory report states (custom app; by default available, allocated, picked, picking and packed inventory, so stock already reserved for Shopify orders still counts until it ships). Kits are reported based on the kit inventory and the inventory of their components.
The reported quantity can be reduced with the setting Inventory › Reporting percent, set for the channel "Shopify", and optionally per location or product. With 75%, a product with 100 available is reported to Shopify as 75. See Inventory reporting percentage.
- ShopifyApp Shop: every 10 minutes Boxture sets the "available" quantity in Shopify for products whose inventory changed, and every 6 hours for all products. Sync inventory on the integration does a full update straight away.
- Shopify Shop: Shopify asks Boxture for stock levels at intervals that Shopify decides. Boxture answers from a stock overview it refreshes every 5 minutes. Sync Inventory pushes the current levels to Shopify immediately for every mapped location.
Fulfillment and tracking
When a shipment is shipped in Boxture, Boxture creates a fulfillment in Shopify about a minute later with the shipped quantities, the tracking number, the tracking URL and the carrier name. Shopify then notifies the customer. When the Boxture order is completed or cancelled (for example because some lines were cancelled), the fulfillment order is closed in Shopify.
Setting up the Boxture app (ShopifyApp Shop)
- The merchant installs the Boxture app in Shopify and approves the requested permissions.
- Boxture sets up the connection automatically:
- creates an account named after the store, with an owner user for the store;
- creates the integration with Accept unpaid orders, Accept partially paid orders and Accept partially refunded orders switched on;
- creates a fulfillment service location in Shopify ("BXTAPP" followed by a number) and a matching location in Boxture.
- In Shopify, the merchant assigns the products that Boxture stocks to the Boxture location.
- A Boxture admin can review the integration under Admin › Integration › Third party.
While setup is in progress, the app shows Incomplete integration: "Your store integration is in progress. Contact Boxture support if it does not complete in a few minutes."
App settings in Shopify
Inside Shopify admin, the Boxture app has an App settings card. Each checkbox is saved as soon as it is changed:
- Accept partially paid orders
- Accept partially refunded orders
- Accept unpaid orders
- Read orders older than 60 days
The Customer Data Exports card lists the files Boxture created for customer data requests (see Privacy requests).
The integration screen in Boxture
| Tab | Fields |
|---|---|
| Basic | Name, Endpoint (the store's domain), User, and the switches Accept partially paid orders, Accept partially refunded orders, Accept unpaid orders, Read all orders |
| Shopify app | The Shopify domain, token and access scopes (read-only) |
| Fulfillment services | The Boxture fulfillment service locations in Shopify (read-only) |
The Sync inventory button sends all stock levels to Shopify immediately.
Setting up a custom app (Shopify Shop)
- In Boxture, go to Admin › Integration › Third party, choose Shopify Shop in the create menu, enter a Name, the Host (the store's full myshopify domain), the User and the Origin location (the warehouse location for this store's orders), and save.
- Open the Urls tab. It shows the App url, the Allowed redirection URL and the Application installation url.
- In Shopify admin, the merchant creates a custom app with the App url and the Allowed redirection URL, and copies its client ID and secret.
- In Boxture, enter them as Custom api key and Custom api secret key, and save.
- Open the Application installation url and approve the app in Shopify. Boxture stores the access token and creates a fulfillment service location in Shopify. The Access scopes then appear on the Basic tab.
- On the Location mappings tab, link each Boxture location to its fulfillment service in Shopify. On the Fulfillment services tab you can create, rename or delete Boxture's fulfillment services.
- On the Webhooks tab, switch on the webhooks you need (see below).
- Set the order acceptance switches on the Basic tab and choose Setup Products to import the products.
Basic tab options
| Field | Meaning |
|---|---|
| Accept partially paid orders, Accept partially refunded orders, Accept unpaid orders | Payment status rules, see above. |
| Request fulfillment automatically | When on, Boxture sends fulfillment requests in Shopify for new orders assigned to its location, so the merchant does not need to do so (for example with Shopify Flow). |
| Inventory report states | Which inventory states count as stock in Shopify. |
| Origin location | The Boxture location that ships this store's orders. |
Webhooks
Each webhook has its own switch. Switching it on registers the webhook in Shopify; switching it off removes it.
| Webhook | Effect in Boxture |
|---|---|
| Orders create, Orders updated | Requests fulfillment for new orders (if Request fulfillment automatically is on); updates contact details |
| Fulfillment orders moved | Requests fulfillment when a fulfillment order is moved to Boxture's location |
| Products create, Product listings update | Imports or updates the product |
| Products delete | Expires the product |
| Inventory items update | Re-imports the product |
WARNING
Leave Orders cancelled switched off. Boxture does not process it, and every call is reported as a failure. Cancellations arrive through fulfillment cancellation requests instead.
If a webhook cannot be processed, Boxture fires the messaging event webhook_failure with the topic and the error, so you can be notified by e-mail with a messaging template (see Messaging).
Menu actions
- Setup Products imports all active Shopify products and links them to Boxture products (see Products).
- Sync Inventory pushes current stock levels to Shopify for every mapped location.
Both run in the background; a notification confirms that they have started.
Privacy requests (GDPR)
For the Boxture app, Shopify forwards its customers' privacy requests:
- Customer data request: Boxture collects the contact details and order lines of that customer's orders into a file, shown under Customer Data Exports in the app.
- Customer erasure: Boxture anonymizes the customer's orders, shipments and contacts. See Anonymization.
- Shop erasure (after the app has been uninstalled): Boxture anonymizes all orders and shipments of the store and removes the stored connection.
Shopify migration
Admin › Integration › Third party › Shopify Migration moves a store from a Shopify Shop (custom app) integration to a ShopifyApp Shop (Boxture app) integration without losing the links between Boxture and Shopify records.
- Make sure the merchant has installed the Boxture app, so the ShopifyApp Shop integration exists.
- Open Shopify Migration.
- Select the source (the Shopify Shop) and the destination (the ShopifyApp Shop).
- Click Start Migration. Boxture confirms: "Migration job from ... to ... has been started."
The migration copies, in order, the links for locations, products (variants), fulfillment orders, fulfillment order lines and shipments (fulfillments). The old links are marked as migrated so the old integration no longer acts on them. When the migration is done you receive a notification with the number of migrated and failed items per step.
Monitoring
- The Third party list shows Last order at and the Connection status traffic light per integration. See Connection status.
- Rejected fulfillment requests are visible in Shopify with Boxture's reason.
- Failed background jobs appear under Exceptions.
Who can do what
Integration screens and the Shopify migration are only available to Admins. The store owner user created for a Boxture app installation works in Boxture as an account owner of the store's account: they can see orders, products, inventory and reports for their store. The settings on the app's App settings page can be changed by anyone with access to the app in Shopify admin.