Shopify API Reference
All public store endpoints are unauthenticated — L402 payment proof serves as authorization. Admin endpoints require your Lightning Enable API key.
Base URL: https://api.lightningenable.com
Public Endpoints
These endpoints are accessible without an API key. The {slug} parameter is the URL-safe identifier you chose when creating the integration.
Get Catalog
Fetches the product catalog from your Shopify store. Results are cached.
GET /api/shopify/{slug}/catalog
Response: 200 OK
{
"storeName": "your-store.com",
"slug": "your-store",
"shipping": {
"domesticUsd": 5.99,
"domesticOnly": true,
"freeShippingEnabled": true,
"freeShippingThresholdUsd": 50.00
},
"products": [
{
"productId": 8234567890123,
"title": "Premium Coffee Beans",
"description": "Single-origin Ethiopian coffee, light roast",
"imageUrl": "https://cdn.shopify.com/s/files/...",
"variants": [
{
"variantId": 44567890123456,
"title": "12oz Bag",
"priceUsd": 18.99,
"available": true
},
{
"variantId": 44567890123457,
"title": "2lb Bag",
"priceUsd": 34.99,
"available": true
}
]
}
]
}
Error Responses:
| Status | Meaning |
|---|---|
404 | Integration not found or inactive |
Create Checkout
Creates an L402 checkout with a Lightning invoice. Returns HTTP 402 with the payment challenge.
POST /api/shopify/{slug}/checkout
Headers (required):
| Header | Format | Description |
|---|---|---|
X-Buyer-Location | {country}-{state}-{zip} | Required. The buyer's location for destination-based tax calculation (e.g., US-FL-34787). There is no fallback — a missing or blank header returns 400. Pass the buyer's actual country-state-zip, never the seller's. |
Request Body:
{
"items": [
{ "variantId": 44567890123456, "quantity": 2 },
{ "variantId": 44567890123457, "quantity": 1 }
],
"email": "customer@example.com"
}
| Field | Required | Description |
|---|---|---|
items | Yes | Array of { variantId, quantity } (1–10 items) |
email | No | Buyer email (max 200 characters). When set, the buyer is emailed the claim URL once the payment lands. This is the recovery path when the buyer's wallet returns no preimage (for example, some Strike-to-Strike payments), so the checkout retry isn't possible. Pass it when buying for a human. |
Validation Rules:
- 1–10 items per checkout
- Each item quantity: 1–10
- Total quantity across all items: max 10
- All variant IDs must exist in the catalog
- All variants must be available (in stock)
Response: 402 Payment Required
The response includes a WWW-Authenticate header with the L402 challenge:
WWW-Authenticate: L402 macaroon="...", invoice="lnbc..."
Response Body:
{
"orderId": "shpfy_a1b2c3d4e5f6",
"items": [
{
"variantId": 44567890123456,
"productTitle": "Premium Coffee Beans",
"variantTitle": "12oz Bag",
"quantity": 2,
"priceUsd": 18.99
},
{
"variantId": 44567890123457,
"productTitle": "Premium Coffee Beans",
"variantTitle": "2lb Bag",
"quantity": 1,
"priceUsd": 34.99
}
],
"subtotalUsd": 72.97,
"shippingUsd": 0.00,
"taxUsd": 5.11,
"taxNote": null,
"totalUsd": 78.08,
"totalSats": 77200,
"claimExpiresAt": "2026-03-05T18:30:00Z",
"invoice": "lnbc721500n1pn...",
"macaroonBase64": "AgELbGlnaHRuaW5n...",
"paymentHash": "a1b2c3d4e5f6...",
"invoiceExpiresAt": "2026-02-26T18:40:00Z"
}
Key Fields:
invoice— BOLT11 Lightning invoice to paymacaroonBase64— L402 macaroon (save this for the post-payment retry and claim steps)paymentHash— links the macaroon to the invoiceclaimExpiresAt— deadline for claiming the order after payment (configurable window, default 30 days)totalSats— BTC amount locked at current exchange ratetaxUsd— tax calculated by Shopify from the buyer'sX-Buyer-LocationtaxNote— alwaysnulltotalUsd— total including subtotal + shipping + tax
The checkout response deliberately does not include a claim token or claim page URL. They are credentials for the post-payment claim flow — emitting them before payment would let an observer race the legitimate buyer to claim the order once the payment lands. To obtain them, prove payment via the checkout retry below.
Tax Calculation: Lightning Enable creates a temporary Shopify draft order with the cart and the buyer's location, reads the tax Shopify computes, and deletes the draft. The tax is included in the invoice total.
Error Responses:
| Status | Meaning |
|---|---|
400 | Invalid cart (bad variant ID, unavailable item, exceeds limits), missing/blank X-Buyer-Location, or a payment credential for a disabled protocol |
404 | Integration not found |
429 | Too many checkout requests. Wait a minute and retry. |
503 | Bitcoin price feed unavailable (no invoice is issued at a stale rate; includes a correlationId), tax calculation failed, or no invoice could be issued (challenge_persist_failed, payment_provider_not_configured, payment_provider_busy). Nothing was invoiced. Retry shortly, or tell the store owner if it persists. |
Complete a Paid Checkout (Checkout Retry)
After paying the invoice, re-POST the same checkout endpoint with your L402 payment proof in the Authorization header. This is the standard L402 client pattern (retry the same URL after payment) and it's how you obtain the claim credentials that are deliberately withheld from the 402 response.
POST /api/shopify/{slug}/checkout
Authorization: L402 {macaroonBase64}:{preimageHex}
Re-send the same body you sent on the first checkout. The body is validated before the credential (an empty {"items": []} returns 400), but its content doesn't affect the retry: the payment credential identifies the paid order.
Response: 200 OK
{
"orderId": "shpfy_a1b2c3d4e5f6",
"status": "PaidAwaitingDetails",
"shopifyOrderNumber": null,
"claimPageUrl": "https://your-store.com/pages/claim-your-order?token=SC-x7k9m2p4",
"message": "Payment verified. Submit shipping details to complete your order."
}
claimPageUrl— the merchant's claim page with the claim token in thetokenquery parameter (appended with&if the page URL already has a query string). Present only when the merchant has configured a claim page; otherwisenull. Hand this URL to the human buyer, or extract the token to call Claim Order directly.claimToken— the raw claim token. Present only when the merchant has not configured a claim page (soclaimPageUrlisnull); otherwisenull, because the token is already inclaimPageUrl. Use it to call Claim Order directly, and keep it: it's also the credential for Get Order Status. This retry response is the only place the raw token appears. If the order is already claimed, the token is still returned for status lookups andmessagesays the order is claimed; if the claim window has expired, it'snullandmessagesays so.- The response is sent with
Cache-Control: no-storebecause it carries the claim token. - If the buyer's wallet doesn't return a preimage (e.g., some Strike-to-Strike payments), this retry isn't possible — that's what the optional
emailfield at checkout is for: the claim URL is sent to the buyer automatically once the payment lands. If the store has no claim page, the email carries the claim code instead of a link, with instructions to reply to the store with it or have an agent call Claim Order.
Error Responses:
| Status | Meaning |
|---|---|
400 | Invalid request body (empty items or more than 10 items), credential for a disabled protocol, or invalid preimage format |
401 | L402 verification failed (macaroon/preimage don't verify) |
404 | No order found for this payment token |
Claim Order
Claims an order after payment: verifies payment, saves shipping details, and creates a Shopify order.
POST /api/shopify/{slug}/claim
Headers:
Authorization: L402 {macaroonBase64}:{preimageHex}
Content-Type: application/json
The Authorization header format is L402 <macaroon>:<preimage>:
macaroon— themacaroonBase64from the checkout responsepreimage— the 64-character hex preimage obtained after paying the invoice
When is the Authorization header required? Only for orders still in PendingPayment — the preimage is what proves payment and transitions the order to paid. For orders already marked paid (PaidAwaitingDetails, e.g. after the checkout retry or a provider webhook), the claim token alone is sufficient — this is what lets the merchant's claim page work from a plain browser without L402 headers.
Request Body:
{
"claimToken": "SC-x7k9m2p4",
"email": "customer@example.com",
"shippingAddress": {
"firstName": "Jane",
"lastName": "Doe",
"address1": "123 Main St",
"address2": "Apt 4B",
"city": "Austin",
"province": "TX",
"zip": "78701",
"country": "US",
"phone": "+15125551234"
}
}
claimToken and email are required (email max 200 characters).
Shipping Address Fields:
| Field | Required | Max Length |
|---|---|---|
firstName | Yes | 200 |
lastName | Yes | 200 |
address1 | Yes | 500 |
address2 | No | 500 |
city | Yes | 100 |
province | No | 100 |
zip | No | 20 |
country | Yes | 100 |
phone | No | 30 |
Response: 200 OK
{
"orderId": "shpfy_a1b2c3d4e5f6",
"status": "PaidWithDetails",
"shopifyOrderNumber": "#1042",
"claimPageUrl": "https://your-store.com/pages/claim-your-order?token=SC-x7k9m2p4",
"message": "Order #1042 created successfully. You'll receive shipping confirmation at customer@example.com."
}
Error Responses:
| Status | Meaning |
|---|---|
400 | Expired claim window, already claimed, missing payment proof, invalid preimage format, failed L402 verification, or international address on a domestic-only store |
401 | Payment credential for a disabled protocol only (a failing macaroon/preimage returns 400, not 401) |
404 | Unknown claim token (or token belongs to a different store) |
Get Order Status
Check the status of an order. Requires the claim token as a query parameter.
GET /api/shopify/{slug}/orders/{orderId}?claimToken={claimToken}
The claim token is single-use for claiming, but it stays valid as a read credential after a successful claim — status lookups with the same token keep working for claimed orders (PaidWithDetails, Fulfilled, Shipped), so the buyer can track their order through to delivery. Claimed orders remain queryable with the claim token for 90 days after claiming, after which they are purged. For orders that were never claimed, status lookups stop working once the claim window expires.
Response: 200 OK
{
"orderId": "shpfy_a1b2c3d4e5f6",
"status": "Shipped",
"totalUsd": 72.97,
"paidSats": 72150,
"shopifyOrderNumber": "#1042",
"trackingNumber": "1Z999AA10123456784",
"trackingCarrier": "UPS",
"trackingUrl": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
"createdAt": "2026-02-26T18:30:00Z",
"paidAt": "2026-02-26T18:31:15Z",
"shippedAt": "2026-02-28T14:22:00Z"
}
Error Responses:
| Status | Meaning |
|---|---|
404 | Order not found, claim token doesn't match, or claim window expired before the order was claimed. A token mismatch is deliberately a uniform 404 (never 401) to prevent order-ID enumeration. |
Get llms.txt Manifest
Returns a plain-text llms.txt manifest for the store — tagline, L402 endpoints, products, shipping rules, and links, formatted for AI agent discovery. Merchants can redirect /llms.txt on their own domain to this endpoint.
GET /api/shopify/{slug}/llms.txt
HEAD /api/shopify/{slug}/llms.txt
Response: 200 OK — text/plain; charset=utf-8. Cached with the same TTL as the catalog.
Error Responses:
| Status | Meaning |
|---|---|
404 | Integration not found or inactive (also text/plain) |
Merchant Admin Endpoints
These endpoints require your Lightning Enable API key in the X-API-Key header. On a plan without the Shopify integration (the Free Producer Sandbox), they return 402 with "error": "plan_feature_disabled".
Get Integration
GET /api/merchant/shopify
Returns your Shopify integration configuration. The Admin API token is never returned — only hasAdminApiToken: true/false.
Create Integration
POST /api/merchant/shopify
See Setup Guide for the full request schema.
Update Integration
PUT /api/merchant/shopify
Partial update — include only the fields you want to change.
{
"domesticShippingUsd": 6.99,
"freeShippingEnabled": true,
"isActive": false,
"listInRegistry": true,
"registryCategories": "[\"commerce\",\"food-and-beverage\"]",
"registryDescription": "Your store description for agent discovery."
}
Invalidate Cache
POST /api/merchant/shopify/invalidate-cache
Forces a refresh of the cached product catalog on the next request.
Refresh Shop Info
POST /api/merchant/shopify/refresh-shop-info
Refreshes the integration's canonical store identity (shopifyDomain and the internal *.myshopify.com handle) from Shopify's shop.json. Use after changing your primary domain in Shopify. Returns the updated integration on success; 400 if no access token is configured; 502 if Shopify doesn't return shop info (e.g., revoked token — the response body includes the upstream status).
Get Stats
GET /api/merchant/shopify/stats
Returns checkout conversion stats for every Shopify integration you own — scoped to your merchant account. total is the roll-up; byStore has one entry per store.
Response:
{
"merchantId": 42,
"total": {
"totalIntegrations": 1,
"totalCheckouts": 120,
"paidOrders": 18,
"conversionRate": 0.15,
"totalPaidSats": 1450000,
"totalPaidUsd": 1312.50,
"fulfilled": 16,
"shipped": 14,
"firstOrderAt": "2026-03-01T10:00:00Z",
"lastOrderAt": "2026-06-30T21:45:00Z"
},
"byStore": [
{
"slug": "my-store",
"shopifyDomain": "your-store.com",
"totalCheckouts": 120,
"paidOrders": 18,
"conversionRate": 0.15,
"totalPaidSats": 1450000,
"totalPaidUsd": 1312.50,
"fulfilled": 16,
"shipped": 14,
"firstOrderAt": "2026-03-01T10:00:00Z",
"lastOrderAt": "2026-06-30T21:45:00Z"
}
]
}
List Orders
GET /api/merchant/shopify/orders
GET /api/merchant/shopify/orders?status=PaidWithDetails
GET /api/merchant/shopify/orders?page=2&pageSize=10
Query Parameters:
| Parameter | Default | Description |
|---|---|---|
status | (all) | Filter by status: PendingPayment, PaidAwaitingDetails, PaidWithDetails, Fulfilled, Shipped |
page | 1 | Page number |
pageSize | 20 | Results per page (max 100) |
Response:
[
{
"orderId": "shpfy_a1b2c3d4e5f6",
"status": "PaidWithDetails",
"totalUsd": 72.97,
"paidSats": 72150,
"email": "customer@example.com",
"shopifyOrderNumber": "#1042",
"createdAt": "2026-02-26T18:30:00Z"
}
]
Complete Purchase Flow Example
Here's the full flow using curl:
# 1. Browse products
CATALOG=$(curl -s https://api.lightningenable.com/api/shopify/my-store/catalog)
echo "$CATALOG" | jq '.products[0].variants[0]'
# 2. Create checkout (get variant ID from catalog)
# X-Buyer-Location is REQUIRED for tax calculation — pass the buyer's country-state-zip
# email is optional but recommended when buying for a human — it's the recovery
# channel if your wallet doesn't return a preimage
# Keep the body in a variable — you re-send the SAME body on the retry (step 4).
CHECKOUT_BODY='{"items": [{"variantId": 44567890123456, "quantity": 1}], "email": "customer@example.com"}'
CHECKOUT=$(curl -s -X POST https://api.lightningenable.com/api/shopify/my-store/checkout \
-H "Content-Type: application/json" \
-H "X-Buyer-Location: US-FL-34787" \
-d "$CHECKOUT_BODY")
# Extract the invoice and macaroon (there is NO claimToken in the 402 response — by design)
INVOICE=$(echo "$CHECKOUT" | jq -r '.invoice')
MACAROON=$(echo "$CHECKOUT" | jq -r '.macaroonBase64')
ORDER_ID=$(echo "$CHECKOUT" | jq -r '.orderId')
# 3. Pay the invoice (using Lightning Enable MCP, lncli, or any Lightning wallet)
# This gives you the preimage (64 hex chars)
PREIMAGE="your_preimage_hex_here"
# 4. Retry the SAME checkout endpoint with your payment proof and the ORIGINAL body.
# This verifies payment and returns the claim page URL.
RETRY=$(curl -s -X POST https://api.lightningenable.com/api/shopify/my-store/checkout \
-H "Content-Type: application/json" \
-H "Authorization: L402 ${MACAROON}:${PREIMAGE}" \
-d "$CHECKOUT_BODY")
# claimPageUrl carries the claim token as ?token=... (when the merchant has a claim page).
# Hand the URL to the human buyer, or extract the token to claim via the API.
# A store with no claim page returns the raw token as claimToken instead:
CLAIM_TOKEN=$(echo "$RETRY" | jq -r '.claimToken // empty')
if [ -z "$CLAIM_TOKEN" ]; then
CLAIM_PAGE_URL=$(echo "$RETRY" | jq -r '.claimPageUrl')
CLAIM_TOKEN="${CLAIM_PAGE_URL##*token=}"
fi
# 5. Claim the order (the order is already marked paid, so the token alone suffices —
# including the Authorization header again is harmless)
curl -X POST https://api.lightningenable.com/api/shopify/my-store/claim \
-H "Content-Type: application/json" \
-d "{
\"claimToken\": \"${CLAIM_TOKEN}\",
\"email\": \"customer@example.com\",
\"shippingAddress\": {
\"firstName\": \"Jane\",
\"lastName\": \"Doe\",
\"address1\": \"123 Main St\",
\"city\": \"Austin\",
\"province\": \"TX\",
\"zip\": \"78701\",
\"country\": \"US\"
}
}"
# 6. Track the order — the claim token keeps working as a read credential after the claim
curl "https://api.lightningenable.com/api/shopify/my-store/orders/${ORDER_ID}?claimToken=${CLAIM_TOKEN}"
Edge Cases
| Scenario | What Happens |
|---|---|
| BTC price moves after checkout | The sats amount is locked in the Lightning invoice at checkout time. The invoice expires in ~10 minutes. |
| Product goes out of stock | Checked at checkout time against cached catalog. At claim time, Shopify's decrement_obeying_policy handles inventory. |
| Claim token used twice | Second claim is rejected (400, already claimed) — tokens are single-use for claiming. The token remains valid for order-status lookups. |
| Wallet returns no preimage | The L402 checkout retry isn't possible (e.g., some Strike-to-Strike payments). If email was provided at checkout, the buyer receives the claim URL automatically once the payment lands — otherwise contact the merchant. |
| Shopify order creation fails | Order stays in PaidAwaitingDetails. Payment is safe. Can be retried via admin. |
| BTC price feed unavailable | Checkout returns 503 with a correlationId rather than quoting a stale rate. Retry shortly. |
| No tax location provided | Checkout returns 400 if the required X-Buyer-Location header is missing or blank. There is no fallback. |
| Invoice expires before payment | Order stays in PendingPayment. Agent must create a new checkout. |
| Claim window expires before claiming | Contact the merchant for manual resolution. Payment is recorded. Default window is 30 days (configurable 1–365). |