---
title: "API Reference"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.giveawaygator.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

### Calculate cart entries

Preview how many entries a cart would earn across all active promotions — same engine as real orders. Used by the checkout extension and custom cart integrations.

This endpoint does **not** use your API key. Send the shop domain in the JSON body.

See the full documentation at [Calculate Cart Entries API](/cart-entries-api).

```
POST /entries/calculate
```

---

### Create Entry

Add one entry for a customer. Use this for loyalty integrations, referrals, or any award that is not a Shopify order.

See the [Manual Entries API](/manual-entries-api) for the full request, errors, and limits. If you do not want to write code, use the [Add Entries](/shopify-flow#add-entries) action in Shopify Flow.

```
POST /entries/create
```

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

| Field | Required | Description |
|-------|----------|-------------|
| `promoId` | Yes | The promotion to add the entry to |
| `totalEntries` | Yes | Number of entries, greater than 0. The stored count is the whole-number part. |
| `email` | One of email or phone | Customer email |
| `phone` | One of email or phone | At least 10 digits. A 10-digit number is stored with a leading 1. |
| `name` | No | Customer name |
| `notes` | No | Reason stored on the entry history. Defaults to "Manual entry via API". |

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

Errors from this endpoint use an `error` string, for example `promoId is required`. The full status list is on the [Manual Entries API](/manual-entries-api) page.

**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
- A promotion limited to specific products does not accept this call
- Send one entry per request. There is no bulk endpoint and no idempotency key. A repeat request creates another entry.
- Entries created via API appear with source "api" in the entry history

---

### 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).

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

Source: https://docs.giveawaygator.app/api-reference/index.mdx
