Faizo

Writing · Stripe · Payments · Rust

Stripe Checkout: a 100%-off promo code that doesn't ask for a card

A 100%-off-forever promo code still showed a card form in Stripe Checkout. Why, and the API details that let your own promo field skip the card.

I wanted to hand out a few free plans for DWEEB: a promotion code for 100% off, forever. Someone with the code should be able to subscribe without entering a card, since they will never be charged. I created the coupon and the code in Stripe, opened Checkout, typed the code into Checkout's promo field, and watched the total drop to $0.00, right above a card form that still had to be filled in.

Here's why, and the setup that works.

Why Checkout still asks for a card

Stripe Checkout can skip card collection for a subscription, but only when two things are true:

  1. the session is created with payment_method_collection=if_required, and
  2. the amount due is already zero when the session is created.

A code typed into Checkout's own promotion-code box is applied after the session exists. The session was built expecting payment, and the card form doesn't go away when the total changes. So a free code entered there discounts the total to zero and still demands a card. There's no way to warn the customer from your side, because the session was already created with card collection on.

The conclusion is that the discount has to arrive with the session-creation request. That means your own promo-code field, sent to your server, applied server-side.

The setup that works

The pricing dialog has its own "Have a promo code?" field. The server looks the code up, checks it, and creates the Checkout Session with the discount attached:

POST /v1/checkout/sessions
  mode=subscription
  line_items[0][price]=price_…
  line_items[0][quantity]=1
  discounts[0][promotion_code]=promo_…          # resolved from the customer's code
  payment_method_collection=if_required          # only when the code covers everything
  success_url=…
  cancel_url=…

Some rules matter here.

Never send allow_promotion_codes

allow_promotion_codes=true shows Checkout's own promo box, and it's mutually exclusive with discounts: Stripe rejects a session that carries both. Leaving it off also removes the trap above. Checkout's box sits right next to the price and looks official, so that's where people type codes. When it doesn't exist, your field is the only way in, and it's always the one that works. Nothing is lost: partial-discount codes work through your field too, and still collect a card as they should. Because it's now the only entrance, I show the field openly rather than hiding it behind a link.

Skip the card only when the code really covers everything

if_required is set only when the coupon is percent_off >= 100 and duration = forever. A 100%-off coupon that lasts three months still needs the card its first real renewal will charge. A fixed amount_off that happens to equal today's price is excluded too: if the price ever goes up, that customer has no card on file and the renewal fails.

Accept only the customer-facing code

The client sends the text the customer typed, never a coupon ID or a promo_… ID. Promotion codes are the objects Stripe designed to be handed out, with their own redemption limits. The server resolves the code and re-checks it rather than trusting a filter alone:

GET /v1/promotion_codes?code=FREEFOREVER&active=true&limit=1&expand[]=data.promotion.coupon

checks: active, expires_at (if set) in the future,
        times_redeemed < max_redemptions (if set), coupon.valid

The API-version trap: where the coupon lives

This one cost me a confusing hour. Older Stripe API versions return the coupon inline at the top level of a promotion code (promotion_code.coupon). On the API version my account uses, the coupon is referenced under promotion.coupon, and only as an ID unless you expand it (expand[]=data.promotion.coupon in a list request). My first parser only read the top-level field, found nothing, and concluded that a live, valid, 100%-off-forever code was expired. I only found out by querying Stripe by hand.

Two lessons came out of that:

  • Read both shapes when a field moved between API versions, especially in a codebase that might be pinned to a different version than your dashboard.
  • Not being able to read the coupon is not a rejection. If the coupon can't be parsed, the code is still applied (Stripe validates it at session creation anyway). It just doesn't qualify for card-free checkout. Refusing a valid code because your parser failed is the worse failure.

Product restrictions are expandable too

A coupon can be limited to specific products with applies_to. That field is expandable, so a plain GET /v1/coupons/{id} omits it, and a restricted coupon looks unrestricted. Ask with ?expand[]=applies_to, and never conclude "no restriction" from the field's absence. If a session is created with a code whose restrictions don't fit the price, Stripe rejects it, and your customer sees an error from a pricing card that promised them a discount.

Errors are the customer's, not yours

In my setup, any 5xx from my API server pages me. A mistyped code and a code that doesn't apply to the chosen plan are both ordinary customer situations, so they return 4xx with a clear message ("That promo code isn't valid", "That promo code can't be used on this plan"). To do that, the Stripe client has to keep Stripe's status code rather than flattening every failure into a string: a 4xx from Stripe about the discount is a customer problem, a 5xx or a network failure is not.

The checkout route also has its own rate limit, since every call creates a Stripe session and may look up a code. Expiry dates and redemption limits stay in Stripe, which already enforces them. I don't rebuild them.

Summary

  • To skip the card, the session must be created with the discount already applied and payment_method_collection=if_required.
  • Use your own promo field and discounts[0][promotion_code]. Don't send allow_promotion_codes.
  • Only skip the card for coupons that are 100% off and last forever.
  • Expect promotion.coupon versus top-level coupon depending on API version, and expand what you need.
  • Return customer mistakes as 4xx.