Skip to content

Management API Specification ​

Servers​

https://api2.sesamy.comCurrent environment

List the vendors the user can access​

GET
/management/vendors

Get vendors from organization memberships or global admin:organizations / access:all_organizations grants on the Authhero Management API. Discovery does not grant provisioning rights.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Responses​

The vendors the user can access

application/json
JSON
[
  
{
  
  
"name": "string",
  
  
"id": "string",
  
  
"logo": "string"
  
}
]

Playground​

Authorization

Samples​


POST /management/vendors​

POST
/management/vendors

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Request Body​

application/json
JSON
{
  
"name": "string",
  
"id": "string",
  
"website": "string",
  
"country": "string"
}

Responses​

Status

Playground​

Authorization
Body

Samples​


Get a vendor the user can access​

GET
/management/vendors/{vendorId}

Get one vendor, including its business currency. Allowed by organization membership or global admin:organizations / access:all_organizations grants on the Authhero Management API, the same rule as the vendor list.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

vendorId*
Type
string
Required
Example"acme"

Responses​

The vendor

application/json
JSON
{
  
"id": "acme",
  
"name": "ACME",
  
"slug": "string",
  
"logo": "string",
  
"currency": "SEK",
  
"country": "SE",
  
"language": "string",
  
"status": "ACTIVE",
  
"siteUrl": "string",
  
"supportEmail": "string",
  
"supportUrl": "string",
  
"termsAndConditionsUrl": "string"
}

Playground​

Authorization
Variables
Key
Value

Samples​


GET /management/bills​

GET
/management/bills

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Query Parameters

q
Type
string
limit
Type
string
from
Type
string
status
Type
string
Valid values
"DRAFT""PENDING""PAID""RETRYING""OVERDUE""CANCELED""EXPIRED""DELETED""VOIDED"
contractId
Type
string
createdGte

Only bills created at or after this ISO 8601 timestamp

Type
string
Example"2026-01-01T00:00:00Z"
Format
"date-time"
Pattern
"(?:Z|[+-]\\d{2}:\\d{2})$"
createdLte

Only bills created at or before this ISO 8601 timestamp

Type
string
Example"2026-01-31T23:59:59Z"
Format
"date-time"
Pattern
"(?:Z|[+-]\\d{2}:\\d{2})$"
modifiedGte

Only bills modified at or after this ISO 8601 timestamp

Type
string
Example"2026-01-01T00:00:00Z"
Format
"date-time"
Pattern
"(?:Z|[+-]\\d{2}:\\d{2})$"
modifiedLte

Only bills modified at or before this ISO 8601 timestamp

Type
string
Example"2026-01-31T23:59:59Z"
Format
"date-time"
Pattern
"(?:Z|[+-]\\d{2}:\\d{2})$"

Responses​

Retrieve the users bills

application/json
JSON
[
  
{
  
  
"id": "1d78271264b9c76d5842911dd70b4353",
  
  
"contractId": "a1b2c3d4e5f6g7h8i9j0",
  
  
"items": [
  
  
  
{
  
  
  
  
"sku": "string",
  
  
  
  
"title": "string",
  
  
  
  
"purchaseOptionId": "string"
  
  
  
}
  
  
],
  
  
"price": 0,
  
  
"currency": "string",
  
  
"receiptUrl": "string",
  
  
"paymentProvider": "string",
  
  
"paymentMethod": "string",
  
  
"status": "string",
  
  
"updatedAt": "string",
  
  
"createdAt": "string"
  
}
]

Playground​

Authorization
Variables
Key
Value

Samples​


GET /management/bills/{id}​

GET
/management/bills/{id}

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"1d78271264b9c76d5842911dd70b4353"

Responses​

Retrieve the users bills

application/json
JSON
{
  
"id": "1d78271264b9c76d5842911dd70b4353",
  
"contractId": "a1b2c3d4e5f6g7h8i9j0",
  
"items": [
  
  
{
  
  
  
"sku": "string",
  
  
  
"title": "string",
  
  
  
"purchaseOptionId": "string"
  
  
}
  
],
  
"price": 0,
  
"currency": "string",
  
"receiptUrl": "string",
  
"paymentProvider": "string",
  
"paymentMethod": "string",
  
"status": "string",
  
"updatedAt": "string",
  
"createdAt": "string"
}

Playground​

Authorization
Variables
Key
Value

Samples​


GET /management/contracts​

GET
/management/contracts

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Query Parameters

q
Type
string
limit
Type
string
from
Type
string
userId
Type
string

Responses​

Retrieve the users contracts

application/json
JSON
[
  
{
  
  
"id": "1d78271264b9c76d5842911dd70b4353",
  
  
"name": "string",
  
  
"userId": "string",
  
  
"payer": {
  
  
  
"id": "string",
  
  
  
"email": "string"
  
  
},
  
  
"createdAt": "string",
  
  
"confirmedAt": "string",
  
  
"updatedAt": "string",
  
  
"price": 0,
  
  
"nextBillAt": "string",
  
  
"nextPrice": 0,
  
  
"currency": "string",
  
  
"manageUrl": "string",
  
  
"contractDuration": "string",
  
  
"issuesRemaining": 0,
  
  
"items": [
  
  
  
{
  
  
  
  
"id": "string",
  
  
  
  
"sku": "string",
  
  
  
  
"purchaseOptionId": "string",
  
  
  
  
"purchaseOptionName": "string",
  
  
  
  
"name": "string",
  
  
  
  
"cover": "string",
  
  
  
  
"productType": "string",
  
  
  
  
"purchaseType": "string",
  
  
  
  
"isMultiseat": true,
  
  
  
  
"quantity": 0,
  
  
  
  
"seats": 0
  
  
  
}
  
  
],
  
  
"status": "string",
  
  
"isActive": true,
  
  
"recurringInterval": "string",
  
  
"recurringTime": 0,
  
  
"recurringPrice": [
  
  
  
{
  
  
  
  
"from": "string",
  
  
  
  
"to": "string",
  
  
  
  
"id": "string",
  
  
  
  
"price": 0,
  
  
  
  
"currency": "string",
  
  
  
  
"interval": "string",
  
  
  
  
"intervalCount": 0,
  
  
  
  
"discount": {
  
  
  
  
  
"amount": 0,
  
  
  
  
  
"percentage": 0,
  
  
  
  
  
"fullPrice": 0,
  
  
  
  
  
"codes": [
  
  
  
  
  
  
{
  
  
  
  
  
  
  
"code": "string",
  
  
  
  
  
  
  
"name": "string",
  
  
  
  
  
  
  
"amount": 0
  
  
  
  
  
  
}
  
  
  
  
  
]
  
  
  
  
}
  
  
  
}
  
  
],
  
  
"willCancelAt": "string",
  
  
"cancelRequestedAt": "string",
  
  
"canceledAt": "string",
  
  
"cancelReason": "string",
  
  
"expiresAt": "string",
  
  
"origin": {
  
  
  
"type": "string",
  
  
  
"id": "string"
  
  
},
  
  
"paymentData": {
  
  
  
"method": "string",
  
  
  
"description": "string",
  
  
  
"brand": "string",
  
  
  
"walletType": "string"
  
  
},
  
  
"appliedDiscounts": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"name": "string",
  
  
  
  
"description": "string",
  
  
  
  
"id": "string",
  
  
  
  
"status": "string",
  
  
  
  
"startsAt": "string",
  
  
  
  
"endsAt": "string"
  
  
  
}
  
  
],
  
  
"discount": {
  
  
  
"endsAt": "string",
  
  
  
"amount": 0,
  
  
  
"percentage": 0,
  
  
  
"fullPrice": 0
  
  
}
  
}
]

Playground​

Authorization
Variables
Key
Value

Samples​


Create a contract​

POST
/management/contracts

Creates a contract for a user without a checkout, billed by invoice. The contract is returned as PENDING: priced, but not billed and granting no access. Review it, then confirm it with POST /management/contracts/{id}/confirm, or pass confirm: true to do both in one call. For a multi-seat contract, use a license product; quantity is what is billed and seats optionally sets how many seats that buys. Creating is not idempotent: a repeated request creates a second contract.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Request Body​

application/json
JSON
{
  
"sku": "string",
  
"purchaseOptionId": "string",
  
"contractType": "string",
  
"user": {
  
  
"email": "string",
  
  
"firstName": "string",
  
  
"lastName": "string",
  
  
"phone": "string",
  
  
"businessDetails": {
  
  
  
"companyName": "string",
  
  
  
"vatNr": "string"
  
  
},
  
  
"address": {
  
  
  
"firstName": "string",
  
  
  
"lastName": "string",
  
  
  
"department": "string",
  
  
  
"co": "string",
  
  
  
"street": "string",
  
  
  
"zip": "string",
  
  
  
"city": "string",
  
  
  
"country": "SE"
  
  
},
  
  
"deliveryAddress": {
  
  
  
"firstName": "string",
  
  
  
"lastName": "string",
  
  
  
"department": "string",
  
  
  
"co": "string",
  
  
  
"street": "string",
  
  
  
"zip": "string",
  
  
  
"city": "string",
  
  
  
"country": "SE"
  
  
}
  
},
  
"payer": {
  
  
"email": "string",
  
  
"firstName": "string",
  
  
"lastName": "string",
  
  
"phone": "string",
  
  
"businessDetails": {
  
  
  
"companyName": "string",
  
  
  
"vatNr": "string"
  
  
},
  
  
"address": {
  
  
  
"firstName": "string",
  
  
  
"lastName": "string",
  
  
  
"department": "string",
  
  
  
"co": "string",
  
  
  
"street": "string",
  
  
  
"zip": "string",
  
  
  
"city": "string",
  
  
  
"country": "SE"
  
  
},
  
  
"deliveryAddress": {
  
  
  
"firstName": "string",
  
  
  
"lastName": "string",
  
  
  
"department": "string",
  
  
  
"co": "string",
  
  
  
"street": "string",
  
  
  
"zip": "string",
  
  
  
"city": "string",
  
  
  
"country": "SE"
  
  
}
  
},
  
"invoice": {
  
  
"email": "string",
  
  
"customerReference": "string",
  
  
"vendorReference": "string",
  
  
"ediNumber": "string"
  
},
  
"quantity": 0,
  
"seats": 0,
  
"unitPrice": {
  
  
"amount": 0,
  
  
"taxIncluded": true
  
},
  
"discountCodes": [
  
  
"string"
  
],
  
"payment": {
  
  
"provider": "string",
  
  
"method": "string",
  
  
"country": "SE"
  
},
  
"startsAt": "string",
  
"anchorDate": "string",
  
"confirm": true
}

Responses​

The created contract

application/json
JSON
{
  
"id": "1d78271264b9c76d5842911dd70b4353",
  
"name": "string",
  
"userId": "string",
  
"payer": {
  
  
"id": "string",
  
  
"email": "string"
  
},
  
"createdAt": "string",
  
"confirmedAt": "string",
  
"updatedAt": "string",
  
"price": 0,
  
"nextBillAt": "string",
  
"nextPrice": 0,
  
"currency": "string",
  
"manageUrl": "string",
  
"contractDuration": "string",
  
"issuesRemaining": 0,
  
"items": [
  
  
{
  
  
  
"id": "string",
  
  
  
"sku": "string",
  
  
  
"purchaseOptionId": "string",
  
  
  
"purchaseOptionName": "string",
  
  
  
"name": "string",
  
  
  
"cover": "string",
  
  
  
"productType": "string",
  
  
  
"purchaseType": "string",
  
  
  
"isMultiseat": true,
  
  
  
"quantity": 0,
  
  
  
"seats": 0
  
  
}
  
],
  
"status": "string",
  
"isActive": true,
  
"recurringInterval": "string",
  
"recurringTime": 0,
  
"recurringPrice": [
  
  
{
  
  
  
"from": "string",
  
  
  
"to": "string",
  
  
  
"id": "string",
  
  
  
"price": 0,
  
  
  
"currency": "string",
  
  
  
"interval": "string",
  
  
  
"intervalCount": 0,
  
  
  
"discount": {
  
  
  
  
"amount": 0,
  
  
  
  
"percentage": 0,
  
  
  
  
"fullPrice": 0,
  
  
  
  
"codes": [
  
  
  
  
  
{
  
  
  
  
  
  
"code": "string",
  
  
  
  
  
  
"name": "string",
  
  
  
  
  
  
"amount": 0
  
  
  
  
  
}
  
  
  
  
]
  
  
  
}
  
  
}
  
],
  
"willCancelAt": "string",
  
"cancelRequestedAt": "string",
  
"canceledAt": "string",
  
"cancelReason": "string",
  
"expiresAt": "string",
  
"origin": {
  
  
"type": "string",
  
  
"id": "string"
  
},
  
"paymentData": {
  
  
"method": "string",
  
  
"description": "string",
  
  
"brand": "string",
  
  
"walletType": "string"
  
},
  
"appliedDiscounts": [
  
  
{
  
  
  
"code": "string",
  
  
  
"name": "string",
  
  
  
"description": "string",
  
  
  
"id": "string",
  
  
  
"status": "string",
  
  
  
"startsAt": "string",
  
  
  
"endsAt": "string"
  
  
}
  
],
  
"discount": {
  
  
"endsAt": "string",
  
  
"amount": 0,
  
  
"percentage": 0,
  
  
"fullPrice": 0
  
}
}

Playground​

Authorization
Body

Samples​


GET /management/contracts/{id}​

GET
/management/contracts/{id}

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"1d78271264b9c76d5842911dd70b4353"

Responses​

Retrieve the users contracts

application/json
JSON
{
  
"id": "1d78271264b9c76d5842911dd70b4353",
  
"name": "string",
  
"userId": "string",
  
"payer": {
  
  
"id": "string",
  
  
"email": "string"
  
},
  
"createdAt": "string",
  
"confirmedAt": "string",
  
"updatedAt": "string",
  
"price": 0,
  
"nextBillAt": "string",
  
"nextPrice": 0,
  
"currency": "string",
  
"manageUrl": "string",
  
"contractDuration": "string",
  
"issuesRemaining": 0,
  
"items": [
  
  
{
  
  
  
"id": "string",
  
  
  
"sku": "string",
  
  
  
"purchaseOptionId": "string",
  
  
  
"purchaseOptionName": "string",
  
  
  
"name": "string",
  
  
  
"cover": "string",
  
  
  
"productType": "string",
  
  
  
"purchaseType": "string",
  
  
  
"isMultiseat": true,
  
  
  
"quantity": 0,
  
  
  
"seats": 0
  
  
}
  
],
  
"status": "string",
  
"isActive": true,
  
"recurringInterval": "string",
  
"recurringTime": 0,
  
"recurringPrice": [
  
  
{
  
  
  
"from": "string",
  
  
  
"to": "string",
  
  
  
"id": "string",
  
  
  
"price": 0,
  
  
  
"currency": "string",
  
  
  
"interval": "string",
  
  
  
"intervalCount": 0,
  
  
  
"discount": {
  
  
  
  
"amount": 0,
  
  
  
  
"percentage": 0,
  
  
  
  
"fullPrice": 0,
  
  
  
  
"codes": [
  
  
  
  
  
{
  
  
  
  
  
  
"code": "string",
  
  
  
  
  
  
"name": "string",
  
  
  
  
  
  
"amount": 0
  
  
  
  
  
}
  
  
  
  
]
  
  
  
}
  
  
}
  
],
  
"willCancelAt": "string",
  
"cancelRequestedAt": "string",
  
"canceledAt": "string",
  
"cancelReason": "string",
  
"expiresAt": "string",
  
"origin": {
  
  
"type": "string",
  
  
"id": "string"
  
},
  
"paymentData": {
  
  
"method": "string",
  
  
"description": "string",
  
  
"brand": "string",
  
  
"walletType": "string"
  
},
  
"appliedDiscounts": [
  
  
{
  
  
  
"code": "string",
  
  
  
"name": "string",
  
  
  
"description": "string",
  
  
  
"id": "string",
  
  
  
"status": "string",
  
  
  
"startsAt": "string",
  
  
  
"endsAt": "string"
  
  
}
  
],
  
"discount": {
  
  
"endsAt": "string",
  
  
"amount": 0,
  
  
"percentage": 0,
  
  
"fullPrice": 0
  
}
}

