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.
Endpoint
POST https://giveawaygator.app/api/entries/create
Content-Type: application/jsonSend 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_hereKeep 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:
{ "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. |
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
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):
{
"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:
{ "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.
