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/apiAll 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_hereKeep 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:
{
"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:
{
"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.
POST /entries/calculateCreate 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 for the full request, errors, and limits. If you do not want to write code, use the Add Entries action in Shopify Flow.
POST /entries/createRequest:
{
"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):
{
"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 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.
POST /theme/pos-claim?shop=yourstore.myshopify.comRequest:
{
"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):
{
"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:
- Open Giveaway Gator in your Shopify admin.
- Click Manage on a promotion.
- The promotion ID is in the URL:
/app/promos/{promotion-id}
