Skip to content

POS Claim External API

Allow customers to claim giveaway entries from POS (Point of Sale) receipts.

Endpoint

POST /api/theme/pos-claim?shop={shop_domain}
Content-Type: application/json

Authentication

  • Theme embed: Automatic via Shopify app proxy signature
  • Custom integration: Authorization: Bearer {GIVEAWAY_GATOR_API_KEY}

Rate Limits

  • Theme embed: 10 requests/minute per IP
  • API key: 60 requests/minute per key

Request Body

{
  "receiptNumber": "POS12345",
  "email": "customer@example.com",
  "firstName": "Ada",
  "lastName": "Lovelace"
}

All fields are required.

Response

{
  "status": "success",
  "orderId": "gid://shopify/Order/123456789",
  "orderName": "#1001",
  "entriesAwarded": 15,
  "claimedAt": "2025-01-05T22:41:03.123Z",
  "promotions": [
    {
      "promoId": "promo-uuid",
      "promoName": "Holiday Giveaway",
      "entriesAwarded": 15,
      "alreadyClaimed": false,
      "claimedAt": "2025-01-05T22:41:03.123Z"
    }
  ]
}

Status Values:

  • success — Entries awarded
  • already_claimed — All promotions already claimed
  • no_active_promotions — Order found but no active promos
  • not_found — No matching order
  • error — Unexpected failure

Theme Embed Example

<form method="post"
  action="/apps/giveaway-gator/api/theme/pos-claim?shop={{ shop.permanent_domain }}"
  id="gg-pos-claim-form">
  <label>Receipt Number <input type="text" name="receiptNumber" required></label>
  <label>Email <input type="email" name="email" required></label>
  <label>First Name <input type="text" name="firstName" required></label>
  <label>Last Name <input type="text" name="lastName" required></label>
  <button type="submit">Claim Entries</button>
</form>

Best Practices

  • Always include the shop query parameter
  • Store API keys securely and rotate if compromised
  • Ensure orders are ingested into Giveaway Gator before claiming
  • Consider CAPTCHA for front-end forms to reduce abuse

Type to search…

↑↓ navigate↵ selectEsc close