Limits and tiers

Every account has a tier. Tiers define the limits below; higher tiers (bigger caps, better pricing) are assigned by the Wizzgift team — contact support with your expected volumes. New accounts start on the starter tier.

Reading your limits

Never hardcode limits — read them live from GET /b2b/account or GET /retailer/v1/account:

{
  "tier": "starter",
  "limits": {
    "maxQuantityPerItem": 250,
    "maxItemsPerOrder": 20,
    "maxOrderAmountUSD": 1000,
    "dailySpendCapUSD": 5000,
    "monthlySpendCapUSD": 50000,
    "maxDepositUSD": 2000,
    "rateLimitTier": "moderate",
    "maxOpenCheckouts": 25,
    "dailyCheckoutCreations": 200,
    "maxMarkupPercent": 20
  },
  "usage": {
    "daily": { "spentUsd": 1200, "capUsd": 5000 },
    "monthly": { "spentUsd": 14300, "capUsd": 50000 }
  }
}

The values above are illustrative — your actual limits come from your tier plus any per-account overrides, and are always current in the account response.

What each limit controls

Limit	Applies to
`maxQuantityPerItem`	Quantity on a single order line
`maxItemsPerOrder`	Number of lines in one order
`maxOrderAmountUSD`	USD value of a single order
`dailySpendCapUSD` / `monthlySpendCapUSD`	Rolling UTC-day / UTC-month B2B spend
`maxDepositUSD`	Single deposit size
`maxOpenCheckouts`	Simultaneously pending retailer checkouts
`dailyCheckoutCreations`	Retailer checkout creations per UTC day
`maxMarkupPercent`	Retailer markup, per checkout and account default

Handling limit errors

Exceeding a limit returns 422 with code B2B_LIMIT_EXCEEDED and machine-readable details:

{
  "error": {
    "code": "B2B_LIMIT_EXCEEDED",
    "message": "Daily spend cap exceeded",
    "details": {
      "limit": "dailySpendCapUSD",
      "limitValue": 5000,
      "current": 4800,
      "requested": 400,
      "window": "day",
      "tier": "starter"
    }
  },
  "requestId": "req_8f3k2"
}

Switch on details.limit to react: queue the order for the next window (dailySpendCapUSD), split it (maxOrderAmountUSD, maxQuantityPerItem), or surface an upgrade prompt.

Rate limiting

API traffic is rate-limited per account, keyed to your tier’s rateLimitTier (strict, moderate, or general). Exceeding it returns 429:

{ "error": "Too many requests", "message": "Rate limit exceeded. Please try again later." }

The 429 body is a flat shape, not the standard error envelope — match on the status code, not the body structure.

Back off exponentially on 429. Spread bulk operations (catalog syncs, reconciliation sweeps) instead of bursting them.

Rebates

Tiers can carry volume rebate offers: spend targetAmountUsd within the window and rewardAmountUsd is credited to your balance. Progress is returned under rebates in the account response — no separate tracking needed.

Getting started

Quickstarts

Core concepts

Webhooks

Reading your limits

What each limit controls

Handling limit errors

Rate limiting

Rebates

​Reading your limits

​What each limit controls

​Handling limit errors

​Rate limiting

​Rebates

Reading your limits

What each limit controls

Handling limit errors

Rate limiting

Rebates