OpenAPI Specification

v1.0.0

API

Download OpenAPI Document

JSON

Download OpenAPI Document

YAML

Servers

https://api2.sesamy.comCurrent environment

---

contracts

Operations

GET/contractsGET/contracts/{contract_id}POST/contracts/{contract_id}/cancelPOST/contracts/{contract_id}/amendmentsPOST/contracts/{contract_id}/amendments/{amendment_id}/confirm

---

List all contracts

GET

/contracts

Retrieves all contracts for the current user. Includes subscription plans and one-time purchases with active entitlements.

Authorizations

OpenID

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

Responses

A list of the user's contracts

Content-Type

application/json

[

{

"id": "1d78271264b9c76d5842911dd70b4353",

"name": "string",

"userId": "string",

"createdAt": "string",

"updatedAt": "string",

"price": 0,

"nextBillAt": "string",

"nextPrice": 0,

"currency": "string",

"manageUrl": "string",

"contractDuration": "string",

"issuesRemaining": 0,

"items": [

{

"sku": "string",

"purchaseOptionId": "string",

"purchaseOptionName": "string",

"name": "string",

"cover": "string",

"purchaseType": "string"

}

],

"status": "string",

"isActive": true,

"recurringInterval": "string",

"recurringTime": 0,

"willCancelAt": "string",

"expiresAt": "string",

"paymentData": {

"method": "string",

"description": "string",

"brand": "string"

},

"appliedDiscounts": [

{

"code": "string",

"name": "string",

"description": "string",

"id": "string"

}

]

}

]

GET

/contracts

Playground

Authorization

OpenID

Samples

cURL

JavaScript

PHP

Python

---

Get a contract by ID

GET

/contracts/{contract_id}

Retrieves a specific contract by its unique identifier.

Authorizations

OpenID

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

Parameters

Path Parameters

contract_id*

The unique identifier of the contract

Typestring

Required

Example"1d78271264b9c76d5842911dd70b4353"

Responses

The requested contract

Content-Type

application/json

{

"id": "1d78271264b9c76d5842911dd70b4353",

"name": "string",

"userId": "string",

"createdAt": "string",

"updatedAt": "string",

"price": 0,

"nextBillAt": "string",

"nextPrice": 0,

"currency": "string",

"manageUrl": "string",

"contractDuration": "string",

"issuesRemaining": 0,

"items": [

{

"sku": "string",

"purchaseOptionId": "string",

"purchaseOptionName": "string",

"name": "string",

"cover": "string",

"purchaseType": "string"

}

],

"status": "string",

"isActive": true,

"recurringInterval": "string",

"recurringTime": 0,

"willCancelAt": "string",

"expiresAt": "string",

"paymentData": {

"method": "string",

"description": "string",

"brand": "string"

},

"appliedDiscounts": [

{

"code": "string",

"name": "string",

"description": "string",

"id": "string"

}

]

}

GET

/contracts/{contract_id}

Playground

Authorization

OpenID

Variables

Key

Value

contract_id*

Samples

cURL

JavaScript

PHP

Python

---

Cancel a contract

POST

/contracts/{contract_id}/cancel

Cancels a specific contract. For subscriptions, this typically means they will not renew at the end of the current billing period.

Authorizations

OpenID

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

Parameters

Path Parameters

contract_id*

The unique identifier of the contract

Typestring

Required

Example"1d78271264b9c76d5842911dd70b4353"

Responses

Contract cancelled successfully

Content-Type

application/json

{

"success": true

}

POST

/contracts/{contract_id}/cancel

Playground

Authorization

OpenID

Variables

Key

Value

contract_id*

Samples

cURL

JavaScript

PHP

Python

---

Create an amendment

POST

/contracts/{contract_id}/amendments

Creates a new amendment for a contract, such as applying a discount code.

Authorizations

OpenID

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

Parameters

Path Parameters

contract_id*

The unique identifier of the contract

Typestring

Required

Example"1d78271264b9c76d5842911dd70b4353"

Request Body

application/json

{

"type": "string",

"discountCode": "string"

}

Responses

The created amendment

Content-Type

application/json

