Shopify Integration for Nodus

1. Introduction to the Shopify Integration

What Is This Integration?

The Shopify integration connects your Shopify e-commerce platform data with Nodus, allowing you to extract, analyze, and transform order data, customer information, product details, and other e-commerce metrics. This integration functions as a source connector, bringing your Shopify store data into the Nodus ecosystem for advanced analytics and business intelligence.

Prerequisites:

• An active Shopify store
• API Access Token from a custom Shopify app with read permissions
• Shop name (your Shopify store URL)

Connection Overview:

The integration leverages Shopify's Admin API (REST) and GraphQL API to extract store data. Authentication is handled through API Access Token, and data is extracted based on templates that specify which datasets to retrieve.

2. Platform Setup Documentation (Setup Form for Shopify)

Purpose & Scope

This section covers how to set up the initial connection between Nodus and Shopify by providing the necessary authentication credentials and store details.

Field-by-Field Breakdown:

Integration Name

• Field Name & Label: Integration Name
• Description & Purpose: A descriptive name to identify this Shopify integration within your Nodus account.
• Validation Rules & Format: Text string, required field.
• Examples: "Main Shopify Store", "Brand X Shopify"
• Troubleshooting Tips: Use a descriptive name that clearly identifies the specific Shopify store.

Shop Name

• Field Name & Label: Shop Name
• Description & Purpose: The name of your Shopify store, used to access your store's data.
• Validation Rules & Format: Text string, required field.
• Examples: "your-store-name" (without the .myshopify.com suffix)
• Troubleshooting Tips: This is the subdomain part of your Shopify URL. If your store URL is "your-store-name.myshopify.com", enter "your-store-name".

API Access Token

• Field Name & Label: API Access Token
• Description & Purpose: The authentication token used to access Shopify API.
• Validation Rules & Format: Alphanumeric string, required field.
• Examples: "shpat_123abc456def789ghijk"
• Troubleshooting Tips: This token is created when you set up a custom app in your Shopify admin. Make sure your app has the necessary read permissions.

External Link

• Link Label: "Locate your API Information"
• URL: https://shopify.dev/
• Purpose: Helps users find documentation for creating Shopify apps and obtaining API credentials.

Step-by-Step Guide:

1. Log in to your Shopify admin dashboard
2. Go to Settings > Apps and sales channels > Develop apps > Create an app
3. Give your app a name and configure Admin API scopes (select read-only permissions)
4. Install the app to your store
5. Copy the Admin API Access Token
6. Enter your Shop Name and API Access Token in the Nodus setup form
7. Verify connection and save the configuration

Reference Links:

• Shopify Developer Documentation
• Shopify Admin Dashboard

3. Extraction/Query Configuration (Extraction Form for Shopify)

Purpose & Overview

This section explains how to configure data extraction from Shopify. Shopify offers various templates for extracting different types of store data and metrics.

Template & Field Documentation:

Template Selection

• Field Name & Label: Select a template
• Description & Purpose: Defines which type of Shopify data to extract
• Validation Rules & Format: Dropdown selection, required field
• Available Options:
  • Shopify Orders Dimensions (dim_orders) - Customer journey data, UTM parameters, and line item details
  • Shopify Orders Facts (fact_orders) - Order metrics like sales, quantities, and financial data

Lookback Range

• Field Name & Label: Lookback Range
• Description & Purpose: Specifies how many days back to extract data
• Validation Rules & Format: Dropdown selection, required field
• Available Options:
  • 3-day Range
  • 7-day Range
  • 28-day Range (recommended)
  • 90-day Range (Optimal if 90-day DDA is used)
• Troubleshooting Tips: Larger date ranges may result in longer processing times.

Historic Date Selection

• Field Name & Label: Historic Date
• Description & Purpose: For historical data extraction, specifies a custom date range
• Validation Rules & Format: Date picker, required field
• Troubleshooting Tips: Shopify maintains historical data, but very old data may have limitations.

Workflow & Examples:

1. Select the appropriate template (e.g., "Shopify Orders Dimensions" for customer journey data)
2. Choose a lookback period or specific historic date range
3. Preview the query to confirm configuration
4. Execute extraction

Example Use Cases:

Order Analysis:

• Template: Shopify Orders Facts
• Metrics: Gross sales, net sales, discounts, shipping
• Lookback: 28-day Range

Marketing Attribution:

• Template: Shopify Orders Dimensions
• Data: UTM parameters, customer journey, source data
• Lookback: 90-day Range

Data Mapping & Underlying Models for Shopify

Data Model Overview

The Shopify integration uses both REST API and GraphQL queries to extract data. Each template corresponds to specific API endpoints and data structures.

Schema & Field Mapping

Shopify Orders Dimensions Schema (dim_orders)

