---
title: "Calculate Cart Entries (Checkout & Custom Integrations)"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.giveawaygator.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/product-entry-tags) 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](#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**

```http
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**

```json
{
  "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](/entry-math).

---

## 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" }` |

Source: https://docs.giveawaygator.app/cart-entries-api/index.mdx