{

"id": "string",

"contractId": "string",

"status": "string",

"appliedDiscounts": [

{

"code": "string",

"status": "string",

"id": "string",

"name": "string",

"description": "string"

}

],

"amendmentType": "string",

"nextBill": {

"total": 0,

"currency": "string",

"date": "string"

}

}

POST

/contracts/{contract_id}/amendments

Playground

Authorization

OpenID

Variables

Key

Value

contract_id*

Body

Samples

cURL

JavaScript

PHP

Python

---

Confirm an amendment

POST

/contracts/{contract_id}/amendments/{amendment_id}/confirm

Confirms a pending amendment for a contract.

Authorizations

OpenID

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

Parameters

Path Parameters

contract_id*

The unique identifier of the contract

Typestring

Required

Example"1d78271264b9c76d5842911dd70b4353"

amendment_id*

The unique identifier of the amendment

Typestring

Required

Example"amendment123"

Responses

Amendment confirmed successfully

Content-Type

application/json

{

"success": true

}

POST

/contracts/{contract_id}/amendments/{amendment_id}/confirm

Playground

Authorization

OpenID

Variables

Key

Value

contract_id*

amendment_id*

Samples

cURL

JavaScript

PHP

Python

---

bills

Operations

GET/billsGET/bills/{id}

---

List all bills

GET

/bills

Retrieves all bills for the current user, excluding draft and expired bills. Results are sorted by creation date (newest first).

Authorizations

OpenID

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

Responses

A list of the user's bills

Content-Type

application/json

[

{

"id": "1d78271264b9c76d5842911dd70b4353",

"items": [

{

"sku": "string",

"title": "string",

"purchaseOptionId": "string"

}

],

"price": 0,

"currency": "string",

"receiptUrl": "string",

"paymentProvider": "string",

"paymentMethod": "string",

"status": "string",

"updatedAt": "string",

"createdAt": "string"

}

]

GET

/bills

Playground

Authorization

OpenID

Samples

cURL

JavaScript

PHP

Python

---

Get a bill by ID

GET

/bills/{id}

Retrieves a specific bill by its unique identifier.

Authorizations

OpenID

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

Parameters

Path Parameters

id*

The unique identifier of the bill

Typestring

Required

Example"1d78271264b9c76d5842911dd70b4353"

Responses

The requested bill

Content-Type

application/json

{

"id": "1d78271264b9c76d5842911dd70b4353",

"items": [

{

"sku": "string",

"title": "string",

"purchaseOptionId": "string"

}

],

"price": 0,

"currency": "string",

"receiptUrl": "string",

"paymentProvider": "string",

"paymentMethod": "string",

"status": "string",

"updatedAt": "string",

"createdAt": "string"

}

GET

/bills/{id}

Playground

Authorization

OpenID

Variables

Key

Value

id*

Samples

cURL

JavaScript

PHP

Python

---

entitlements

Operations

GET/entitlementsGET/entitlements/{id}GET/entitlements/{id}/access

---

List all entitlements

GET

/entitlements

Retrieves all entitlements for the current user with optional filtering by type, SKU, or purchase option ID.

Authorizations

OpenID

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

Parameters

Query Parameters

type

Typestring

Valid values

"article""audiobook""ebook""bundle""podcast""pass""publication""physical_issue"

Example"article"

sku

Typestring

Example"premium-article-123"

purchase-option-id

Typestring

Example"one-time"

wait-for-entitlement-after

If specified the api will wait until an entitlement after this timestamp is available before it returns

Typestring

Example"2023-01-01T00:00:00Z"

Responses

A list of the user's entitlements

Content-Type

application/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,

"createdAt": "string",

"updatedAt": "string",

"token": "string",

"expiresAt": "string"

}

]

GET

/entitlements

Playground

Authorization

OpenID

Variables

Key

Value

type

sku

purchase-option-id

wait-for-entitlement-after

Samples

cURL

JavaScript

PHP

Python

---

Get an entitlement by ID

GET

/entitlements/{id}

Retrieves a specific entitlement by its unique identifier.

Authorizations

OpenID

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

Parameters

Path Parameters

id*

The unique identifier of the entitlement

Typestring

Required

