Skip to content

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:

{
  "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/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 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/create

Request:

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

Request:

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

  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}

Type to search…

↑↓ navigate↵ selectEsc close