Shopify Setup Guide

This guide walks you through connecting your Shopify store to Lightning Enable for L402 agentic commerce. Setup takes about 10 minutes.

Step 1: Create a Custom App for Your Store

Lightning Enable uses Shopify's OAuth client-credentials flow to securely create orders in your store after Lightning payment. You create a custom app in your Shopify store admin (via the Dev Dashboard, which is Shopify's current workflow for merchant-created apps) and connect it to Lightning Enable using the app's Client ID and Client Secret.

Coming soon: one-click install from the Shopify App Store

Lightning Enable is in review for listing in the Shopify App Store. Once approved, you'll install it directly from the App Store with a single click and this step goes away. Until then, every merchant creates their own custom app using the steps below — Shopify's preferred path for single-store integrations.

Dev Dashboard vs Partner Dashboard

You do not need a Shopify Partners account for this. The Dev Dashboard is launched from inside your own store admin (Settings → Apps and sales channels → Develop apps → Build apps) and is the current path for merchants creating an app for their own store. Partners Dashboard is a separate product for agencies and developers building apps that distribute to other merchants — that's not what you want here.

Sign in to your Shopify store admin
Go to Settings → Apps and sales channels
Click Develop apps
Click Build apps (this opens the Shopify Dev Dashboard)
In the Dev Dashboard, click Create application
Name the app Lightning Enable (or anything you prefer)
Under Configuration → API scopes, add the following Admin API access scopes:

Scope	Purpose
`write_orders`	Create orders after Lightning payment
`write_draft_orders`	Create temporary draft orders for tax calculation
`read_products`	Verify product availability at claim time
`read_inventory`	Check stock levels

Click Save on the scope configuration
Go to the app's Home tab in the Dev Dashboard and click Install app → select your store → Install
After install, open the app's API credentials (or Overview) panel and copy:
- Client ID
- Client Secret (starts with shpss_) — Shopify reveals this value one time on this screen

Keep this tab open — you'll paste both values into Lightning Enable in Step 5.

Save Your Client Secret

Shopify reveals the Client Secret only once on the API credentials screen after the app is installed. If you lose it, you can regenerate it from the same screen, but you'll need to update it in Lightning Enable afterward — the old secret stops working immediately on regeneration.

If your store already has a legacy custom app

Shopify stopped allowing creation of new legacy custom apps in January 2026, but existing legacy custom apps still work. If you created yours before the cutoff, it's under Settings → Apps and sales channels → Develop apps (with no "Build apps" step), and you can use its existing Client ID and Client Secret. If you have to re-create for any reason, you'll go through the Dev Dashboard flow above.

Step 2: Verify Your Products Are Ready

Lightning Enable fetches your catalog from the Shopify Admin API using the app credentials from Step 1. Make sure the products you want available via L402 are set up correctly:

Go to Products in Shopify admin
For each product you want available via L402:
- Status should be Active — the Admin API catalog fetch filters to active products
- Confirm inventory and pricing are accurate
- Publishing to Online Store is recommended but not strictly required — Lightning Enable uses the Admin API, which doesn't filter by sales channel. That said, keeping Online Store checked keeps your catalog consistent with your customer-facing storefront and makes the optional check below work.

Optional sanity check — if you want to verify your products are also visible on Shopify's public storefront, open this URL in your browser (replace with your domain):

https://your-store.com/products.json

If it returns your products, they're published to the Online Store channel. An empty response only means products aren't published to Online Store — Lightning Enable's Admin API catalog fetch can still work regardless.

If you don't already have a Lightning Enable account:

Visit lightningenable.com and sign up for an Agentic Commerce plan — either Individual ($99/month) or Business ($299/month)
Complete the Stripe checkout
Save your API key from the confirmation page — you'll need it for the next step

Already Have a Subscription?

If you're on a plan that doesn't include L402/Agentic Commerce, upgrade through the merchant dashboard or contact support.

Step 4: Configure Your Payment Provider

You need a payment provider to handle Lightning invoice creation and settlement.

Option A: Strike (Recommended)

Create a Strike account
Generate an API key in the Strike dashboard with the partner.receive-request.create scope (required for creating Lightning invoices)
Configure it in Lightning Enable:

curl -X PUT https://api.lightningenable.com/api/merchant/settings \
  -H "X-API-Key: YOUR_LIGHTNING_ENABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentProvider": 0,
    "strikeApiKey": "YOUR_STRIKE_API_KEY"
  }'

