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:
| Status | Meaning |
|---|---|
DRAFT | Just created. Applies to nothing until you activate it. |
PENDING | Activated, waiting for its startDate. |
ACTIVE | Applies to new purchases. |
PAUSED | Stopped by you. Applies to no new purchases until you activate it again. |
EXPIRED | Its endDate has passed. |
CANCELED | Retired for good. |
ACTIVATION_ERROR | Activation 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.comAuthentication
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_TOKENSee 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.
| Type | What it does |
|---|---|
percentage | Takes a percentage off the price |
fixedAmount | Takes a fixed amount off the price |
trialPeriod | Gives free days before the first bill |
specialPriceTranche | Sets an introductory price and billing period |
developerTest | Makes a purchase free, for testing your integration |
Parameters
| Type | Field | Type | Description |
|---|---|---|---|
percentage | percentage | number | Percentage to take off, above 0 and at most 100 |
fixedAmount | amount | number | Amount to take off, in the currency of the purchase (for example 49.5) |
percentage, fixedAmount | numberOfMonths | integer | How long the discount applies to a subscription: 0 for the first bill only, -1 forever, or a number of months |
percentage, fixedAmount | curbToMaxAmount | number | (Optional) Never take off more than this per bill |
trialPeriod | days | integer | Length of the trial |
specialPriceTranche | period | string | Billing period while the special price applies: day, week, month, quarter, or year |
specialPriceTranche | times | integer | Periods per bill, for example 3 with month for quarterly bills |
specialPriceTranche | forcedPricePerItem | number | (Optional) Price per item while the special price applies. Defaults to the regular price |
specialPriceTranche | forcedPriceTaxIncluded | boolean | (Optional) Whether forcedPricePerItem includes tax. Defaults to the item's VAT settings |
specialPriceTranche | numberOfMonths | integer | (Optional) How long the special price applies. Defaults to one billing period |
Every type except trialPeriod also limits which products it applies to:
| Field | Type | Description |
|---|---|---|
allowSKUs | string[] | (Optional) Only apply to these products |
allowPOs | string[] | (Optional) Only apply to these purchase options |
ignoreSKUs | string[] | (Optional) Never apply to these products. percentage and fixedAmount only |
requireVerticals | string[] | (Optional) Only apply to these product types. percentage and fixedAmount only |
ignoreVerticals | string[] | (Optional) Never apply to these product types. percentage and fixedAmount only |
Conditions
conditions limits when a discount can be used. Every field is optional.
| Field | Type | Applies to | Description |
|---|---|---|---|
totalTimesApplicable | integer | Every type | How many times the discount can be used in total |
totalTimesApplicablePerUser | integer | Every type except developerTest | How many times one reader can use the discount |
minimumTotalItems | integer | percentage, fixedAmount | Minimum number of items in the cart |
minimumTotalAmount | number | percentage, fixedAmount | Minimum cart total, in the currency of the purchase |
skus | string[] | trialPeriod | Only apply to these products |
purchaseOptionIds | string[] | trialPeriod | Only 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:
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 }
}'| Field | Type | Description |
|---|---|---|
type | string | One of the discount types |
name | string | Name shown in the portal |
description | string | (Optional) Internal description |
code | string | 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 |
startDate | string | When the discount starts applying, ISO 8601 with Z or an offset |
endDate | string | When it stops applying |
currency | string | (Optional) Only apply to purchases in this currency, for example SEK |
parameters | object | See Parameters |
conditions | object | See Conditions |
The response is 201 with the discount:
{
"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:
| Endpoint | From | To |
|---|---|---|
POST /management/discounts/{id}/activate | DRAFT, PAUSED | PENDING, then ACTIVE at startDate |
POST /management/discounts/{id}/pause | PENDING, ACTIVE | PAUSED |
POST /management/discounts/{id}/cancel | DRAFT, PAUSED | CANCELED |
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:
{ "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:
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.
| Parameter | Type | Description |
|---|---|---|
status | string | (Optional) Only discounts in this status |
type | string | (Optional) Only discounts of this type |
limit | integer | (Optional) Items read per page, 1 to 100 |
cursor | string | (Optional) The nextCursor of the previous page |
{
"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:
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"
}'| Field | Type | Description |
|---|---|---|
count | integer | How many codes to generate, 1 to 10,000 |
startDate | string | When the codes become usable |
endDate | string | When the codes stop being usable |
The response is 201 with the generated codes:
[
{
"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
- Changing Plans: apply plan changes to existing subscriptions
- Creating Contracts: create invoiced contracts without a checkout
- Partner Checkout: sell through your own checkout
- Management API reference