# 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

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

All fields are required.

## Response

```json
{
  "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

```html
<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