Shopify integration
Technical guide for connecting a Shopify store to a Gatta loyalty brand so agent and app checkouts can create store orders and settle loyalty when you Mark as paid.
What the integration does
| Direction | Behavior |
|---|---|
| Gatta → Shopify | Creates a payment-pending order with shopper email + shipping address from Open Orders |
| Shopify → Gatta | Notifies Gatta when the order is marked paid so loyalty settlement can finish |
| Gatta → Shopper | Applies points + cash top-up according to the quote |
You keep merchandising, inventory, and fulfillment in Shopify Admin.
Prerequisites
- Approved Gatta brand (
brand_token_id) - Shopify store admin
- Brand admin (or Gatta service) credentials to call Gatta APIs
- Payout address (EVM) for merchant proceeds
- App base URL used by Gatta for OAuth/webhooks (production: API host configured as
SHOPIFY_APP_URL)
Supported connection methods
A. OAuth from Business (recommended)
- Sign in at agent.gatta.io/business as the brand owner.
- After your brand is live, open Shopify store.
- Enter your
{shop}.myshopify.comdomain and click Connect Shopify. - Approve Gatta in Shopify Admin. You return to Business automatically.
- Save your payout address (EVM) so quotes can settle.
- Confirm webhooks show as registered (or click Register webhooks).
Gatta never asks you to paste an Admin API token into the app.
B. OAuth via API (ops / automation)
- Start OAuth with your shop domain and brand id (authenticated as the brand owner):
POST /v1/commerce/shops/oauth/start
Authorization: Bearer {gatta_token}
Content-Type: application/json
{ "shop": "{shop}.myshopify.com", "brand_token_id": "{id}" }
- Response includes
authorize_url— open it as the store owner and approve requested scopes. - Gatta’s callback stores an encrypted Admin token, links
shop_domain↔brand_token_id, registers webhooks, then redirects to Business.
C. Direct connect (dev / migration)
POST /v1/commerce/shops/connect
Authorization: Bearer {gatta_token}
Content-Type: application/json
{
"shop_domain": "your-store.myshopify.com",
"access_token": "{admin_api_access_token}",
"brand_token_id": "3",
"brand_payout_address": "0x…",
"scopes": "read_products,write_products,read_orders,write_orders,read_draft_orders,write_draft_orders"
}
Requires brand_admin (or service) auth. Token is stored encrypted at rest.
Scopes
Minimum practical set for Gatta checkout pilots:
read_products/write_products(catalog search & variant pricing)read_draft_orders/write_draft_ordersread_orders/write_orders
Exact installed scopes are returned on connect and stored with the shop record.
Webhooks
Gatta registers store webhooks pointing at:
POST https://api.gatta.io/v1/webhooks/shopify
Required for settlement: order paid notification (orders/paid) so Gatta can finalize when a staff member Marks as paid.
Re-register if needed:
POST /v1/commerce/shops/{shopDomain}/register-webhooks
Authorization: Bearer {gatta_token}
Verify the callback URL is reachable from Shopify and that your Gatta deployment has webhook verification configured.
Payout address
Set brand_payout_address on connect (or update via shop record). This is the merchant wallet that receives USDC proceeds when a checkout settles.
Quotes fail if the linked shop has no payout address.
Order lifecycle (Shopify)
Shopper funds on Gatta
↓
Shopify order created (payment pending)
↓
Staff: Mark as paid (Admin)
↓
orders/paid webhook → Gatta settlement
↓
Loyalty finalize + earn reward (per program rules)
What to look for in Admin
- Order note / tags identifying the Gatta checkout (short
gatta:…tag + note metadata) - Customer email and shipping address filled from Gatta handoff (shopper entered on Open Orders)
- Financial status transitioning after Mark as paid
- Fulfillment proceeds as with any other order
Catalog access
While the shop is connected and active, Gatta may:
- Search products (title / query) for agent shopping
- Read variant prices for quotes
Only active products with sellable variants are offered. Keep titles clear — agents search by natural language.
Security & ops notes
- Prefer OAuth over pasting long-lived tokens into chat or tickets
- Rotate tokens via reconnect if a store is compromised
- Do not share Admin tokens in ChatGPT prompts
- Encryption of stored tokens is handled by Gatta; you do not manage the ciphertext
Test plan
- Connect shop + set payout address
- Confirm webhooks registered
- From ChatGPT or API: quote a known SKU → fund Open Orders → confirm Shopify pending order
- Mark as paid → confirm shopper reward / settlement status in Gatta