# Discounts API overview

**Current version: v1**  
*For versioning details, read the [Versioning](/commerce-apis/versioning) guide.*

Use the Discounts API to manage discounts for a Squarespace merchant site. The Discounts API provides create, read, update, delete and list (CRUDL) access to discount records.

## API resources

### Discounts

`Discount` represents a discount configured for a merchant site.

Every discount also has three required, independently-configurable parts:

- **`criteria`** - the conditions an order must meet for the discount to apply
- **`template`** - the shape of the discount itself (fixed amount or percentage)
- **`trigger`** - how the discount is activated (automatically or via a promo code)

Optional `subscriptionOptions` and `paymentPlanOptions` control how the discount applies to subscription and payment-plan payments, respectively.

### Criteria

`Criteria` is a polymorphic field, discriminated by a `type` property:

| Type | Fields                                                         | Description |
| --- |----------------------------------------------------------------| --- |
| `ANY_ORDER` | *(none)*                                                       | Applies to any order with no additional conditions. |
| `CART_TOTAL` | `minimumCartTotal` (monetary amount, required, greater than 0; `currency` optional, defaults to and must match the site's currency) | Applies when the cart total meets or exceeds a minimum. |
| `PRODUCT` | `productId`, `productName` (display snapshot)                  | Applies when the cart contains a specific product. |
| `BUY_X_GET_Y` | `requiredFullPriceQuantity`, `eligibleForDiscountQuantity` (both required, ≥ 1); `criteriaAppliesTo`/`criteriaProductIds` (buy side); `rewardAppliesTo`/`rewardProductIds` (reward side) | Applies when the cart contains a required quantity of qualifying items (buy side), granting a discount on a quantity of eligible items (reward side). Currently, both sides only support targeting by product (`PRODUCT`). |

### Template

`DiscountTemplate` is a polymorphic field, discriminated by a `type` property:

| Type | Fields                                                       | Description |
| --- |--------------------------------------------------------------| --- |
| `FIXED_AMOUNT` | `discountAmount` (monetary amount, required, greater than 0; `currency` optional, defaults to and must match the site's currency) | Reduces the order by a fixed monetary amount. |
| `PERCENTAGE` | `percentage` (1–100, required)                               | Reduces the order by a percentage. |
| `BUY_X_GET_Y_FIXED_AMOUNT` | `discountAmount` (monetary amount, required, greater than 0; `currency` optional, defaults to and must match the site's currency); `maxApplicationsPerCart` (0 = unlimited) | Applies a fixed monetary amount off each reward item in a `BUY_X_GET_Y` discount. |
| `BUY_X_GET_Y_PERCENTAGE` | `discountPercentage` ((0, 100], required); `maxApplicationsPerCart` (0 = unlimited) | Applies a percentage off each reward item in a `BUY_X_GET_Y` discount. |
| `FREE_SHIPPING` | `appliesToFulfillmentOptionType` (`SHIPPING`, `PICKUP`, or `LOCAL_DELIVERY`); `selectedShippingOption` | Waives shipping cost for eligible carts. See [Fulfillments API](#fulfillments-api) for how to look up shipping option and carrier service values. |

### Trigger

`Trigger` is a polymorphic field, discriminated by a `type` property:

| Type | Fields | Description                                                                                                                                                                                                                                 |
| --- | --- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `AUTO` | *(none)* | Automatically applied - no promo code required.                                                                                                                                                                                             |
| `CODE` | `promoCode` (required, 1–50 characters; letters, digits, underscore, hyphen) | Unlocked by a shopper-entered promo code. Codes that match the Squarespace gift card format (`GC` followed by 14 alphanumerics, with or without hyphens) are rejected, since promo codes and gift card codes share the same checkout input. |

### Subscription and payment plan options

`subscriptionOptions.type` controls how the discount applies to subscription payments: `EXCLUDED` (subscriptions don't receive the discount), `ALL_PAYMENTS` (every subscription payment), or `LIMITED_PAYMENTS` (only the first `maxPaymentsToApplyDiscount` payments, which is required when this type is used).

`paymentPlanOptions.type` controls how the discount applies to [Payment Plan](/commerce-apis/orders-overview#payment-plans) payments: `NONE` or `ALL_PAYMENTS`.

## Fulfillments API

`GET /v1/fulfillments/fulfillment-options` lists a site's shipping options and their available shipping services. Use it to look up the `id` (shipping option ID) and carrier service names needed to target a specific shipping option when creating a `FREE_SHIPPING` discount.

| Field | Description                                                                                                                                      |
| --- |--------------------------------------------------------------------------------------------------------------------------------------------------|
| `id` | Shipping option identifier.                                                                                                                      |
| `name` | Display name for the shipping option.                                                                                                            |
| `type` | Fulfillment channel: `SHIPPING`, `PICKUP`, or `LOCAL_DELIVERY`.                                                                                  |
| `availableServices` | Shipping services available on this option (`name`, `description`). Empty for options that aren't priced by a carrier (flat-rate, weight-based). |

## Cross-API resource relationships

| API | Field | Relationship |
| --- | --- | --- |
| **Products** | `criteria.productId` | A `PRODUCT` criteria discount targets a specific product by its Products API `id`. |

## Listing and filtering discounts

`GET /v1/commerce/discounts` supports the following query parameters:

- **Sorting** - `sortBy` (`CREATED_ON`, `PROMO_CODE`, or `USES_COUNT`, default `CREATED_ON`) and `sortDirection` (`ASCENDING` or `DESCENDING`, default `DESCENDING`)
- **Text search** - `search`, matched against discount name and promo code
- **Status** - `status` (`ALL`, `ACTIVE`, `EXPIRED`, or `SCHEDULED`, default `ALL`)
- **Type filters** - `criteria`, `template`, and `trigger` each accept a list of the type values described above
- **`limitedUseOnly`** - restrict results to discounts with a redemption cap
- **Pagination** - `offset` (default `0`) and `limit` (default `50`, maximum `1000`)

## Common workflows

**Create a promo-code discount for a specific product**  
Create a discount with a `PRODUCT` criteria referencing the target product's `id`, a `PERCENTAGE` or `FIXED_AMOUNT` template, and a `CODE` trigger with the desired promo code.

**Run a site-wide automatic sale**  
Create a discount with an `ANY_ORDER` criteria, a `PERCENTAGE` template, and an `AUTO` trigger so it applies without requiring shoppers to enter a code. Set `validFrom` and `validTo` to bound the sale window.

**Cap redemptions**  
Set `isLimitedUses` to `true` with a `maxUsesAllowed` to run a limited-quantity promotion, or set `isOncePerCustomer` to `true` to restrict a discount to a single use per customer.

## Not currently available

The following are not yet supported by the Discounts API:

- **Category criteria** - targeting a discount by product category rather than by individual `productId`
- **`CategoryId` criteria** - referencing a category by id (e.g., as a `BUY_X_GET_Y` buy-side or reward-side target)

## Further reading

- Become familiar with [common commerce terms](/commerce-apis/glossary) and how they're related to the API
- [Obtain an API key or use OAuth](/commerce-apis/authentication-and-permissions)
- Read the [FAQ](/commerce-apis/faq) guide for answers to common questions