Example"1d78271264b9c76d5842911dd70b4353"

Responses

The requested entitlement

Content-Type

application/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,

"createdAt": "string",

"updatedAt": "string",

"token": "string",

"expiresAt": "string"

}

GET

/entitlements/{id}

Playground

Authorization

OpenID

Variables

Key

Value

id*

Samples

cURL

JavaScript

PHP

Python

---

Get access information for an entitlement

GET

/entitlements/{id}/access

Retrieves access information (URL and token) for a specific entitlement. The access type (URL or RSS) is determined based on the entitlement type.

Authorizations

OpenID

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

Parameters

Path Parameters

id*

The unique identifier of the entitlement

Typestring

Required

Example"1d78271264b9c76d5842911dd70b4353"

Responses

Access information for the entitlement

Content-Type

application/json

{

"id": "string",

"url": "string",

"token": "string",

"title": "string",

"filename": "string",

"type": "string"

}

GET

/entitlements/{id}/access

Playground

Authorization

OpenID

Variables

Key

Value

id*

Samples

cURL

JavaScript

PHP

Python

---

transactions

Operations

GET/transactions

---

List transactions

GET

/transactions

Retrieves all transactions for the current user, with optional filtering by search query.

Authorizations

OpenID

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

Parameters

Query Parameters

q

Typestring

Example"premium"

Responses

A list of the user's transactions

Content-Type

application/json

[

{

"id": "1d78271264b9c76d5842911dd70b4353",

"amount": 0,

"currency": "string",

"contractId": "string",

"isRefund": true,

"userId": "string",

"billId": "string",

"updatedAt": "string",

"createdAt": "string"

}

]

GET

/transactions

Playground

Authorization

OpenID

Variables

Key

Value

q

Samples

cURL

JavaScript

PHP

Python

---

subscriptions

Operations

GET/subscriptionsGET/subscriptions/{id}

---

List subscriptions

GET

/subscriptions

Retrieves all subscriptions for the current user. This includes both active and canceled subscriptions.

Authorizations

OpenID

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

Responses

A list of the user's subscriptions

Content-Type

application/json

[

{

"id": "string",

"currency": "string",

"cancelAt": "string",

"createdAt": "string",

"status": "string",

"product": {

"name": "string",

"description": "string",

"image": "string",

"optionId": "string",

"sku": "string"

},

"totalIssues": 0,

"remainingIssues": 0,

"price": 0,

"nextPrice": 0,

"nextPaymentAt": "string",

"hasAccess": true,

"manageUrl": "string",

"userId": "string"

}

]

GET

/subscriptions

Playground

Authorization

OpenID

Samples

cURL

JavaScript

PHP

Python

---

Get a subscription by ID

GET

/subscriptions/{id}

Retrieves a specific subscription by its unique identifier.

Authorizations

OpenID

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

Parameters

Path Parameters

id*

The unique identifier of the subscription

Typestring

Required

Example"1d78271264b9c76d5842911dd70b4353"

Responses

The requested subscription

Content-Type

application/json

{

"id": "string",

"currency": "string",

"cancelAt": "string",

"createdAt": "string",

"status": "string",

"product": {

"name": "string",

"description": "string",

"image": "string",

"optionId": "string",

"sku": "string"

},

"totalIssues": 0,

"remainingIssues": 0,

"price": 0,

"nextPrice": 0,

"nextPaymentAt": "string",

"hasAccess": true,

"manageUrl": "string",

"userId": "string"

}

GET

/subscriptions/{id}

Playground

Authorization

OpenID

Variables

Key

Value

id*

Samples

cURL

JavaScript

PHP

Python

---

user-metadata

Operations

GET/user-metadataPUT/user-metadata/{id}DELETE/user-metadata/{id}

---

Get all user metadata

GET

/user-metadata

Retrieves all metadata entries for the current user.

Authorizations

OpenID

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

Responses

Object with metadata key-value pairs

Content-Type

application/json

{

"additionalProperties": "string"

}

GET

/user-metadata

Playground

Authorization

OpenID

Samples

cURL

JavaScript

PHP

Python

---

Set user metadata value

PUT

/user-metadata/{id}

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

