Allow customers to claim giveaway entries from POS (Point of Sale) receipts.
Endpoint
POST /api/theme/pos-claim?shop={shop_domain}
Content-Type: application/jsonAuthentication
- 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 awardedalready_claimed— All promotions already claimedno_active_promotions— Order found but no active promosnot_found— No matching ordererror— 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
shopquery 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
