Shopify setup

Keylight integrates with Shopify through HMAC-signed webhooks on order events. Every paid order and every refund hits Keylight, and Keylight mints or refunds the matching license. There’s no OAuth and no Shopify Admin API call from Keylight — only the signed webhook with a shared secret.

Tip

Shopify is one-time only. Native Shopify orders don’t recur, so the Shopify integration supports purchase, upgrade, and refund — but no subscription lifecycle. For recurring licenses, use Paddle, Lemon Squeezy, Polar, or Creem.

1. Enable Shopify in the dashboard

From your dashboard, go to Settings → Integrations → Shopify and click Enable Shopify. Keylight reveals the webhook URL:

https://api.keylight.dev/webhooks/shopify/<your-tenant-id>

Copy it — you’ll register it as a webhook topic in Shopify in step 3.

2. Map Shopify Variant IDs to Keylight apps

In Settings → Integrations → Shopify, add one row per variant.

Shopify Variant ID	Keylight app	Key type
40000000123	myapp	pro
40000000124	myapp	team

Keylight reads line_items[0].variant_id from each order event to pick the row. Unmapped variants are rejected with 400 unmapped_variant instead of being minted against an unknown app.

Note

If an order contains multiple line items, Keylight uses the first one. For multi-product carts, either split them into separate Shopify checkouts, or use only one Keylight-licensed line per order.

3. Register webhook topics in Shopify

In your Shopify Admin:

1. Open Settings → Notifications → Webhooks (or use a custom/private app for finer control).
2. Add three webhooks, all pointing at the Keylight URL from step 1, format JSON:
   • Topic: orders/create
   • Topic: orders/paid
   • Topic: refunds/create
3. Save. Shopify reveals a webhook signing secret at the bottom of the page (the “API secret key” for that webhook subscription) — copy it.

Back in Keylight (Settings → Integrations → Shopify), paste the secret into Webhook signing secret and save. Keylight uses it to verify the X-Shopify-Hmac-Sha256 header on every delivery.

Caution

Shopify’s signature is base64-encoded HMAC-SHA256 (not hex). If you reuse a secret from another platform, the format matters — paste exactly the value Shopify shows you.

4. Test the connection

Shopify’s webhook editor has a Send test notification button on each subscription.

• Send a test from the orders/create topic. Keylight returns 204 No Content for test pings — that means signature + URL are correct.
• For a true end-to-end test, place a real (or draft) order in your store and mark it paid. You should see a license appear in Dashboard → Licenses within a second.
• 400 invalid_signature → secret mismatch; re-copy from Shopify.
• 400 unmapped_variant → add the test order’s variant ID to your map.

What happens on a real sale

When a customer checks out, Shopify fires orders/create immediately, then orders/paid once the payment clears. Keylight provisions on whichever event arrives first with financial_status === 'paid' — deferred-payment orders are skipped at create and caught at paid. The order id deduplicates so you never get two licenses for one order. refunds/create flips the license to refunded and reverses the payment record.

Upgrades

To send a customer to a Shopify checkout that upgrades their existing license, append attributes[keylight_upgrade_key]=<license-key> to the Upgrade checkout URL you set on the key type. Shopify writes the value to note_attributes on the order, and Keylight links the new order to the existing license.

Disconnecting

Settings → Integrations → Shopify → Disconnect clears the signing secret and the variant map. Existing licenses are untouched — only new webhook deliveries stop minting. Remember to also delete the webhook subscriptions in Shopify, otherwise the dashboard will start logging delivery failures.