Skip to content

Calculate Cart Entries (Checkout & Custom Integrations)

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/json

App proxy (same handler)

POST https://{shop}.myshopify.com/apps/giveaway-gator/api/entries/calculate
Content-Type: application/json

Shopify 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 uses checkoutAfterLineDiscounts and allocation logic instead of list price × quantity.
  • checkoutOrderAllocationTotal — gap between the sum of line totals (after line discounts) and merchandise actually paid (totalAmount minus shipping, minus tax when tax is not included in prices). Covers order-level cart discounts; shipping discounts are not included.
  • totalPrice — parsed totalAmount from 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:

  1. Base entries — For each line, divide earning merchandise by the promotion’s dollar-per-entry rate and round down.
  2. Promotion window — Outside the start/end dates, that promotion returns zero entries.
  3. Product bonuses — Per-product multipliers or flat bonuses (product bonus periods, super bonuses, or promotion defaults).
  4. Bonus period — Time-based shop multiplier on lines without their own product bonus.
  5. Order bonuses — Extra entries when counted merchandise crosses spending thresholds.
  6. Discount code bonuses — Flat entries for codes you’ve configured in the promotion.
  7. Order tag bonuses — If enabled and you send tags, matching tag rules apply.
  8. 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 checkoutAfterLineDiscounts on each line and checkoutOrderAllocationTotal for 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" }

Type to search…

↑↓ navigate↵ selectEsc close