Skip to content

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.

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:

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

Type to search…

↑↓ navigate↵ selectEsc close