Authorizations

OpenID

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

Parameters

Path Parameters

id*

The key of the metadata entry

Typestring

Required

Example"preferences"

Request Body

text/plain

"string"

Responses

Metadata value set successfully

Content-Type

application/json

{

"success": true

}

PUT

/user-metadata/{id}

Playground

Authorization

OpenID

Variables

Key

Value

id*

Body

Samples

cURL

JavaScript

PHP

Python

---

Delete user metadata value

DELETE

/user-metadata/{id}

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

Authorizations

OpenID

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

Parameters

Path Parameters

id*

The key of the metadata entry

Typestring

Required

Example"preferences"

Responses

Metadata value deleted successfully

Content-Type

application/json

{

"success": true

}

DELETE

/user-metadata/{id}

Playground

Authorization

OpenID

Variables

Key

Value

id*

Samples

cURL

JavaScript

PHP

Python

---

tallies

Operations

GET/talliesGET/tallies/{id}PUT/tallies/{id}POST/tallies/{id}/push

---

List all tallies

GET

/tallies

Retrieve all tallies for the authenticated user.

Authorizations

Basic

TypeHTTP (basic)

+

OpenID

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

Responses

A record of tallies where keys are tally IDs and values are the tally values

Content-Type

application/json

{

"additionalProperties": [

]

}

GET

/tallies

Playground

Authorization

Basic

OpenID

Samples

cURL

JavaScript

PHP

Python

---

Get a tally by ID

GET

/tallies/{id}

Retrieve a specific tally by its ID for the authenticated user.

Authorizations

Basic

TypeHTTP (basic)

+

OpenID

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

Parameters

Path Parameters

id*

Typestring

Required

Example"test"

Responses

The tally value for the specified ID

Content-Type

application/json

[

"string"

]

GET

/tallies/{id}

Playground

Authorization

Basic

OpenID

Variables

Key

Value

id*

Samples

cURL

JavaScript

PHP

Python

---

Update a tally

PUT

/tallies/{id}

Set a tally to a new value for the authenticated user.

Authorizations

Basic

TypeHTTP (basic)

+

OpenID

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

Parameters

Path Parameters

id*

Typestring

Required

Example"test"

Request Body

application/json

{

"value": "string",

"policies": {

"ttl": 0,

"maxItems": 0,

"unique": true,

"overflow": "string",

"ipSessionSharing": true

}

}

Responses

The updated tally object

Content-Type

application/json

{

"id": "string",

"value": [

"string"

],

"policies": {

"ttl": 0,

"maxItems": 0,

"unique": true,

"overflow": "string",

"ipSessionSharing": true

},

"createdAt": "string",

"updatedAt": "string",

"expiresAt": "string"

}

PUT

/tallies/{id}

Playground

Authorization

Basic

OpenID

Variables

Key

Value

id*

Body

Samples

cURL

JavaScript

PHP

Python

---

Push value to tally

POST

/tallies/{id}/push

Add a new value to an existing tally list for the authenticated user.

Authorizations

Basic

TypeHTTP (basic)

+

OpenID

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

Parameters

Path Parameters

id*

Typestring

Required

Example"test"

Request Body

application/json

{

"value": "string",

"policies": {

"ttl": 0,

"maxItems": 0,

"unique": true,

"overflow": "string",

"ipSessionSharing": true

}

}

Responses

The updated tally value after pushing the new value

Content-Type

application/json

[

"string"

]

POST

/tallies/{id}/push

Playground

Authorization

Basic

OpenID

Variables

Key

Value

id*

Body

Samples

cURL

JavaScript

PHP

Python

---

fulfillments

Operations

GET/fulfillmentsPOST/fulfillments/{id}/request-delivery

---

List fulfillments

GET

/fulfillments

Retrieves all fulfillments for a specific SKU. Useful for tracking delivery status of physical items.

Authorizations

OpenID

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

Parameters

Query Parameters

sku*

Typestring

Required

Example"magazine-april-2023"

Responses

A list of user's fulfillments for the requested SKU

Content-Type

application/json

