This guide explains how to connect your Shopify store to the Newo platform, configure OAuth authentication, and enable your AI agent to look up customer orders by email or phone number.

🗒️ NOTE

This is a read-only integration. The agent can retrieve order information but cannot create, modify, or cancel orders.

What the agent can do

Look up a customer's orders by email and/or phone number
Return the financial status of each order (e.g., paid, pending, refunded, partially_refunded)
Match returning customers by phone number and retrieve their order history

What the agent cannot do

Create, modify, or cancel orders
Browse products or inventory
Provide shipping tracking numbers (financial status is returned, not shipping status)

Requirements

Before beginning setup, confirm you have the following:

An active Shopify store
A Shopify OAuth App with a Client ID and Client Secret
Your store domain (e.g., abcde1-11.myshopify.com)
The Shopify OAuth App configured with the following API scopes:

read_all_orders,read_assigned_fulfillment_orders,write_assigned_fulfillment_orders,read_audit_events,read_customer_events,read_customers,write_customers,read_customer_data_erasure,write_customer_data_erasure,read_customer_payment_methods,read_customer_merge,write_customer_merge,write_draft_orders,read_draft_orders,read_inventory,read_inventory_shipments,read_merchant_managed_fulfillment_orders,write_merchant_managed_fulfillment_orders,write_order_edits,read_order_edits,read_orders,write_orders,read_products,write_products,read_content,customer_read_companies,customer_read_draft_orders,customer_read_orders,customer_write_orders

Step 1: Authorize in Shopify

The OAuth flow establishes a secure, token-based connection between the Newo platform and your Shopify store.

In the Newo Builder, navigate to Attributes and set the following fields:
shopify_shop_id
shopify_client_id
shopify_client_secret
shopify_redirect_url (set to https://static.newo.ai/auth.html)
Click Save + Publish All. After 1–2 seconds, refresh the page — the shopify_oauth_code attribute will appear with the authorization link in its description.
Click the authorization link inside the shopify_oauth_code attribute description.
Log in to your Shopify store admin when prompted.
Review the permissions and authorize the Newo app. Accept the agreement.
On the redirect page, click Copy Code to copy the verification code.
Return to the Builder and paste the code into the shopify_oauth_code attribute field.

⚠️ CAUTION

The OAuth authorization code is single-use. If it expires or is used incorrectly, you must repeat the entire authorization flow to generate a new code.

Step 2: Configure attributes in the platform

Open Newo and go to Projects.
Select the relevant project and navigate to Builder > Attributes.
Set the following attributes:

Attribute	Required	Description
`shopify_shop_id`	Yes	Store domain ID (e.g., `abcde1-11` from `abcde1-11.myshopify.com`)
`shopify_client_id`	Yes	OAuth2 Client ID from your Shopify app
`shopify_client_secret`	Yes	OAuth2 Client Secret from your Shopify app
`shopify_redirect_url`	Yes	Redirect URL for the OAuth callback — use `https://static.newo.ai/auth.html`
`shopify_oauth_code`	Yes	One-time OAuth authorization code obtained in Step 1
`shopify_base_url`	No	Store API URL — auto-generated from `shopify_shop_id` if left blank
`shopify_timezone`	No	Store timezone — defaults to the project timezone if not set

Click Save + Publish All.

After 1–2 seconds, refresh the page. If the shopify_oauth_code attribute disappears, the OAuth token exchange completed and the integration is connected successfully.

On publish, the platform automatically:

Exchanges the OAuth code for access and refresh tokens
Constructs the base API URL from the shop ID
Creates HTTP connectors for the Shopify API
Registers the order lookup tool (shopify_check_order_tool) with the agent

How it works

When a customer asks about their order status, the agent invokes the shopify_check_order_tool. The integration follows this sequence:

Extracts the customer's email and/or phone number from the conversation
Searches Shopify customers using an OR query across both identifiers (if both are available)
If a matching customer is found, retrieves all their orders with financial status details
Returns the results to the agent, which relays the information to the customer

The agent decides when to invoke the order lookup tool based on conversation context, typically when a customer asks about order status. The tool is triggered when the agent explicitly says: "I'm checking your order right now. Please give me a moment, and I'll get back to you shortly." This exact phrase is required — without it, the order lookup will not execute.

Order information returned

Each order returns the following fields:

Field	Description
`order_id`	The Shopify order identifier
`financial_status`	Payment status: `paid`, `pending`, `refunded`, or `partially_refunded`

Test the integration

Test through the Newo conversation interface (chat or voice channel). The agent must have access to the customer's email or phone number — either collected during the conversation or detected from caller ID.

Setup verification — Publish the project and confirm the OAuth token exchange completes without errors.
Customer search — Start a conversation and provide an email or phone number. Verify a Shopify customer is matched.
Order lookup — Ask "What's my order status?" and verify orders are returned with the correct financial statuses.
No customer found — Test with an unknown email or phone number and verify the agent responds appropriately.
Token refresh — After token expiration, verify the integration automatically refreshes the token and retries successfully.

Troubleshooting

If the agent does not look up orders or the integration does not activate after publish:

Confirm shopify_shop_id, shopify_client_id, and shopify_client_secret are all set correctly.
Verify shopify_access_token is populated after publish — if it is empty, the OAuth exchange failed.
Confirm the shopify_oauth_code was valid and had not already been used. Authorization codes are single-use.
Check that shopify_base_url is correctly formed: https://{shop_id}.myshopify.com.
Verify the customer's email or phone number is available in the conversation persona.
Re-publish the project if any credentials were changed after the initial setup.

Frequently asked questions

Can the integration create or modify orders? No. This is a read-only integration. Orders can only be viewed — they cannot be created, modified, or cancelled through the agent.

What customer identifiers are used for lookup? The integration searches by email and/or phone number. If both are available, it uses an OR query across both. If only one is available, it searches by that field alone.

What order information is returned? Each order returns the order_id and financial_status (e.g., paid, pending, refunded, partially_refunded). The agent relays these details to the customer.

What happens if the OAuth token expires? The integration automatically detects HTTP 401 responses and uses the refresh token to obtain a new access token. It retries the failed request up to three times. A separate HTTP connector handles token operations to keep them isolated from order queries.

Can I connect multiple Shopify stores? Each integration instance supports one Shopify store, identified by shopify_shop_id. To connect multiple stores, create separate project instances.

What Shopify app scopes are required? The OAuth app must have all scopes listed in the Requirements section enabled. The full list includes read_customers, read_orders, read_all_orders, and additional scopes for customers, inventory, products, and fulfillment operations.