Discounts

Manage discounts for a website.

List discounts

GET

https://api.squarespace.com

/v1/commerce/discounts

Returns a paginated list of discounts for the website. Requires OAuth website scope website.discounts.read or website.discounts, or API key scope DISCOUNTS_READONLY or DISCOUNTS.

List discounts › query Parameters

sortBy

string · enum

Sort field for the result set.

Enum values:

CREATED_ON

PROMO_CODE

USES_COUNT

Default: CREATED_ON

sortDirection

string · enum

Sort direction.

Enum values:

ASCENDING

DESCENDING

Default: DESCENDING

search

string

Free-text search across a discount's name and promo code.

status

string · enum

Filter by discount lifecycle status.

Enum values:

ALL

ACTIVE

EXPIRED

SCHEDULED

Default: ALL

criteria

string[]

Filter by one or more criteria types (comma-separated). When omitted, defaults to all allowable values.

Enum values:

ANY_ORDER

CART_TOTAL

PRODUCT

BUY_X_GET_Y

Default: ["ANY_ORDER","CART_TOTAL","PRODUCT","BUY_X_GET_Y"]

template

string[]

Filter by one or more template types (comma-separated). When omitted, defaults to all allowable values.

Enum values:

FIXED_AMOUNT

PERCENTAGE

BUY_X_GET_Y_FIXED_AMOUNT

BUY_X_GET_Y_PERCENTAGE

FREE_SHIPPING

Default: ["FIXED_AMOUNT","PERCENTAGE","BUY_X_GET_Y_FIXED_AMOUNT","BUY_X_GET_Y_PERCENTAGE","FREE_SHIPPING"]

trigger

string[] · enum

Filter by one or more trigger types (comma-separated): AUTO (auto-applied) or CODE (promo code). When omitted, or when all allowable values are supplied, defaults to all allowable values.

Enum values:

AUTO

CODE

limitedUseOnly

boolean

When true, only discounts with limited-use semantics (per product rules) are returned.

Default: false

offset

integer · int32 · min: 0

Zero-based offset into the result set. Must be non-negative. Default 0.

Default: 0

limit

integer · int32 · min: 1 · max: 1000

Page size (1–1000; default 50).

Default: 50

List discounts › Headers

Authorization

string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN

User-Agent

string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

List discounts › Responses

Paginated discounts for the website (empty page is a successful response).

Offset-paginated list of discounts for a website.

PaginatedDiscountListResponse

Discount[] · required

Discounts for this page.

hasNextPage

boolean

True when more results exist after the current window.

hasPreviousPage

boolean

True when a page of results exists before the current window.

GET/v1/commerce/discounts

curl https://api.squarespace.com/v1/commerce/discounts \
  --header 'User-Agent: YOUR_CUSTOM_APP_DESCRIPTION' \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "discounts": [
    {
      "criteria": {
        "type": "type"
      },
      "id": "id",
      "isLimitedUses": true,
      "isOncePerCustomer": true,
      "lastRedeemedAt": "2024-08-25T15:00:00Z",
      "maxUsesAllowed": 0,
      "name": "name",
      "numberOfUses": 0,
      "paymentPlanOptions": {
        "type": "NONE"
      },
      "status": "ACTIVE",
      "subscriptionOptions": {
        "type": "EXCLUDED"
      },
      "template": {
        "type": "type",
        "discountAmount": {
          "currency": "USD",
          "value": 49.99
        },
        "maxApplicationsPerCart": 0
      },
      "trigger": {
        "type": "type"
      },
      "validFrom": "2024-08-25T15:00:00Z",
      "validTo": "2024-08-25T15:00:00Z",
      "websiteId": "websiteId"
    }
  ],
  "hasNextPage": true,
  "hasPreviousPage": true
}

json

application/json

Create discount

POST

https://api.squarespace.com

/v1/commerce/discounts

Creates a discount. A successful request returns the created Discount resource. Requires OAuth website scope website.discounts, or API key scope DISCOUNTS.

Create discount › Headers

Authorization

string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN

User-Agent

string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Create discount › Request Body

Request body for creating a discount.

CreateDiscountRequest

required

name

string · required

Display name for the discount.

required

validFrom

string · date-time · required

When the discount becomes active.

isLimitedUses

boolean

If true, the discount can only be used maxUsesAllowed times site-wide.

isOncePerCustomer

boolean

If true, a given customer can only use this discount once.

maxUsesAllowed

integer · int32

Maximum site-wide redemptions. Required when isLimitedUses=true; null otherwise.

PaymentPlanOptions

Payment-plan applicability settings for this discount. When omitted from a create or update request, defaults to NONE.

SubscriptionOptions

Subscription applicability settings for this discount. When omitted from a create or update request, defaults to EXCLUDED.

validTo

string · date-time

When the discount expires. Null = no expiry.

Create discount › Responses

The created discount.

Envelope for a single discount response.

DiscountResponse

Discount · required