Strike supports preimage extraction, which is required for L402 payment verification.

Option B: OpenNode

See the OpenNode Setup Guide for configuration details.

L402 Compatibility

OpenNode does not return preimages for incoming payments. For Shopify L402 integration, Strike is strongly recommended as it provides the preimage needed for cryptographic payment verification.

Step 5: Create the Shopify Integration

With your Lightning Enable API key, create the integration using the Client ID and Client Secret you copied in Step 1:

curl -X POST https://api.lightningenable.com/api/merchant/shopify \
  -H "X-API-Key: YOUR_LIGHTNING_ENABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "your-store-name",
    "shopifyDomain": "your-store.com",
    "shopifyClientId": "YOUR_CLIENT_ID",
    "adminApiAccessToken": "shpss_YOUR_CLIENT_SECRET",
    "domesticShippingUsd": 5.99,
    "internationalShippingUsd": 14.99,
    "freeShippingEnabled": false,
    "freeShippingThresholdUsd": 50.00,
    "catalogCacheTtlMinutes": 15,
    "defaultTaxLocation": "US-FL-34787",
    "registryCategories": "[\"commerce\",\"food-and-beverage\",\"coffee\"]",
    "registryDescription": "Premium coffee beans available for AI agent purchases via Lightning L402 payments."
  }'

Lightning Enable exchanges your Client ID and Client Secret with Shopify for a short-lived access token (valid ~24 hours), then reuses that token for Admin API calls until it needs to be refreshed. You don't need to rotate or refresh tokens manually — Lightning Enable handles that automatically and transparently.

Configuration Options

Field	Required	Description
`slug`	Yes	URL-safe identifier for your store (lowercase, hyphens OK). Used in endpoint URLs: `/api/shopify/{slug}/catalog`
`shopifyDomain`	Yes	Your Shopify store domain (e.g., `your-store.com` or `your-store.myshopify.com`). On save, Lightning Enable calls Shopify's `shop.json` and auto-corrects this to your customer-facing primary domain — your customers see `your-store.com`, your canonical `*.myshopify.com` handle is captured separately and managed for you. You can refresh both at any time from the dashboard.
`shopifyClientId`	Yes	Shopify app Client ID from Step 1
`adminApiAccessToken`	Yes	Shopify app Client Secret (starts with `shpss_`) from Step 1
`domesticShippingUsd`	No	US flat-rate shipping (default: $5.99)
`internationalShippingUsd`	No	International flat-rate shipping (default: $14.99)
`freeShippingEnabled`	No	Enable free shipping above threshold (default: false)
`freeShippingThresholdUsd`	No	Order subtotal for free shipping (default: $50.00)
`catalogCacheTtlMinutes`	No	How long to cache products (default: 15 min, range: 1-1440)
`defaultTaxLocation`	No	Fallback tax location when agent doesn't pass `X-Buyer-Location` header. Format: `US-FL-34787` (country-state-zip).
`listInRegistry`	No	List in L402 API registry for agent discovery (default: true)
`registryCategories`	No	JSON array of categories, e.g. `["commerce","food-and-beverage"]`
`registryDescription`	No	Description for registry keyword search

Choosing a Slug

Your slug determines the public URL for your store's endpoints:

https://api.lightningenable.com/api/shopify/{slug}/catalog
https://api.lightningenable.com/api/shopify/{slug}/checkout
https://api.lightningenable.com/api/shopify/{slug}/claim

Choose something short and memorable. It must be:

Lowercase letters, numbers, and hyphens only
Unique across all Lightning Enable merchants
Examples: my-store, acme-goods, coffee-co

Step 6: Verify Your Setup

Test the Catalog

curl https://api.lightningenable.com/api/shopify/your-store-name/catalog

You should see your products with variants, prices, and shipping rules. No authentication is required for this endpoint.

Test a Checkout

# Use a real variant ID from the catalog response
# Pass X-Buyer-Location for tax calculation (or configure defaultTaxLocation on the integration)
curl -X POST https://api.lightningenable.com/api/shopify/your-store-name/checkout \
  -H "Content-Type: application/json" \
  -H "X-Buyer-Location: US-FL-34787" \
  -d '{
    "items": [
      {"variantId": 12345678901234, "quantity": 1}
    ]
  }'

You should receive an HTTP 402 response with:

