# API Reference

Giveaway Gator provides a REST API for integrating entry management with your own systems — loyalty programs, mobile apps, POS terminals, custom referral systems, and more.

## Base URL

```
https://giveawaygator.app/api
```

All endpoints below are relative to this base URL.

## Authentication

Every API request requires an API key. Generate one from **Giveaway Gator > Settings > API Key** in your Shopify admin.

API keys use the format `gg_` followed by 64 hex characters:
```
gg_a1b2c3d4e5f6...
```

Include it as a Bearer token in the `Authorization` header:
```
Authorization: Bearer gg_your_api_key_here
```

> **Keep your API key secret.** Don't expose it in client-side code, public repos, or storefront themes. API calls should always be made from your server or a secure backend.

---

## Rate Limits

API key requests are limited to **60 requests per minute** per key.

When you hit the limit, the API returns `429 Too Many Requests`:
```json
{
  "status": "error",
  "message": "Too many requests. Please try again later."
}
```

---

## Common Response Format

**Success responses** return `2xx` status codes with a JSON body.

**Error responses** follow this structure:
```json
{
  "success": false,
  "message": "Description of what went wrong"
}
```

| Status | Meaning |
|--------|---------|
| 200 | Success |
| 201 | Created (new entry) |
| 400 | Bad request — missing or invalid fields |
| 401 | Unauthorized — invalid or missing API key |
| 403 | Forbidden — shop inactive or feature not enabled |
| 404 | Not found — promotion, order, or entry doesn't exist |
| 429 | Rate limit exceeded |
| 500 | Server error |

---

## Endpoints

### Create Entry

Add entries for a customer programmatically. Use this for loyalty integrations, custom referral systems, or any workflow where you need to award entries outside of a Shopify order.

```
POST /entries/create
```

**Request:**
```json
{
  "promoId": "promotion-uuid",
  "email": "customer@example.com",
  "totalEntries": 100,
  "name": "Jane Smith",
  "phone": "+15551234567",
  "notes": "Referral bonus from campaign X"
}
```

| Field | Required | Description |
|-------|----------|-------------|
| `promoId` | Yes | The promotion to add entries to |
| `totalEntries` | Yes | Number of entries (positive integer) |
| `email` | Yes* | Customer email (*at least one of email or phone) |
| `phone` | No* | Customer phone in E.164 format (*at least one of email or phone) |
| `name` | No | Customer name |
| `notes` | No | Reason for the entry (appears in audit log) |

**Response (201):**
```json
{
  "success": true,
  "entry": {
    "id": "entry-uuid",
    "email": "customer@example.com",
    "phone": "+15551234567",
    "name": "Jane Smith",
    "totalEntries": 100,
    "createdAt": "2026-01-15T12:00:00Z",
    "promoName": "Spring Giveaway"
  }
}
```

**Notes:**
- The promotion must be currently active (between its start and end dates)
- The promotion must belong to the shop that owns the API key
- Entries created via API appear with source "api" in audit logs

---

### Claim POS Receipt

Allow customers to claim giveaway entries from in-store POS purchases by providing their receipt number and email address. This is how you bridge the gap between in-store sales and your online giveaway.

See the full documentation at [POS Claim API](pos-claim-api.md).

```
POST /theme/pos-claim?shop=yourstore.myshopify.com
```

**Request:**
```json
{
  "receiptNumber": "1001",
  "email": "customer@example.com"
}
```

| Field | Required | Description |
|-------|----------|-------------|
| `receiptNumber` | Yes | The POS receipt/order number |
| `email` | Yes | Customer email to associate entries with |

**Response (200):**
```json
{
  "success": true,
  "entries": [
    {
      "promotionName": "Spring Giveaway",
      "totalEntries": 50
    }
  ]
}
```

**Notes:**
- The receipt number must match an existing POS order in your Shopify store
- Entries are calculated the same way as online orders (bonuses, multipliers, etc. all apply)
- Each receipt can only be claimed once per email address

---

## Finding Your Promotion ID

The Create Entry endpoint requires a `promoId`. To find it:

1. Open **Giveaway Gator** in your Shopify admin.
2. Click **Manage** on a promotion.
3. The promotion ID is in the URL: `/app/promos/{promotion-id}`