Discount configured for a Commerce store.

POST/v1/commerce/discounts

curl https://api.squarespace.com/v1/commerce/discounts \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: YOUR_CUSTOM_APP_DESCRIPTION' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "criteria": {
    "type": "type"
  },
  "isLimitedUses": true,
  "isOncePerCustomer": true,
  "maxUsesAllowed": 0,
  "name": "name",
  "paymentPlanOptions": {
    "type": "NONE"
  },
  "subscriptionOptions": {
    "type": "EXCLUDED"
  },
  "template": {
    "type": "type",
    "discountAmount": {
      "currency": "USD",
      "value": 49.99
    },
    "maxApplicationsPerCart": 0
  },
  "trigger": {
    "type": "type"
  },
  "validFrom": "2024-08-25T15:00:00Z",
  "validTo": "2024-08-25T15:00:00Z"
}'

Example Request Body

{
  "criteria": {
    "type": "type"
  },
  "isLimitedUses": true,
  "isOncePerCustomer": true,
  "maxUsesAllowed": 0,
  "name": "name",
  "paymentPlanOptions": {
    "type": "NONE"
  },
  "subscriptionOptions": {
    "type": "EXCLUDED"
  },
  "template": {
    "type": "type",
    "discountAmount": {
      "currency": "USD",
      "value": 49.99
    },
    "maxApplicationsPerCart": 0
  },
  "trigger": {
    "type": "type"
  },
  "validFrom": "2024-08-25T15:00:00Z",
  "validTo": "2024-08-25T15:00:00Z"
}

json

Example Responses

{
  "discount": {
    "criteria": {
      "type": "type"
    },
    "id": "id",
    "isLimitedUses": true,
    "isOncePerCustomer": true,
    "lastRedeemedAt": "2024-08-25T15:00:00Z",
    "maxUsesAllowed": 0,
    "name": "name",
    "numberOfUses": 0,
    "paymentPlanOptions": {
      "type": "NONE"
    },
    "status": "ACTIVE",
    "subscriptionOptions": {
      "type": "EXCLUDED"
    },
    "template": {
      "type": "type",
      "discountAmount": {
        "currency": "USD",
        "value": 49.99
      },
      "maxApplicationsPerCart": 0
    },
    "trigger": {
      "type": "type"
    },
    "validFrom": "2024-08-25T15:00:00Z",
    "validTo": "2024-08-25T15:00:00Z",
    "websiteId": "websiteId"
  }
}

json

application/json

Get discount

GET

https://api.squarespace.com

/v1/commerce/discounts/{discountId}

Returns the discount for the given discount ID. Requires OAuth website scope website.discounts.read or website.discounts, or API key scope DISCOUNTS_READONLY or DISCOUNTS.

Get discount › path Parameters

discountId

string · required

The discount's ID

Get discount › Headers

Authorization

string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN

User-Agent

string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Get discount › Responses

Discount found.

Envelope for a single discount response.

DiscountResponse

Discount · required

Discount configured for a Commerce store.

GET/v1/commerce/discounts/{discountId}

curl https://api.squarespace.com/v1/commerce/discounts/:discountId \
  --header 'User-Agent: YOUR_CUSTOM_APP_DESCRIPTION' \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "discount": {
    "criteria": {
      "type": "type"
    },
    "id": "id",
    "isLimitedUses": true,
    "isOncePerCustomer": true,
    "lastRedeemedAt": "2024-08-25T15:00:00Z",
    "maxUsesAllowed": 0,
    "name": "name",
    "numberOfUses": 0,
    "paymentPlanOptions": {
      "type": "NONE"
    },
    "status": "ACTIVE",
    "subscriptionOptions": {
      "type": "EXCLUDED"
    },
    "template": {
      "type": "type",
      "discountAmount": {
        "currency": "USD",
        "value": 49.99
      },
      "maxApplicationsPerCart": 0
    },
    "trigger": {
      "type": "type"
    },
    "validFrom": "2024-08-25T15:00:00Z",
    "validTo": "2024-08-25T15:00:00Z",
    "websiteId": "websiteId"
  }
}

json

application/json

Update discount

PUT

https://api.squarespace.com

/v1/commerce/discounts/{discountId}

Replaces the discount for the given discount ID. Requires OAuth website scope website.discounts, or API key scope DISCOUNTS.

Update discount › path Parameters

discountId

string · required

The discount's unique identifier.

Update discount › Headers

Authorization

string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN

User-Agent

string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Update discount › Request Body

Discount configured for a Commerce store.

Discount

required

name

string · required

Display name for the discount.

required

validFrom

string · date-time · required

When the discount becomes active.

id

string · readOnly

Discount id.

isLimitedUses

boolean

If true, the discount can only be used maxUsesAllowed times site-wide.

isOncePerCustomer

boolean

If true, a given customer can only use this discount once.

lastRedeemedAt

string · date-time · readOnly

