Gatta

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

DirectionBehavior
Gatta → ShopifyCreates a payment-pending order with shopper email + shipping address from Open Orders
Shopify → GattaNotifies Gatta when the order is marked paid so loyalty settlement can finish
Gatta → ShopperApplies 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)

  1. Sign in at agent.gatta.io/business as the brand owner.
  2. After your brand is live, open Shopify store.
  3. Enter your {shop}.myshopify.com domain and click Connect Shopify.
  4. Approve Gatta in Shopify Admin. You return to Business automatically.
  5. Save your payout address (EVM) so quotes can settle.
  6. 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)

  1. 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}" }
  1. Response includes authorize_url — open it as the store owner and approve requested scopes.
  2. 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_orders
  • read_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

  1. Connect shop + set payout address
  2. Confirm webhooks registered
  3. From ChatGPT or API: quote a known SKU → fund Open Orders → confirm Shopify pending order
  4. Mark as paid → confirm shopper reward / settlement status in Gatta

Related