---
title: "Manual Entries API"
---

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

# Manual Entries API

Create one giveaway entry from your own system. Use this for loyalty programs, referrals, and other awards that are not a Shopify order.

If you do not want to write code, use the **Add Entries** action in [Shopify Flow](/shopify-flow#add-entries).

## Endpoint

```
POST https://giveawaygator.app/api/entries/create
Content-Type: application/json
```

Send one entry per request. There is no bulk endpoint.

## Authentication

Create a key in **Giveaway Gator > Settings > API Key**. Send it on every request:

```
Authorization: Bearer gg_your_api_key_here
```

Keep the key on your server. Do not put it in a theme, a public repo, or browser code.

## Rate Limits

Each key can make **60 requests per minute**. A request over the limit returns `429` with:

```json
{ "error": "Too many requests, please try again later" }
```

## Request Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `promoId` | string | Yes | Promotion to add the entry to. See [Finding your promotion ID](/api-reference#finding-your-promotion-id). |
| `totalEntries` | number | Yes | Number of entries. Must be greater than 0. Giveaway Gator stores the whole-number part, so `2.9` is stored as `2`. |
| `email` | string | One of email or phone | Customer email. |
| `phone` | string | One of email or phone | Customer phone. Send at least 10 digits. Spaces, dashes, and parentheses are ignored. A 10-digit number is stored with a leading `1` (US and Canada). A longer number is stored as digits only. |
| `name` | string | No | Customer name. |
| `notes` | string | No | Reason stored on the entry history. If you omit it, the history says "Manual entry via API". |

You can send both `email` and `phone`. The entry stores both.

## Example

```bash
curl -X POST \
  https://giveawaygator.app/api/entries/create \
  -H 'Authorization: Bearer gg_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "promoId": "promotion-uuid",
    "email": "customer@example.com",
    "totalEntries": 10,
    "name": "Jane Smith",
    "notes": "Referral bonus"
  }'
```

## Response

**Success (201):**

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

**Errors** return an `error` string:

```json
{ "error": "promoId is required" }
```

| Status | When | `error` |
|--------|------|---------|
| 400 | `promoId` is missing | `promoId is required` |
| 400 | Both email and phone are missing | `Either email or phone is required` |
| 400 | `totalEntries` is missing or not greater than 0 | `totalEntries must be a positive number` |
| 400 | The promotion is outside its start and end dates | `Promotion is not currently active` |
| 400 | The phone has fewer than 10 digits | `Invalid phone number format` |
| 401 | The `Authorization` header is missing or is not a Bearer token | `Authorization header required` |
| 401 | The key does not match a shop | `Invalid API key` |
| 403 | The shop is not active | `Shop is not active` |
| 403 | The promotion is limited to specific products | `This promotion is restricted to specific products and does not accept API entries` |
| 404 | The promotion is missing, or it belongs to another shop | `Promotion not found` |
| 405 | The method is not POST | `Method not allowed` |
| 429 | The key is over 60 requests per minute | `Too many requests, please try again later` |
| 500 | The server could not create the entry | The server's error text |

When the promotion is outside its dates, the `400` body also includes `promoStart` and `promoEnd`.

Send valid JSON. A body that is not JSON returns `500`.

## Notes

- The promotion must be active (the current time is between its start and end) and must belong to the shop that owns the API key.
- A promotion limited to specific products does not accept this call. Use a promotion with no product limit, or add the entry in the app.
- There is no idempotency key. A repeat request creates another entry.
- The entry history shows source **api**.
- For a no-code award, use [Add Entries in Shopify Flow](/shopify-flow#add-entries).

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