Timestamp of the most recent redemption. Null if never redeemed.

maxUsesAllowed

integer · int32

Maximum site-wide redemptions. Required when isLimitedUses=true; null otherwise.

numberOfUses

integer · int32 · readOnly

Number of times this discount has been redeemed.

PaymentPlanOptions

Payment-plan applicability settings for this discount. When omitted from a create or update request, defaults to NONE.

status

string · enum · readOnly

Defines the lifecycle status of a discount.

Enum values:

ACTIVE

SCHEDULED

EXPIRED

SubscriptionOptions

Subscription applicability settings for this discount. When omitted from a create or update request, defaults to EXCLUDED.

validTo

string · date-time

When the discount expires. Null = no expiry.

websiteId

string · readOnly

24-char website id.

Update discount › Responses

The updated discount.

Envelope for a single discount response.

DiscountResponse

Discount · required

Discount configured for a Commerce store.

PUT/v1/commerce/discounts/{discountId}

curl https://api.squarespace.com/v1/commerce/discounts/:discountId \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: YOUR_CUSTOM_APP_DESCRIPTION' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "criteria": {
    "type": "type"
  },
  "id": "id",
  "isLimitedUses": true,
  "isOncePerCustomer": true,
  "lastRedeemedAt": "2024-08-25T15:00:00Z",
  "maxUsesAllowed": 0,
  "name": "name",
  "numberOfUses": 0,
  "paymentPlanOptions": {
    "type": "NONE"
  },
  "status": "ACTIVE",
  "subscriptionOptions": {
    "type": "EXCLUDED"
  },
  "template": {
    "type": "type",
    "discountAmount": {
      "currency": "USD",
      "value": 49.99
    },
    "maxApplicationsPerCart": 0
  },
  "trigger": {
    "type": "type"
  },
  "validFrom": "2024-08-25T15:00:00Z",
  "validTo": "2024-08-25T15:00:00Z",
  "websiteId": "websiteId"
}'

Example Request Body

{
  "criteria": {
    "type": "type"
  },
  "id": "id",
  "isLimitedUses": true,
  "isOncePerCustomer": true,
  "lastRedeemedAt": "2024-08-25T15:00:00Z",
  "maxUsesAllowed": 0,
  "name": "name",
  "numberOfUses": 0,
  "paymentPlanOptions": {
    "type": "NONE"
  },
  "status": "ACTIVE",
  "subscriptionOptions": {
    "type": "EXCLUDED"
  },
  "template": {
    "type": "type",
    "discountAmount": {
      "currency": "USD",
      "value": 49.99
    },
    "maxApplicationsPerCart": 0
  },
  "trigger": {
    "type": "type"
  },
  "validFrom": "2024-08-25T15:00:00Z",
  "validTo": "2024-08-25T15:00:00Z",
  "websiteId": "websiteId"
}

json

Example Responses

{
  "discount": {
    "criteria": {
      "type": "type"
    },
    "id": "id",
    "isLimitedUses": true,
    "isOncePerCustomer": true,
    "lastRedeemedAt": "2024-08-25T15:00:00Z",
    "maxUsesAllowed": 0,
    "name": "name",
    "numberOfUses": 0,
    "paymentPlanOptions": {
      "type": "NONE"
    },
    "status": "ACTIVE",
    "subscriptionOptions": {
      "type": "EXCLUDED"
    },
    "template": {
      "type": "type",
      "discountAmount": {
        "currency": "USD",
        "value": 49.99
      },
      "maxApplicationsPerCart": 0
    },
    "trigger": {
      "type": "type"
    },
    "validFrom": "2024-08-25T15:00:00Z",
    "validTo": "2024-08-25T15:00:00Z",
    "websiteId": "websiteId"
  }
}

json

application/json

Delete discount

DELETE

https://api.squarespace.com

/v1/commerce/discounts/{discountId}

Deletes the discount for the given discount ID. Deletion is permitted for any discount owned by the website, including discounts whose criteria, template, or trigger types are not supported by this API version; no type validation is performed. Requires OAuth website scope website.discounts, or API key scope DISCOUNTS.

Delete discount › path Parameters

discountId

string · required

The discount's ID.

Delete discount › Headers

Authorization

string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN

User-Agent

string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Delete discount › Responses

No content. The discount was deleted successfully.

No data returned

Get fulfillment options

GET

https://api.squarespace.com

/v1/fulfillments/fulfillment-options

Returns a list of fulfillment option IDs and carrier services that can be used with discounts. Requires OAuth website scope website.discounts.read or website.discounts, or API key scope DISCOUNTS_READONLY or DISCOUNTS.

Get fulfillment options › Headers

Authorization

string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN

User-Agent

string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Get fulfillment options › Responses

List of fulfillment option IDs and carrier services for the website.

List of fulfillment option IDs and carrier services.

FulfillmentOptionsList

FulfillmentOption[] · required

Fulfillment option IDs and carrier services for this website.

Analytics Products