A Lightning invoice (BOLT11 string)
A macaroon (base64)
A payment hash
A claim token
Order details with amounts in both USD and sats
Tax breakdown (taxUsd and taxNote)

Test a Full Purchase

To test the complete flow, use the Lightning Enable MCP server:

Use the pay_invoice tool to pay the invoice from the checkout response
Claim the order with the preimage:

curl -X POST https://api.lightningenable.com/api/shopify/your-store-name/claim \
  -H "Content-Type: application/json" \
  -H "Authorization: L402 MACAROON_BASE64:PREIMAGE_HEX" \
  -d '{
    "claimToken": "SC-xxxxxxxx",
    "email": "customer@example.com",
    "shippingAddress": {
      "firstName": "Jane",
      "lastName": "Doe",
      "address1": "123 Main St",
      "city": "Austin",
      "province": "TX",
      "zip": "78701",
      "country": "US"
    }
  }'

Check your Shopify admin — a new order should appear, marked as paid

Step 7: Add the Claim Page and `llms.txt` to Your Store

After an AI agent pays the Lightning invoice, a human still needs to submit a shipping address. Lightning Enable provides a Shopify section + page template (compatible with Dawn and any OS 2.0 theme) and an llms.txt template to run this flow on your own domain so the buyer experience stays within your brand.

The templates are provided when you start your integration:

le-claim.liquid — a configurable section that renders the shipping-details form after payment. Brand colors, copy, card layout, and typography are all set in the theme editor — no code edits per merchant.
page.claim.json — the page template that wires the section into a Shopify page.
llms-txt.liquid — a machine-readable page that tells AI agents how to browse and purchase from your store using L402.

Install the claim section + page template

Shopify admin → Online Store → Themes → Edit code
Under Sections, click Add a new section → name it le-claim → choose Liquid → paste the contents of sections/le-claim.liquid
Under Templates, click Add a new template → type page → name it claim → choose JSON → paste the contents of templates/page.claim.json
Shopify admin → Online Store → Pages → Add page, title it Claim Your Order, leave the body empty, and under Theme template select claim → save and copy the page URL
In your Lightning Enable dashboard, set Claim Page URL to the page URL (e.g., https://your-store.com/pages/claim-your-order)
Open the page in the theme editor and click the Lightning Enable Claim section. Set the required slug (your Lightning Enable store slug from Step 5) and adjust brand colors, copy, and typography to match your theme. The default white card works on any background — leave it on unless your page already provides a contrasting container.

Install the `llms.txt` template

Shopify admin → Online Store → Themes → Edit code
Under Templates, click Add a new template → type page → name it llms-txt
Paste the contents of llms-txt.liquid into the new template
In Shopify admin → Online Store → Pages → Add page, title it llms, leave the body empty, and under Theme template select llms-txt
Verify at https://your-store.com/pages/llms — you should see plain text (no site header or footer)

Make llms.txt discoverable at your domain root

AI agents typically look for llms.txt at https://your-store.com/llms.txt. Because Shopify serves custom pages under /pages/, add a URL redirect in Shopify admin (Online Store → Navigation → URL Redirects) from /llms.txt to /pages/llms so agents can find it at the canonical path.

Step 8: Go Live

Once testing is complete, your L402 store endpoints are live and ready for AI agents. Your store is automatically listed in the L402 API registry, which means AI agents can find it using the discover_api MCP tool:

Agent: discover_api(query="coffee")
→ Your store appears in results with description, categories, and manifest URL

You can also share your catalog URL directly:

https://api.lightningenable.com/api/shopify/your-store-name/catalog

To manage your registry listing (categories, description, or opt out), see the Agent Discovery & Registry guide.

Managing Your Integration

Update Settings

curl -X PUT https://api.lightningenable.com/api/merchant/shopify \
  -H "X-API-Key: YOUR_LIGHTNING_ENABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domesticShippingUsd": 6.99,
    "freeShippingEnabled": true,
    "freeShippingThresholdUsd": 75.00,
    "defaultTaxLocation": "US-TX-78701"
  }'

Only include fields you want to change — all others remain unchanged. To clear defaultTaxLocation, send an empty string ("").

Refresh the Catalog Cache

After updating products or prices in Shopify, force a cache refresh:

curl -X POST https://api.lightningenable.com/api/merchant/shopify/invalidate-cache \
  -H "X-API-Key: YOUR_LIGHTNING_ENABLE_API_KEY"