[

{

"status": "string",

"updatedAt": "string",

"createdAt": "string",

"deliversAt": "string",

"sku": "string",

"title": "string",

"id": "string",

"cover": "string",

"numericId": 0,

"deliveryProvider": "string",

"itemId": "string",

"copies": 0

}

]

GET

/fulfillments

Playground

Authorization

OpenID

Variables

Key

Value

sku*

Samples

cURL

JavaScript

PHP

Python

---

Request delivery for a fulfillment item

POST

/fulfillments/{id}/request-delivery

Request a new delivery for a specific fulfillment item by ID and SKU.

Authorizations

OpenID

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

Parameters

Path Parameters

id*

The fulfillment item ID

Typestring

Required

Example"item123"

Request Body

application/json

{

"sku": "magazine-april-2023"

}

Responses

Delivery request result

Content-Type

application/json

{

"ok": true

}

POST

/fulfillments/{id}/request-delivery

Playground

Authorization

OpenID

Variables

Key

Value

id*

Body

Samples

cURL

JavaScript

PHP

Python

---

tags

Operations

GET/tagsPOST/tagsDELETE/tags/{tag}

---

List user tags

GET

/tags

Retrieve all tags associated with the authenticated user.

Authorizations

OpenID

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

Responses

Array of user tags

Content-Type

application/json

[

"string"

]

GET

/tags

Playground

Authorization

OpenID

Samples

cURL

JavaScript

PHP

Python

---

Add a tag

POST

/tags

Add a new tag to the authenticated user.

Authorizations

OpenID

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

Request Body

text/plain

"premium"

Responses

Confirmation that the tag was added

Content-Type

application/json

"string"

POST

/tags

Playground

Authorization

OpenID

Body

Samples

cURL

JavaScript

PHP

Python

---

Delete a tag

DELETE

/tags/{tag}

Remove a tag from the authenticated user.

Authorizations

OpenID

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

Parameters

Path Parameters

tag*

Typestring

Required

Example"premium"

Responses

Confirmation that the tag was deleted

Content-Type

application/json

"string"

DELETE

/tags/{tag}

Playground

Authorization

OpenID

Variables

Key

Value

tag*

Samples

cURL

JavaScript

PHP

Python

---

profile

Operations

GET/profileDELETE/profilePATCH/profileGET/profile/spotify-linkPOST/profile/unlink-spotify

---

Get user profile

GET

/profile

Retrieves the authenticated user's profile information.

Authorizations

OpenID

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

Responses

The user's profile information

Content-Type

application/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",

"company": "string",

"sub": "string",

"given_name": "string",

"family_name": "string",

"phone_number": "string"

}

GET

/profile

Playground

Authorization

OpenID

Samples

cURL

JavaScript

PHP

Python

---

Delete own profile

DELETE

/profile

Allows the authenticated user to delete their own account. This action is irreversible.

Authorizations

OpenID

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

Responses

Profile deleted successfully

Content-Type

application/json

{

"success": true

}

DELETE

/profile

Playground

Authorization

OpenID

Samples

cURL

JavaScript

PHP

Python

---

Update user profile

PATCH

/profile

Updates the authenticated user's profile information with the provided data.

Authorizations

OpenID

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

Request Body

application/json

{

"firstName": "John",

"lastName": "Doe",

"nickname": "Johnny",

"mobilePhone": "+1234567890",

"workPhone": "+1234567891",

"homePhone": "+1234567892",

"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"

},

"given_name": "string",

"family_name": "string",

"phone_number": "string"

}

Responses

The updated user profile

Content-Type

application/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",

"company": "string",

"sub": "string",

"given_name": "string",

"family_name": "string",

"phone_number": "string"

}

PATCH

/profile

Playground

Authorization

OpenID

Body

Samples

cURL

JavaScript

PHP

Python

---

Check Spotify link status

GET

/profile/spotify-link

Checks if the user has connected their Spotify account.

Authorizations

OpenID

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

Responses

Spotify link status

Content-Type

application/json

{

"isSpotifyLinked": true

}

GET

/profile/spotify-link

Playground

Authorization

OpenID

Samples

cURL

JavaScript

PHP

Python

---

Unlink Spotify account

POST

/profile/unlink-spotify

