Discounts

A discount is a code that reduces price at checkout — percentage-off or fixed-amount, optionally limited in duration, redemptions, and which price variants it covers. Create it once, then apply it wherever buyers pay. You can ask Crevio to “make a 20% launch code that expires in two weeks” and the agent creates the discount through the same API below. For programmatic campaigns, you’ll create them directly.

The discount model

POST /discounts returns a discount with an id like disc_.... The shape is centered on two enums: the type of discount and its duration.

Field	Type	Notes
`code`	string	The code buyers enter, e.g. `LAUNCH20`.
`discount_type`	enum	`percentage` or `fixed`.
`percent_off`	number	The percentage off (for `percentage` discounts), e.g. `20`.
`amount_off`	int (cents)	The amount off (for `fixed` discounts), e.g. `1000` = $10.00.
`currency`	string	Lowercase ISO, required for `fixed` discounts.
`duration`	enum	`forever`, `once`, or `repeating` — how long the discount applies to a subscription.
`duration_in_months`	int	Required when `duration` is `repeating`.
`starts_at`	date-time	The code is rejected at checkout before this. Omit to make it usable right away.
`redeem_by`	date-time	Expiry — the code stops working after this.
`max_redemptions`	int	How many live orders can use the code, across all customers. Test purchases don’t count.
`times_redeemed`	int	Read-only. Live orders that used the code so far.
`minimum_amount`	int (cents)	Smallest subtotal, before the discount, that can use the code. Requires `currency`; a checkout in another currency is refused.
`once_per_customer`	boolean	Each customer can use the code on one live order. Default `false`.
`first_order_only`	boolean	Only customers with no earlier live paid order from this business can use the code. Free orders and test purchases don’t count as earlier orders. Default `false`.
`price_variants`	array	Price variant ids (`price_...`) the discount is scoped to. Every line item must be in scope, or the code is refused. Omit to apply account-wide.

duration matters most for subscriptions: once discounts only the first charge, repeating discounts for duration_in_months, and forever discounts every charge. For one-time purchases the discount simply applies to that purchase.

Worked example: a 20% launch code

A percentage code, capped at 500 redemptions, expiring in two weeks, applying to everything:

curl -X POST https://api.crevio.co/v1/discounts \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "LAUNCH20",
    "discount_type": "percentage",
    "percent_off": 20,
    "duration": "once",
    "redeem_by": "2026-07-05T00:00:00Z",
    "max_redemptions": 500
  }'

const discount = await crevio.discounts.create({
  code: "LAUNCH20",
  discount_type: "percentage",
  percent_off: 20,
  duration: "once",
  max_redemptions: 500,
});

Worked example: $10 off, scoped to one variant

A fixed-amount code that only works on a specific price variant:

curl -X POST https://api.crevio.co/v1/discounts \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SAVE10",
    "discount_type": "fixed",
    "amount_off": 1000,
    "currency": "usd",
    "duration": "once",
    "price_variants": ["price_abc123"]
  }'

Because price_variants lists a single variant, SAVE10 is rejected at checkout for any other item.

Worked example: a welcome code for new customers

15% off a first order of at least $50, usable once per customer:

curl -X POST https://api.crevio.co/v1/discounts \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "WELCOME15",
    "discount_type": "percentage",
    "percent_off": 15,
    "duration": "once",
    "minimum_amount": 5000,
    "currency": "usd",
    "once_per_customer": true,
    "first_order_only": true
  }'

minimum_amount, once_per_customer, and first_order_only can be changed later with PATCH /v1/discounts/{id}. Send "minimum_amount": null to remove the minimum.

Eligibility and redemptions

Crevio, not Stripe, decides whether a code applies. The checks run in this order, and the first failure is the reason the buyer sees:

Check	Message
`status` is `active`	That discount code isn’t valid.
`starts_at` has passed	That discount code isn’t active yet.
`redeem_by` hasn’t passed	That discount code has expired.
`times_redeemed` is below `max_redemptions`	That discount code has reached its usage limit.
Every line item is in `price_variants`	That code only applies to specific products, which aren’t in your cart.
Subtotal meets `minimum_amount` in the same currency	That code needs an order of at least $50.00.
`once_per_customer`: the customer hasn’t redeemed it	You’ve already used that discount code.
`first_order_only`: the customer has no earlier live paid order	That code is only for your first order.

The two customer checks need to know who is buying. A checkout created with customer or email is checked when it’s created. On the hosted checkout page, a guest is checked again with the email they enter, before payment is taken. If a payment still completes with an ineligible code, the order is kept and the redemption is recorded. A redemption is recorded when a live order paid with the code is created, which increments times_redeemed. Test purchases never count. A discount with at least one redemption can’t be deleted; set status to inactive instead.

Applying a discount

A discount reaches a buyer in one of two ways:

At checkout — `discount_code`

Pass the code’s string when creating a checkout. Every eligibility check above runs against the checkout’s line items and its customer or email. A code that fails returns 400 with code: "invalid_parameter" and the reason as message, and no checkout is created:

curl -X POST https://api.crevio.co/v1/checkouts \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "discount_code": "LAUNCH20",
    "line_items": [{ "price_variant": "price_abc123", "quantity": 1 }]
  }'

On a checkout link — `discount`

Attach a discount by id to a reusable checkout link so it’s applied automatically, and decide whether buyers may also enter their own code:

curl -X POST https://api.crevio.co/v1/checkout_links \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Launch link",
    "price_variants": ["price_abc123"],
    "discount": "disc_launch20",
    "allow_discount_codes": false
  }'

In a link — `?discount=`

Append ?discount=CODE to a buy link (/buy/{price_variant_or_checkout_link_id}) or a hosted checkout URL (/checkout/{checkout_id}). The checkout opens with the code applied, even when allow_discount_codes is false. An unusable code never errors: the checkout opens without it and shows the buyer the reason from the table above.

At checkout you reference a discount by its code (discount_code: "LAUNCH20"); on a checkout link you reference it by its id (discount: "disc_launch20"). Set allow_discount_codes: false to lock a link to just its attached discount.

Discounts support full CRUD — create, update, delete, list, and retrieve.

Next steps

Checkouts

Apply discounts via discount_code and on reusable checkout links.

Products & pricing

Create the price variants you scope discounts to.

Subscriptions & billing

How duration shapes discounts on recurring subscriptions.

Commerce overview

See where discounts sit in the full commerce model.

Getting started

AI & agents

Core concepts

Integrations

Recipes

The discount model

Worked example: a 20% launch code

Worked example: $10 off, scoped to one variant

Worked example: a welcome code for new customers

Eligibility and redemptions

Applying a discount

At checkout — `discount_code`

On a checkout link — `discount`

In a link — `?discount=`

Next steps

Checkouts

Products & pricing

Subscriptions & billing

Commerce overview

​The discount model

​Worked example: a 20% launch code

​Worked example: $10 off, scoped to one variant

​Worked example: a welcome code for new customers

​Eligibility and redemptions

​Applying a discount

​At checkout — discount_code

​On a checkout link — discount

​In a link — ?discount=

​Next steps

Checkouts

Products & pricing

Subscriptions & billing

Commerce overview

The discount model

Worked example: a 20% launch code

Worked example: $10 off, scoped to one variant

Worked example: a welcome code for new customers

Eligibility and redemptions

Applying a discount

At checkout — `discount_code`

On a checkout link — `discount`

In a link — `?discount=`

Next steps