Or wait for the cache TTL to expire naturally (default: 15 minutes).

View Orders

# All orders
curl "https://api.lightningenable.com/api/merchant/shopify/orders" \
  -H "X-API-Key: YOUR_LIGHTNING_ENABLE_API_KEY"

# Filter by status
curl "https://api.lightningenable.com/api/merchant/shopify/orders?status=PaidWithDetails" \
  -H "X-API-Key: YOUR_LIGHTNING_ENABLE_API_KEY"

# Paginate
curl "https://api.lightningenable.com/api/merchant/shopify/orders?page=2&pageSize=10" \
  -H "X-API-Key: YOUR_LIGHTNING_ENABLE_API_KEY"

Pause the Integration

To temporarily disable L402 purchases without losing your configuration:

curl -X PUT https://api.lightningenable.com/api/merchant/shopify \
  -H "X-API-Key: YOUR_LIGHTNING_ENABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"isActive": false}'

Set isActive back to true to re-enable.

Troubleshooting

`Invalid API key or access token` from Shopify

Double-check that the Client ID and Client Secret pasted into Lightning Enable match what's shown in your Shopify app's configuration, with no extra whitespace.
Confirm the app is still installed on your store (Settings → Apps and sales channels → Develop apps → your app). Uninstalling the app revokes its credentials immediately.
If you regenerated the Client Secret, update it in your Lightning Enable dashboard — the previous secret stops working immediately.
If you updated the app's Admin API scopes after install, Shopify requires the app to be re-installed for the new scopes to take effect. Open the app in the Dev Dashboard and click Install (or Update) to re-apply.

Catalog endpoint returns an empty list

Confirm your products are Active. Publishing to the Online Store sales channel is only required for Shopify's public storefront endpoints, not for the Admin API catalog fetch Lightning Enable uses.
Open https://your-store.com/products.json directly only if you want to verify public storefront visibility or suspect Lightning Enable is falling back to Shopify's public endpoint. If it returns an empty list, Shopify isn't serving the products publicly yet, but the Admin API catalog fetch can still work.
If you set allowedProductTypes on your integration, the values must match a product's Shopify product_type field, but letter casing does not matter.
The catalog is cached for 15 minutes by default — trigger a refresh by calling the invalidate-cache endpoint shown above in Refresh the Catalog Cache.

Checkout returns a 400 about location

Tax calculation needs to know where the buyer is. Either the agent must pass an X-Buyer-Location header on the checkout request (format US-FL-34787), or you must set defaultTaxLocation on your integration. If neither is present, checkout will fail.

Order appears as unpaid or with no shipping info in Shopify admin

An order marked PaidAwaitingDetails in Lightning Enable means the Lightning payment succeeded but the buyer hasn't submitted the claim form yet. The default claim window is 30 days.
If the buyer never claims, the order does not post to your Shopify store at all — the agent paid, but no fulfillment request was ever made. Refunds for these cases are handled through your payment provider (e.g., Strike dashboard) as outgoing Lightning payments.

Lightning invoice not being created at checkout

Verify your Strike API key is active in the Strike dashboard and has the partner.receive-request.create scope.
Re-save the key in your Lightning Enable dashboard to confirm it's stored correctly.

Next Steps

API Reference — Full endpoint documentation with request/response schemas
MCP Server Guide — Help AI agents connect to your store
Strike Setup — Configure Strike as your payment provider

Step 1: Create a Custom App for Your Store​

Step 2: Verify Your Products Are Ready​

Step 3: Sign Up for Lightning Enable​

Step 4: Configure Your Payment Provider​

Option A: Strike (Recommended)​

Option B: OpenNode​

Step 5: Create the Shopify Integration​

Configuration Options​

Choosing a Slug​

Step 6: Verify Your Setup​

Test the Catalog​

Test a Checkout​

Test a Full Purchase​

Step 7: Add the Claim Page and llms.txt to Your Store​

Install the claim section + page template​

Install the llms.txt template​

Step 8: Go Live​

Managing Your Integration​

Update Settings​

Refresh the Catalog Cache​

View Orders​

Pause the Integration​

Troubleshooting​

Invalid API key or access token from Shopify​

Catalog endpoint returns an empty list​

Checkout returns a 400 about location​

Order appears as unpaid or with no shipping info in Shopify admin​

Lightning invoice not being created at checkout​

Next Steps​