Shopify Adapter
NexusCommerce integration with the Shopify Admin API for storefront and channel management.
Overview
The Shopify adapter connects NexusCommerce to the Shopify Admin API, enabling bidirectional sync of products, inventory, and orders between NexusCommerce and a Shopify storefront. This adapter is designed for sellers who use Shopify as their primary storefront and NexusCommerce for centralized multi-channel management.
Unlike marketplace adapters (Amazon, eBay), the Shopify adapter treats Shopify as a storefront channel, not a third-party marketplace. Products pushed to Shopify appear in your own branded store.
The adapter targets the Shopify Admin API version 2024-10 and uses GraphQL for bulk operations and REST for real-time reads/writes.
Key Concepts
Custom App — NexusCommerce connects to Shopify via a custom app installed on your store. Custom apps use scoped access tokens instead of OAuth user flows, making them stable and non-expiring.
Shopify Product vs. Variant — A Shopify Product is a top-level entity with one or more Variants. NexusCommerce maps its products to Shopify Products and its SKUs to Shopify Variants. A single NexusCommerce product with multiple variants creates one Shopify Product with multiple Variants.
Location — Shopify supports multiple fulfillment locations. Inventory levels are tracked per location. NexusCommerce syncs inventory to a configured primary location by default, with optional multi-location support.
Fulfillment Order — Shopify wraps each order in a Fulfillment Order structure. The adapter uses the Fulfillment Order API to mark shipments, which is required for orders processed after Shopify's transition away from the legacy Fulfillment API.
Getting Started
Required Credentials
| Field | Description |
|---|---|
| Shop Domain | Your store's .myshopify.com domain (e.g., your-store.myshopify.com) |
| Admin API Access Token | Generated when creating the custom app |
Creating the Custom App
- In your Shopify admin, go to Settings > Apps and sales channels
- Click Develop apps (enable developer preview if prompted)
- Click Create an app and name it
NexusCommerce - Under Configuration, click Configure Admin API scopes
- Grant these scopes:
| Scope | Purpose |
|---|---|
read_products, write_products | Sync product catalog |
read_inventory, write_inventory | Manage inventory levels |
read_orders, write_orders | Sync and update orders |
read_fulfillments, write_fulfillments | Submit shipment confirmations |
read_locations | Read fulfillment location IDs |
read_shipping | Read shipping zones and rates |
- Click Save then Install app
- Copy the Admin API access token — it is shown only once
Entering Credentials in NexusCommerce
Navigate to Connections > Add Connection > Shopify, enter the shop domain and access token, then click Test Connection. The test verifies the token and returns the shop name and plan.
Synced Data
| Data Type | Direction | Shopify API | Notes |
|---|---|---|---|
| Products | Read / Write | Admin REST /products | Creates/updates products and variants |
| Product Images | Read / Write | Admin REST /products/{id}/images | Syncs up to 10 images per product |
| Collections | Read | Admin REST /custom_collections | Reads collection assignments |
| Inventory | Read / Write | Admin REST /inventory_levels | Per-location inventory levels |
| Orders | Read | Admin REST /orders | All financial and fulfillment statuses |
| Fulfillments | Write | Admin GraphQL fulfillmentCreate | Marks orders as shipped with tracking |
| Customers | Read | Admin REST /customers | Order customer data |
| Metafields | Read / Write | Admin REST /metafields | Custom product attributes |
Configuration Options
| Key | Type | Default | Description |
|---|---|---|---|
shop_domain | string | required | .myshopify.com domain |
primary_location_id | string | auto-detected | Shopify location ID for inventory sync |
sync_interval_minutes | integer | 30 | Polling frequency |
order_lookback_days | integer | 30 | Historical order import window |
inventory_buffer_pct | integer | 0 | Safety stock reserve |
publish_status | string | active | Default product status on Shopify (active / draft) |
sync_collections | boolean | false | Mirror NexusCommerce categories to Shopify collections |
multi_location | boolean | false | Sync inventory to all locations instead of primary only |
Supported Features
| Feature | Supported | Notes |
|---|---|---|
| Product sync | Yes | Full bidirectional sync |
| Variant sync | Yes | Maps NexusCommerce SKUs to Shopify Variants |
| Image sync | Yes | Up to 10 images per product |
| Inventory updates | Yes | Primary location by default |
| Multi-location inventory | Yes | Enable multi_location config option |
| Order sync | Yes | REST polling + webhooks |
| Shipment confirmation | Yes | Fulfillment Order API |
| Metafields | Yes | Custom attributes stored as metafields |
| Webhooks | Yes | Real-time order and product events |
| Shopify Markets | No | Multi-currency pricing requires Shopify Plus |
| POS orders | Yes | Synced alongside online orders |
| Draft orders | No | Excluded from sync by default |
Webhooks
The Shopify adapter registers webhooks automatically on connection setup. NexusCommerce subscribes to:
| Topic | Trigger |
|---|---|
orders/create | New order placed |
orders/updated | Order status changes |
orders/cancelled | Order cancelled |
products/update | Product edited in Shopify admin |
inventory_levels/update | Inventory changed in Shopify |
fulfillments/create | Fulfillment created outside NexusCommerce |
Webhook payloads are verified using HMAC-SHA256 with the X-Shopify-Hmac-SHA256 header and the shared secret from the custom app.
Webhook URL format:
https://your-nexuscommerce-domain.com/api/webhooks/shopify/<connection-id>Rate Limits & Quotas
Shopify uses a leaky bucket rate limiting model. Standard (non-Plus) limits:
| Limit Type | Value |
|---|---|
| REST API bucket size | 40 requests |
| REST API refill rate | 2 req/s |
| GraphQL query cost | 1,000 points/s |
| Bulk operation concurrency | 1 active operation at a time |
The adapter reads the X-Shopify-Shop-Api-Call-Limit header and throttles when the bucket is above 80% capacity. For large catalog syncs, the adapter switches to GraphQL bulk operations which bypass per-request rate limits.
Shopify Plus stores have higher limits (500 REST bucket, 10 req/s). No configuration is needed — the adapter detects the plan from the shop response.
Troubleshooting
401 Unauthorized — Invalid API key or access token
Access tokens for custom apps do not expire, but they are invalidated if the app is uninstalled and reinstalled. Go to Connections > Edit Credentials and paste the new access token from the reinstalled app.
Products syncing but not appearing on storefront
Check the publish_status config option. If set to draft, products are created but not visible. Change to active and re-sync, or manually publish from the Shopify admin.
Inventory not updating at correct location
The primary_location_id may be pointing to a location that is not the default fulfillment location. Go to Shopify admin > Settings > Locations to find the correct location ID, then update the connection config.
Duplicate products appearing after sync
This happens when the external ID mapping is lost (e.g., after a connection was deleted and recreated). NexusCommerce matches products by SKU on re-sync. Ensure SKUs are unique and consistent across both systems before re-connecting.
Webhooks not firing
Verify that NexusCommerce's webhook endpoint is reachable from the internet. Shopify requires the endpoint to return 200 OK within 5 seconds. Check Shopify admin > Settings > Notifications > Webhooks for delivery failure logs.