Field	Description
id	Order ID
name	Order name (typically #1001, etc.)
createdAt	Order creation timestamp
registeredSourceUrl	Referring URL
customerJourneySummary_customerOrderIndex	Customer's order index (first purchase, repeat customer, etc.)
customerJourneySummary_firstVisit_id	ID of customer's first visit
customerJourneySummary_firstVisit_landingPage	First landing page URL
customerJourneySummary_firstVisit_landingPageHtml	HTML title of first landing page
customerJourneySummary_firstVisit_referralCode	Referral code if used
customerJourneySummary_firstVisit_referralInfoHtml	HTML with referral information
customerJourneySummary_firstVisit_referrerUrl	URL that referred the customer on first visit
customerJourneySummary_firstVisit_source	Marketing source of first visit
customerJourneySummary_firstVisit_sourceDescription	Description of marketing source
customerJourneySummary_firstVisit_sourceType	Type of marketing source
customerJourneySummary_firstVisit_utmCampaign	UTM campaign parameter from first visit
customerJourneySummary_firstVisit_utmContent	UTM content parameter from first visit
customerJourneySummary_firstVisit_utmMedium	UTM medium parameter from first visit
customerJourneySummary_firstVisit_utmSource	UTM source parameter from first visit
customerJourneySummary_firstVisit_utmTerm	UTM term parameter from first visit
customerJourneySummary_lastVisit_id	ID of customer's last visit before purchase
customerJourneySummary_lastVisit_landingPage	Last landing page URL
customerJourneySummary_lastVisit_landingPageHtml	HTML title of last landing page
customerJourneySummary_lastVisit_referralCode	Referral code used in last visit
customerJourneySummary_lastVisit_referralInfoHtml	HTML with referral information from last visit
customerJourneySummary_lastVisit_referrerUrl	URL that referred the customer on last visit
customerJourneySummary_lastVisit_source	Marketing source of last visit
customerJourneySummary_lastVisit_sourceDescription	Description of marketing source for last visit
customerJourneySummary_lastVisit_sourceType	Type of marketing source for last visit
customerJourneySummary_lastVisit_utmCampaign	UTM campaign parameter from last visit
customerJourneySummary_lastVisit_utmContent	UTM content parameter from last visit
customerJourneySummary_lastVisit_utmMedium	UTM medium parameter from last visit
customerJourneySummary_lastVisit_utmSource	UTM source parameter from last visit
customerJourneySummary_lastVisit_utmTerm	UTM term parameter from last visit
lineItems_edges_node_id	Line item ID
lineItems_edges_node_sku	Product SKU
lineItems_edges_node_quantity	Quantity ordered
lineItems_edges_node_title	Product title
lineItems_edges_node_product_id	Product ID
lineItems_edges_node_product_title	Product title
lineItems_edges_node_variant_id	Product variant ID
lineItems_edges_node_variant_title	Product variant title

Shopify Orders Facts Schema (fact_orders)

Field	Description
order_id	Unique order identifier
day	Order date
additional_fees	Additional fees charged
discounts	Discount amount applied
duties	Duty charges applied
gross_sales	Total gross sales amount
net_sales	Net sales amount after discounts
ordered_product_quantity	Total quantity of items ordered
returned_product_quantity	Quantity of returned items
net_product_quantity	Net quantity after returns
orders	Number of orders (typically 1)
shipping	Shipping charges
taxes	Tax amount
tips	Tip amount if applicable
returns	Total returns value
gross_sales_adjustments	Adjustments to gross sales
discounts_adjustments	Adjustments to discounts

5. Troubleshooting & FAQs for Shopify

Common Issues & Error Messages

Authentication Failures

• Error: "Access denied" or "Invalid API token"
• Solution: Verify your API Access Token and ensure your custom app has the necessary read permissions.

Missing Marketing Attribution Data

• Common Causes:
  • Missing UTM parameters in original traffic
  • Customer Journey feature not enabled in Shopify
• Solution: Verify marketing attribution is properly configured in Shopify and UTM parameters are present in your marketing campaigns.

Access Scope Issues

• Error: "Access scope not granted"
• Solution: Ensure your custom app has all the required scopes. For the Orders template, you need at minimum read_orders, read_customers, and read_products scopes.

Contact & Support Information

• Nodus Support: support@nodus.com

API Scope Requirements

For full functionality, your Shopify API token should have the following read scopes:

• read_orders
• read_customers
• read_products
• read_inventory
• read_locations
• read_fulfillments
• read_content
• read_discounts
• read_marketing_events
• read_price_rules

Data Retention & Limitations

• Shopify maintains historical order data indefinitely
• Certain metrics like customer journey data may only be available for more recent orders
• GraphQL API has pagination limits (default 250 items per page)
• ShopifyQL has analytical limitations compared to direct API access