Documentation Index
Fetch the complete documentation index at: https://docs.narrativebanking.com/llms.txt
Use this file to discover all available pages before exploring further.
Use this page to set up Shopify, understand the connection flow, and review the data currently supported by Narrative SDK.
Overview
Shopify lets users connect their commerce store through a hosted OAuth flow. After connection, Narrative SDK starts an initial sync for the supported Shopify data scope.What’s new in v1.5.7
Shopify is now part of the supported connected-data experience for commerce users. The connection flow is designed to bring store, order, product, inventory, and location context into Narrative SDK where available. The connection status experience has also been improved. A Shopify connection that is still completing in the provider window should no longer be treated as a failed connection just because the browser reports the window state differently.When to use Shopify
Use Shopify when you want commerce store, order, catalogue, and inventory context alongside other connected data sources. Key outcomes:- a guided user connection flow from the integration experience
- an initial Shopify data load after a successful connection
- store-level context for supported commerce records
- clearer visibility into supported Shopify source data within Narrative SDK
Prerequisites
Before enabling Shopify, confirm:| Requirement | Why it matters | Notes |
|---|---|---|
| Shopify app credentials provisioned for the environment | Required to start and complete the OAuth authorisation flow. | Keep credentials server-side only. |
| Correct redirect URI for the target environment | Shopify callback must return to the correct hosted Narrative SDK endpoint. | Use the environment-specific callback URL configured for the integration. |
| Integration entry point in your deployment model | Users need a clear place to start the Shopify connection flow. | Available from the embedded surface or the hosted standalone application. |
| Tenant user session in place | The platform must associate the Shopify connection with the correct tenant user. | Start the connect action only from an authenticated experience. |
| Store access available to the connecting user | The user must be able to approve access for the Shopify store being connected. | The exact approval options depend on the Shopify account and app configuration. |
Connection flow
Start the connect action from your integration experience
The signed-in user starts the Shopify connect flow from the available integration surface.
Redirect the user to Shopify authorisation
The user reviews and approves the requested Shopify access in the Shopify-hosted OAuth flow.
Complete the callback in Narrative SDK
After approval, Shopify returns the user to the hosted callback endpoint configured for the environment.
Callback behaviour
After the callback, Narrative SDK returns the user to the relevant integration experience with a Shopify success or error status.- On success, the integration is marked as connected and an initial Shopify sync starts for the supported data scope.
- On error, surface a retry path and keep the previous state unchanged until the user completes a successful connection.
- If the Shopify provider window is still in progress, wait for the final connection result before showing a failure message.
- return the user to a location where connection status can be confirmed
- reconcile active integration state immediately after callback completion
- surface a Shopify-specific success or failure state in the integration experience
- avoid assuming the data load is complete at the exact moment the callback succeeds
Setup guide
Redirect URI
Use the Narrative SDK hosted production callback endpoint for Shopify:https://app.narrativebanking.com/api/integrations/shopify/finish
If the redirect URI does not match the configured production callback endpoint, authorisation will fail.
Credential ownership
Treat these values as environment-specific backend configuration:- Shopify client id
- Shopify client secret
- redirect URI
- requested access scope
Data load lifecycle
Initial load after connection
After a successful Shopify connection, Narrative SDK starts an immediate sync for the supported Shopify data scope.Follow-on refresh behaviour
After activation, Shopify data can continue to refresh through the platform’s normal sync lifecycle.What this means for the integration experience
- users should not expect all downstream outputs to update instantly at the exact moment of connection
- the connection can succeed before all supported Shopify records finish loading
- the integration experience should distinguish between connection success and data availability
Supported data
The current supported Shopify data categories are:- Shop
- Orders
- Products
- Inventory
- Locations
Supported data here means the current Shopify sync scope. It does not mean every category appears as a first-class UI view or downstream insight.
Current limitations
The current Shopify scope does not include:- customer ingestion
- discounts as a standalone sync category
- returns as a standalone synced resource
- mapped commerce metrics, insights, or downstream financial outputs
Operational expectations
- Refresh the integrations state after every connect attempt.
- Keep provider-specific messaging aligned with your integration experience.
- Plan support workflows around callback errors, denied consent, or store-access issues.
- Explain that connection status and data readiness are related but not identical states.
Failure handling
| Scenario | Recommended response |
|---|---|
| User cancels or fails authorisation | Return to the integrations surface and offer a clear retry action. |
| Callback completes with error status | Surface a Shopify-specific message and keep the integration marked as not connected. |
| Configuration mismatch between environment and redirect URI | Stop the rollout until environment settings are corrected. |
| Data does not appear immediately after connection | Explain that the initial sync completes asynchronously after a successful connection. |