stubkit docs

Feature · Marketing · Web checkout

Discount codes

Public promo codes your users can type at checkout — percent-off or fixed-amount, with optional expiry and redemption limits. Stubkit stores the canonical definition; the underlying Stripe coupon is created lazily on first successful use so unused codes don't clutter your Stripe dashboard.

Create a code

Dashboard: /apps/<app_id>/discounts → fill the form. Or via REST:

POST /v1/admin/discount-codes
Authorization: Bearer sk_live_...

{
  "app_id": "taskpomo",
  "code": "BLACKFRIDAY50",
  "percent_off": 50,
  "max_redemptions": 1000,
  "expires_at": 1798761600000
}

For fixed-amount codes, replace percent_off with amount_off_cents + currency:

{
  "code": "SAVE5USD",
  "amount_off_cents": 500,
  "currency": "USD"
}

Apply at checkout

Your tenant app collects the code from the user and passes it in the checkout session call:

POST /v1/checkout/sessions

{
  "app_id": "taskpomo",
  "price_id": "price_1ABC...",
  "user_id": "user-123",
  "success_url": "https://taskpomo.app/thank-you",
  "cancel_url": "https://taskpomo.app/pricing",
  "discount_code": "BLACKFRIDAY50"
}

Stubkit validates (active + non-expired + redemptions-left), creates the Stripe coupon if needed, attaches it to the session, and increments the redemption counter. The checkout.session that lands on Stripe already has the discount applied — your user sees the reduced price.

Validation rules

  • Code must match ^[A-Z0-9_-]{3,64}$ (any casing accepted on input; uppercased before match).
  • Exactly one of percent_off OR amount_off_cents.
  • amount_off_cents requires currency; the Stripe coupon is minted in that currency.
  • max_redemptions null = unlimited. expires_at null = never expires.
  • Optimistic counter: redemption increments when the checkout session is created, not when payment completes. Abandoned checkouts inflate the count slightly.

Stripe-native promotion codes vs stubkit discount codes

Pass allow_promotion_codes: true in the checkout session body if you want users to type a Stripe-side promotion code too. Stubkit discount codes and Stripe promotion codes can coexist — they apply on different sides of the Stripe API.

Apple / Google promo codes

iOS and Android IAP promo codes are platform-specific and not creatable via stubkit — use App Store Connect and Play Console directly. Stubkit discount codes apply only to the web (Stripe) checkout path.