Unlinks the user's connected Spotify account from their profile.

Authorizations

OpenID

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

Responses

Spotify account unlinked successfully

Content-Type

application/json

{

"success": true

}

POST

/profile/unlink-spotify

Playground

Authorization

OpenID

Samples

cURL

JavaScript

PHP

Python

---

products

Operations

GET/products/{sku}POST/products/{sku}/auto-onboard

---

Get a product by SKU

GET

/products/{sku}

Retrieves a specific product by its unique SKU identifier.

Authorizations

OpenID

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

Parameters

Path Parameters

sku*

The unique stock keeping unit (SKU) identifier of the product

Typestring

Required

Example"sid:PRVc_h8FIgR2ntoZh9SNu"

Responses

The requested product

Content-Type

application/json

{

"cover": "string",

"language": "string",

"createdAt": "string",

"updatedAt": "string",

"sku": "string",

"title": "string",

"productType": "string",

"publisherContentId": "string"

}

GET

/products/{sku}

Playground

Authorization

OpenID

Variables

Key

Value

sku*

Samples

cURL

JavaScript

PHP

Python

---

Auto-onboard a product

POST

/products/{sku}/auto-onboard

Triggers the auto-onboarding process for a product. This typically grants additional entitlements based on external systems when supported by the product.

Authorizations

OpenID

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

Parameters

Path Parameters

sku*

The unique stock keeping unit (SKU) identifier of the product

Typestring

Required

Example"sid:PRVc_h8FIgR2ntoZh9SNu"

Responses

The entitlements returned from the auto-onboard process

Content-Type

application/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,

"createdAt": "string",

"updatedAt": "string",

"token": "string",

"expiresAt": "string"

}

]

POST

/products/{sku}/auto-onboard

Playground

Authorization

OpenID

Variables

Key

Value

sku*

Samples

cURL

JavaScript

PHP

Python

---

payment-issues

Operations

GET/payment-issues

---

List payment issues

GET

/payment-issues

Retrieves all payment issues for the current user. This includes overdue payments and expired payment methods.

Authorizations

OpenID

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

Responses

A list of the user's payment issues

Content-Type

application/json

[

{

"contractId": "1d78271264b9c76d5842911dd70b4353",

"createdAt": "string",

"updatedAt": "string",

"nextPaymentAt": "string",

"manageUrl": "string",

"status": "string"

}

]

GET

/payment-issues

Playground

Authorization

OpenID

Samples

cURL

JavaScript

PHP

Python

---

content

Operations

GET/proxy

---

Proxy content

GET

/proxy

Proxies content from supported providers, optionally extracting specific elements.

Authorizations

OpenID

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

Parameters

Query Parameters

url*

Typestring

Required

Example"https://www.example.com/article"

selector

Typestring

Example".article-content"

cache

Typestring

Example"true"

Responses

The unlocked content

Content-Type

text/html

"string"

GET

/proxy

Playground

Authorization

OpenID

Variables

Key

Value

url*

selector

cache

Samples

cURL

JavaScript

PHP

Python

---

checkouts

Operations

POST/checkoutsGET/checkouts/{id}PATCH/checkouts/{id}

---

Create a checkout

POST

/checkouts

Creates a new checkout session with the specified items and settings.

Authorizations

Basic

TypeHTTP (basic)

+

OpenID

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

Request Body

application/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",

"itemSrc": "string",

"publisherContentId": "string",

"_ga": "string",

"_gid": "string",

"_fbp": "string",

"_fbc": "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,

"requestedDiscountCodes": [

"string"

],

"payerEmail": "string"

}

Responses

The created checkout session

Content-Type

application/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",

"itemSrc": "string",

"publisherContentId": "string",

"_ga": "string",

"_gid": "string",

"_fbp": "string",

"_fbc": "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,

"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"

}

POST

/checkouts

Playground

Authorization

Basic

OpenID

Body

Samples

cURL

JavaScript

PHP

Python

---

Get a checkout by ID

GET

/checkouts/{id}

Retrieves a specific checkout session by its ID.

Authorizations

Basic

TypeHTTP (basic)

+

OpenID

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

Parameters

Path Parameters

