Use this endpoint to calculate giveaway entries for a cart before checkout completes. It runs the same entry engine as real orders and returns totals for every active promotion on the shop.
Typical uses:
- Checkout UI extension — show live entry counts as the customer edits their cart
- Custom storefronts — cart drawer, headless checkout, or any integration that needs discounted, multi-line totals
Product cards vs. cart: Entries on product cards use the app embed and list price for a single product. They do not call this API. For cart-level math (discounts, multiple lines), use this endpoint or the checkout extension.
Identify the shop with the shop field in the JSON body (your myshopify.com domain).
Endpoint
Direct app URL
POST https://giveawaygator.app/api/entries/calculate
Content-Type: application/jsonApp proxy (same handler)
POST https://{shop}.myshopify.com/apps/giveaway-gator/api/entries/calculate
Content-Type: application/jsonShopify may add query parameters on proxy requests (shop, signature, timestamp, etc.). The shop used for calculation is always the shop value in the JSON body.
CORS: Browser clients may call the direct app URL. OPTIONS is supported for preflight (Access-Control-Allow-Origin: *).
Request body
| Field | Type | Required | Description |
|---|---|---|---|
shop |
string | Yes | Shop domain, e.g. your-store.myshopify.com |
lineItems |
array | Yes | Cart lines (may be empty) |
discountCodes |
string[] | Yes | Discount codes applied at checkout; use [] if none |
totalPrice |
number | Yes | Cart total from checkout (cost.totalAmount) |
checkoutOrderAllocationTotal |
number | No | Order-level merchandise discount gap (see After-discount counting) |
tags |
string[] | No | Order tags for tag bonuses (requires Order Tag Bonuses on the shop) |
Line item fields
| Field | Type | Required | Description |
|---|---|---|---|
productId |
string | Yes | Shopify product GID or numeric ID |
variantId |
string | Yes | Variant GID or numeric ID |
quantity |
number | Yes | Quantity |
price |
number | Yes | Unit list/catalog price when after-discount counting is off |
title |
string | Yes | Line title |
checkoutAfterLineDiscounts |
number | No | Line merchandise total after line-level discounts; used when after-discount counting is on |
lineItemGroupId |
string | null | No | Bundle/group identifier when applicable |
bundleProductId |
string | null | No | Parent bundle product ID |
bundleVariantId |
string | null | No | Parent bundle variant ID |
bundleQuantity |
number | null | No | Bundle quantity |
bundleTitle |
string | null | No | Bundle title |
Checkout-aligned values
checkoutAfterLineDiscounts— per-line merchandise after line discounts (bundle components expanded).price— pre-discount unit price when after-discount counting is off; when it is on, counting usescheckoutAfterLineDiscountsand allocation logic instead of list price × quantity.checkoutOrderAllocationTotal— gap between the sum of line totals (after line discounts) and merchandise actually paid (totalAmountminus shipping, minus tax when tax is not included in prices). Covers order-level cart discounts; shipping discounts are not included.totalPrice— parsedtotalAmountfrom checkout (as Shopify reports it, including shipping/tax where applicable).discountCodes— code strings only; the engine matches configured bonus entry rules by code (not discount amounts).
Response
Top-level envelope:
| Field | Type | Description |
|---|---|---|
success |
boolean | Whether the request succeeded |
message |
string | Human-readable summary (optional) |
error |
string | Present when success is false |
promotions |
array | One result per active promotion (empty on errors) |
Each item in promotions:
| Field | Type | Description |
|---|---|---|
id |
string | Promotion ID |
name |
string | Promotion name |
totalEntries |
number | Final entry count for this cart |
baseEntries |
number | Entries from merchandise before bonuses/multipliers |
breakdown |
object | Numeric breakdown of bonuses and multipliers |
appliedBonuses |
object | Which rules fired (product bonuses, order bonus, codes, bonus period, order multipliers, tags) |
breakdown fields
| Field | Meaning |
|---|---|
productBonusEntries |
Flat product bonus entries |
productMultiplier |
Winning product-level multiplier for the cart |
orderBonusEntries |
Flat entries from order value thresholds |
discountCodeBonusEntries |
Flat entries from matched discount codes |
bonusPeriodMultiplier |
Active time-based bonus period multiplier |
orderMultiplierTotal |
Combined order multiplier product effect |
preOrderMultiplierEntries |
Subtotal immediately before the final order-multiplier step |
checkoutBonusEntries |
Deprecated — always 0 |
tagBonusEntries |
Flat entries from order tag bonuses |
tagMultiplier |
Order tag multiplier applied to the subtotal |
appliedBonuses
| Field | Description |
|---|---|
productBonuses |
Per-product bonuses (productId, name, bonusEntries, multiplier) |
orderBonus |
Threshold bonus or null |
discountCodes |
Matched codes and bonus entries |
activeBonusPeriod |
Active bonus period or null |
orderMultipliers |
Purchased multiplier products (multiplierType: upgrade or super) |
checkoutBonus |
Deprecated — always null |
tagBonuses |
Matched tags and entries/multiplier |
Promotions outside their date window return totalEntries: 0 for that promo. If one promotion fails to calculate, others can still appear in the response.
Example
Single-line cart: $100 hat, no discounts, promotion at $1 per entry with a 25× bonus period active.
Request
POST https://giveawaygator.app/api/entries/calculate
Content-Type: application/json
{
"shop": "example.myshopify.com",
"totalPrice": 100,
"checkoutOrderAllocationTotal": 0,
"discountCodes": [],
"lineItems": [
{
"productId": "gid://shopify/Product/100",
"variantId": "gid://shopify/ProductVariant/100-v",
"quantity": 1,
"price": 100,
"title": "Hat",
"checkoutAfterLineDiscounts": 100
}
]
}Response
{
"success": true,
"promotions": [
{
"id": "promo_abc123",
"name": "Spring Giveaway",
"totalEntries": 2500,
"baseEntries": 100,
"breakdown": {
"productBonusEntries": 0,
"productMultiplier": 1,
"orderBonusEntries": 0,
"discountCodeBonusEntries": 0,
"bonusPeriodMultiplier": 25,
"orderMultiplierTotal": 1,
"preOrderMultiplierEntries": 2500,
"checkoutBonusEntries": 0,
"tagBonusEntries": 0,
"tagMultiplier": 1
},
"appliedBonuses": {
"productBonuses": [],
"orderBonus": null,
"discountCodes": [],
"activeBonusPeriod": {
"id": "bp_xyz",
"name": "25X Weekend",
"multiplier": 25
},
"orderMultipliers": [],
"checkoutBonus": null,
"tagBonuses": []
}
}
],
"message": "Calculated entries for 1 active promotions"
}Exact numbers depend on your live promotion settings.
How entries are calculated
The server evaluates each active promotion separately at request time (using the promotion’s timezone for bonus windows). In plain terms:
- Base entries — For each line, divide earning merchandise by the promotion’s dollar-per-entry rate and round down.
- Promotion window — Outside the start/end dates, that promotion returns zero entries.
- Product bonuses — Per-product multipliers or flat bonuses (product bonus periods, super bonuses, or promotion defaults).
- Bonus period — Time-based shop multiplier on lines without their own product bonus.
- Order bonuses — Extra entries when counted merchandise crosses spending thresholds.
- Discount code bonuses — Flat entries for codes you’ve configured in the promotion.
- Order tag bonuses — If enabled and you send
tags, matching tag rules apply. - Order multiplier products — Virtual “upgrade” or “super” products that multiply entries (upgrade replaces other multipliers; super applies at the end).
For a full walkthrough with examples, see How Entry Math Works.
After-discount counting
Some shops enable after-discount entries (after-discount-entries feature flag). When it is on:
- Send
checkoutAfterLineDiscountson each line andcheckoutOrderAllocationTotalfor order-level merchandise discounts. - The engine prorates counted merchandise from those values.
When it is off, send list-style price × quantity (the checkout extension reconstructs pre-discount unit prices). Discount code strings still drive bonus entry rules; they do not change base merchandise counting unless your shop counts entries after discounts.
Rate limits
30 requests per minute per IP.
When exceeded, the API returns 429 with success: false, an error message, and promotions: [].
There is no response caching on this endpoint.
Errors
| Status | Condition | Body |
|---|---|---|
400 |
Missing shop |
{ "success": false, "error": "Shop parameter is required", "promotions": [] } |
400 |
Missing or invalid lineItems |
{ "success": false, "error": "Line items are required", "promotions": [] } |
405 |
GET or other non-POST methods |
{ "message": "Method not allowed" } |
429 |
Rate limit | { "success": false, "error": "<message>", "promotions": [] } |
500 |
Server error | { "success": false, "error": "<message>", "promotions": [] } |
200 |
No active promotions | { "success": true, "promotions": [], "message": "No active promotions found for this shop" } |
200 |
Success | { "success": true, "promotions": [...], "message": "Calculated entries for N active promotions" } |
