# Shopify Integration Guide

**Complete guide for integrating Shopify with Forter Agentic Orchestration.**

This guide is specifically for merchants using Shopify. For other platforms, see [SFCC Integration](https://docs.forter.com/quickstart-sfcc)  or [Custom Integration](https://docs.forter.com/quickstart-custom) .

## [How It Works](https://docs.forter.com/quickstart-shopify#how-it-works) How It Works

With Shopify integration, Forter:

1. **Pulls your product catalog** via Shopify Admin API
2. **Generates and maintains** the AI-optimized feed automatically
3. **Creates orders** directly in your Shopify store via Admin API Draft Orders

**You provide:** Shopify Admin API Access Token  
**You implement:** Nothing - Forter handles everything

## [Prerequisites](https://docs.forter.com/quickstart-shopify#prerequisites) Prerequisites

Before starting, ensure you have:

**Shopify Store** — Any Shopify plan (Basic, Shopify, Advanced, Plus)

**Admin Access** — Ability to create custom apps or install private apps

**Forter Account** — Contact your Forter representative to enable Agentic Orchestration

**Tax Settings** — Tax collection configured in Shopify

## [Step 1: Create Shopify Admin API Access Token](https://docs.forter.com/quickstart-shopify#step-1-create-shopify-admin-api-access-token) Step 1: Create Shopify Admin API Access Token

You'll need to create a custom app in Shopify to get an Admin API access token.

### [A. Create Custom App](https://docs.forter.com/quickstart-shopify#a-create-custom-app) A. Create Custom App

1. Log in to your Shopify Admin  
2. Navigate to: **Settings > Apps and sales channels**  
3. Click **Develop apps**  
4. If prompted, click **Allow custom app development**  
5. Click **Create an app**  
6. Enter app details:
    - App name: Forter Agentic Commerce  
    - App developer: [Your email]
7. Click **Create app**

### [B. Configure API Scopes](https://docs.forter.com/quickstart-shopify#b-configure-api-scopes) B. Configure API Scopes

1. Click **Configure Admin API scopes**  
2. Select the following scopes:

**Products (Read):**
- ☑ read_products  
- ☑ read_product_listings  
- ☑ read_inventory

**Orders (Read & Write):**
- ☑ read_orders  
- ☑ write_orders  
- ☑ read_draft_orders  
- ☑ write_draft_orders

**Customers (Read & Write - optional, for customer lookup):**
- ☑ read_customers  
- ☑ write_customers

**Locations (Read - for inventory):**
- ☑ read_locations

3. Click **Save**

### [C. Install App and Get Access Token](https://docs.forter.com/quickstart-shopify#c-install-app-and-get-access-token) C. Install App and Get Access Token

1. Click **Install app** in the top right  
2. Click **Install** to confirm  
3. You'll see the **Admin API access token**  
4. **IMPORTANT:** Click **Reveal token once** and copy it immediately - it's only shown once!
5. Store this token securely - you'll need it for the Forter Portal

### [D. Test Your Access Token](https://docs.forter.com/quickstart-shopify#d-test-your-access-token) D. Test Your Access Token

Test with curl to ensure it works:
```bash
# Test product access
curl -X GET "https://your-store.myshopify.com/admin/api/2024-01/products.json?limit=10" \
-H "X-Shopify-Access-Token: YOUR_ACCESS_TOKEN"

# Test draft order creation (dry run)
curl -X POST "https://your-store.myshopify.com/admin/api/2024-01/draft_orders.json" \
-H "X-Shopify-Access-Token: YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "draft_order": {
    "line_items": [
      {
        "variant_id": 123456789,
        "quantity": 1
      }
    ]
  }
}'
```
If successful, you'll receive product/order data.

## [Step 2: Configure in Forter Portal](https://docs.forter.com/quickstart-shopify#step-2-configure-in-forter-portal) Step 2: Configure in Forter Portal

Log in to the Forter Portal and navigate to **Integrations > Shopify**.

### [A. Basic Store Information](https://docs.forter.com/quickstart-shopify#a-basic-store-information) A. Basic Store Information

| Field | Description | Example |
| --- | --- | --- |
| **Store Title** | Your store name | "My Shopify Store" |
| **Store URL** | Your storefront URL | "https://mycustomstore.com" |
| **Logo URL** | URL to your logo | "https://cdn.shopify.com/.../ logo.png" |
| **Currency** | Primary currency | "USD" |
| **Origin Country** | Shipping origin | "US" |
| **Origin Region** | State/region | "CA" |

### [B. Shopify Platform Configuration](https://docs.forter.com/quickstart-shopify#b-shopify-platform-configuration) B. Shopify Platform Configuration

| Field | Description | Example |
| --- | --- | --- |
| **Platform** | Select platform type | "shopify" |
| **Shop Domain** | Your myshopify.com domain | "mycustomstore.myshopify.com" |
| **Admin API Access Token** | From Step 1C | "shpat_..." (encrypted) |
| **API Version** | Shopify API version | "2024-01" (or latest stable) |

**Note:** Use your .myshopify.com domain, not your custom domain.

### [C. Store Policies](https://docs.forter.com/quickstart-shopify#c-store-policies) C. Store Policies

| Field | Description |
| --- | --- |
| **Terms of Service URL** | Link to your terms |
| **Privacy Policy URL** | Link to your privacy policy |
| **Return Policy URL** | Link to your return policy |
| **Return Window (Days)** | Days allowed for returns (e.g., 30) |

### [D. Tax Configuration](https://docs.forter.com/quickstart-shopify#d-tax-configuration) D. Tax Configuration

**Important:** Shopify handles tax calculation automatically based on your Shopify tax settings.

| Field | Description | Example |
| --- | --- | --- |
| **Tax Nexus Regions** | US states where you collect sales tax | ["CA", "NY", "TX"] |

Forter will use Shopify's tax engine for all orders, respecting your configured tax rules.

### [E. Order Management](https://docs.forter.com/quickstart-shopify#e-order-management) E. Order Management

| Field | Description | Example |
| --- | --- | --- |
| **Order Status URL Template** | URL for order tracking | "https://mycustomstore.com/orders/{order_id}" |

The {order_id} placeholder will be replaced with the Shopify order number.

## [Step 3: Payment & Fraud Settings (Optional)](https://docs.forter.com/quickstart-shopify#step-3-payment-fraud-settings-optional) Step 3: Payment & Fraud Settings (Optional)

By default, **you handle payment validation and authorization** on your Shopify store. This section is only needed if you want **Forter to handle fraud detection and payments**.

### [Option A: Merchant-Side Validation/Authorization (Default)](https://docs.forter.com/quickstart-shopify#option-a-merchant-side-validationauthorization-def) Option A: Merchant-Side Validation/Authorization (Default)

**What happens:**

- Forter creates draft orders in Shopify with payment references
- Shopify processes payments through your existing payment gateway
- Shopify handles fraud checks through your existing Shopify settings

**Configuration:** No additional setup needed - this is the default behavior.

**Settings in Portal:**
```js
Enable Forter Validation: false (default)  
Enable Forter Authorization: false (default)  
Enable Forter Capture: false (default)
```

### [Option B: Forter-Side Validation/Authorization (Optional)](https://docs.forter.com/quickstart-shopify#option-b-forter-side-validationauthorization-optio) Option B: Forter-Side Validation/Authorization (Optional)

**What happens:**

- Forter validates orders for fraud before creating them in Shopify
- Forter authorizes/captures payments via Forter Payment Orchestration
- Orders are created in Shopify with completed payment status

**Configuration Required:**
Contact your Forter representative to obtain:

| Field | Description |
| --- | --- |
| **Validation API Key** | Forter fraud detection credentials |
| **Payment API Key** | Forter payment orchestration credentials |

**Settings in Portal:**
```js
Enable Forter Validation: true  
Enable Forter Authorization: true  
Enable Forter Capture: true (or false for manual capture)
```

## [Step 4: Catalog Sync & Testing](https://docs.forter.com/quickstart-shopify#step-4-catalog-sync-testing) Step 4: Catalog Sync & Testing

### [A. Initiate First Sync](https://docs.forter.com/quickstart-shopify#a-initiate-first-sync) A. Initiate First Sync

After configuring Shopify credentials in the portal:

1. Forter automatically tests the Admin API connection
2. Initial catalog sync begins (pulls all products via Admin API)
3. Products are normalized to AI-optimized format
4. Feed is distributed to AI platforms

**Processing Time:**
- < 10,000 products: Minutes
- 10,000 - 100,000 products: Under an hour
- > 100,000 products: A few hours

### [B. Verify Catalog](https://docs.forter.com/quickstart-shopify#b-verify-catalog) B. Verify Catalog

Check that products were synced by updating inventory for a test product:
```bash
curl -X POST \
 https://{site_id}.agentic.checkouttools.com/v1/inventory \
-H "Authorization: Bearer YOUR_FORTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "id": "gid://shopify/ProductVariant/12345678",
  "quantity": 100
}'
```
If the product exists, you'll receive:
```json
{
  "success": true,
  "updated": 1,
  "results": [{"success": true, "id": "gid://shopify/ProductVariant/12345678"}]
}
```

### [C. Test Checkout Flow](https://docs.forter.com/quickstart-shopify#c-test-checkout-flow) C. Test Checkout Flow

Test end-to-end checkout in the test environment:

**1. Create a checkout session:**
```bash
curl -X POST \
 https://{site_id}.agentic.checkouttools.com/checkout_sessions \
-H "Authorization: Bearer sk_test_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: test-001" \
-d '{
  "items": [{ "id": "gid://shopify/ProductVariant/12345678", "quantity": 1 }],
  "buyer": {
    "first_name": "Test",
    "email": "test@example.com"
  }
}'
```

**2. Add shipping and complete order:**
```bash
curl -X POST \
 https://{site_id}.agentic.checkouttools.com/checkout_sessions/{session_id}/complete \
-H "Authorization: Bearer sk_test_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "fulfillment_address": {
    "name": "Test User",
    "line_one": "123 Test St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "US"
  },
  "payment_data": {
    "token": "tok_test_visa_4242",
    "provider": "test"
  }
}'
```

**3. Verify order in Shopify Admin**
The order should appear in: **Shopify Admin > Orders**

## [Step 5: Go Live](https://docs.forter.com/quickstart-shopify#step-5-go-live) Step 5: Go Live

### [Production Checklist](https://docs.forter.com/quickstart-shopify#production-checklist) Production Checklist

Replace test access token with production access token (if different)  
Verify production catalog sync completes successfully  
Test at least one production order end-to-end  
Configure monitoring and alerting  
Enable AI platform distribution (OpenAI, Google, etc.)

### [Monitoring](https://docs.forter.com/quickstart-shopify#monitoring) Monitoring

Use the Forter Portal to monitor:
- **Catalog Health** — Product count, sync status, errors
- **Order Volume** — Checkout sessions, completions, failures
- **Shopify API Usage** — API call volume, rate limits
- **Error Rates** — Failed checkouts, Shopify API errors

## [Troubleshooting](https://docs.forter.com/quickstart-shopify#troubleshooting) Troubleshooting

### ["Invalid access token"](https://docs.forter.com/quickstart-shopify#invalid-access-token) "Invalid access token"
**Solution:**
- Verify token starts with shpat_
- Check token hasn't been revoked in Shopify Admin
- Ensure no extra spaces when copying token
- Regenerate token if necessary (Settings > Apps > Custom apps > [Your app])

### ["Insufficient permissions"](https://docs.forter.com/quickstart-shopify#insufficient-permissions) "Insufficient permissions"
**Solution:**
- Check app scopes include read_products, write_draft_orders, etc.
- Reinstall the app after adding scopes
- Wait a few minutes for permissions to propagate

### [Products not syncing](https://docs.forter.com/quickstart-shopify#products-not-syncing) Products not syncing
**Solution:**
- Test product endpoint with curl
- Check Shopify rate limits (2 requests/second for REST Admin API)
- Verify products are published and active
- Review Forter Portal logs for sync errors

### [Orders not appearing in Shopify](https://docs.forter.com/quickstart-shopify#orders-not-appearing-in-shopify) Orders not appearing in Shopify
**Solution:**
- Verify draft order creation permissions
- Check Shopify Admin for draft orders (may not be auto-completed)
- Review Forter Portal logs for Shopify API errors
- Confirm shop domain is correct (use .myshopify.com)

## [Shopify-Specific Considerations](https://docs.forter.com/quickstart-shopify#shopify-specific-considerations) Shopify-Specific Considerations

### [Rate Limits](https://docs.forter.com/quickstart-shopify#rate-limits) Rate Limits

Shopify Admin API has rate limits:
- **REST API: 2 requests per second** (burst up to 40)
- **GraphQL API: Cost-based** (1000 points per second)

Forter automatically handles rate limiting with exponential backoff.

### [Product Variants](https://docs.forter.com/quickstart-shopify#product-variants) Product Variants

Shopify treats variants as separate items. Forter:
- Syncs all variants as individual products
- Uses Shopify's GraphQL ID format: gid://shopify/ProductVariant/12345678
- Maintains parent product relationships

### [Inventory Tracking](https://docs.forter.com/quickstart-shopify#inventory-tracking) Inventory Tracking

Forter syncs inventory from all Shopify locations. If using multiple locations:
- Specify primary fulfillment location in Forter Portal
- Or use Shopify's default inventory policy

### [Draft Orders vs Orders](https://docs.forter.com/quickstart-shopify#draft-orders-vs-orders) Draft Orders vs Orders

Forter creates **draft orders** which can be:
- Auto-completed (if payment is pre-authorized)
- Manually reviewed and completed by you
- Converted to regular orders via Shopify's workflow

## [Quick Reference](https://docs.forter.com/quickstart-shopify#quick-reference) Quick Reference

### [Required API Scopes](https://docs.forter.com/quickstart-shopify#required-api-scopes) Required API Scopes

```js
read_products
read_product_listings
read_inventory
read_orders
write_orders
read_draft_orders
write_draft_orders
read_locations
read_customers (optional)
write_customers (optional)
```

### [API Endpoints Used](https://docs.forter.com/quickstart-shopify#api-endpoints-used) API Endpoints Used

```js
GET /admin/api/2024-01/products.json
GET /admin/api/2024-01/product_listings.json
POST /admin/api/2024-01/draft_orders.json
PUT /admin/api/2024-01/draft_orders/{id}/complete.json
```

## [Next Steps](https://docs.forter.com/quickstart-shopify#next-steps) Next Steps

- [Catalog & Inventory](https://docs.forter.com/catalog-and-inventory-orchestration)  — Product data synchronization details
- [Checkout & Payments](https://docs.forter.com/checkout-and-payments)  — Payment processing and order management
- [FAQ](https://docs.forter.com/faq)  — Common questions

## [Support](https://docs.forter.com/quickstart-shopify#support) Support

For Shopify-specific integration questions, contact your Forter representative or email support@forter.com.