id*

The unique identifier of the checkout

Typestring

Required

Example"checkout123"

Responses

The requested checkout session

Content-Type

application/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",

"itemSrc": "string",

"publisherContentId": "string",

"_ga": "string",

"_gid": "string",

"_fbp": "string",

"_fbc": "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,

"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"

}

GET

/checkouts/{id}

Playground

Authorization

Basic

OpenID

Variables

Key

Value

id*

Samples

cURL

JavaScript

PHP

Python

---

Update a checkout

PATCH

/checkouts/{id}

Updates an existing checkout session with new customer information or payment method.

Authorizations

Basic

TypeHTTP (basic)

+

OpenID

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

Parameters

Path Parameters

id*

The unique identifier of the checkout

Typestring

Required

Example"checkout123"

Request Body

application/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",

"itemSrc": "string",

"publisherContentId": "string",

"_ga": "string",

"_gid": "string",

"_fbp": "string",

"_fbc": "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,

"requestedDiscountCodes": [

"string"

],

"payerEmail": "string"

}

Responses

The updated checkout session

Content-Type

application/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",

"itemSrc": "string",

"publisherContentId": "string",

"_ga": "string",

"_gid": "string",

"_fbp": "string",

"_fbc": "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,

"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"

}

PATCH

/checkouts/{id}

Playground

Authorization

Basic

OpenID

Variables

Key

Value

id*

Body

Samples

cURL

JavaScript

PHP

Python

---

vendor

Operations

GET/vendorGET/vendors

---

Get vendor settings

GET

/vendor

Retrieves the current vendor settings and configuration.

Authorizations

OpenID

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

Responses

The vendor settings and configuration

Content-Type

application/json

{

"id": "vendor123",

"name": "Sesamy Publisher",

"logo": "https://example.com/logo.png"

}

GET

/vendor

Playground

Authorization

OpenID

Samples

cURL

JavaScript

PHP

Python

---

List linked vendors

GET

/vendors

Get the vendors a user with matching email is linked to. This endpoint is not available for publisher tokens.

Authorizations

OpenID

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

Responses

The vendors a user with matching email is linked to

Content-Type

application/json

[

{

"name": "Sesamy Publisher",

"id": "vendor123",

"logo": "https://example.com/logo.png"

}

]

GET

/vendors

Playground

Authorization

OpenID

Samples

cURL

JavaScript

PHP

Python

---

paywalls

Operations

GET/paywalls/{paywallId}

---

Get paywall by ID

GET

/paywalls/{paywallId}

Retrieves the paywall configuration and settings for the specified paywall ID.

Authorizations

OpenID

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

Parameters

Path Parameters

paywallId*

Typestring

Required

Example"pw123456"

Responses

The paywall information and configuration

Content-Type

application/json

{

"currency": "string",

"settings": {

"useDefaultLogo": true,

"useDefaultCurrency": true,

"useDefaultColor": true

},

"subscriptions": [

{

"discountCode": "string",

"price": 0,

"periodText": "string",

"description": "string",

"tag": "string",

"id": "string",

"sku": "string",

"title": "string",

"poId": "string",

"selected": true

}

],

"showLoginButton": true,

"vendorId": "string",

"features": [

"string"

],

"mainColor": "string",

"headline": "string",

"singlePurchase": {

"description": "string",

"title": "string",

"discountCode": "string",

"enabled": true

},

"footerPaymentMethods": [

"string"

],

"version": 0,

"logoUrl": "string"

}

GET

/paywalls/{paywallId}

Playground

Authorization

OpenID

Variables

Key

Value

paywallId*

Samples

cURL

JavaScript

PHP

Python

---

Powered by VitePress OpenAPI

Interactive API Documentation

This is the complete OpenAPI specification for the Sesamy API. You can explore all endpoints, request/response schemas, and try out API calls directly from this page.

About This API

The Sesamy API provides comprehensive endpoints for managing content monetization, subscriptions, and user entitlements.

For additional guides and examples, check out:

• Getting Started - Quick start guide
• Authentication - Authentication methods
• Client API Guide - Client API overview
• Management API Guide - Management API overview
• SDKs - Official client libraries