Create a promotion listing
POST
/api/v3/promotions/listings
const url = 'https://api.tryletterhead.com/api/v3/promotions/listings?api=true';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"title":"Front newsletter banner","description":"Prime placement at the top of every send.","channels":["news-daily"],"zone":"A","price":250,"runLengthDays":7,"totalSlots":4}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url 'https://api.tryletterhead.com/api/v3/promotions/listings?api=true' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "title": "Front newsletter banner", "description": "Prime placement at the top of every send.", "channels": [ "news-daily" ], "zone": "A", "price": 250, "runLengthDays": 7, "totalSlots": 4 }'Create a new self-serve marketplace listing — a placement your company offers for sale.
v3 endpoints expect a company API key.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ” api
required
boolean
Required. Set to true.
Request Body required
Section titled “Request Body required ” Media type application/json
object
title
required
string
description
string
channels
required
Channel slugs this listing runs on. Required, at least one.
Array<string>
zone
required
Template position. One of A-J.
string
price
required
number
runLengthDays
required
How many days a single purchase runs for.
integer
totalSlots
How many concurrent purchases this listing allows. Defaults to 1 if omitted.
integer
availableFrom
Y-m-d. Optional.
string
availableTo
Y-m-d. Optional.
string
status
available | reserved | sold | unavailable. Optional.
string
Example
{ "title": "Front newsletter banner", "description": "Prime placement at the top of every send.", "channels": [ "news-daily" ], "zone": "A", "price": 250, "runLengthDays": 7, "totalSlots": 4}Responses
Section titled “ Responses ”201 Created
Media type application/json
object
items
object
uniqueId
string
channels
Array<object>
object
channel
string
channelTitle
string
zone
string
title
string
description
string
price
number
runLengthDays
integer
totalSlots
integer
availableSlots
integer
soldSlots
integer
availableFrom
string
availableTo
string
status
string
createdAt
string
updatedAt
string
message
string
total
integer
Example
{ "items": { "uniqueId": "c3d4e5f6a7", "channels": [ { "channel": "news-daily", "channelTitle": "News Daily" } ], "zone": "A", "title": "Front newsletter banner", "description": "Prime placement at the top of every send.", "price": 250, "runLengthDays": 7, "totalSlots": 4, "availableSlots": 4, "soldSlots": 0, "availableFrom": null, "availableTo": null, "status": "available", "createdAt": "2026-06-04 17:30:00", "updatedAt": "2026-06-04 17:30:00" }, "message": "Promotion listing created successfully", "total": 1}Still can’t find what you need? Contact support.