Shopify Integration

SDK

Shopify/shopify-api-js

The platform syncs orders to Shopify for fulfillment management. When a customer completes checkout on the Next.js storefront, the order is pushed to Shopify via the Admin REST API. Shopify then handles fulfillment, inventory tracking, and shipping label generation.

Architecture

Next.js Storefront -> Order Created -> syncOrderToShopify()
  -> ShopifyAdminClient.createOrder() -> Shopify Admin API
  -> Order record updated with Shopify IDs

The Shopify integration consists of three modules:

File	Purpose
`lib/shopify/client.ts`	ShopifyAdminClient class and order transformation
`lib/shopify/sync.ts`	Order sync orchestration
`lib/shopify/webhook.ts`	Webhook signature verification and status mapping

Environment Variables

Variable	Description	Required
`SHOPIFY_STORE_DOMAIN`	Shopify store domain (e.g., `my-store.myshopify.com`)	Yes
`SHOPIFY_ADMIN_API_TOKEN`	Shopify Admin API access token	Yes
`SHOPIFY_API_VERSION`	API version (defaults to `2024-10`)	No
`SHOPIFY_WEBHOOK_SECRET`	Webhook HMAC signing secret	Yes

Setup

Create a Shopify Custom App

In the Shopify admin, go to Settings > Apps and sales channels > Develop apps. Create a custom app with the following scopes:

write_orders
read_orders
write_fulfillments
read_fulfillments

Install and get the access token

Install the app in your store and copy the Admin API access token.

Configure environment variables

SHOPIFY_STORE_DOMAIN=josemadridsalsa.myshopify.com
SHOPIFY_ADMIN_API_TOKEN=shpat_...
SHOPIFY_API_VERSION=2024-10
SHOPIFY_WEBHOOK_SECRET=your_webhook_secret

Register webhooks

Create webhooks in the Shopify admin pointing to https://your-domain.com/api/webhooks/shopify for these topics:

orders/create
orders/updated
orders/paid
orders/cancelled
fulfillments/create
fulfillments/update

Order Transformation

The transformOrderForShopify() function converts a Prisma order (with items, addresses, and user) into Shopify's order format:

Field Mapping

Prisma Field	Shopify Field
`items[].productName`	`line_items[].title`
`items[].unitPrice`	`line_items[].price` (formatted to 2 decimals)
`items[].quantity`	`line_items[].quantity`
`shippingAddress`	`shipping_address`
`billingAddress`	`billing_address`
`paymentStatus`	`financial_status` (mapped via `PAYMENT_STATUS_MAP`)
`shippingCost`	`shipping_lines[].price`
`tax`	`total_tax`
`discountAmount`	`total_discounts`

Payment Status Mapping

Prisma Status	Shopify Status
`PENDING` / `PROCESSING`	`pending`
`SUCCEEDED` / `PAID`	`paid`
`FAILED` / `CANCELED`	`voided`
`REFUNDED`	`refunded`
`PARTIALLY_REFUNDED`	`partially_refunded`

Metadata

Each Shopify order includes:

Tags: Jose Madrid Salsa, Next.js Storefront
Note attributes: orderNumber and orderId (used for webhook matching)
inventory_behaviour: 'decrement_obeying_policy'
Receipt and fulfillment emails are disabled (send_receipt: false)

ShopifyAdminClient

A singleton client accessed via getShopifyClient(). Methods:

`createOrder(order)`

Creates a Shopify order from a Prisma order. Returns { success, order?, error? }.

`cancelOrder(shopifyOrderId, reason?)`

Cancels a Shopify order with optional restock and reason.

`getOrder(shopifyOrderId)`

Retrieves a Shopify order by ID, including fulfillment and tracking data.

Order Sync

File: lib/shopify/sync.ts

`syncOrderToShopify(orderId)`

Checks if Shopify is configured (skips silently if not)
Fetches the full order with items, addresses, and user
Calls ShopifyAdminClient.createOrder()
On success: updates the order with shopifyOrderId, shopifyOrderName, shopifySyncedAt, and appends sync info to adminNotes
On failure: stores the error in shopifySyncError

`queueShopifySync(orderId)`

Fire-and-forget wrapper that calls syncOrderToShopify() without awaiting. Used in checkout flows where Shopify sync should not block the response.

Shopify sync is optional. If SHOPIFY_STORE_DOMAIN and SHOPIFY_ADMIN_API_TOKEN are not set, syncOrderToShopify() returns immediately without error.

Key Files

File	Purpose
`lib/shopify/client.ts`	ShopifyAdminClient and order transformation
`lib/shopify/sync.ts`	Order sync orchestration
`lib/shopify/webhook.ts`	Webhook verification and status mapping
`app/api/webhooks/shopify/route.ts`	Webhook HTTP endpoint

How is this guide?

Shopify

On this page