VIvimeo
On Demand\Promotions

Add a promotion to an On Demand page

Information about this method appears below.

post/ondemand/pages/{ondemand_id}/promotions

Request

Path parameters

ondemand_idnumber required
Example:61326

The ID of the On Demand.

Request body

access_type'default' | 'vip'

The promotion access type, which is a purchase option that isn't available on the container. VIP promotions always make the content free of charge. If you use this type, you must further define the promotion with the download or stream_period fields.

Option descriptions:

  • default - Promotions grant discount on the existing purchase options for an On Demand Container.
  • vip - Promotions can be used to grant free access to VOD content before it is released, or to offer a purchase option that isn't available on the container. "vip" promotions will always make the content free, and must be further defined with the download or stream_period fields.
codestring

The promotion code. This field is ignored for batch promotions.

discount_type'free' | 'percent'

The type of discount offered by the promo code. When access_type is vip, the value of this field must be free.

Option descriptions:

  • free - Reduces the price to zero.
  • percent - Reduces the price by an amount defined in the "percent_off" field.
downloadboolean required

Whether the promotion grants download access to VOD content. This is necessary only when not previously defined in the On Demand container or when access_type is vip or product_type is buy.

end_timestring

The end of the promotion period. If you don't specify a value, the promotion will never expire.

labelstring

The description of a batch promotion. This field is ignored for single promotions.

percent_offnumber

The percentage of the discount by using this promo code. This field is applicable only when discount_type is percent.

product_type'any' | 'buy' | 'buy_episode' | 'rent' | 'rent_episode' | 'subscribe'

The type of transaction to which the promotion applies. When access_type is default, the default value is any, but the default value is rent when access_type is vip. Also, when access_type is vip, the only valid product types are buy and rent.

start_timestring

The start of the promotion period. If you don't specify a value, the start time defaults to the time that the promotion was created.

stream_period'1_week' | '1_year' | '24_hour' | '30_day' | '3_month' | '48_hour' | '6_month' | '72_hour' required

The amount of time that a user has access to the VOD content upon redeeming a promo code. This field is necessary only when not defined in the On Demand container or when creating promotions when access_type is vip or product_type is rent.

totalnumber required

The number of promotions to generate when type is batch, or the number of uses of the promotion when type is single.

type'batch' | 'single' required

The type of promotion. When access_type is vip, the value for this field must be batch.

Option descriptions:

  • batch - Generates many random promo codes with one use each.
  • single - Generates one promo code that can be used many times.

Example request

{
  "code": "sxsw2018",
  "download": true,
  "end_time": "1526089920",
  "label": "sxsw",
  "percent_off": 50,
  "start_time": "1526089920",
  "total": 9
}

Response

The promotion was added.

access_type'default' | 'vip' required

The type of access that this promotion grants:

Option descriptions:

  • default - Grants discounts on existing product offerings.
  • vip - Grants free access either to VOD content before it is released or to access types that aren't part of the existing product offerings.
discount_type'dollars' | 'free' | 'percent' required

The type of discount for which this promotion can be used.

Option descriptions:

  • dollars - The discount is a certain fixed amount.
  • free - The discount is the full purchase price. VIP access promotions always use this discount type.
  • percent - The discount is a certain percentage of the full price.
downloadboolean required

Whether this promotion grants download access to On Demand content.

labelstring nullable required

The prefix string for batch codes, or the null value for single codes.

percent_offnumber required

The percentage amount that is deducted from the product price.

product_type'any' | 'buy' | 'buy_episode' | 'rent' | 'rent_episode' | 'subscribe' required

The type of product to which this promotion can be applied. Only buy and rent are available for the VIP access type:

Option descriptions:

  • any - The promotion can be applied to any product.
  • buy - The promotion can be applied to a buyable single video.
  • buy_episode - The promotion can be applied to a buyable single episode.
  • rent - The promotion can be applied to a rentable single video.
  • rent_episode - The promotion can be applied to a rentable single episode.
  • subscribe - The promotion can be applied to a subscription.
stream_period'1_week' | '1_year' | '24_hour' | '30_days' | '3_month' | '48_hour' | '6_month' | '72_hour' nullable required

The amount of time that the user has access to the VOD content after redeeming a promo code.

Option descriptions:

  • 1_week - Access lasts for one week.
  • 1_year - Access lasts for one year.
  • 24_hour - Access lasts for 24 hours.
  • 30_days - Access lasts for 30 days.
  • 3_month - Access lasts for 3 months.
  • 48_hour - Access lasts for 48 hours.
  • 6_month - Access lasts for 6 months.
  • 72_hour - Access lasts for 72 hours.
totalnumber required

The total amount of times that this promotion can be used.

type'batch' | 'batch_prefix' | 'single' required

The way in which this promotion can generate promo codes:

Option descriptions:

  • batch - Provides many unique promo codes that can only be used once each.
  • batch_prefix - Similar to batch, except that all codes have a similar prefix string. This mode is deprecated, yet it may still appear for some users.
  • single - Provides a single promo code with many uses.
uristring required

The promotion's canonical relative URI.

Example response

{
  "access_type": "default",
  "discount_type": "free",
  "download": true,
  "label": "8jgaieumbzstujhn8k304iwwezawkvwm",
  "metadata": {
    "connections": {
      "codes": {
        "total": 1,
        "uri": "/ondemand/pages/61326/promotion/12345/codes"
      }
    }
  },
  "product_type": "any",
  "stream_period": "1_week",
  "total": 1,
  "type": "batch",
  "uri": "/ondemand/pages/61326/promotions/12345"
}

Changes

No recorded changes to this operation across all 13 revisions of this API.