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:
  • Order Details - Customer journey data, UTM parameters, and line item details
  • Order Performance - Order metrics like sales, quantities, and financial data
  • Marketing Attribution - Marketing attribution data
  • Order Items Performance - Order items performance data
  • Order Item Details - Order item details data
  • Customer Profiles - Customer profiles 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., "Order Details" for customer journey data)
2. Choose a lookback period or specific historic date range
3. Preview the query to confirm configuration
4. Execute extraction

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 Dimension Tables

Order Details Schema

Field	Description
order_id	Order ID (primary key)
order_name	Order name (typically #1001, etc.)
legacy_id	Legacy resource ID
confirmation_number	Order confirmation number
created_at	Order creation timestamp
processed_at	Order processing timestamp
updated_at	Order update timestamp
closed_at	Order closed timestamp
cancelled_at	Order cancellation timestamp
financial_status	Order financial status (paid, pending, etc.)
fulfillment_status	Order fulfillment status
cancel_reason	Reason for cancellation if applicable
is_closed	Whether the order is closed
is_confirmed	Whether the order is confirmed
is_paid	Whether the order is fully paid
is_tax_exempt	Whether the order is tax exempt
taxes_included	Whether taxes are included in prices
is_test_order	Whether this is a test order
currency_code	Order currency code
presentment_currency_code	Presentment currency code
phone	Customer phone number
email	Customer email
note	Order notes
tags	Order tags
po_number	Purchase order number
client_ip	Client IP address
source_identifier	Source identifier
has_estimated_taxes	Whether the order has estimated taxes
requires_shipping	Whether the order requires shipping
customer_id	Customer ID reference

Order Line Item Details Schema

Field	Description
order_id	Order ID
order_name	Order name
line_item_id	Line item ID (unique with order_id)
sku	Product SKU
line_item_title	Line item title
product_id	Product ID
product_title	Product title
variant_id	Product variant ID
variant_title	Product variant title
vendor	Product vendor
custom_attribute_keys	Custom attribute keys
custom_attribute_values	Custom attribute values
is_taxable	Whether the item is taxable
requires_shipping	Whether the item requires shipping
is_gift_card	Whether the item is a gift card
selling_plan_name	Selling plan name if applicable

Customer Profiles Schema

Field	Description
customer_id	Customer ID (primary key)
first_name	Customer first name
last_name	Customer last name
email	Customer email
phone	Customer phone number
verified_email	Whether email is verified
accepts_marketing	Whether customer accepts marketing
created_at	Customer creation timestamp
updated_at	Customer update timestamp
orders_count	Number of orders placed
tax_exempt	Whether customer is tax exempt
tags	Customer tags
currency	Customer preferred currency
locale	Customer locale
default_address_id	Default address ID
default_address_address1	Default address line 1
default_address_address2	Default address line 2
default_address_city	Default address city
default_address_company	Default address company
default_address_country	Default address country
default_address_country_code	Default address country code
default_address_country_name	Default address country name
default_address_province	Default address province/state
default_address_province_code	Default address province/state code
default_address_zip	Default address ZIP/postal code
default_address_name	Default address name
default_address_phone	Default address phone

Shopify Fact Tables

Marketing Attribution Schema

Field	Description
order_id	Order ID (primary key)
order_name	Order name
created_at	Order creation timestamp
processed_at	Order processing timestamp
order_value	Order total value
source_url	Referring source URL
customer_order_index	Customer order sequence number
first_visit_id	ID of customer's first visit
first_landing_page	First landing page URL
first_referrer_url	URL that first referred the customer
first_source	Marketing source of first visit
first_source_description	Description of marketing source for first visit
first_source_type	Type of marketing source for first visit
first_utm_campaign	UTM campaign parameter from first visit
first_utm_content	UTM content parameter from first visit
first_utm_medium	UTM medium parameter from first visit
first_utm_source	UTM source parameter from first visit
first_utm_term	UTM term parameter from first visit
last_visit_id	ID of customer's last visit before purchase
last_landing_page	Last landing page URL
last_referrer_url	URL that referred the customer on last visit
last_source	Marketing source of last visit
last_source_description	Description of marketing source for last visit
last_source_type	Type of marketing source for last visit
last_utm_campaign	UTM campaign parameter from last visit
last_utm_content	UTM content parameter from last visit
last_utm_medium	UTM medium parameter from last visit
last_utm_source	UTM source parameter from last visit
last_utm_term	UTM term parameter from last visit

Order Items Performance Schema

Field	Description
order_id	Order ID
line_item_id	Line item ID
day	Order date
quantity	Quantity ordered
price	Item price
total_discount	Total discount amount
pre_tax_price	Pre-tax price
tax_amount	Tax amount
tax_rate	Tax rate
total_price	Total price

Order Performance Schema

Field	Description
order_id	Unique order identifier (primary key)
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