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

# Organization discounts

> Create one promotion for an organization and target all or selected locations safely.

Crave promotions belong to one organization. A definition can apply to every active location or an
explicit location set, while product and category rules use canonical organization catalog IDs.
Location pricing, availability, publication revision, and timezone are resolved again when the cart
is evaluated and immediately before payment.

## Authentication and scopes

Private management calls use an authenticated Business Manager session or a server-only
`X-API-Key`. API-key reads require `catalog:read`; API-key creates, updates, and archives require
`catalog:write`. Business Manager mutations require an organization administrator. A
location-limited key cannot create an all-location definition, target a location outside its
grants, or read/mutate a definition whose complete selected-location set is not contained by those
grants.

Storefront cart calls use the cart capability and `Idempotency-Key`, never a private API key.

## Create a definition

Call `POST /api/v1/discounts`. Codes are trimmed and normalized to uppercase, and are unique within
the organization. Use `locationScope: "all"` with an empty `locationIds` array, or
`locationScope: "selected"` with at least one organization-owned location ID.

```json theme={null}
{
  "code": "LUNCH10",
  "description": "Weekday lunch promotion",
  "state": "active",
  "locationScope": "selected",
  "locationIds": ["11111111-1111-4111-8111-111111111111"],
  "currency": "USD",
  "value": {
    "type": "percentage",
    "basisPoints": 1000,
    "maximumAmountMinor": 1500
  },
  "target": {
    "type": "categories",
    "ids": ["22222222-2222-4222-8222-222222222222"]
  },
  "application": "each_eligible_item",
  "minimumSubtotalMinor": 2000,
  "totalLimit": 500,
  "perCustomerLimit": 1,
  "weeklySchedule": [
    { "dayOfWeek": 1, "startsAt": "11:00", "endsAt": "14:00" },
    { "dayOfWeek": 2, "startsAt": "11:00", "endsAt": "14:00" }
  ]
}
```

Money uses integer minor units and percentages use basis points (`1000` = 10%). Weekly windows use
the location timezone and half-open intervals: the start is included and the end is excluded.
`dayOfWeek` is `0` for Sunday through `6` for Saturday. A per-customer limit requires a verified
organization customer; guests fail closed for that code.

Use `GET /api/v1/discounts/catalog-targets` to discover active canonical products and categories and
the locations where each target is currently published.

## Preview, update, and archive

* `GET /api/v1/discounts` lists definitions with organization and per-location ledger metrics.
* `GET /api/v1/discounts/{discountId}` reads one definition.
* `POST /api/v1/discounts/{discountId}/preview` evaluates supplied cart lines without reserving or
  consuming usage.
* `PUT /api/v1/discounts/{discountId}` requires the current positive `revision` in the request body.
* `DELETE /api/v1/discounts/{discountId}` archives the definition and requires `{ "revision": N }`.

Disabling or archiving an active definition with reserved or committed usage fails closed unless the
request also includes `"confirmActiveUsage": true`. Business Manager asks for this confirmation and
then sends the same explicit API evidence; integrations must do likewise.

A stale revision or normalized duplicate returns a conflict. Foreign locations and targets are not
disclosed. Archiving prevents new evaluation but does not rewrite historical order or redemption
evidence.

## Storefront use

Apply a code with
`POST /api/v1/storefront/locations/{locationId}/carts/{cartId}/discount` and `{ "code": "LUNCH10" }`.
Remove it with the corresponding `DELETE`. Both mutations require the cart capability, an
`Idempotency-Key`, and the current cart precondition used by the Storefront contract.

Crave supports one public promotion or one loyalty reward on a cart, not both. Applying a public
code while loyalty is reserved fails without silently releasing the reward. The response is the
authoritative cart, including the exact adjustment and current revision.

At payment creation Crave evaluates the definition again, reserves capacity atomically, and stores
the definition, cart, and catalog revisions. Payment cancellation releases the reservation; order
materialization commits it; a full provider-confirmed refund reverses it. Partial refunds retain the
usage and record cumulative proportional evidence.

> [!WARNING]
>
> Do not calculate discount eligibility or usage limits in a client. Never retry
> checkout with a new idempotency key after an ambiguous response; read the cart
> or order and reconcile the canonical state first.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.