Discounts API overview

Current version: v1
For versioning details, read the 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 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 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)