Playground​

Authorization
Variables
Key
Value

Samples​


Confirm a contract​

POST
/management/contracts/{id}/confirm

Confirms a PENDING contract: the customer is billed and access is granted, including the seats of a multi-seat contract. A contract that starts later becomes FORTHCOMING instead of ACTIVE. Confirming an already confirmed contract returns it unchanged.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"1d78271264b9c76d5842911dd70b4353"

Responses​

The confirmed contract

application/json
JSON
{
  
"id": "1d78271264b9c76d5842911dd70b4353",
  
"name": "string",
  
"userId": "string",
  
"payer": {
  
  
"id": "string",
  
  
"email": "string"
  
},
  
"createdAt": "string",
  
"confirmedAt": "string",
  
"updatedAt": "string",
  
"price": 0,
  
"nextBillAt": "string",
  
"nextPrice": 0,
  
"currency": "string",
  
"manageUrl": "string",
  
"contractDuration": "string",
  
"issuesRemaining": 0,
  
"items": [
  
  
{
  
  
  
"id": "string",
  
  
  
"sku": "string",
  
  
  
"purchaseOptionId": "string",
  
  
  
"purchaseOptionName": "string",
  
  
  
"name": "string",
  
  
  
"cover": "string",
  
  
  
"productType": "string",
  
  
  
"purchaseType": "string",
  
  
  
"isMultiseat": true,
  
  
  
"quantity": 0,
  
  
  
"seats": 0
  
  
}
  
],
  
"status": "string",
  
"isActive": true,
  
"recurringInterval": "string",
  
"recurringTime": 0,
  
"recurringPrice": [
  
  
{
  
  
  
"from": "string",
  
  
  
"to": "string",
  
  
  
"id": "string",
  
  
  
"price": 0,
  
  
  
"currency": "string",
  
  
  
"interval": "string",
  
  
  
"intervalCount": 0,
  
  
  
"discount": {
  
  
  
  
"amount": 0,
  
  
  
  
"percentage": 0,
  
  
  
  
"fullPrice": 0,
  
  
  
  
"codes": [
  
  
  
  
  
{
  
  
  
  
  
  
"code": "string",
  
  
  
  
  
  
"name": "string",
  
  
  
  
  
  
"amount": 0
  
  
  
  
  
}
  
  
  
  
]
  
  
  
}
  
  
}
  
],
  
"willCancelAt": "string",
  
"cancelRequestedAt": "string",
  
"canceledAt": "string",
  
"cancelReason": "string",
  
"expiresAt": "string",
  
"origin": {
  
  
"type": "string",
  
  
"id": "string"
  
},
  
"paymentData": {
  
  
"method": "string",
  
  
"description": "string",
  
  
"brand": "string",
  
  
"walletType": "string"
  
},
  
"appliedDiscounts": [
  
  
{
  
  
  
"code": "string",
  
  
  
"name": "string",
  
  
  
"description": "string",
  
  
  
"id": "string",
  
  
  
"status": "string",
  
  
  
"startsAt": "string",
  
  
  
"endsAt": "string"
  
  
}
  
],
  
"discount": {
  
  
"endsAt": "string",
  
  
"amount": 0,
  
  
"percentage": 0,
  
  
"fullPrice": 0
  
}
}

Playground​

Authorization
Variables
Key
Value

Samples​


Cancel a contract​

POST
/management/contracts/{id}/cancel

Cancels a contract on behalf of its customer. By default (when: "end") the customer keeps access until the end of the current period and the contract does not renew; when: "now" cancels at once. Only ACTIVE, OVERDUE and FORTHCOMING contracts can be canceled. An already canceled contract is returned unchanged. Canceling does not refund anything.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"1d78271264b9c76d5842911dd70b4353"

Request Body​

application/json
JSON
{
  
"when": "string",
  
"reason": "string",
  
"comment": "string"
}

Responses​

The contract after the cancellation

