Skip to content

Managing Discounts ​

Learn how to create, schedule, and retire discounts through the Management API, and how to generate single-use codes for them.

Overview ​

A discount changes what a reader pays at checkout. It either applies automatically or when the reader enters its code, for example WELCOME20. The Management API manages the same discounts as the Discounts page in the Sesamy portal.

Every discount moves through these statuses:

StatusMeaning
DRAFTJust created. Applies to nothing until you activate it.
PENDINGActivated, waiting for its startDate.
ACTIVEApplies to new purchases.
PAUSEDStopped by you. Applies to no new purchases until you activate it again.
EXPIREDIts endDate has passed.
CANCELEDRetired for good.
ACTIVATION_ERRORActivation failed. Contact Sesamy support.

You can only edit or cancel a discount while it is DRAFT or PAUSED. To change a live discount, pause it, edit it, and activate it again. Pausing or cancelling a discount never takes it away from subscriptions that already have it.

Base URL ​

https://api2.sesamy.com

Authentication ​

Reading discounts needs the discounts:read scope, and creating or changing them needs discounts:write. Request a Management API token from https://token.sesamy.com/oauth/token with the client credentials flow, and send it as a bearer token:

Authorization: Bearer YOUR_ACCESS_TOKEN

See Authentication for how to obtain a token.

API keys

The API key presets do not include the discounts scopes yet. Contact Sesamy to have them enabled for your client.

Discount Types ​

type decides what the discount does, and which fields parameters and conditions take. You can't change the type of an existing discount.

TypeWhat it does
percentageTakes a percentage off the price
fixedAmountTakes a fixed amount off the price
trialPeriodGives free days before the first bill
specialPriceTrancheSets an introductory price and billing period
developerTestMakes a purchase free, for testing your integration

Parameters ​

TypeFieldTypeDescription
percentagepercentagenumberPercentage to take off, above 0 and at most 100
fixedAmountamountnumberAmount to take off, in the currency of the purchase (for example 49.5)
percentage, fixedAmountnumberOfMonthsintegerHow long the discount applies to a subscription: 0 for the first bill only, -1 forever, or a number of months
percentage, fixedAmountcurbToMaxAmountnumber(Optional) Never take off more than this per bill
trialPerioddaysintegerLength of the trial
specialPriceTrancheperiodstringBilling period while the special price applies: day, week, month, quarter, or year
specialPriceTranchetimesintegerPeriods per bill, for example 3 with month for quarterly bills
specialPriceTrancheforcedPricePerItemnumber(Optional) Price per item while the special price applies. Defaults to the regular price
specialPriceTrancheforcedPriceTaxIncludedboolean(Optional) Whether forcedPricePerItem includes tax. Defaults to the item's VAT settings
specialPriceTranchenumberOfMonthsinteger(Optional) How long the special price applies. Defaults to one billing period

Every type except trialPeriod also limits which products it applies to:

FieldTypeDescription
allowSKUsstring[](Optional) Only apply to these products
allowPOsstring[](Optional) Only apply to these purchase options
ignoreSKUsstring[](Optional) Never apply to these products. percentage and fixedAmount only
requireVerticalsstring[](Optional) Only apply to these product types. percentage and fixedAmount only
ignoreVerticalsstring[](Optional) Never apply to these product types. percentage and fixedAmount only

Conditions ​

conditions limits when a discount can be used. Every field is optional.

FieldTypeApplies toDescription
totalTimesApplicableintegerEvery typeHow many times the discount can be used in total
totalTimesApplicablePerUserintegerEvery type except developerTestHow many times one reader can use the discount
minimumTotalItemsintegerpercentage, fixedAmountMinimum number of items in the cart
minimumTotalAmountnumberpercentage, fixedAmountMinimum cart total, in the currency of the purchase
skusstring[]trialPeriodOnly apply to these products
purchaseOptionIdsstring[]trialPeriodOnly apply to these purchase options

The API rejects a field that the discount's type doesn't take with a 400 naming the field.

Create a Discount ​

POST /management/discounts creates a discount as a DRAFT:

bash
curl -X POST https://api2.sesamy.com/management/discounts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "percentage",
    "name": "Welcome offer",
    "code": "WELCOME20",
    "startDate": "2026-10-01T00:00:00Z",
    "endDate": "2026-12-31T23:59:59Z",
    "parameters": {
      "percentage": 20,
      "numberOfMonths": 3,
      "allowSKUs": ["sid:acme-plus-monthly"]
    },
    "conditions": { "totalTimesApplicablePerUser": 1 }
  }'
