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

# Discounts

> Create percentage and fixed-amount discount codes, scope them to specific price variants, and apply them at checkout or on checkout links.

**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`.                                               |
| `redeem_by`          | date-time   | Expiry — the code stops working after this.                                            |
| `max_redemptions`    | int         | Total number of times the code can be used.                                            |
| `price_variants`     | array       | Price variant ids (`price_...`) the discount is scoped to. Omit to apply account-wide. |

<Note>
  `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.
</Note>

## Worked example: a 20% launch code

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

```bash theme={null}
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
  }'
```

```typescript theme={null}
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:

```bash theme={null}
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.

## 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:

```bash theme={null}
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](/developer/guides/checkouts#reusable-checkout-links) so it's applied automatically, and decide whether buyers may also enter their own code:

```bash theme={null}
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
  }'
```

<Tip>
  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.
</Tip>

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

## Next steps

<CardGroup cols={2}>
  <Card title="Checkouts" icon="cart-shopping" href="/developer/guides/checkouts">
    Apply discounts via `discount_code` and on reusable checkout links.
  </Card>

  <Card title="Products & pricing" icon="tag" href="/developer/guides/products-and-pricing">
    Create the price variants you scope discounts to.
  </Card>

  <Card title="Subscriptions & billing" icon="arrows-rotate" href="/developer/guides/subscriptions-and-billing">
    How `duration` shapes discounts on recurring subscriptions.
  </Card>

  <Card title="Commerce overview" icon="diagram-project" href="/developer/guides/commerce-overview">
    See where discounts sit in the full commerce model.
  </Card>
</CardGroup>