---
title: "Create an offer"
method: POST
path: "/offers"
---

# Create an offer

`POST /offers`

Use this endpoint to create offers. Supported offer types include subscription (including [seasonal subscription](https://publisher.support.cleeng.com/hc/en-us/articles/9565373130268-Seasonal-Subscriptions)), pass, live event (previously called live pay-per-view), and one-time purchase (previously called TVOD). (For more information on offers, see [What is a Cleeng offer?](https://publisher.support.cleeng.com/hc/en-us/articles/360012552919-What-is-a-Cleeng-offer-)).  With this endpoint, you can also create offer localizations - versions of your offer for different countries and currencies.

## Headers

- `Content-Type` string
- `X-Publisher-Token` string, required

## Request body

- object
  - `title` string, required — Offer title, up to 70 characters
  - `description` string — Offer description, up to 255 characters
  - `type` string, required — Offer type. Allowed values: 'subscription', 'pass', 'live', 'vod'.
  - `geoRestriction` object — `geoRestriction` might be object or null (if not specified). If `geoRestriction`is an object, then `type` and `countries` are required.
    - `type` string — Specify the type of geo-restriction. Allowed values: `whitelist` (allowed in) or `blacklist` (blocked in)
    - `countries` string[] — Based on geo-restriction type, set the array of whitelisted/blacklisted country codes. Allowed values: 2-letter country codes (ISO-3166 country code without UK)
  - `tags` string[] — Tags to which a customer has access.
  - `price` object, required — Offer price. The offer price may be equal to zero. If it is above zero, it must be higher than the set minimum price (the minimum price differs per offer type and currency).
    - `amount` number, float, required — Strict number float or int
    - `currency` string, required — Only currencies available in Cleeng allowed. A list of supported values can be found [here](https://developers.cleeng.com/docs/supported-features#supported-currencies-and-locale)
    - `rules` object[] — These are special price rules for initial purchase of a **seasonal subscription** that define promotional prices that a broadcaster wants to offer in certain periods (e.g. before the season begins or once the season is halfway through). Price rules are defined with their name, start date, end date, and amount. Allowed values: the same restrictions as for price object apply.
      - `from` integer — The start date of a special price rule that defines a promotional price. Format: unix timestamp.
      - `to` integer — The end date of a special price rule that defines a promtional price. Format: unix timestamp
      - `name` string — The name of a promotional price period defined by a price rule, e.g. "Early-bird", "Mid-season".
      - `amount` number, float — Strict number float or int
  - `billingCycle` object — The parameter is **required** for **'subscription'** offer type.
    - `periodUnit` string, required — The unit in which the subscription period is measured. Allowed values: 'day', 'week', 'month', 'year', 'season'.
    - `amount` integer, required — Only combinations for Cleeng supported subscription types allowed: 1, 2, 3, 6. Values allowed for a given `periodUnit`: day - 1; week - 1, 2; month - 1, 3, 6; year - 1, season - 1.
  - `entitlement` object — The parameter is **required** for **'pass'** and **'vod'** offer types. Either `expiresAt` or `duration` is used depending on the offer type.
    - `expiresAt` integer — End date in unix timestamp. Only available and **required** for 'pass' offer type. It must be greater (the time must be later) than the current time. It takes precedence over duration.
    - `duration` object — Duration of an entitlement to an offer
      - `amount` integer — Allowed value: integer greater or equal 0. For 'vod' offer type: amount is not limited. For 'pass' offer type: you can create passes for any number of days under 1000: a week, 2 weeks, a month, 3 months, 6 months and a year.
      - `periodUnit` string — `hour` - a required unit for 'vod'; `day`, `week`, `month`, `year` - allowed units for 'pass'
  - `event` object — The parameter is **required** for **'live'** offer type.
    - `timezone` string — A valid timezone from supported [timezones](https://www.php.net/manual/en/timezones.php)
    - `startsAt` integer — Start time of a live pay-per-view event. It must be smaller than `endsAt`; it can be in the past.
    - `endsAt` integer — End time of a live pay-per-view event.
  - `freeTrial` object — Used only in 'subscription' offer type.
    - `type` string — Allowed values: 'day', 'period'. 'period' is only available for weekly and monthly subscriptions.
    - `duration` integer — The length of a free trial. Allowed values: for the type `day`: min value = 1, max value = 365; for the type `period` and weekly subscriptions: 1 - 52 weeks ; for monthly subscriptions: 1-12 months. (See [Free Trials](https://publisher.support.cleeng.com/hc/en-us/articles/360011481813-Free-Trials) for more information).
  - `url` string — Url to your content described in the offer
  - `imageUrl` string — Url to an image for an offer; up to 255 characters.
  - `externalProperties` object — Object with string values.
    - `property1` string — Example property
  - `appStoreProductIds` object — ID of an offer in a given App store.
    - `apple` string
    - `android` string
    - `roku` string
    - `amazon` string
    - `samsung` string
    - `vizio` string
  - `sessionsLimit` integer — The number of allowed simultaneous sessions. Allowed values: Integer greater than 0 or null if disabled, not required at creation.
  - `localizations` object[] — Offer localizations - versions of your offer for different countries.
    - `title` string — Offer title, up to 70 characters
    - `description` string — Offer description, up to 255 characters
    - `countryCode` string — A 2-letter country code. Allowed values: ISO-3166 country code without UK.
    - `freeTrial` object
      - `type` string — Allowed values: 'day', 'period'. 'period' is only available for weekly and monthly subscriptions.
      - `duration` integer — The length of a free trial. Allowed values: for the type `day`: min value = 4, max value = 365; for the type `period` and weekly subscriptions: 1 - 52 weeks ; for monthly subscriptions: 1-12 months.
    - `price` object
      - `amount` number, float, required — Strict number float or int
      - `currency` string, required — Only currencies available in Cleeng allowed. A list of supported values can be found [here](https://developers.cleeng.com/docs/supported-features#supported-currencies-and-locale)
      - `rules` object[] — These are special price rules for initial purchase of a **seasonal subscription** that define promotional prices that a broadcaster wants to offer in certain periods (e.g. before the season begins or once the season is halfway through). Price rules are defined with their name, start date, end date, and amount. Allowed values: the same restrictions as for price object apply.
        - `from` integer — The start date of a special price rule that defines a promotional price. Format: unix timestamp.
        - `to` integer — The end date of a special price rule that defines a promtional price. Format: unix timestamp
        - `name` string — The name of a promotional price period defined by a price rule, e.g. "Early-bird", "Mid-season".
        - `amount` number, float — Strict number float or int
    - `geoRestriction` object
      - `type` string — Specify the type of geo-restriction. Allowed values: `whitelist` (allowed in) or `blacklist` (blocked in)
      - `countries` string[] — Based on geo-restriction type, set the array of whitelisted/blacklisted country codes. Allowed values: 2-letter country codes (ISO-3166 country code without UK)
  - `seasonGroupId` string — Required conditionally when `billing cycle`: `season` Format: UUID. This is the identifier of a seasonal schedule - a group of seasons, each with its start and end date defined. (For more information on seasonal schedules, see [Seasonal subscriptions](https://publisher.support.cleeng.com/hc/en-us/articles/9565373130268-Seasonal-Subscriptions).)
  - `giftable` boolean — Whether an offer can be purchased as a gift. Default: `false`.
  - `countryCode` string — A 2-letter country code. Allowed values: ISO-3166 country code without UK.

## Response `200`

200

- object
  - `id` string
  - `longId` string
  - `type` string
  - `tags` unknown[]
    - unknown
  - `active` boolean
  - `title` string
  - `description` string
  - `url` string
  - `imageUrl` string
  - `hasLandingPage` boolean
  - `externalProperties` object
    - `custom-attribute` string
  - `appStoreProductIds` unknown[]
    - unknown
  - `price` object
    - `amount` integer
    - `currency` string
    - `taxIncluded` boolean
  - `geoRestriction` object
    - `type` string
    - `countries` string[]
  - `createdAt` integer
  - `updatedAt` integer
  - `billingCycle` object
    - `periodUnit` string
    - `amount` integer
  - `freeTrial` object
    - `type` string
    - `duration` integer
  - `localizations` unknown[]
    - unknown
  - `sessionsLimit` unknown
  - `giftable` boolean

## Other responses

- `400` — 400

---

[API](https://skmtc.net/cleeng/apis/mediastore-api.md) · [All operations](https://skmtc.net/cleeng/apis/mediastore-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cleeng/mediastore-api/versions/00cbfe7998a4/schema)