FieldTypeDescription
typestringOne of the discount types
namestringName shown in the portal
descriptionstring(Optional) Internal description
codestring | null(Optional) The code readers enter: letters, digits, - and _, at most 64 characters. Stored in upper case. null applies the discount automatically. ANY is reserved
startDatestringWhen the discount starts applying, ISO 8601 with Z or an offset
endDatestringWhen it stops applying
currencystring(Optional) Only apply to purchases in this currency, for example SEK
parametersobjectSee Parameters
conditionsobjectSee Conditions

The response is 201 with the discount:

json
{
  "id": "6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11",
  "type": "percentage",
  "status": "DRAFT",
  "name": "Welcome offer",
  "code": "WELCOME20",
  "startDate": "2026-10-01T00:00:00Z",
  "endDate": "2026-12-31T23:59:59Z",
  "parameters": { "percentage": 20, "numberOfMonths": 3, "allowSKUs": ["sid:acme-plus-monthly"] },
  "conditions": { "totalTimesApplicablePerUser": 1 },
  "usageCount": 0,
  "createdAt": "2026-09-28T09:00:00.000Z"
}

Creating is not idempotent

Every successful request creates a new discount. If a request times out, list your discounts before you retry, so you don't create the same discount twice.

Activate, Pause, and Cancel ​

Each status change is a POST with no body, and returns the discount with its new status:

EndpointFromTo
POST /management/discounts/{id}/activateDRAFT, PAUSEDPENDING, then ACTIVE at startDate
POST /management/discounts/{id}/pausePENDING, ACTIVEPAUSED
POST /management/discounts/{id}/cancelDRAFT, PAUSEDCANCELED
bash
curl -X POST https://api2.sesamy.com/management/discounts/6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11/activate \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Repeating an action is safe: activating a discount that is already PENDING or ACTIVE returns it unchanged. An action that doesn't apply to the current status answers 409:

json
{ "message": "Cannot cancel a discount that is ACTIVE" }

To cancel a live discount, pause it first.

Update a Discount ​

PATCH /management/discounts/{id} changes the fields you send and leaves the rest. parameters and conditions are replaced whole, so send every field you want to keep:

bash
curl -X PATCH https://api2.sesamy.com/management/discounts/6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "endDate": "2027-01-31T23:59:59Z" }'

Only DRAFT and PAUSED discounts can be edited. Any other status answers 409.

List and Read Discounts ​

GET /management/discounts lists your discounts. GET /management/discounts/{id} reads one.

ParameterTypeDescription
statusstring(Optional) Only discounts in this status
typestring(Optional) Only discounts of this type
limitinteger(Optional) Items read per page, 1 to 100
cursorstring(Optional) The nextCursor of the previous page
json
{
  "items": [
    {
      "id": "6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11",
      "type": "percentage",
      "status": "ACTIVE",
      "name": "Welcome offer",
      "code": "WELCOME20",
      "usageCount": 42
    }
  ],
  "nextCursor": "eyJpZCI6IjZmMWMifQ"
}

The example is shortened: each item has the same fields as a single discount. Pass nextCursor back as cursor until it is null. usageCount is how many times the discount has been used.

Keep paging until nextCursor is null

status and type filter each page after limit is applied, so a page can hold fewer discounts than limit, or none, while more remain.

One-Time Codes ​

One-time codes are single-use codes that each apply a discount once, for example for a printed campaign or a partner giveaway.

Generate Codes ​

POST /management/discounts/{id}/codes generates up to 10,000 codes at a time:

bash
curl -X POST https://api2.sesamy.com/management/discounts/6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11/codes \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "count": 500,
    "startDate": "2026-10-01T00:00:00Z",
    "endDate": "2026-12-31T23:59:59Z"
  }'
FieldTypeDescription
countintegerHow many codes to generate, 1 to 10,000
startDatestringWhen the codes become usable
endDatestringWhen the codes stop being usable

The response is 201 with the generated codes:

json
[
  {
    "id": "b8f2c1d4-7a3e-4c9b-8e1f-2d6a5c3b9e70",
    "code": "K7Q2M9XW4D1P",
    "status": "ACTIVE",
    "startDate": "2026-10-01T00:00:00Z",
    "endDate": "2026-12-31T23:59:59Z"
  }
]

Generating is not idempotent: a repeated request generates another batch.

List Codes ​

GET /management/discounts/{id}/codes lists the codes generated for a discount, with the same limit and cursor paging as discounts. A code's status is PENDING, ACTIVE, EXPIRED, CANCELED, or REDEEMED. A redeemed code carries redeemedBy, the user who used it, and redeemedAt.

Cancel Codes ​

DELETE /management/discounts/{id}/codes cancels every code of the discount that hasn't been redeemed, and answers 204. Redeemed codes are kept.

Next Steps ​

Released under the MIT License.