application/json
JSON
{
  
"id": "1d78271264b9c76d5842911dd70b4353",
  
"name": "string",
  
"userId": "string",
  
"payer": {
  
  
"id": "string",
  
  
"email": "string"
  
},
  
"createdAt": "string",
  
"confirmedAt": "string",
  
"updatedAt": "string",
  
"price": 0,
  
"nextBillAt": "string",
  
"nextPrice": 0,
  
"currency": "string",
  
"manageUrl": "string",
  
"contractDuration": "string",
  
"issuesRemaining": 0,
  
"items": [
  
  
{
  
  
  
"id": "string",
  
  
  
"sku": "string",
  
  
  
"purchaseOptionId": "string",
  
  
  
"purchaseOptionName": "string",
  
  
  
"name": "string",
  
  
  
"cover": "string",
  
  
  
"productType": "string",
  
  
  
"purchaseType": "string",
  
  
  
"isMultiseat": true,
  
  
  
"quantity": 0,
  
  
  
"seats": 0
  
  
}
  
],
  
"status": "string",
  
"isActive": true,
  
"recurringInterval": "string",
  
"recurringTime": 0,
  
"recurringPrice": [
  
  
{
  
  
  
"from": "string",
  
  
  
"to": "string",
  
  
  
"id": "string",
  
  
  
"price": 0,
  
  
  
"currency": "string",
  
  
  
"interval": "string",
  
  
  
"intervalCount": 0,
  
  
  
"discount": {
  
  
  
  
"amount": 0,
  
  
  
  
"percentage": 0,
  
  
  
  
"fullPrice": 0,
  
  
  
  
"codes": [
  
  
  
  
  
{
  
  
  
  
  
  
"code": "string",
  
  
  
  
  
  
"name": "string",
  
  
  
  
  
  
"amount": 0
  
  
  
  
  
}
  
  
  
  
]
  
  
  
}
  
  
}
  
],
  
"willCancelAt": "string",
  
"cancelRequestedAt": "string",
  
"canceledAt": "string",
  
"cancelReason": "string",
  
"expiresAt": "string",
  
"origin": {
  
  
"type": "string",
  
  
"id": "string"
  
},
  
"paymentData": {
  
  
"method": "string",
  
  
"description": "string",
  
  
"brand": "string",
  
  
"walletType": "string"
  
},
  
"appliedDiscounts": [
  
  
{
  
  
  
"code": "string",
  
  
  
"name": "string",
  
  
  
"description": "string",
  
  
  
"id": "string",
  
  
  
"status": "string",
  
  
  
"startsAt": "string",
  
  
  
"endsAt": "string"
  
  
}
  
],
  
"discount": {
  
  
"endsAt": "string",
  
  
"amount": 0,
  
  
"percentage": 0,
  
  
"fullPrice": 0
  
}
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


Reactivate a contract​

POST
/management/contracts/{id}/reactivate

Removes a scheduled cancellation on behalf of the customer, so the contract renews again as before. Only ACTIVE, OVERDUE and CLOSED contracts can be reactivated: a contract that has ended (CANCELED or EXPIRED) has to be bought again. Reactivating a contract that is not set to cancel returns it unchanged.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"1d78271264b9c76d5842911dd70b4353"

Responses​

The contract, no longer set to cancel

application/json
JSON
{
  
"id": "1d78271264b9c76d5842911dd70b4353",
  
"name": "string",
  
"userId": "string",
  
"payer": {
  
  
"id": "string",
  
  
"email": "string"
  
},
  
"createdAt": "string",
  
"confirmedAt": "string",
  
"updatedAt": "string",
  
"price": 0,
  
"nextBillAt": "string",
  
"nextPrice": 0,
  
"currency": "string",
  
"manageUrl": "string",
  
"contractDuration": "string",
  
"issuesRemaining": 0,
  
"items": [
  
  
{
  
  
  
"id": "string",
  
  
  
"sku": "string",
  
  
  
"purchaseOptionId": "string",
  
  
  
"purchaseOptionName": "string",
  
  
  
"name": "string",
  
  
  
"cover": "string",
  
  
  
"productType": "string",
  
  
  
"purchaseType": "string",
  
  
  
"isMultiseat": true,
  
  
  
"quantity": 0,
  
  
  
"seats": 0
  
  
}
  
],
  
"status": "string",
  
"isActive": true,
  
"recurringInterval": "string",
  
"recurringTime": 0,
  
"recurringPrice": [
  
  
{
  
  
  
"from": "string",
  
  
  
"to": "string",
  
  
  
"id": "string",
  
  
  
"price": 0,
  
  
  
"currency": "string",
  
  
  
"interval": "string",
  
  
  
"intervalCount": 0,
  
  
  
"discount": {
  
  
  
  
"amount": 0,
  
  
  
  
"percentage": 0,
  
  
  
  
"fullPrice": 0,
  
  
  
  
"codes": [
  
  
  
  
  
{
  
  
  
  
  
  
"code": "string",
  
  
  
  
  
  
"name": "string",
  
  
  
  
  
  
"amount": 0
  
  
  
  
  
}
  
  
  
  
]
  
  
  
}
  
  
}
  
],
  
"willCancelAt": "string",
  
"cancelRequestedAt": "string",
  
"canceledAt": "string",
  
"cancelReason": "string",
  
"expiresAt": "string",
  
"origin": {
  
  
"type": "string",
  
  
"id": "string"
  
},
  
"paymentData": {
  
  
"method": "string",
  
  
"description": "string",
  
  
"brand": "string",
  
  
"walletType": "string"
  
},
  
"appliedDiscounts": [
  
  
{
  
  
  
"code": "string",
  
  
  
"name": "string",
  
  
  
"description": "string",
  
  
  
"id": "string",
  
  
  
"status": "string",
  
  
  
"startsAt": "string",
  
  
  
"endsAt": "string"
  
  
}
  
],
  
"discount": {
  
  
"endsAt": "string",
  
  
"amount": 0,
  
  
"percentage": 0,
  
  
"fullPrice": 0
  
}
}

Playground​

Authorization
Variables
Key
Value

Samples​


List the refunds of a bill​

GET
/management/contracts/{id}/bills/{billId}/refunds

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"1d78271264b9c76d5842911dd70b4353"
billId*
Type
string
Required
Example"B-acme-123456"

Responses​

The refunds made on the bill

application/json
JSON
[
  
{
  
  
"id": "string",
  
  
"contractId": "string",
  
  
"status": "string",
  
  
"amount": 0,
  
  
"currency": "string",
  
  
"createdAt": "string"
  
}
]

Playground​

Authorization
Variables
Key
Value

Samples​


Refund a bill​

POST
/management/contracts/{id}/bills/{billId}/refunds

Refunds part or all of a paid bill to the original payment method. amount is in minor units (öre/cents) and the refund uses the currency of the bill. Does not cancel the contract; use POST /management/contracts/{id}/cancel for that. A refund is never retried automatically and there is no idempotency key: if the request times out, check GET /management/contracts/{id}/bills/{billId}/refunds before sending it again. Providers without refund support (such as invoices) are refused.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"1d78271264b9c76d5842911dd70b4353"
billId*
Type
string
Required
Example"B-acme-123456"

Request Body​

application/json
JSON
{
  
"amount": 24600,
  
"reason": "string"
}

Responses​

The refund

application/json
JSON
{
  
"id": "string",
  
"contractId": "string",
  
"status": "string",
  
"amount": 0,
  
"currency": "string",
  
"createdAt": "string"
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


Set the seats of a contract​

PUT
/management/contracts/{id}/seats

Sets how many seats a multi-seat contract grants. It does not change what is billed: the seats are not part of the price. The change applies at once. Setting the seats the contract already has returns it unchanged. Seats cannot be lowered below the number of users holding one.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"1d78271264b9c76d5842911dd70b4353"

Request Body​

application/json
JSON
{
  
"seats": 25,
  
"sku": "sid:acme-plus-business"
}

Responses​

The contract with its new seats

application/json
JSON
{
  
"id": "1d78271264b9c76d5842911dd70b4353",
  
"name": "string",
  
"userId": "string",
  
"payer": {
  
  
"id": "string",
  
  
"email": "string"
  
},
  
"createdAt": "string",
  
"confirmedAt": "string",
  
"updatedAt": "string",
  
"price": 0,
  
"nextBillAt": "string",
  
"nextPrice": 0,
  
"currency": "string",
  
"manageUrl": "string",
  
"contractDuration": "string",
  
"issuesRemaining": 0,
  
"items": [
  
  
{
  
  
  
"id": "string",
  
  
  
"sku": "string",
  
  
  
"purchaseOptionId": "string",
  
  
  
"purchaseOptionName": "string",
  
  
  
"name": "string",
  
  
  
"cover": "string",
  
  
  
"productType": "string",
  
  
  
"purchaseType": "string",
  
  
  
"isMultiseat": true,
  
  
  
"quantity": 0,
  
  
  
"seats": 0
  
  
}
  
],
  
"status": "string",
  
"isActive": true,
  
"recurringInterval": "string",
  
"recurringTime": 0,
  
"recurringPrice": [
  
  
{
  
  
  
"from": "string",
  
  
  
"to": "string",
  
  
  
"id": "string",
  
  
  
"price": 0,
  
  
  
"currency": "string",
  
  
  
"interval": "string",
  
  
  
"intervalCount": 0,
  
  
  
"discount": {
  
  
  
  
"amount": 0,
  
  
  
  
"percentage": 0,
  
  
  
  
"fullPrice": 0,
  
  
  
  
"codes": [
  
  
  
  
  
{
  
  
  
  
  
  
"code": "string",
  
  
  
  
  
  
"name": "string",
  
  
  
  
  
  
"amount": 0
  
  
  
  
  
}
  
  
  
  
]
  
  
  
}
  
  
}
  
],
  
"willCancelAt": "string",
  
"cancelRequestedAt": "string",
  
"canceledAt": "string",
  
"cancelReason": "string",
  
"expiresAt": "string",
  
"origin": {
  
  
"type": "string",
  
  
"id": "string"
  
},
  
"paymentData": {
  
  
"method": "string",
  
  
"description": "string",
  
  
"brand": "string",
  
  
"walletType": "string"
  
},
  
"appliedDiscounts": [
  
  
{
  
  
  
"code": "string",
  
  
  
"name": "string",
  
  
  
"description": "string",
  
  
  
"id": "string",
  
  
  
"status": "string",
  
  
  
"startsAt": "string",
  
  
  
"endsAt": "string"
  
  
}
  
],
  
"discount": {
  
  
"endsAt": "string",
  
  
"amount": 0,
  
  
"percentage": 0,
  
  
"fullPrice": 0
  
}
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


List users holding contract seats​

GET
/management/contracts/{id}/seats/users

Lists the users holding seats across all license items on a multi-seat contract. Removed seats are left out. Filter by sku to list one item.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"1d78271264b9c76d5842911dd70b4353"

Query Parameters

sku

Filter seat users by license item SKU. Omit to list all contract seat users.

Type
string

Responses​

Users holding seats on the contract

application/json
JSON
[
  
{
  
  
"userId": "auth0|123456",
  
  
"email": "user@example.com",
  
  
"fullName": "John Doe",
  
  
"sku": "premium-subscription",
  
  
"status": "ACTIVE",
  
  
"entitlementId": "ent_123456"
  
}
]

Playground​

Authorization
Variables
Key
Value

Samples​


Assign a contract seat to a user​

POST
/management/contracts/{id}/seats/users

Assigns a seat by email. Vault picks the license item with a free seat. The change does not affect billing.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"1d78271264b9c76d5842911dd70b4353"

Request Body​

application/json
JSON
{
  
"email": "reader@example.com"
}

Responses​

Seat assigned

Playground​

Authorization
Variables
Key
Value
Body

Samples​


Remove a user from a contract seat​

DELETE
/management/contracts/{id}/seats/users/{userId}

Removes a user from the contract seat license. The change does not affect billing.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"1d78271264b9c76d5842911dd70b4353"
userId*

User ID of the seat holder to remove.

Type
string
Required
Example"auth0|123456"

Responses​

Seat user removed

Playground​

Authorization
Variables
Key
Value

Samples​


Deprecated

List users holding contract seats (deprecated)​

GET
/management/contracts/{id}/licenses

Use GET /management/contracts/{id}/seats/users instead.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"1d78271264b9c76d5842911dd70b4353"

Responses​

Retrieve users with license entitlements for the contract

application/json
JSON
[
  
{
  
  
"userId": "auth0|123456",
  
  
"email": "user@example.com",
  
  
"fullName": "John Doe",
  
  
"sku": "premium-subscription",
  
  
"status": "ACTIVE",
  
  
"entitlementId": "ent_123456"
  
}
]

Playground​

Authorization
Variables
Key
Value

Samples​


List upgrade options​

GET
/management/contracts/{id}/upgrade-options

Lists the products and purchase options each item of the contract can be upgraded, downgraded, or switched to. Returns 400 when the contract cannot be changed (inactive or non-recurring).

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"1d78271264b9c76d5842911dd70b4353"

Responses​

The available upgrade and downgrade paths for the contract

application/json
JSON
[
  
{
  
  
"itemId": "string",
  
  
"sku": "string",
  
  
"purchaseOptionId": "string",
  
  
"paths": [
  
  
  
{
  
  
  
  
"type": "string",
  
  
  
  
"sku": "string",
  
  
  
  
"purchaseOptionId": "string",
  
  
  
  
"title": "string",
  
  
  
  
"cover": "string",
  
  
  
  
"description": "string",
  
  
  
  
"features": [
  
  
  
  
  
"string"
  
  
  
  
]
  
  
  
}
  
  
]
  
}
]

Playground​

Authorization
Variables
Key
Value

Samples​


Create an amendment​

POST
/management/contracts/{id}/amendments

Prepares a change to a contract. PLAN_CHANGE moves a contract item to another product or purchase option, which must be one of the paths listed by GET /management/contracts/{id}/upgrade-options. The amendment is PENDING and changes nothing until it is confirmed with POST /management/contracts/{id}/amendments/{amendmentId}/confirm, so it doubles as a preview: nextPrice and proration show what the change costs. Only active recurring contracts that are not set to cancel can change plan. Creating is not idempotent, but an unconfirmed amendment has no effect.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"1d78271264b9c76d5842911dd70b4353"

Request Body​

application/json
JSON
{
  
"type": "string",
  
"itemId": "item_1",
  
"sku": "sid:acme-plus-yearly",
  
"purchaseOptionId": "yearly",
  
"prorationMethod": "string"
}

Responses​

The pending amendment

application/json
JSON
{
  
"id": "string",
  
"contractId": "string",
  
"status": "string",
  
"amendmentType": "string",
  
"nextBillAt": "string",
  
"nextPrice": 0,
  
"currency": "string",
  
"items": [
  
  
{
  
  
  
"id": "item_1",
  
  
  
"sku": "sid:acme-plus-yearly",
  
  
  
"purchaseOptionId": "yearly"
  
  
}
  
],
  
"proration": {
  
  
"method": "string",
  
  
"amount": 41.5,
  
  
"currency": "SEK",
  
  
"appliesAt": "2026-12-01T00:00:00.000Z"
  
},
  
"appliedDiscounts": [
  
  
{
  
  
  
"code": "string",
  
  
  
"status": "string",
  
  
  
"id": "string",
  
  
  
"name": "string",
  
  
  
"description": "string"
  
  
}
  
]
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


Confirm an amendment​

POST
/management/contracts/{id}/amendments/{amendmentId}/confirm

Applies a pending amendment. For a plan change, the new plan takes effect at proration.appliesAt. With proration.method UPFRONT or RESTART_PERIOD, proration.amount is charged to the saved payment method now, and a declined payment answers 400. A plan change cannot be confirmed while the contract is set to cancel: reactivate it first. Confirming an already confirmed amendment returns it unchanged, so a request that timed out can be repeated.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"1d78271264b9c76d5842911dd70b4353"
amendmentId*
Type
string
Required
Example"amendment123"

Responses​

The confirmed amendment

application/json
JSON
{
  
"id": "string",
  
"contractId": "string",
  
"status": "string",
  
"amendmentType": "string",
  
"nextBillAt": "string",
  
"nextPrice": 0,
  
"currency": "string",
  
"items": [
  
  
{
  
  
  
"id": "item_1",
  
  
  
"sku": "sid:acme-plus-yearly",
  
  
  
"purchaseOptionId": "yearly"
  
  
}
  
],
  
"proration": {
  
  
"method": "string",
  
  
"amount": 41.5,
  
  
"currency": "SEK",
  
  
"appliesAt": "2026-12-01T00:00:00.000Z"
  
},
  
"appliedDiscounts": [
  
  
{
  
  
  
"code": "string",
  
  
  
"status": "string",
  
  
  
"id": "string",
  
  
  
"name": "string",
  
  
  
"description": "string"
  
  
}
  
]
}

Playground​

Authorization
Variables
Key
Value

Samples​


Transactions​


GET /management/transactions​

GET
/management/transactions

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Query Parameters

q
Type
string
transactionId
Type
string
billId
Type
string
contractId
Type
string
userId
Type
string
dateFrom
Type
string
dateTo
Type
string
limit
Type
string
from
Type
string

Responses​

A list of transactions

application/json
JSON
[
  
{
  
  
"id": "1d78271264b9c76d5842911dd70b4353",
  
  
"amount": 0,
  
  
"currency": "string",
  
  
"contractId": "string",
  
  
"isRefund": true,
  
  
"userId": "string",
  
  
"billId": "string",
  
  
"updatedAt": "string",
  
  
"createdAt": "string"
  
}
]

Playground​

Authorization
Variables
Key
Value

Samples​


GET /management/products​

GET
/management/products

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Query Parameters

q
Type
string

Responses​

Retrieve products with purchase option IDs, market prices, schedules and availability flags.

application/json
JSON
[
  
{
  
  
"cover": "string",
  
  
"language": "string",
  
  
"createdAt": "string",
  
  
"updatedAt": "string",
  
  
"sku": "string",
  
  
"title": "string",
  
  
"productType": "string",
  
  
"publisherContentId": "string",
  
  
"purchaseOptions": [
  
  
  
{
  
  
  
  
"id": "string",
  
  
  
  
"title": "string",
  
  
  
  
"purchaseType": "string",
  
  
  
  
"prices": [
  
  
  
  
  
{
  
  
  
  
  
  
"market": "SE",
  
  
  
  
  
  
"currency": "SEK",
  
  
  
  
  
  
"amount": 149,
  
  
  
  
  
  
"amountExcludingTax": 140.57,
  
  
  
  
  
  
"tax": 8.43
  
  
  
  
  
}
  
  
  
  
],
  
  
  
  
"recurring": {
  
  
  
  
  
"interval": "string",
  
  
  
  
  
"intervalCount": 0
  
  
  
  
},
  
  
  
  
"duration": {
  
  
  
  
  
"interval": "string",
  
  
  
  
  
"intervalCount": 0
  
  
  
  
},
  
  
  
  
"issues": 0,
  
  
  
  
"seatsPerUnit": 0,
  
  
  
  
"minQuantity": 0,
  
  
  
  
"maxQuantity": 0,
  
  
  
  
"isForSale": true,
  
  
  
  
"isListed": true
  
  
  
}
  
  
]
  
}
]

Playground​

Authorization
Variables
Key
Value

Samples​


POST /management/products​

POST
/management/products

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Request Body​

application/json
JSON
{
  
"type": "string",
  
"url": "string",
  
"spotifyId": "string"
}

Responses​

A created product

application/json
JSON
{
  
"cover": "string",
  
"language": "string",
  
"createdAt": "string",
  
"updatedAt": "string",
  
"sku": "string",
  
"title": "string",
  
"productType": "string",
  
"publisherContentId": "string",
  
"purchaseOptions": [
  
  
{
  
  
  
"id": "string",
  
  
  
"title": "string",
  
  
  
"purchaseType": "string",
  
  
  
"prices": [
  
  
  
  
{
  
  
  
  
  
"market": "SE",
  
  
  
  
  
"currency": "SEK",
  
  
  
  
  
"amount": 149,
  
  
  
  
  
"amountExcludingTax": 140.57,
  
  
  
  
  
"tax": 8.43
  
  
  
  
}
  
  
  
],
  
  
  
"recurring": {
  
  
  
  
"interval": "string",
  
  
  
  
"intervalCount": 0
  
  
  
},
  
  
  
"duration": {
  
  
  
  
"interval": "string",
  
  
  
  
"intervalCount": 0
  
  
  
},
  
  
  
"issues": 0,
  
  
  
"seatsPerUnit": 0,
  
  
  
"minQuantity": 0,
  
  
  
"maxQuantity": 0,
  
  
  
"isForSale": true,
  
  
  
"isListed": true
  
  
}
  
]
}

Playground​

Authorization
Body

Samples​


GET /management/products/{sku}​

GET
/management/products/{sku}

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

sku*
Type
string
Required

Responses​

Retrieve a product by SKU with purchase option IDs, market prices, schedules and availability flags.

application/json
JSON
{
  
"cover": "string",
  
"language": "string",
  
"createdAt": "string",
  
"updatedAt": "string",
  
"sku": "string",
  
"title": "string",
  
"productType": "string",
  
"publisherContentId": "string",
  
"purchaseOptions": [
  
  
{
  
  
  
"id": "string",
  
  
  
"title": "string",
  
  
  
"purchaseType": "string",
  
  
  
"prices": [
  
  
  
  
{
  
  
  
  
  
"market": "SE",
  
  
  
  
  
"currency": "SEK",
  
  
  
  
  
"amount": 149,
  
  
  
  
  
"amountExcludingTax": 140.57,
  
  
  
  
  
"tax": 8.43
  
  
  
  
}
  
  
  
],
  
  
  
"recurring": {
  
  
  
  
"interval": "string",
  
  
  
  
"intervalCount": 0
  
  
  
},
  
  
  
"duration": {
  
  
  
  
"interval": "string",
  
  
  
  
"intervalCount": 0
  
  
  
},
  
  
  
"issues": 0,
  
  
  
"seatsPerUnit": 0,
  
  
  
"minQuantity": 0,
  
  
  
"maxQuantity": 0,
  
  
  
"isForSale": true,
  
  
  
"isListed": true
  
  
}
  
]
}

Playground​

Authorization
Variables
Key
Value

Samples​


PATCH /management/products/{sku}​

PATCH
/management/products/{sku}

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

sku*
Type
string
Required

Request Body​

application/json
JSON
{
  
"externalIds": {
  
  
"spotifyId": "string"
  
},
  
"language": "string"
}

Responses​

The updated product

application/json
JSON
{
  
"cover": "string",
  
"language": "string",
  
"createdAt": "string",
  
"updatedAt": "string",
  
"sku": "string",
  
"title": "string",
  
"productType": "string",
  
"publisherContentId": "string",
  
"purchaseOptions": [
  
  
{
  
  
  
"id": "string",
  
  
  
"title": "string",
  
  
  
"purchaseType": "string",
  
  
  
"prices": [
  
  
  
  
{
  
  
  
  
  
"market": "SE",
  
  
  
  
  
"currency": "SEK",
  
  
  
  
  
"amount": 149,
  
  
  
  
  
"amountExcludingTax": 140.57,
  
  
  
  
  
"tax": 8.43
  
  
  
  
}
  
  
  
],
  
  
  
"recurring": {
  
  
  
  
"interval": "string",
  
  
  
  
"intervalCount": 0
  
  
  
},
  
  
  
"duration": {
  
  
  
  
"interval": "string",
  
  
  
  
"intervalCount": 0
  
  
  
},
  
  
  
"issues": 0,
  
  
  
"seatsPerUnit": 0,
  
  
  
"minQuantity": 0,
  
  
  
"maxQuantity": 0,
  
  
  
"isForSale": true,
  
  
  
"isListed": true
  
  
}
  
]
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


GET /management/products/{sku}/fulfillments​

GET
/management/products/{sku}/fulfillments

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

sku*
Type
string
Required

Responses​

Retrieve a a product by SKU

application/json
JSON
[
  
{
  
  
"status": "string",
  
  
"updatedAt": "string",
  
  
"createdAt": "string",
  
  
"deliversAt": "string",
  
  
"sku": "string",
  
  
"title": "string"
  
}
]

Playground​

Authorization
Variables
Key
Value

Samples​


List user logs​

GET
/management/users/{user_id}/logs

Returns paginated user logs for the authenticated vendor.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

user_id*

The unique identifier of the user

Type
string
Required
Example"user123"

Query Parameters

page

Zero-based page number

Type
integer
Minimum
0
Default
0
per_page

Items per page (maximum 100)

Type
integer
Minimum
1
Maximum
100
Default
20

Responses​

User logs and total matching count

application/json
JSON
{
  
"logs": [
  
  
{
  
  
  
"id": "string",
  
  
  
"date": "string",
  
  
  
"type": "string",
  
  
  
"description": "string",
  
  
  
"ip": "string",
  
  
  
"clientId": "string"
  
  
}
  
],
  
"total": 0
}

Playground​

Authorization
Variables
Key
Value

Samples​


List user sessions​

GET
/management/users/{user_id}/sessions

Returns paginated user sessions for the authenticated vendor.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

user_id*

The unique identifier of the user

Type
string
Required
Example"user123"

Query Parameters

page

Zero-based page number

Type
integer
Minimum
0
Default
0
per_page

Items per page (maximum 100)

Type
integer
Minimum
1
Maximum
100
Default
20

Responses​

User sessions and total matching count

application/json
JSON
{
  
"sessions": [
  
  
{
  
  
  
"id": "string",
  
  
  
"createdAt": "string",
  
  
  
"lastInteractionAt": "string",
  
  
  
"expiresAt": "string",
  
  
  
"idleExpiresAt": "string",
  
  
  
"revokedAt": "string",
  
  
  
"lastIp": "string",
  
  
  
"lastUserAgent": "string",
  
  
  
"clientIds": [
  
  
  
  
"string"
  
  
  
]
  
  
}
  
],
  
"total": 0
}

Playground​

Authorization
Variables
Key
Value

Samples​


List users​

GET
/management/users

Returns a list of users with optional filtering.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Query Parameters

q

Search query

Type
string
Example"john"
limit

Number of results to return

Type
string
Example"10"
from

Offset for pagination

Type
string
Example"0"

Responses​

A list of users matching the query parameters

application/json
JSON
[
  
{
  
  
"userId": "string",
  
  
"firstName": "string",
  
  
"lastName": "string",
  
  
"email": "string",
  
  
"emailVerified": true,
  
  
"locale": "string",
  
  
"nickname": "string",
  
  
"picture": "string",
  
  
"name": "string",
  
  
"mobilePhone": "string",
  
  
"workPhone": "string",
  
  
"homePhone": "string",
  
  
"tags": [
  
  
  
"string"
  
  
],
  
  
"user_metadata": {
  
  
  
"additionalProperties": "string"
  
  
},
  
  
"billingAddress": {
  
  
  
"country": "string",
  
  
  
"zip": "string",
  
  
  
"city": "string",
  
  
  
"street": "string",
  
  
  
"co": "string",
  
  
  
"lastName": "string",
  
  
  
"firstName": "string"
  
  
},
  
  
"deliveryAddress": {
  
  
  
"country": "string",
  
  
  
"zip": "string",
  
  
  
"city": "string",
  
  
  
"street": "string",
  
  
  
"co": "string",
  
  
  
"lastName": "string",
  
  
  
"firstName": "string"
  
  
},
  
  
"createdAt": "string",
  
  
"updatedAt": "string",
  
  
"companyInfo": {
  
  
  
"companyName": "string",
  
  
  
"vatNr": "string",
  
  
  
"invoiceEmail": "string"
  
  
},
  
  
"company": "string",
  
  
"sub": "string",
  
  
"given_name": "string",
  
  
"family_name": "string",
  
  
"phone_number": "string"
  
}
]

Playground​

Authorization
Variables
Key
Value

Samples​


Create a user​

POST
/management/users

Creates a new user with the specified email and optional name.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Request Body​

application/json
JSON
{
  
"email": "new.user@example.com",
  
"firstName": "New",
  
"lastName": "User"
}

Responses​

User created successfully

application/json
JSON
{
  
"success": true
}

Playground​

Authorization
Body

Samples​


Get a user by ID​

GET
/management/users/{user_id}

Retrieves a specific user's profile by their ID.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

user_id*

The unique identifier of the user

Type
string
Required
Example"user123"

Responses​

The requested user profile

application/json
JSON
{
  
"userId": "string",
  
"firstName": "string",
  
"lastName": "string",
  
"email": "string",
  
"emailVerified": true,
  
"locale": "string",
  
"nickname": "string",
  
"picture": "string",
  
"name": "string",
  
"mobilePhone": "string",
  
"workPhone": "string",
  
"homePhone": "string",
  
"tags": [
  
  
"string"
  
],
  
"user_metadata": {
  
  
"additionalProperties": "string"
  
},
  
"billingAddress": {
  
  
"country": "string",
  
  
"zip": "string",
  
  
"city": "string",
  
  
"street": "string",
  
  
"co": "string",
  
  
"lastName": "string",
  
  
"firstName": "string"
  
},
  
"deliveryAddress": {
  
  
"country": "string",
  
  
"zip": "string",
  
  
"city": "string",
  
  
"street": "string",
  
  
"co": "string",
  
  
"lastName": "string",
  
  
"firstName": "string"
  
},
  
"createdAt": "string",
  
"updatedAt": "string",
  
"companyInfo": {
  
  
"companyName": "string",
  
  
"vatNr": "string",
  
  
"invoiceEmail": "string"
  
},
  
"company": "string",
  
"sub": "string",
  
"given_name": "string",
  
"family_name": "string",
  
"phone_number": "string"
}

Playground​

Authorization
Variables
Key
Value

Samples​


Delete a user​

DELETE
/management/users/{user_id}

Deletes a user from the auth server. This action is irreversible. Set allowPurchases=true to allow one-off purchase entitlements. Active subscription entitlements and active, overdue or forthcoming contracts always block deletion.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

user_id*

The unique identifier of the user

Type
string
Required
Example"user123"

Query Parameters

allowPurchases

Allow deletion with one-off purchases. Does not bypass subscription checks.

Type
string
Valid values
"true""false"
Example"false"
Default
"false"

Responses​

User deleted successfully

application/json
JSON
{
  
"success": true
}

Playground​

Authorization
Variables
Key
Value

Samples​


Update a user​

PATCH
/management/users/{user_id}

Updates a specific user's profile with the provided data.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

user_id*

The unique identifier of the user

Type
string
Required
Example"user123"

Request Body​

application/json
JSON
{
  
"firstName": "John",
  
"lastName": "Doe",
  
"nickname": "Johnny",
  
"mobilePhone": "+1234567890",
  
"workPhone": "+1234567891",
  
"homePhone": "+1234567892",
  
"billingAddress": {
  
  
"country": "string",
  
  
"zip": "string",
  
  
"city": "Stockholm",
  
  
"street": "string",
  
  
"co": "string",
  
  
"lastName": "string",
  
  
"firstName": "string"
  
},
  
"deliveryAddress": {
  
  
"country": "string",
  
  
"zip": "string",
  
  
"city": "Stockholm",
  
  
"street": "string",
  
  
"co": "string",
  
  
"lastName": "string",
  
  
"firstName": "string"
  
},
  
"user_metadata": {
  
  
"additionalProperties": "string"
  
},
  
"companyInfo": {
  
  
"companyName": "string",
  
  
"vatNr": "string",
  
  
"invoiceEmail": "string"
  
},
  
"given_name": "string",
  
"family_name": "string",
  
"phone_number": "string"
}

Responses​

The updated user profile

application/json
JSON
{
  
"userId": "string",
  
"firstName": "string",
  
"lastName": "string",
  
"email": "string",
  
"emailVerified": true,
  
"locale": "string",
  
"nickname": "string",
  
"picture": "string",
  
"name": "string",
  
"mobilePhone": "string",
  
"workPhone": "string",
  
"homePhone": "string",
  
"tags": [
  
  
"string"
  
],
  
"user_metadata": {
  
  
"additionalProperties": "string"
  
},
  
"billingAddress": {
  
  
"country": "string",
  
  
"zip": "string",
  
  
"city": "string",
  
  
"street": "string",
  
  
"co": "string",
  
  
"lastName": "string",
  
  
"firstName": "string"
  
},
  
"deliveryAddress": {
  
  
"country": "string",
  
  
"zip": "string",
  
  
"city": "string",
  
  
"street": "string",
  
  
"co": "string",
  
  
"lastName": "string",
  
  
"firstName": "string"
  
},
  
"createdAt": "string",
  
"updatedAt": "string",
  
"companyInfo": {
  
  
"companyName": "string",
  
  
"vatNr": "string",
  
  
"invoiceEmail": "string"
  
},
  
"company": "string",
  
"sub": "string",
  
"given_name": "string",
  
"family_name": "string",
  
"phone_number": "string"
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


Change user login identifier​

POST
/management/users/{user_id}/change-login-identifier

Changes the email address that a user uses to log in.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

user_id*

The unique identifier of the user

Type
string
Required
Example"user123"

Request Body​

application/json
JSON
{
  
"email": "new.email@example.com"
}

Responses​

Login identifier changed successfully

application/json
JSON
{
  
"success": true
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


Add phone login identifier​

POST
/management/users/{user_id}/add-phone-identifier

Creates a new SMS user in Auth0 and links it as an additional login identity to the existing user.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

user_id*

The unique identifier of the user

Type
string
Required
Example"user123"

Request Body​

application/json
JSON
{
  
"phoneNumber": "+46701234567"
}

Responses​

Phone identifier added successfully

application/json
JSON
{
  
"success": true
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


Set user metadata value​

PUT
/management/users/{user_id}/user_metadata/{key}

Sets a metadata value for a specific user with the specified key.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

user_id*

The unique identifier of the user

Type
string
Required
Example"user123"
key*

The key of the metadata entry

Type
string
Required
Example"preferences"

Request Body​

text/plain
JSON
"string"

Responses​

Metadata value set successfully

application/json
JSON
{
  
"success": true
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


Delete user metadata value​

DELETE
/management/users/{user_id}/user_metadata/{key}

Deletes a metadata value for a specific user with the specified key.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

user_id*

The unique identifier of the user

Type
string
Required
Example"user123"
key*

The key of the metadata entry

Type
string
Required
Example"preferences"

Responses​

Metadata value deleted successfully

application/json
JSON
{
  
"success": true
}

Playground​

Authorization
Variables
Key
Value

Samples​


Set user password​

POST
/management/users/{user_id}/set-password

Sets or updates the password for a user. Creates a password authentication method if one does not exist.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

user_id*

The unique identifier of the user

Type
string
Required
Example"user123"

Request Body​

application/json
JSON
{
  
"password": "SecurePassword123!"
}

Responses​

Password set successfully

application/json
JSON
{
  
"success": true
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


List team members​

GET
/management/team

Returns the list of users with portal access for the current vendor.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Responses​

A list of team members

application/json
JSON
[
  
{
  
  
"userId": "auth0|61715b8ebe82f0006ab0613b",
  
  
"email": "user@example.com",
  
  
"roles": [
  
  
  
[
  
  
  
  
"PortalFullAccess"
  
  
  
]
  
  
]
  
}
]

Playground​

Authorization

Samples​


Invite a team member​

POST
/management/team

Adds a new team member identified by email and assigns one or more portal roles.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Request Body​

application/json
JSON
{
  
"email": "user@example.com",
  
"roles": [
  
  
[
  
  
  
"PortalFullAccess"
  
  
]
  
]
}

Responses​

Team member added successfully

application/json
JSON
{
  
"userId": "auth0|61715b8ebe82f0006ab0613b",
  
"email": "user@example.com",
  
"roles": [
  
  
[
  
  
  
"PortalFullAccess"
  
  
]
  
]
}

Playground​

Authorization
Body

Samples​


Set team member roles​

PUT
/management/team/{userId}

Replaces the portal roles for a team member. Only portal-managed roles are affected; other roles on the user are left untouched. Pass an empty array to remove all portal roles.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

userId*
Type
string
Required
Example"auth0|61715b8ebe82f0006ab0613b"

Request Body​

application/json
JSON
{
  
"roles": [
  
  
[
  
  
  
"PortalFullAccess"
  
  
]
  
]
}

Responses​

Roles updated successfully

application/json
JSON
{
  
"userId": "auth0|61715b8ebe82f0006ab0613b",
  
"email": "user@example.com",
  
"roles": [
  
  
[
  
  
  
"PortalFullAccess"
  
  
]
  
]
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


Remove a team member​

DELETE
/management/team/{userId}

Removes all portal-managed role assignments for a user. Other roles on the user are left untouched.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

userId*
Type
string
Required
Example"auth0|61715b8ebe82f0006ab0613b"

Responses​

Team member removed

Playground​

Authorization
Variables
Key
Value

Samples​


List API keys​

GET
/management/api-keys

Returns the vendor's machine-to-machine API keys, newest first. Secrets are never included — a secret is readable only in the response that created it.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Responses​

The vendor's API keys

application/json
JSON
[
  
{
  
  
"clientId": "apikey_9f2c1d8e4b7a4f1e9c3d5a6b7c8d9e0f",
  
  
"name": "Newsroom CMS",
  
  
"role": "read",
  
  
"scopes": [
  
  
  
[
  
  
  
  
"access-lists:read",
  
  
  
  
"bills:read",
  
  
  
  
"checkouts:read",
  
  
  
  
"contracts:read",
  
  
  
  
"domains:read",
  
  
  
  
"entitlements:read",
  
  
  
  
"products:read",
  
  
  
  
"sites:read",
  
  
  
  
"stats:views:read",
  
  
  
  
"transactions:read",
  
  
  
  
"users:read"
  
  
  
]
  
  
],
  
  
"createdAt": "2026-09-01T09:12:44.000Z"
  
}
]

Playground​

Authorization

Samples​


Create an API key​

POST
/management/api-keys

Creates a machine-to-machine key and returns its secret. This is the only response that ever carries the secret. Use the returned clientId, clientSecret, tokenUrl and audience in an OAuth 2.0 client-credentials exchange to mint Management API tokens.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Request Body​

application/json
JSON
{
  
"name": "Newsroom CMS",
  
"role": "read"
}

Responses​

Key created — the secret is in this response and nowhere else

application/json
JSON
{
  
"clientId": "apikey_9f2c1d8e4b7a4f1e9c3d5a6b7c8d9e0f",
  
"name": "Newsroom CMS",
  
"role": "read",
  
"scopes": [
  
  
[
  
  
  
"access-lists:read",
  
  
  
"bills:read",
  
  
  
"checkouts:read",
  
  
  
"contracts:read",
  
  
  
"domains:read",
  
  
  
"entitlements:read",
  
  
  
"products:read",
  
  
  
"sites:read",
  
  
  
"stats:views:read",
  
  
  
"transactions:read",
  
  
  
"users:read"
  
  
]
  
],
  
"createdAt": "2026-09-01T09:12:44.000Z",
  
"clientSecret": "k2Jd8sV1pQ7wE4rT6yU9iO0aS3dF5gH8",
  
"tokenUrl": "https://acme.token.sesamy.com/oauth/token",
  
"audience": "urn:sesamy"
}

Playground​

Authorization
Body

Samples​


Revoke an API key​

DELETE
/management/api-keys/{clientId}

Revokes the key immediately and irreversibly. Tokens already minted with it keep working until they expire — the key can mint no new ones. Only API keys can be deleted here; a client id belonging to a site is reported as not found.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

clientId*
Type
string
Required
Example"apikey_9f2c1d8e4b7a4f1e9c3d5a6b7c8d9e0f"

Responses​

Key revoked

Playground​

Authorization
Variables
Key
Value

Samples​


Compatibility​


Get customer information​

GET
/management/mc/customers/{customerId}

Returns customer information in XML format for Mediaconnect compatibility.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)
+
Basic
Type
HTTP (basic)

Parameters​

Path Parameters

customerId*

The unique identifier of the customer

Type
string
Required
Example"958280"

Responses​

Customer information in XML format

application/xml
XML

Playground​

Authorization
Variables
Key
Value

Samples​


Entitlements​


GET /management/entitlements​

GET
/management/entitlements

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Query Parameters

q

Search query for entitlements

Type
string
Example"premium article"
limit

Maximum number of results to return

Type
string
Example"20"
from

Pagination cursor for fetching next page

Type
string
Example"cursor123"
userId*

Filter entitlements by user ID

Type
string
Required
Example"user123"
type

Filter by entitlement type

Type
string
Valid values
"article""audiobook""ebook""bundle""podcast""pass""publication""physical_issue"
Example"article"
sku

Filter by product SKU

Type
string
Example"premium-article-123"

Responses​

List of entitlements

application/json
JSON
[
  
{
  
  
"id": "1d78271264b9c76d5842911dd70b4353",
  
  
"sku": "string",
  
  
"purchaseOption": "string",
  
  
"cover": "string",
  
  
"title": "string",
  
  
"url": "string",
  
  
"presentationUrl": "string",
  
  
"publisherContentId": "string",
  
  
"type": "string",
  
  
"origin": {
  
  
  
"type": "string",
  
  
  
"id": "string",
  
  
  
"listId": "string",
  
  
  
"name": "string"
  
  
},
  
  
"hasAccess": true,
  
  
"isPaused": true,
  
  
"createdAt": "string",
  
  
"updatedAt": "string",
  
  
"token": "string",
  
  
"expiresAt": "string"
  
}
]

Playground​

Authorization
Variables
Key
Value

Samples​


List a reader's checkouts​

GET
/management/checkouts

Lists the checkouts started with the caller's vendor, newest first. Pass userId for one reader's, and status=PENDING to find incomplete checkouts. A listed id can return 404 from GET /management/checkouts/{id} once the checkout is older than 7 days.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Query Parameters

q

Search query, up to 200 characters and 20 words

Type
string
userId

Only return the checkouts of this reader

Type
string
Example"auth0|6123456789"
Min Length
1
status

Only return checkouts in this status. PENDING are the incomplete ones

Type
string
Valid values
"PENDING""WAITING_PAYMENT_CONFIRMATION""COMPLETED""FAILED"
limit

Maximum number of results, 1 to 100. Defaults to 20

Type
string
Example"20"
from

Offset of the first result, for paging

Type
string
Example"20"

Responses​

A page of checkouts

application/json
JSON
[
  
{
  
  
"id": "checkout123",
  
  
"status": "string",
  
  
"type": "RECURRING",
  
  
"source": "string",
  
  
"createdAt": "string",
  
  
"updatedAt": "string",
  
  
"completedAt": "string",
  
  
"contractId": "string",
  
  
"currency": "SEK",
  
  
"country": "string",
  
  
"userId": "string",
  
  
"email": "string",
  
  
"firstName": "string",
  
  
"lastName": "string",
  
  
"mobilePhone": "string",
  
  
"isBusiness": true,
  
  
"total": 14900,
  
  
"items": [
  
  
  
{
  
  
  
  
"sku": "string",
  
  
  
  
"purchaseOptionId": "string",
  
  
  
  
"title": "string"
  
  
  
}
  
  
]
  
}
]

Playground​

Authorization
Variables
Key
Value

Samples​


Get a checkout by id​

GET
/management/checkouts/{id}

Fetches a single checkout belonging to the caller's vendor. Primarily used to hydrate a checkout.1#confirm webhook event, which carries only a checkoutId.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*

The unique identifier of the checkout

Type
string
Required
Example"checkout123"

Responses​

The checkout

application/json
JSON
{
  
"items": [
  
  
{
  
  
  
"sku": "string",
  
  
  
"url": "string",
  
  
  
"purchaseOptionId": "string",
  
  
  
"price": 0,
  
  
  
"currency": "string",
  
  
  
"geoRestrictions": {
  
  
  
  
"countries": [
  
  
  
  
  
"string"
  
  
  
  
],
  
  
  
  
"type": "string"
  
  
  
}
  
  
}
  
],
  
"address": {
  
  
"country": "string",
  
  
"zip": "string",
  
  
"city": "string",
  
  
"street": "string",
  
  
"co": "string",
  
  
"lastName": "string",
  
  
"firstName": "string"
  
},
  
"businessAddress": {
  
  
"country": "string",
  
  
"zip": "string",
  
  
"city": "string",
  
  
"street": "string",
  
  
"co": "string",
  
  
"lastName": "string",
  
  
"firstName": "string"
  
},
  
"email": "string",
  
"givenName": "string",
  
"familyName": "string",
  
"birthDate": "string",
  
"phoneNumber": "string",
  
"country": "string",
  
"referralEmail": "string",
  
"language": "string",
  
"redirectUrl": "string",
  
"isBusiness": true,
  
"price": 0,
  
"currency": "string",
  
"anonymousUserId": "string",
  
"attribution": {
  
  
"utmSource": "string",
  
  
"utmMedium": "string",
  
  
"utmCampaign": "string",
  
  
"utmTerm": "string",
  
  
"utmContent": "string",
  
  
"source": "string",
  
  
"sourceId": "string",
  
  
"decisionId": "6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f",
  
  
"strategyId": "st_abc123",
  
  
"itemSrc": "string",
  
  
"referrer": "string",
  
  
"publisherContentId": "string",
  
  
"_ga": "string",
  
  
"_gid": "string",
  
  
"_fbp": "string",
  
  
"_fbc": "string",
  
  
"_pk_id": "string",
  
  
"gaSessionId": "string"
  
},
  
"paymentData": {
  
  
"provider": "string",
  
  
"method": "string"
  
},
  
"paymentMethodsFilter": [
  
  
{
  
  
  
"provider": "string",
  
  
  
"methods": [
  
  
  
  
"string"
  
  
  
]
  
  
}
  
],
  
"fieldSettings": {
  
  
"name": {
  
  
  
"enabled": true,
  
  
  
"required": true
  
  
},
  
  
"phone": {
  
  
  
"enabled": true,
  
  
  
"required": true
  
  
},
  
  
"birthdate": {
  
  
  
"enabled": true,
  
  
  
"required": true
  
  
},
  
  
"referral": {
  
  
  
"enabled": true
  
  
}
  
},
  
"giftMode": true,
  
"requireAddress": true,
  
"metadata": {
  
  
"additionalProperties": "string"
  
},
  
"id": "string",
  
"checkoutUrl": "string",
  
"status": "string",
  
"type": "string",
  
"itemsOwned": [
  
  
{
  
  
  
"sku": "string",
  
  
  
"purchaseOptionId": "string",
  
  
  
"title": "string"
  
  
}
  
],
  
"appliedDiscountCodes": [
  
  
{
  
  
  
"name": "string",
  
  
  
"id": "string",
  
  
  
"code": "string",
  
  
  
"description": "string",
  
  
  
"status": "string"
  
  
}
  
],
  
"availablePaymentMethods": [
  
  
{
  
  
  
"provider": "string",
  
  
  
"methods": [
  
  
  
  
"string"
  
  
  
]
  
  
}
  
],
  
"payer": {
  
  
"id": "string",
  
  
"email": "string"
  
},
  
"createdAt": "string",
  
"updatedAt": "string"
}

Playground​

Authorization
Variables
Key
Value

Samples​


List discounts​

GET
/management/discounts

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Query Parameters

status

A new discount is a DRAFT. Activating it makes it PENDING, and it becomes ACTIVE once its start date is reached and EXPIRED after its end date. Only DRAFT and PAUSED discounts can be edited or canceled.

Type
string
Valid values
"DRAFT""PENDING""ACTIVE""PAUSED""EXPIRED""CANCELED""ACTIVATION_ERROR"
type

percentage and fixedAmount reduce the price, trialPeriod gives free days before the first bill, specialPriceTranche sets an introductory price and billing period, and developerTest makes a purchase free for testing.

Type
string
Valid values
"percentage""fixedAmount""trialPeriod""specialPriceTranche""developerTest"
limit

Maximum number of items read for a page

Type
integer
Example50
Minimum
1
Maximum
100
cursor

The nextCursor of the previous page

Type
string

Responses​

The discounts

application/json
JSON
{
  
"items": [
  
  
{
  
  
  
"name": "Welcome offer",
  
  
  
"description": "string",
  
  
  
"code": "WELCOME20",
  
  
  
"startDate": "2026-10-01T00:00:00Z",
  
  
  
"endDate": "2026-12-31T23:59:59Z",
  
  
  
"currency": "SEK",
  
  
  
"id": "6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11",
  
  
  
"status": "string",
  
  
  
"usageCount": 0,
  
  
  
"createdAt": "string",
  
  
  
"type": "string",
  
  
  
"parameters": {
  
  
  
  
"percentage": 20,
  
  
  
  
"numberOfMonths": 3,
  
  
  
  
"curbToMaxAmount": 0,
  
  
  
  
"allowSKUs": [
  
  
  
  
  
"string"
  
  
  
  
],
  
  
  
  
"allowPOs": [
  
  
  
  
  
"string"
  
  
  
  
],
  
  
  
  
"ignoreSKUs": [
  
  
  
  
  
"string"
  
  
  
  
],
  
  
  
  
"requireVerticals": [
  
  
  
  
  
"string"
  
  
  
  
],
  
  
  
  
"ignoreVerticals": [
  
  
  
  
  
"string"
  
  
  
  
]
  
  
  
},
  
  
  
"conditions": {
  
  
  
  
"minimumTotalItems": 0,
  
  
  
  
"minimumTotalAmount": 0,
  
  
  
  
"totalTimesApplicable": 0,
  
  
  
  
"totalTimesApplicablePerUser": 0
  
  
  
}
  
  
}
  
],
  
"nextCursor": "string"
}

Playground​

Authorization
Variables
Key
Value

Samples​


Create a discount​

POST
/management/discounts

Creates a discount as a DRAFT. It applies to nothing until it is activated with POST /management/discounts/{id}/activate. parameters and conditions depend on type. Creating is not idempotent: a repeated request creates a second discount.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Request Body​

application/json
JSON
{
  
"name": "Welcome offer",
  
"description": "string",
  
"code": "WELCOME20",
  
"startDate": "2026-10-01T00:00:00Z",
  
"endDate": "2026-12-31T23:59:59Z",
  
"currency": "SEK",
  
"type": "string",
  
"parameters": {
  
  
"percentage": 20,
  
  
"numberOfMonths": 3,
  
  
"curbToMaxAmount": 0,
  
  
"allowSKUs": [
  
  
  
"string"
  
  
],
  
  
"allowPOs": [
  
  
  
"string"
  
  
],
  
  
"ignoreSKUs": [
  
  
  
"string"
  
  
],
  
  
"requireVerticals": [
  
  
  
"string"
  
  
],
  
  
"ignoreVerticals": [
  
  
  
"string"
  
  
]
  
},
  
"conditions": {
  
  
"minimumTotalItems": 0,
  
  
"minimumTotalAmount": 0,
  
  
"totalTimesApplicable": 0,
  
  
"totalTimesApplicablePerUser": 0
  
}
}

Responses​

The created discount

application/json
JSON
{
  
"name": "Welcome offer",
  
"description": "string",
  
"code": "WELCOME20",
  
"startDate": "2026-10-01T00:00:00Z",
  
"endDate": "2026-12-31T23:59:59Z",
  
"currency": "SEK",
  
"id": "6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11",
  
"status": "string",
  
"usageCount": 0,
  
"createdAt": "string",
  
"type": "string",
  
"parameters": {
  
  
"percentage": 20,
  
  
"numberOfMonths": 3,
  
  
"curbToMaxAmount": 0,
  
  
"allowSKUs": [
  
  
  
"string"
  
  
],
  
  
"allowPOs": [
  
  
  
"string"
  
  
],
  
  
"ignoreSKUs": [
  
  
  
"string"
  
  
],
  
  
"requireVerticals": [
  
  
  
"string"
  
  
],
  
  
"ignoreVerticals": [
  
  
  
"string"
  
  
]
  
},
  
"conditions": {
  
  
"minimumTotalItems": 0,
  
  
"minimumTotalAmount": 0,
  
  
"totalTimesApplicable": 0,
  
  
"totalTimesApplicablePerUser": 0
  
}
}

Playground​

Authorization
Body

Samples​


Get a discount​

GET
/management/discounts/{id}

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11"

Responses​

The discount

application/json
JSON
{
  
"name": "Welcome offer",
  
"description": "string",
  
"code": "WELCOME20",
  
"startDate": "2026-10-01T00:00:00Z",
  
"endDate": "2026-12-31T23:59:59Z",
  
"currency": "SEK",
  
"id": "6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11",
  
"status": "string",
  
"usageCount": 0,
  
"createdAt": "string",
  
"type": "string",
  
"parameters": {
  
  
"percentage": 20,
  
  
"numberOfMonths": 3,
  
  
"curbToMaxAmount": 0,
  
  
"allowSKUs": [
  
  
  
"string"
  
  
],
  
  
"allowPOs": [
  
  
  
"string"
  
  
],
  
  
"ignoreSKUs": [
  
  
  
"string"
  
  
],
  
  
"requireVerticals": [
  
  
  
"string"
  
  
],
  
  
"ignoreVerticals": [
  
  
  
"string"
  
  
]
  
},
  
"conditions": {
  
  
"minimumTotalItems": 0,
  
  
"minimumTotalAmount": 0,
  
  
"totalTimesApplicable": 0,
  
  
"totalTimesApplicablePerUser": 0
  
}
}

Playground​

Authorization
Variables
Key
Value

Samples​


Update a discount​

PATCH
/management/discounts/{id}

Changes the fields sent and leaves the rest. parameters and conditions are replaced whole when sent. Only DRAFT and PAUSED discounts can be edited: pause an active discount first. The type cannot be changed.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11"

Request Body​

application/json
JSON
{
  
"name": "Welcome offer",
  
"description": "string",
  
"code": "WELCOME20",
  
"startDate": "2026-10-01T00:00:00Z",
  
"endDate": "2026-12-31T23:59:59Z",
  
"currency": "SEK",
  
"parameters": {
  
  
"additionalProperties": "string"
  
},
  
"conditions": {
  
  
"additionalProperties": "string"
  
}
}

Responses​

The updated discount

application/json
JSON
{
  
"name": "Welcome offer",
  
"description": "string",
  
"code": "WELCOME20",
  
"startDate": "2026-10-01T00:00:00Z",
  
"endDate": "2026-12-31T23:59:59Z",
  
"currency": "SEK",
  
"id": "6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11",
  
"status": "string",
  
"usageCount": 0,
  
"createdAt": "string",
  
"type": "string",
  
"parameters": {
  
  
"percentage": 20,
  
  
"numberOfMonths": 3,
  
  
"curbToMaxAmount": 0,
  
  
"allowSKUs": [
  
  
  
"string"
  
  
],
  
  
"allowPOs": [
  
  
  
"string"
  
  
],
  
  
"ignoreSKUs": [
  
  
  
"string"
  
  
],
  
  
"requireVerticals": [
  
  
  
"string"
  
  
],
  
  
"ignoreVerticals": [
  
  
  
"string"
  
  
]
  
},
  
"conditions": {
  
  
"minimumTotalItems": 0,
  
  
"minimumTotalAmount": 0,
  
  
"totalTimesApplicable": 0,
  
  
"totalTimesApplicablePerUser": 0
  
}
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


Activate a discount​

POST
/management/discounts/{id}/activate

Schedules a DRAFT or PAUSED discount. It becomes PENDING, and ACTIVE once its start date is reached. Activating an already PENDING or ACTIVE discount returns it unchanged.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11"

Responses​

The discount with its new status

application/json
JSON
{
  
"name": "Welcome offer",
  
"description": "string",
  
"code": "WELCOME20",
  
"startDate": "2026-10-01T00:00:00Z",
  
"endDate": "2026-12-31T23:59:59Z",
  
"currency": "SEK",
  
"id": "6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11",
  
"status": "string",
  
"usageCount": 0,
  
"createdAt": "string",
  
"type": "string",
  
"parameters": {
  
  
"percentage": 20,
  
  
"numberOfMonths": 3,
  
  
"curbToMaxAmount": 0,
  
  
"allowSKUs": [
  
  
  
"string"
  
  
],
  
  
"allowPOs": [
  
  
  
"string"
  
  
],
  
  
"ignoreSKUs": [
  
  
  
"string"
  
  
],
  
  
"requireVerticals": [
  
  
  
"string"
  
  
],
  
  
"ignoreVerticals": [
  
  
  
"string"
  
  
]
  
},
  
"conditions": {
  
  
"minimumTotalItems": 0,
  
  
"minimumTotalAmount": 0,
  
  
"totalTimesApplicable": 0,
  
  
"totalTimesApplicablePerUser": 0
  
}
}

Playground​

Authorization
Variables
Key
Value

Samples​


Pause a discount​

POST
/management/discounts/{id}/pause

Stops a PENDING or ACTIVE discount from applying to new purchases until it is activated again. A paused discount can be edited. Subscriptions that already have it keep it.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11"

Responses​

The discount with its new status

application/json
JSON
{
  
"name": "Welcome offer",
  
"description": "string",
  
"code": "WELCOME20",
  
"startDate": "2026-10-01T00:00:00Z",
  
"endDate": "2026-12-31T23:59:59Z",
  
"currency": "SEK",
  
"id": "6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11",
  
"status": "string",
  
"usageCount": 0,
  
"createdAt": "string",
  
"type": "string",
  
"parameters": {
  
  
"percentage": 20,
  
  
"numberOfMonths": 3,
  
  
"curbToMaxAmount": 0,
  
  
"allowSKUs": [
  
  
  
"string"
  
  
],
  
  
"allowPOs": [
  
  
  
"string"
  
  
],
  
  
"ignoreSKUs": [
  
  
  
"string"
  
  
],
  
  
"requireVerticals": [
  
  
  
"string"
  
  
],
  
  
"ignoreVerticals": [
  
  
  
"string"
  
  
]
  
},
  
"conditions": {
  
  
"minimumTotalItems": 0,
  
  
"minimumTotalAmount": 0,
  
  
"totalTimesApplicable": 0,
  
  
"totalTimesApplicablePerUser": 0
  
}
}

Playground​

Authorization
Variables
Key
Value

Samples​


Cancel a discount​

POST
/management/discounts/{id}/cancel

Retires a DRAFT or PAUSED discount for good. Pause an active discount first. Subscriptions that already have it keep it.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11"

Responses​

The discount with its new status

application/json
JSON
{
  
"name": "Welcome offer",
  
"description": "string",
  
"code": "WELCOME20",
  
"startDate": "2026-10-01T00:00:00Z",
  
"endDate": "2026-12-31T23:59:59Z",
  
"currency": "SEK",
  
"id": "6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11",
  
"status": "string",
  
"usageCount": 0,
  
"createdAt": "string",
  
"type": "string",
  
"parameters": {
  
  
"percentage": 20,
  
  
"numberOfMonths": 3,
  
  
"curbToMaxAmount": 0,
  
  
"allowSKUs": [
  
  
  
"string"
  
  
],
  
  
"allowPOs": [
  
  
  
"string"
  
  
],
  
  
"ignoreSKUs": [
  
  
  
"string"
  
  
],
  
  
"requireVerticals": [
  
  
  
"string"
  
  
],
  
  
"ignoreVerticals": [
  
  
  
"string"
  
  
]
  
},
  
"conditions": {
  
  
"minimumTotalItems": 0,
  
  
"minimumTotalAmount": 0,
  
  
"totalTimesApplicable": 0,
  
  
"totalTimesApplicablePerUser": 0
  
}
}

Playground​

Authorization
Variables
Key
Value

Samples​


List one-time codes​

GET
/management/discounts/{id}/codes

Lists the single-use codes generated for a discount.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11"

Query Parameters

limit

Maximum number of items read for a page

Type
integer
Example50
Minimum
1
Maximum
100
cursor

The nextCursor of the previous page

Type
string

Responses​

The codes

application/json
JSON
{
  
"items": [
  
  
{
  
  
  
"id": "string",
  
  
  
"code": "K7Q2M9XW4D1P",
  
  
  
"status": "string",
  
  
  
"startDate": "string",
  
  
  
"endDate": "string",
  
  
  
"redeemedBy": "string",
  
  
  
"redeemedAt": "string"
  
  
}
  
],
  
"nextCursor": "string"
}

Playground​

Authorization
Variables
Key
Value

Samples​


Generate one-time codes​

POST
/management/discounts/{id}/codes

Generates single-use codes that each apply the discount once. Not idempotent: a repeated request generates another batch.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11"

Request Body​

application/json
JSON
{
  
"count": 500,
  
"startDate": "2026-10-01T00:00:00Z",
  
"endDate": "2026-12-31T23:59:59Z"
}

Responses​

The generated codes

application/json
JSON
[
  
{
  
  
"id": "string",
  
  
"code": "K7Q2M9XW4D1P",
  
  
"status": "string",
  
  
"startDate": "string",
  
  
"endDate": "string",
  
  
"redeemedBy": "string",
  
  
"redeemedAt": "string"
  
}
]

Playground​

Authorization
Variables
Key
Value
Body

Samples​


Cancel one-time codes​

DELETE
/management/discounts/{id}/codes

Cancels every code of the discount that has not been redeemed. Redeemed codes are kept.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11"

Responses​

The unredeemed codes were canceled

Playground​

Authorization
Variables
Key
Value

Samples​


List paywalls​

GET
/management/paywalls

Lists all paywalls configured for the authenticated vendor.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Responses​

The list of paywalls for the vendor

application/json
JSON
[
  
{
  
  
"id": "aM8o7LqpkGZJ-szyPwe_E",
  
  
"vendorId": "acme",
  
  
"currency": "SEK",
  
  
"version": 2,
  
  
"settings": {
  
  
  
"template": "BOXES",
  
  
  
"useDefaultLogo": true,
  
  
  
"useDefaultCurrency": true,
  
  
  
"useDefaultColor": true,
  
  
  
"styling": {
  
  
  
  
"dropShadow": true,
  
  
  
  
"backgroundColor": "#000000",
  
  
  
  
"showBackground": false
  
  
  
},
  
  
  
"displayOptions": {
  
  
  
  
"enableGift": true,
  
  
  
  
"enableCompany": true,
  
  
  
  
"enableLoginButton": true
  
  
  
},
  
  
  
"loginFields": {
  
  
  
  
"name": true
  
  
  
},
  
  
  
"leaky": {
  
  
  
  
"enabled": true,
  
  
  
  
"count": 3,
  
  
  
  
"periodInHours": 720
  
  
  
},
  
  
  
"redirectUrl": "https://acme.example.com/welcome",
  
  
  
"redirectLabel": "Go to ACME",
  
  
  
"showPricesExVat": false
  
  
},
  
  
"showLoginButton": true,
  
  
"subscriptions": [
  
  
  
{
  
  
  
  
"id": "R4gX0YSbSU1WJA7bCrbQw",
  
  
  
  
"sku": "sid:acme-plus-monthly",
  
  
  
  
"poId": "VDuH_poxqIPKW638Ok43q",
  
  
  
  
"title": "ACME Plus monthly",
  
  
  
  
"description": "<p>Only 720 kr/year - save 20%</p>",
  
  
  
  
"price": 99,
  
  
  
  
"discountPrice": 75,
  
  
  
  
"discountCode": "WELCOME20",
  
  
  
  
"periodText": "3 months",
  
  
  
  
"comparePeriodText": "month",
  
  
  
  
"tag": "Most popular",
  
  
  
  
"selected": true,
  
  
  
  
"features": [
  
  
  
  
  
[
  
  
  
  
  
  
"Daily news",
  
  
  
  
  
  
"Exclusive interviews"
  
  
  
  
  
]
  
  
  
  
],
  
  
  
  
"buttonText": "BUY ACCESS",
  
  
  
  
"readMoreLink": "https://acme.example.com/subscriptions",
  
  
  
  
"readMoreText": "Read more",
  
  
  
  
"preferBusiness": false,
  
  
  
  
"redirectUrl": "https://acme.example.com/welcome",
  
  
  
  
"redirectLabel": "Start reading ACME Plus",
  
  
  
  
"discountId": "disc_acme_welcome",
  
  
  
  
"priceMode": "AUTOMATIC",
  
  
  
  
"url": "https://acme.example.com/business"
  
  
  
}
  
  
],
  
  
"subscriptionsUrl": "https://acme.example.com/subscriptions.json",
  
  
"features": [
  
  
  
[
  
  
  
  
"Everything on acme.example.com"
  
  
  
]
  
  
],
  
  
"mainColor": "#3377fe",
  
  
"headline": "Get access to ACME Plus",
  
  
"description": "<p>Read every article, on every device.</p>",
  
  
"logoUrl": "https://assets.sesamy.com/vendor-assets/acme/logo.svg",
  
  
"footerPaymentMethods": [
  
  
  
[
  
  
  
  
"visa",
  
  
  
  
"mastercard",
  
  
  
  
"google-pay",
  
  
  
  
"apple-pay"
  
  
  
]
  
  
],
  
  
"singlePurchase": {
  
  
  
"enabled": true,
  
  
  
"title": "Buy Now",
  
  
  
"description": "One-time purchase",
  
  
  
"discountCode": "WELCOME20",
  
  
  
"discountId": "disc_acme_welcome"
  
  
},
  
  
"name": "Article paywall",
  
  
"status": "ACTIVE",
  
  
"entity": "Paywall",
  
  
"createdAt": "2026-01-01T00:00:00.000Z",
  
  
"modifiedAt": "2026-01-01T00:00:00.000Z",
  
  
"previewUrl": "https://api.sesamy.com/paywall/paywalls/acme/aM8o7LqpkGZJ-szyPwe_E/preview"
  
}
]

Playground​

Authorization

Samples​


Get paywall by ID​

GET
/management/paywalls/{paywallId}

Retrieves the paywall configuration and settings for the specified paywall ID. This resolves the rendered paywall, so — unlike the list route — the response does not carry the admin-only name, status, entity, createdAt, modifiedAt or previewUrl fields.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

paywallId*

Unique identifier of the paywall

Type
string
Required
Example"pw123456"

Responses​

The paywall information and configuration

application/json
JSON
{
  
"id": "aM8o7LqpkGZJ-szyPwe_E",
  
"vendorId": "acme",
  
"currency": "SEK",
  
"version": 2,
  
"settings": {
  
  
"template": "BOXES",
  
  
"useDefaultLogo": true,
  
  
"useDefaultCurrency": true,
  
  
"useDefaultColor": true,
  
  
"styling": {
  
  
  
"dropShadow": true,
  
  
  
"backgroundColor": "#000000",
  
  
  
"showBackground": false
  
  
},
  
  
"displayOptions": {
  
  
  
"enableGift": true,
  
  
  
"enableCompany": true,
  
  
  
"enableLoginButton": true
  
  
},
  
  
"loginFields": {
  
  
  
"name": true
  
  
},
  
  
"leaky": {
  
  
  
"enabled": true,
  
  
  
"count": 3,
  
  
  
"periodInHours": 720
  
  
},
  
  
"redirectUrl": "https://acme.example.com/welcome",
  
  
"redirectLabel": "Go to ACME",
  
  
"showPricesExVat": false
  
},
  
"showLoginButton": true,
  
"subscriptions": [
  
  
{
  
  
  
"id": "R4gX0YSbSU1WJA7bCrbQw",
  
  
  
"sku": "sid:acme-plus-monthly",
  
  
  
"poId": "VDuH_poxqIPKW638Ok43q",
  
  
  
"title": "ACME Plus monthly",
  
  
  
"description": "<p>Only 720 kr/year - save 20%</p>",
  
  
  
"price": 99,
  
  
  
"discountPrice": 75,
  
  
  
"discountCode": "WELCOME20",
  
  
  
"periodText": "3 months",
  
  
  
"comparePeriodText": "month",
  
  
  
"tag": "Most popular",
  
  
  
"selected": true,
  
  
  
"features": [
  
  
  
  
[
  
  
  
  
  
"Daily news",
  
  
  
  
  
"Exclusive interviews"
  
  
  
  
]
  
  
  
],
  
  
  
"buttonText": "BUY ACCESS",
  
  
  
"readMoreLink": "https://acme.example.com/subscriptions",
  
  
  
"readMoreText": "Read more",
  
  
  
"preferBusiness": false,
  
  
  
"redirectUrl": "https://acme.example.com/welcome",
  
  
  
"redirectLabel": "Start reading ACME Plus",
  
  
  
"discountId": "disc_acme_welcome",
  
  
  
"priceMode": "AUTOMATIC",
  
  
  
"url": "https://acme.example.com/business",
  
  
  
"pricePeriod": {
  
  
  
  
"period": "month",
  
  
  
  
"time": 3
  
  
  
},
  
  
  
"discountPeriod": {
  
  
  
  
"period": "month",
  
  
  
  
"time": 3
  
  
  
},
  
  
  
"discountMonths": 6,
  
  
  
"trialDays": 14
  
  
}
  
],
  
"subscriptionsUrl": "https://acme.example.com/subscriptions.json",
  
"features": [
  
  
[
  
  
  
"Everything on acme.example.com"
  
  
]
  
],
  
"mainColor": "#3377fe",
  
"headline": "Get access to ACME Plus",
  
"description": "<p>Read every article, on every device.</p>",
  
"logoUrl": "https://assets.sesamy.com/vendor-assets/acme/logo.svg",
  
"footerPaymentMethods": [
  
  
[
  
  
  
"visa",
  
  
  
"mastercard",
  
  
  
"google-pay",
  
  
  
"apple-pay"
  
  
]
  
],
  
"singlePurchase": {
  
  
"enabled": true,
  
  
"title": "Buy Now",
  
  
"description": "One-time purchase",
  
  
"discountCode": "WELCOME20",
  
  
"discountId": "disc_acme_welcome"
  
},
  
"decisionId": "6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f",
  
"strategyId": "st_abc123"
}

Playground​

Authorization
Variables
Key
Value

Samples​


GET /management/access-lists​

GET
/management/access-lists

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Responses​

Retrieve a list of access lists

application/json
JSON
[
  
{
  
  
"id": "src_123abc",
  
  
"name": "My Partner API",
  
  
"description": "Purchases from partner system",
  
  
"type": "MANUAL",
  
  
"status": "ACTIVE",
  
  
"excludeFromStats": false
  
}
]

Playground​

Authorization

Samples​


POST /management/access-lists​

POST
/management/access-lists

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Request Body​

application/json
JSON
{
  
"name": "My Partner API",
  
"description": "Purchases from partner system",
  
"type": "MANUAL",
  
"status": "ACTIVE",
  
"excludeFromStats": false
}

Responses​

Access list created successfully

application/json
JSON
{
  
"id": "src_123abc",
  
"name": "My Partner API",
  
"description": "Purchases from partner system",
  
"type": "MANUAL",
  
"status": "ACTIVE",
  
"excludeFromStats": false
}

Playground​

Authorization
Body

Samples​


GET /management/access-lists/{id}​

GET
/management/access-lists/{id}

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*

Access list ID

Type
string
Required
Example"src_123abc"

Responses​

Retrieve an access list by ID

application/json
JSON
{
  
"id": "src_123abc",
  
"name": "My Partner API",
  
"description": "Purchases from partner system",
  
"type": "MANUAL",
  
"status": "ACTIVE",
  
"excludeFromStats": false
}

Playground​

Authorization
Variables
Key
Value

Samples​


PUT /management/access-lists/{id}​

PUT
/management/access-lists/{id}

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*

Access list ID

Type
string
Required
Example"src_123abc"

Request Body​

application/json
JSON
{
  
"name": "My Partner API",
  
"description": "Purchases from partner system",
  
"type": "MANUAL",
  
"status": "ACTIVE",
  
"excludeFromStats": false
}

Responses​

Access list updated successfully

application/json
JSON
{
  
"id": "src_123abc",
  
"name": "My Partner API",
  
"description": "Purchases from partner system",
  
"type": "MANUAL",
  
"status": "ACTIVE",
  
"excludeFromStats": false
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


PATCH /management/access-lists/{id}​

PATCH
/management/access-lists/{id}

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*

Access list ID

Type
string
Required
Example"src_123abc"

Request Body​

application/json
JSON
{
  
"name": "My Partner API",
  
"description": "Purchases from partner system",
  
"type": "MANUAL",
  
"status": "ACTIVE",
  
"excludeFromStats": false
}

Responses​

Access list patched successfully

application/json
JSON
{
  
"id": "src_123abc",
  
"name": "My Partner API",
  
"description": "Purchases from partner system",
  
"type": "MANUAL",
  
"status": "ACTIVE",
  
"excludeFromStats": false
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


GET /management/access-lists/{id}/grants​

GET
/management/access-lists/{id}/grants

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*

Access list ID

Type
string
Required
Example"src_123abc"

Responses​

Retrieve a list of grants for an access list

application/json
JSON
[
  
{
  
  
"id": "grant_123abc",
  
  
"source": "src_123abc",
  
  
"email": "user@example.com",
  
  
"userId": "pub_user_123",
  
  
"publisherUserId": "pub_user_123",
  
  
"sku": "premium-article-123",
  
  
"poId": "po_123abc",
  
  
"status": "ACTIVE",
  
  
"startsAt": "2024-01-01T00:00:00Z",
  
  
"endsAt": "2024-12-31T23:59:59Z",
  
  
"firstName": "John",
  
  
"lastName": "Doe",
  
  
"phone": "+1234567890",
  
  
"deliveryAddress": {
  
  
  
"street": "string",
  
  
  
"city": "string",
  
  
  
"zip": "string",
  
  
  
"country": "string",
  
  
  
"co": "string"
  
  
},
  
  
"billingAddress": {
  
  
  
"street": "string",
  
  
  
"city": "string",
  
  
  
"zip": "string",
  
  
  
"country": "string",
  
  
  
"co": "string"
  
  
},
  
  
"publisherPurchaseId": "pub_purchase_123",
  
  
"notes": "Bulk purchase",
  
  
"extraFields": {
  
  
  
"additionalProperties": "string"
  
  
},
  
  
"excludeFromStats": false
  
}
]

Playground​

Authorization
Variables
Key
Value

Samples​


POST /management/access-lists/{id}/grants​

POST
/management/access-lists/{id}/grants

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*

Access list ID

Type
string
Required
Example"src_123abc"

Request Body​

application/json
JSON
{
  
"email": "user@example.com",
  
"userId": "pub_user_123",
  
"publisherUserId": "pub_user_123",
  
"sku": "premium-article-123",
  
"poId": "po_123abc",
  
"status": "ACTIVE",
  
"startsAt": "2024-01-01T00:00:00Z",
  
"endsAt": "2024-12-31T23:59:59Z",
  
"firstName": "John",
  
"lastName": "Doe",
  
"phone": "+1234567890",
  
"deliveryAddress": {
  
  
"street": "string",
  
  
"city": "string",
  
  
"zip": "string",
  
  
"country": "string",
  
  
"co": "string"
  
},
  
"billingAddress": {
  
  
"street": "string",
  
  
"city": "string",
  
  
"zip": "string",
  
  
"country": "string",
  
  
"co": "string"
  
},
  
"publisherPurchaseId": "pub_purchase_123",
  
"notes": "Bulk purchase",
  
"extraFields": {
  
  
"additionalProperties": "string"
  
},
  
"excludeFromStats": false,
  
"source": "src_123abc"
}

Responses​

Grant created successfully

application/json
JSON
{
  
"id": "grant_123abc",
  
"source": "src_123abc",
  
"email": "user@example.com",
  
"userId": "pub_user_123",
  
"publisherUserId": "pub_user_123",
  
"sku": "premium-article-123",
  
"poId": "po_123abc",
  
"status": "ACTIVE",
  
"startsAt": "2024-01-01T00:00:00Z",
  
"endsAt": "2024-12-31T23:59:59Z",
  
"firstName": "John",
  
"lastName": "Doe",
  
"phone": "+1234567890",
  
"deliveryAddress": {
  
  
"street": "string",
  
  
"city": "string",
  
  
"zip": "string",
  
  
"country": "string",
  
  
"co": "string"
  
},
  
"billingAddress": {
  
  
"street": "string",
  
  
"city": "string",
  
  
"zip": "string",
  
  
"country": "string",
  
  
"co": "string"
  
},
  
"publisherPurchaseId": "pub_purchase_123",
  
"notes": "Bulk purchase",
  
"extraFields": {
  
  
"additionalProperties": "string"
  
},
  
"excludeFromStats": false
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


GET /management/access-lists/{id}/grants/{grantId}​

GET
/management/access-lists/{id}/grants/{grantId}

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*

Access list ID

Type
string
Required
Example"src_123abc"
grantId*

Grant (purchase) ID

Type
string
Required
Example"purchase_123abc"

Responses​

Retrieve a grant by ID

application/json
JSON
{
  
"id": "grant_123abc",
  
"source": "src_123abc",
  
"email": "user@example.com",
  
"userId": "pub_user_123",
  
"publisherUserId": "pub_user_123",
  
"sku": "premium-article-123",
  
"poId": "po_123abc",
  
"status": "ACTIVE",
  
"startsAt": "2024-01-01T00:00:00Z",
  
"endsAt": "2024-12-31T23:59:59Z",
  
"firstName": "John",
  
"lastName": "Doe",
  
"phone": "+1234567890",
  
"deliveryAddress": {
  
  
"street": "string",
  
  
"city": "string",
  
  
"zip": "string",
  
  
"country": "string",
  
  
"co": "string"
  
},
  
"billingAddress": {
  
  
"street": "string",
  
  
"city": "string",
  
  
"zip": "string",
  
  
"country": "string",
  
  
"co": "string"
  
},
  
"publisherPurchaseId": "pub_purchase_123",
  
"notes": "Bulk purchase",
  
"extraFields": {
  
  
"additionalProperties": "string"
  
},
  
"excludeFromStats": false
}

Playground​

Authorization
Variables
Key
Value

Samples​


PUT /management/access-lists/{id}/grants/{grantId}​

PUT
/management/access-lists/{id}/grants/{grantId}

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*

Access list ID

Type
string
Required
Example"src_123abc"
grantId*

Grant (purchase) ID

Type
string
Required
Example"purchase_123abc"

Request Body​

application/json
JSON
{
  
"email": "user@example.com",
  
"userId": "pub_user_123",
  
"publisherUserId": "pub_user_123",
  
"sku": "premium-article-123",
  
"poId": "po_123abc",
  
"status": "ACTIVE",
  
"startsAt": "2024-01-01T00:00:00Z",
  
"endsAt": "2024-12-31T23:59:59Z",
  
"firstName": "John",
  
"lastName": "Doe",
  
"phone": "+1234567890",
  
"deliveryAddress": {
  
  
"street": "string",
  
  
"city": "string",
  
  
"zip": "string",
  
  
"country": "string",
  
  
"co": "string"
  
},
  
"billingAddress": {
  
  
"street": "string",
  
  
"city": "string",
  
  
"zip": "string",
  
  
"country": "string",
  
  
"co": "string"
  
},
  
"publisherPurchaseId": "pub_purchase_123",
  
"notes": "Bulk purchase",
  
"extraFields": {
  
  
"additionalProperties": "string"
  
},
  
"excludeFromStats": false
}

Responses​

Grant updated successfully

application/json
JSON
{
  
"id": "grant_123abc",
  
"source": "src_123abc",
  
"email": "user@example.com",
  
"userId": "pub_user_123",
  
"publisherUserId": "pub_user_123",
  
"sku": "premium-article-123",
  
"poId": "po_123abc",
  
"status": "ACTIVE",
  
"startsAt": "2024-01-01T00:00:00Z",
  
"endsAt": "2024-12-31T23:59:59Z",
  
"firstName": "John",
  
"lastName": "Doe",
  
"phone": "+1234567890",
  
"deliveryAddress": {
  
  
"street": "string",
  
  
"city": "string",
  
  
"zip": "string",
  
  
"country": "string",
  
  
"co": "string"
  
},
  
"billingAddress": {
  
  
"street": "string",
  
  
"city": "string",
  
  
"zip": "string",
  
  
"country": "string",
  
  
"co": "string"
  
},
  
"publisherPurchaseId": "pub_purchase_123",
  
"notes": "Bulk purchase",
  
"extraFields": {
  
  
"additionalProperties": "string"
  
},
  
"excludeFromStats": false
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


DELETE /management/access-lists/{id}/grants/{grantId}​

DELETE
/management/access-lists/{id}/grants/{grantId}

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*

Access list ID

Type
string
Required
Example"src_123abc"
grantId*

Grant (purchase) ID

Type
string
Required
Example"purchase_123abc"

Responses​

Grant deleted successfully

Playground​

Authorization
Variables
Key
Value

Samples​


List all sites for the calling vendor​

GET
/management/sites

Returns every site with per-capability status. Each upstream is read once per vendor, so a vendor with 200 sites costs the same round-trips as one with a single site. A failing upstream degrades only its own capability to failed rather than failing the whole response.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Responses​

All sites registered under this vendor

application/json
JSON
[
  
{
  
  
"domain": "alingsasnytt.se",
  
  
"clientId": "alingsasnytt",
  
  
"loginDomain": "login.alingsasnytt.se",
  
  
"template": "string",
  
  
"sesamyJsVersion": "string",
  
  
"sesamyComponentsVersion": "string",
  
  
"capabilities": {
  
  
  
"scraper": {
  
  
  
  
"status": "string",
  
  
  
  
"active": true,
  
  
  
  
"brand": "string",
  
  
  
  
"error": "string"
  
  
  
},
  
  
  
"client": {
  
  
  
  
"status": "string",
  
  
  
  
"error": "string"
  
  
  
},
  
  
  
"auth": {
  
  
  
  
"status": "string",
  
  
  
  
"customDomain": "string",
  
  
  
  
"error": "string"
  
  
  
},
  
  
  
"capsule": {
  
  
  
  
"status": "string",
  
  
  
  
"error": "string"
  
  
  
}
  
  
},
  
  
"observedAt": "string"
  
}
]

Playground​

Authorization

Samples​


Get a single site​

GET
/management/sites/{domain}

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

domain*
Type
string
Required
Example"alingsasnytt.se"

Responses​

The site, with resolved content selectors and capsule config

application/json
JSON
{
  
"domain": "alingsasnytt.se",
  
"clientId": "alingsasnytt",
  
"loginDomain": "login.alingsasnytt.se",
  
"template": "string",
  
"sesamyJsVersion": "string",
  
"sesamyComponentsVersion": "string",
  
"capabilities": {
  
  
"scraper": {
  
  
  
"status": "string",
  
  
  
"active": true,
  
  
  
"brand": "string",
  
  
  
"error": "string"
  
  
},
  
  
"client": {
  
  
  
"status": "string",
  
  
  
"error": "string"
  
  
},
  
  
"auth": {
  
  
  
"status": "string",
  
  
  
"customDomain": "string",
  
  
  
"error": "string"
  
  
},
  
  
"capsule": {
  
  
  
"status": "string",
  
  
  
"error": "string"
  
  
}
  
},
  
"observedAt": "string",
  
"content": [
  
],
  
"jwksUri": "string",
  
"signingKeyPem": "string"
}

Playground​

Authorization
Variables
Key
Value

Samples​


Provision or update a site​

PUT
/management/sites/{domain}

Every block is optional and provisioning is strictly opt-in per capability — omitted blocks are left untouched. Legs run least-live-first (client → content → login domain → scrape origin) and each is attempted independently, so one failure does not abandon the rest. Returns 207 when some legs succeeded and others failed; retry should target only the failed ones.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

domain*
Type
string
Required
Example"alingsasnytt.se"

Request Body​

application/json
JSON
{
  
"scraper": {
  
  
"brand": "string",
  
  
"requestHeaders": {
  
  
  
"additionalProperties": "string"
  
  
},
  
  
"active": true
  
},
  
"auth": {
  
  
"customDomain": "login.alingsasnytt.se"
  
},
  
"content": {
  
  
"clientId": "string",
  
  
"template": "string",
  
  
"overrides": {
  
  
  
"selectors": {
  
  
  
  
"additionalProperties": {
  
  
  
  
  
"selector": "string",
  
  
  
  
  
"attribute": "string"
  
  
  
  
}
  
  
  
}
  
  
}
  
}
}

Responses​

All requested capabilities provisioned

application/json
JSON
{
  
"domain": "string",
  
"outcome": {
  
  
"additionalProperties": {
  
  
  
"status": "string",
  
  
  
"error": "string"
  
  
}
  
}
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


Delete a site​

DELETE
/management/sites/{domain}

Removes the site from every upstream it was provisioned into. Destructive and not reversible: the AuthHero client is deleted, so re-provisioning mints a new client_id and every end-user session and the installed snippet break with it. Prefer PUT with scraper.active: false to take a domain out of service. Legs run most-live-first (scrape origin -> capsule -> login domain -> content config -> client) and each is attempted independently, so a teardown that stops halfway leaves the site inert rather than scraped with a dead client. Only legs with something to remove are reported. The request carries no body, so a retry re-runs every applicable leg rather than a chosen subset; legs whose upstream resource is already absent report ok, so a retry after a partial teardown converges. Returns 207 when some legs failed and 502 when all did.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

domain*
Type
string
Required
Example"alingsasnytt.se"

Responses​

Every leg torn down

application/json
JSON
{
  
"domain": "string",
  
"outcome": {
  
  
"additionalProperties": {
  
  
  
"status": "string",
  
  
  
"error": "string"
  
  
}
  
}
}

Playground​

Authorization
Variables
Key
Value

Samples​


Get user diagnostics​

GET
/management/diagnostics/{identifier}

Retrieve diagnostics entries for a user by their user ID or fallback ID. Returns the most recent entries.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

identifier*

The user ID or fallback ID to fetch diagnostics for

Type
string
Required
Example"user_123"

Query Parameters

limit

Maximum number of entries to return (default: 10)

Type
string
Example"10"

Responses​

List of diagnostics entries

application/json
JSON
{
  
"items": [
  
  
{
  
  
  
"userId": "string",
  
  
  
"fallbackId": "string",
  
  
  
"timestamp": "string",
  
  
  
"pageUrl": "string",
  
  
  
"pageTitle": "string",
  
  
  
"profile": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"entitlements": [
  
  
  
  
{
  
  
  
  
  
"additionalProperties": "string"
  
  
  
  
}
  
  
  
],
  
  
  
"contracts": [
  
  
  
  
{
  
  
  
  
  
"additionalProperties": "string"
  
  
  
  
}
  
  
  
],
  
  
  
"tags": [
  
  
  
  
"string"
  
  
  
],
  
  
  
"tallies": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"browser": {
  
  
  
  
"userAgent": "string",
  
  
  
  
"platform": "string",
  
  
  
  
"language": "string",
  
  
  
  
"languages": [
  
  
  
  
  
"string"
  
  
  
  
],
  
  
  
  
"cookiesEnabled": true,
  
  
  
  
"onLine": true,
  
  
  
  
"hardwareConcurrency": 0,
  
  
  
  
"deviceMemory": 0,
  
  
  
  
"maxTouchPoints": 0,
  
  
  
  
"vendor": "string",
  
  
  
  
"viewportWidth": 0,
  
  
  
  
"viewportHeight": 0,
  
  
  
  
"screenWidth": 0,
  
  
  
  
"screenHeight": 0,
  
  
  
  
"pixelRatio": 0,
  
  
  
  
"colorDepth": 0,
  
  
  
  
"timezone": "string",
  
  
  
  
"timezoneOffset": 0
  
  
  
},
  
  
  
"detection": {
  
  
  
  
"adBlockEnabled": true,
  
  
  
  
"incognitoMode": true,
  
  
  
  
"inAppBrowser": true
  
  
  
},
  
  
  
"localStorage": [
  
  
  
  
{
  
  
  
  
  
"key": "string",
  
  
  
  
  
"value": "string",
  
  
  
  
  
"redacted": true
  
  
  
  
}
  
  
  
],
  
  
  
"sessionStorage": [
  
  
  
  
{
  
  
  
  
  
"key": "string",
  
  
  
  
  
"value": "string",
  
  
  
  
  
"redacted": true
  
  
  
  
}
  
  
  
],
  
  
  
"sdkVersion": "string",
  
  
  
"clientId": "string",
  
  
  
"errors": [
  
  
  
  
"string"
  
  
  
],
  
  
  
"storedAt": "string",
  
  
  
"requestId": "string"
  
  
}
  
],
  
"count": 0
}

Playground​

Authorization
Variables
Key
Value

Samples​


Delete user diagnostics​

DELETE
/management/diagnostics/{identifier}

Delete all diagnostics entries for a user by their user ID or fallback ID.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

identifier*

The user ID or fallback ID to delete diagnostics for

Type
string
Required
Example"user_123"

Responses​

Diagnostics deleted successfully

application/json
JSON
{
  
"success": true,
  
"deletedCount": 0
}

Playground​

Authorization
Variables
Key
Value

Samples​


Get a metric over time​

GET
/management/stats/series/{metric}

Returns one metric for the vendor across a date range: a headline figure plus a per-product daily series. Monetary values are in major units (e.g. kronor) with the currency named in currency.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

metric*

Which metric to return. One of: currentMrr, newMrr, churnMrr, projectedMrr, totalRevenue, totalSales, subscriptionSales, totalSubscribers.

Type
string
Required
Valid values
"currentMrr""newMrr""churnMrr""projectedMrr""totalRevenue""totalSales""subscriptionSales""totalSubscribers"
Example"currentMrr"

Query Parameters

fromDate*

Start of the date range, inclusive. ISO 8601 date (YYYY-MM-DD).

Type
string
Required
Example"2026-01-01"
Format
"date"
toDate*

End of the date range, inclusive. ISO 8601 date (YYYY-MM-DD).

Type
string
Required
Example"2026-03-31"
Format
"date"

Responses​

The metric over the requested range

application/json
JSON
{
  
"vendorId": "acme",
  
"metric": "currentMrr",
  
"dateRange": {
  
  
"fromDate": "2026-01-01",
  
  
"toDate": "2026-03-31"
  
},
  
"title": "string",
  
"description": "string",
  
"unit": "string",
  
"currency": "SEK",
  
"headline": 145680.35,
  
"series": [
  
  
{
  
  
  
"key": "ACME Plus",
  
  
  
"points": [
  
  
  
  
{
  
  
  
  
  
"date": "2026-01-01",
  
  
  
  
  
"value": 0
  
  
  
  
}
  
  
  
]
  
  
}
  
]
}

Playground​

Authorization
Variables
Key
Value

Samples​


Get purchases attributed to a tracking dimension​

GET
/management/stats/breakdown/{dimension}

Returns a checkout-attribution table for the vendor, grouped by one tracking dimension (UTM tags, referrer, or the content the visit came from). Each row carries sessions, users, transactions, conversion rate and revenue per currency. Rows whose purchases carried no value for the dimension have a null key.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

dimension*

Attribution dimension to group by. One of: utm_source, utm_medium, utm_campaign, utm_content, utm_source_medium, referrer, item_source, section, tag, author.

Type
string
Required
Valid values
"utm_source""utm_medium""utm_campaign""utm_content""utm_source_medium""referrer""item_source""section""tag""author"
Example"utm_source"

Query Parameters

fromDate*

Start of the date range, inclusive. ISO 8601 date (YYYY-MM-DD).

Type
string
Required
Example"2026-01-01"
Format
"date"
toDate*

End of the date range, inclusive. ISO 8601 date (YYYY-MM-DD).

Type
string
Required
Example"2026-03-31"
Format
"date"
subset

Which purchases to report on: all, subscriptions (recurring only) or single (one-off only).

Type
string
Valid values
"all""subscriptions""single"
Example"all"
Default
"all"
limit

Maximum rows to return, highest revenue first. Defaults to 100, maximum 1000. The response flags whether rows were dropped.

Type
integer
Example100
Minimum
0
Exclusive Minimum
true
Maximum
1000
Default
100

Responses​

The attribution breakdown for the requested range

application/json
JSON
{
  
"vendorId": "acme",
  
"dimension": "utm_source",
  
"subset": "all",
  
"dateRange": {
  
  
"fromDate": "2026-01-01",
  
  
"toDate": "2026-03-31"
  
},
  
"title": "string",
  
"description": "string",
  
"rows": [
  
  
{
  
  
  
"key": "newsletter",
  
  
  
"label": "newsletter",
  
  
  
"sessions": 0,
  
  
  
"users": 0,
  
  
  
"transactions": 0,
  
  
  
"conversionRate": 21.59,
  
  
  
"revenue": {
  
  
  
  
"additionalProperties": 0
  
  
  
},
  
  
  
"meta": {
  
  
  
  
"additionalProperties": "string"
  
  
  
}
  
  
}
  
],
  
"totals": {
  
  
"sessions": 0,
  
  
"users": 0,
  
  
"transactions": 0,
  
  
"revenue": {
  
  
  
"additionalProperties": 0
  
  
}
  
},
  
"rowCount": 0,
  
"truncated": true
}

Playground​

Authorization
Variables
Key
Value

Samples​


List the available metrics and dimensions​

GET
/management/stats/catalogue

Returns every metric /series/{metric} accepts and every dimension /breakdown/{dimension} accepts, with a title and description for each. Static — it makes no upstream call — so a client can discover the surface instead of hard-coding it.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Responses​

The metrics and dimensions this API exposes

application/json
JSON
{
  
"metrics": [
  
  
{
  
  
  
"key": "string",
  
  
  
"title": "string",
  
  
  
"description": "string",
  
  
  
"unit": "string"
  
  
}
  
],
  
"dimensions": [
  
  
{
  
  
  
"key": "string",
  
  
  
"title": "string",
  
  
  
"description": "string"
  
  
}
  
]
}

Playground​

Authorization

Samples​


List report types​

GET
/management/report-types

The reports you can create, with the parameters each one takes. Use a type id as typeId when you create a report.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Responses​

The report types

application/json
JSON
{
  
"items": [
  
  
{
  
  
  
"id": "transactions_report",
  
  
  
"name": "Transactions",
  
  
  
"description": "string",
  
  
  
"category": "Finance",
  
  
  
"parameters": [
  
  
  
  
{
  
  
  
  
  
"name": "groupBy",
  
  
  
  
  
"label": "Group by",
  
  
  
  
  
"description": "Summarise the rows instead of listing them one by one.",
  
  
  
  
  
"type": "string",
  
  
  
  
  
"isRequired": true,
  
  
  
  
  
"options": [
  
  
  
  
  
  
{
  
  
  
  
  
  
  
"value": "string",
  
  
  
  
  
  
  
"label": "string"
  
  
  
  
  
  
}
  
  
  
  
  
],
  
  
  
  
  
"default": "string"
  
  
  
  
}
  
  
  
],
  
  
  
"documentation": {
  
  
  
  
"businessPurpose": "string",
  
  
  
  
"grain": "One active contract at the date",
  
  
  
  
"columns": [
  
  
  
  
  
{
  
  
  
  
  
  
"name": "string",
  
  
  
  
  
  
"description": "string"
  
  
  
  
  
}
  
  
  
  
],
  
  
  
  
"caveats": [
  
  
  
  
  
"string"
  
  
  
  
],
  
  
  
  
"exampleQuestions": [
  
  
  
  
  
"string"
  
  
  
  
]
  
  
  
}
  
  
}
  
],
  
"nextCursor": "string"
}

Playground​

Authorization

Samples​


Get a report type​

GET
/management/report-types/{id}

One report type with its parameters and, where written, documentation: what the report answers, what a row stands for and what each column of the file means.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"transactions_report"

Responses​

The report type

application/json
JSON
{
  
"id": "transactions_report",
  
"name": "Transactions",
  
"description": "string",
  
"category": "Finance",
  
"parameters": [
  
  
{
  
  
  
"name": "groupBy",
  
  
  
"label": "Group by",
  
  
  
"description": "Summarise the rows instead of listing them one by one.",
  
  
  
"type": "string",
  
  
  
"isRequired": true,
  
  
  
"options": [
  
  
  
  
{
  
  
  
  
  
"value": "string",
  
  
  
  
  
"label": "string"
  
  
  
  
}
  
  
  
],
  
  
  
"default": "string"
  
  
}
  
],
  
"documentation": {
  
  
"businessPurpose": "string",
  
  
"grain": "One active contract at the date",
  
  
"columns": [
  
  
  
{
  
  
  
  
"name": "string",
  
  
  
  
"description": "string"
  
  
  
}
  
  
],
  
  
"caveats": [
  
  
  
"string"
  
  
],
  
  
"exampleQuestions": [
  
  
  
"string"
  
  
]
  
}
}

Playground​

Authorization
Variables
Key
Value

Samples​


List reports​

GET
/management/reports

The reports you have created, most recently updated first.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Query Parameters

typeId

Only reports of this report type

Type
string
Example"transactions_report"

Responses​

The reports

application/json
JSON
{
  
"items": [
  
  
{
  
  
  
"id": "9b2c6f0e4d1a8b7c3e5f2a1d0c9b8a7e",
  
  
  
"typeId": "transactions_report",
  
  
  
"name": "Transactions",
  
  
  
"status": "string",
  
  
  
"parameters": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"downloadUrl": "string",
  
  
  
"downloadUrlExpiresAt": "string",
  
  
  
"createdAt": "string",
  
  
  
"updatedAt": "string"
  
  
}
  
],
  
"nextCursor": "string"
}

Playground​

Authorization
Variables
Key
Value

Samples​


Create a report​

POST
/management/reports

Asks for a report of a type with the given parameters. The same type and parameters always give the same report, so asking again is safe: you get the existing report back, and one that FAILED is run again. A report that is ready is returned with 200. Otherwise the answer is 202 with the report PENDING or PROCESSING; poll the Location until it is COMPLETED.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Request Body​

application/json
JSON
{
  
"typeId": "transactions_report",
  
"parameters": {
  
  
"additionalProperties": "string"
  
}
}

Responses​

The report, already generated

application/json
JSON
{
  
"id": "9b2c6f0e4d1a8b7c3e5f2a1d0c9b8a7e",
  
"typeId": "transactions_report",
  
"name": "Transactions",
  
"status": "string",
  
"parameters": {
  
  
"additionalProperties": "string"
  
},
  
"downloadUrl": "string",
  
"downloadUrlExpiresAt": "string",
  
"createdAt": "string",
  
"updatedAt": "string"
}

Playground​

Authorization
Body

Samples​


Get a report​

GET
/management/reports/{id}

Poll this until status is COMPLETED, then download the file from downloadUrl. Reading the report again gives a fresh link.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"9b2c6f0e4d1a8b7c3e5f2a1d0c9b8a7e"

Responses​

The report

application/json
JSON
{
  
"id": "9b2c6f0e4d1a8b7c3e5f2a1d0c9b8a7e",
  
"typeId": "transactions_report",
  
"name": "Transactions",
  
"status": "string",
  
"parameters": {
  
  
"additionalProperties": "string"
  
},
  
"downloadUrl": "string",
  
"downloadUrlExpiresAt": "string",
  
"createdAt": "string",
  
"updatedAt": "string"
}

Playground​

Authorization
Variables
Key
Value

Samples​


Links​


Create a signed link for content access​

POST
/management/create-signed-link

Creates a signed token that grants access to encrypted content. Optionally appends it to a URL. Use for share links, email campaigns, gift access, or temporary tier access.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Request Body​

application/json
JSON
{
  
"url": "https://example.com/article/123",
  
"sku": "premium-subscription",
  
"scopes": [
  
  
[
  
  
  
"url:acme-article-hash"
  
  
]
  
],
  
"purchaseOption": "monthly",
  
"publisherContentId": "article-2024-01-15-news",
  
"userId": "user-456",
  
"maxUses": 1000,
  
"expiresIn": "7d",
  
"meta": {
  
  
"additionalProperties": "string"
  
}
}

Responses​

The signed link/token

application/json
JSON
{
  
"signedUrl": "string",
  
"token": "string",
  
"tokenId": "string",
  
"expiresAt": "string",
  
"sku": "string",
  
"scopes": [
  
  
"string"
  
],
  
"publisherContentId": "string"
}

Playground​

Authorization
Body

Samples​


List trusted publisher domains for the calling vendor​

GET
/management/domains

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Responses​

All trusted publisher domains registered under this vendor

application/json
JSON
{
  
"domains": [
  
  
{
  
  
  
"domain": "string",
  
  
  
"signingKeyPem": "string",
  
  
  
"jwksUri": "string",
  
  
  
"allowedResourceIds": [
  
  
  
  
"string"
  
  
  
],
  
  
  
"signingKeyKids": [
  
  
  
  
"string"
  
  
  
],
  
  
  
"keysRefreshedAt": "string",
  
  
  
"createdAt": "string",
  
  
  
"updatedAt": "string",
  
  
  
"updatedBy": "string"
  
  
}
  
]
}

Playground​

Authorization

Samples​


Get a single trusted publisher domain​

GET
/management/domains/{domain}

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

domain*

Publisher domain (lowercase, no scheme, no trailing dot)

Type
string
Required
Example"example.wordpress.com"

Responses​

The trusted publisher domain entry

application/json
JSON
{
  
"domain": "string",
  
"signingKeyPem": "string",
  
"jwksUri": "string",
  
"allowedResourceIds": [
  
  
"string"
  
],
  
"signingKeyKids": [
  
  
"string"
  
],
  
"keysRefreshedAt": "string",
  
"createdAt": "string",
  
"updatedAt": "string",
  
"updatedBy": "string"
}

Playground​

Authorization
Variables
Key
Value

Samples​


Register or update a trusted publisher domain​

PUT
/management/domains/{domain}

Upserts a trusted publisher domain entry under the calling vendor. Provide exactly one of signingKeyPem (pinned ES256) or jwksUri (HTTPS URL whose hostname matches {domain}). Idempotent: re-registration replaces the entry and advances updatedAt.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

domain*

Publisher domain (lowercase, no scheme, no trailing dot)

Type
string
Required
Example"example.wordpress.com"

Request Body​

application/json
JSON
{
  
"signingKeyPem": "string",
  
"jwksUri": "string",
  
"allowedResourceIds": [
  
  
"string"
  
]
}

Responses​

Domain updated

application/json
JSON
{
  
"domain": "string",
  
"signingKeyPem": "string",
  
"jwksUri": "string",
  
"allowedResourceIds": [
  
  
"string"
  
],
  
"signingKeyKids": [
  
  
"string"
  
],
  
"keysRefreshedAt": "string",
  
"createdAt": "string",
  
"updatedAt": "string",
  
"updatedBy": "string",
  
"probe": {
  
  
"ok": true,
  
  
"activeKeys": 0,
  
  
"error": "string"
  
}
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


Remove a trusted publisher domain​

DELETE
/management/domains/{domain}

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

domain*

Publisher domain (lowercase, no scheme, no trailing dot)

Type
string
Required
Example"example.wordpress.com"

Responses​

Domain removed (or did not exist)

Playground​

Authorization
Variables
Key
Value

Samples​


Powered by VitePress OpenAPI

Released under the MIT License.