Offers API

Document created by pubmatic-archivist on Mar 27, 2017Last modified by catherine.racette on Aug 2, 2017
Version 6Show Document
  • View in full screen mode

Description

An offer is a combination of a product and a targeting unit which you can then sell to specific buyers for a proposed amount. These APIs allows a user to create and manage offers in the PubMatic system.

 

The Offers APIs are part of Inventory APIs. To learn more about Inventory APIs, refer to Inventory Overview 

Methods

                                 
Method Path
HTTP Method Type
Description
Link to Definition
/offers
POST
Create a new offer in the PubMatic system

Creating an Offer

/offers/{id}GETRetrieve the details of a specific offer

Retrieving Details of an Offer (for Publishers)


Retrieving Details of an Offer (for Demand Partners)

/offersGETRetrieve the list of offers
/offers/{id}PUTUpdate the details of a specific offerUpdating an Offer
/offers/{id}DELETEDelete an OfferDeleting an Offer

 

 

Creating an Offer

 

Overview

This API allows you to create an offer in the PubMatic system.

Request

         
URI

$URI_PREFIX/offers


Note: For sandbox testing, $URI_PREFIX should be replaced with "http://api-sandbox.pubmatic.com/v1/inventory".

 

For production, $URI_PREFIX should be replaced with "http://api.pubmatic.com/v1/inventory/".
HTTP MethodPOST

Request Headers

                 

Header Name
Type
Value
Required
Description
Authorization
String
Bearer ${access_token}
Yes
Need to send the access token generating for authentication at the place of ${access_token}.
For more information about access tokens, refer to Getting Started with PubMatic APIs

Request Body

                                                                                                                                                                                                

Body Parameter
Type
Required
Validations
Description
name
String
Yes
  • Maximum length is 255 characters
  • Name should be unique for your account
  • Characters check should be done
Name of the offer.
description
 String
No
  • Maximum length is 512 characters
  • Characters check should be done
Description about the offer.
notes
String
No
  • Maximum length is 512 characters
  • Characters check should be done
Note about the offer.
logoPath
String
No
  • Valid URL check should be done
  • Maximum length is 256 characters
  • Characters check should be done
Path of the logo for the offer.
tags
String
No
  • Values should be comma-separated strings
  • Characters allowed are alphabets, digits, space
  • Maximum length is 255 characters
Hashtags/Keywords which will be used to search the offer.
product
Integer
Yes
  • Value should already exist in the system
  • User should have access to the specified product
ID of the product to be associated with the offer.
targeting
Integer
No
  • Value should already exist in the system
  • User should have access to the specified targeting
ID of the targeting to be associated with the offer.
timezone
Integer
No (Default is PST)
Value should already exist in the system. For a list of available time zones, refer the Reference data section.
ID of the timezone which is used to define startDate and endDate of the offer
offerStartDate
ISO Date
Yes
  • Offer Start date is Mandatory.
  • Offer should not be available beyond the specified date range.
  • Offer Start date cannot be earlier than today.
  • Offer Start date should be sent in GMT.
Date from which the offer will be visible for discovery.
offerEndDate
ISO Date
Yes
  • Offer End date is Mandatory.
  • Offer should not be available beyond the specified date range.
  • Offer End date can be equal to or greater than offer start date.
  • Offer End date should be sent in GMT.
Date till which the offer will be visible for discovery.
transactionStartDate
ISO Date
Yes
  • Transaction Start date is Mandatory.
  • Transaction Start date should be sent in GMT.
  • Transaction start date cannot be earlier than offer start date.
Date from which offer can be bought or transacted
transactionEndDate
ISO Date
Yes
  • Transaction End date is Mandatory.
  • Transaction End date can be equal or greater than transaction start date.
  • Offer End date should be sent in GMT.
Date till which offer can be bought or transacted
impressions
Long
No
Valid numeric value with a minimum value of 0
Number of impressions available in the offer.
percentageAvails
Integer
No
Valid numeric value with a minimum value of 0 and a maximum value of 100
Percentage of the avails defined by the publisher that will be used in this offer.
cpm
Decimal
Yes
Valid decimal value with a minimum value of 0.00 and a maximum value of 999.99
eCPM at which the offer will be available.
spend
Decimal
No
 
Spend expected for the offer.
minSpend
Decimal
No
Valid decimal value with a minimum value of 0
Minimum spend expected for the offer.
currency
Integer
No (Default is USD)
Value should already exist in the system. For a list of available currencies, refer the Reference data section.
Currency used to define the spend for the offer.
oneClickBuy
Boolean
No (Default is false)
Valid Boolean value
Indicates whether the offer is available for one-click buy or not.
featured
Boolean
No (Default is false)
Valid Boolean value
Indicates whether the offer should be marked as featured or not.
customizableEntities
JSON array of Integers
No
Value should already exist in the system.
Identifiers of entities that can be customized or edited in the offer.
channels
JSON array of Integers
Yes
  • Value should already exist in the system.
  • For a list of channels, refer the Reference data section.
  • A single valid value will be accepted for channel except "All".
IDs of the channels (such as PMP, RTB, Spot buys, etc.) using which the offer can be used.
dsps
JSON array of Integers
No
  • Value should already exist in the system
  • Offer will be visible to a DSP only when
    • The offer is made discoverable to the DSP and
    • During the specified date range of the offer
IDs of DSPs to whom the offer will be available / discoverable.
buyers
JSON array of Integers
No
  • Value should already exist in the system
  • Offer will be visible to a buyer/ATD only when
    • The offer is made discoverable to the buyer/ATD and
    • During the specified date range of the offer.
IDs of ATDs/buyers to whom the offer will be available / discoverable.
advertisers
JSON array of Integers
No
  • Value should already exist in the system
  • Offer will be visible to the advertiser only when
    • The offer is made discoverable to the advertiser and
    • During the specified date range of the offer.
IDs of Advertisers to whom this offer is available / discoverable.
publishers
JSON array of Integers
No
  • Value should already exist in the system
  • Offer will be visible to a publisher only when
    • The offer is made discoverable to the publisher and
    • During the specified date range of the offer.
Identifiers of publishers to whom this offer is available / discoverable.

Sample Request


POST $URI_PREFIX/offers

{

    "name": "test offer 123",

    "description": "test description 1234",

    "tags": "test hashtag, hastag123",

    "notes": "test notes",

    "logoPath": "test logo path",

    "product": 3,

    "targeting": 1,

    "timezone": 1,

    "offerStartDate": "2014-11-17T00:00:00Z",

    "offerEndDate": "2014-11-25T10:00:00Z",

    "transactionStartDate": "2014-11-17T00:00:00Z",

    "transactionEndDate": "2014-11-25T10:00:00Z",

    "impressions": 1500000,

    "percentageAvails": 30,

    "cpm": 4.5,

    "spend": 75000,

    "minSpend": 50000,

    "oneClickBuy": true,

    "featured": true,

    "currency": 1,

    "channels": [

        1

    ],

    "dsps": [

        1,

        2

    ],

    "buyers": [

        1,

        2,

        3,

        4

    ],

    "advertisers": [

        1,

        2

    ]

}


Response

Response Body

           
Type
Description
Offer objectJSON response of successfully-created offer

Sample Response for an IAB-enabled User

{
    "id": 123,
    "name": "test offer 123",
    "description": "test description",
    "notes": "test notes",
    "tags": "test hashtag, hastag123",
    "logoPath": "test logo path",
    "publisherId": 1234,
    "deleted": false,
    "creationTime": "2014-08-30T19:16:58Z",
    "modificationTime": "2014-08-30T19:16:58Z",
    "product": {
        "id": 3,
        "name": "test inventory unit 3",
        "uri": "$URI_PREFIX/products/3",
        "productCategory": [
            {
                "id": 52,
                "name": "Automotive",
                "iabCategoryId": "IAB1"
            },
            {
                "id": 76,
                "name": "Business",
                "iabCategoryId": "IAB2"

             }
        ],
        "platforms": [
            {
                "id": 1,
                "name": "Web"
            },
            {
                "id": 2,
                "name": "Mobile Web"
            },
            {
                "id": 4,
                "name": "Mobile App IOS"
            }
        ],
        "iabEnabled": true
    },
    "targeting": {
        "id": 1,
        "name": "test targeting unit 1",
        "uri": "$URI_PREFIX/targeting/1"
    },
    "timezone": {
        "id": 1,
        "name": "PST"
    },
    "offerStartDate": "2014-08-30T12:00:00Z",
    "offerEndDate": "2014-12-31T12:00:00Z",
    "transactionStartDate": "2014-11-01T00:00:00Z",
    "transactionEndDate": "2014-11-30T10:00:00Z",
    "impressions": 1500000,
    "percentageAvails": 30,
    "cpm": 4.5,
    "spend": 75000,
    "minSpend": 50000,
    "currency": {
        "id": 1,
        "name": "USD"
    },
    "oneClickBuy": true,
    "featured": true,
    "channels": [
        {
            "id": 1,
            "name": "PMP"
        }
    ],
    "dsps": [
        {
            "id": 1,
            "name": "DSP 1",
            "uri": "$URI_PREFIX/advertisingEntity/1"
        },
        {
            "id": 2,
            "name": "DSP 2",
            "uri": "$URI_PREFIX/advertisingEntity/2"
        }
    ],
    "buyers": [
        {
            "id": 1,
            "name": "Buyer 1",
            "uri": "$URI_PREFIX/buyer/1"
        },
        {
            "id": 2,
            "name": "Buyer 2",
            "uri": "$URI_PREFIX/buyer/2"
        },
        {
            "id": 3,
            "name": "Buyer 3",
            "uri": "$URI_PREFIX/buyer/3"
        },
        {
            "id": 4,
            "name": "Buyer 4",
            "uri": "$URI_PREFIX/buyer/4"
        }
    ],
    "advertisers": [
        {
            "id": 1,
            "name": "Advertiser 1",
            "uri": "$URI_PREFIX/advertiser/1"
        },
        {
            "id": 2,
            "name": "Advertiser 2",
            "uri": "$URI_PREFIX/advertiser/2"
        }
    ]
}

 

Sample Response for a Non-IAB User


{
    "id": 123,
    "name": "test offer 123",
    "description": "test description",
    "notes": "test notes",
    "tags": "test hashtag, hastag123",
    "logoPath": "test logo path",
    "publisherId": 1234,
    "deleted": false,
    "creationTime": "2014-08-30T19:16:58Z",
    "modificationTime": "2014-08-30T19:16:58Z",
  "product": {
    "id": 3,
    "name": "test inventory unit 3",
    "uri": "$URI_PREFIX/products/3",
    "productCategory": [
      {
        "id": 2,
        "name": "Automotive",
        "iabCategoryId": null
      },
      {
        "id": 3,
        "name": "Business and Finance",
        "iabCategoryId": null
      }
    ],
    "platforms": [
      {
        "id": 1,
        "name": "Web"
      },
      {
        "id": 2,
        "name": "Mobile Web"
      },
      {
        "id": 4,
        "name": "Mobile App IOS"
      }
    ],
    "iabEnabled": false
  }
    "targeting": {
        "id": 1,
        "name": "test targeting unit 1",
        "uri": "$URI_PREFIX/targeting/1"
    },
    "timezone": {
        "id": 1,
        "name": "PST"
    },
    "offerStartDate": "2014-08-30T12:00:00Z",
    "offerEndDate": "2014-12-31T12:00:00Z",
    "transactionStartDate": "2014-11-01T00:00:00Z",
    "transactionEndDate": "2014-11-30T10:00:00Z",
    "impressions": 1500000,
    "percentageAvails": 30,
    "cpm": 4.5,
    "spend": 75000,
    "minSpend": 50000,
    "currency": {
        "id": 1,
        "name": "USD"
    },
    "oneClickBuy": true,
    "featured": true,
    "channels": [
        {
            "id": 1,
            "name": "PMP"
        }
    ],
    "dsps": [
        {
            "id": 1,
            "name": "DSP 1",
            "uri": "$URI_PREFIX/advertisingEntity/1"
        },
        {
            "id": 2,
            "name": "DSP 2",
            "uri": "$URI_PREFIX/advertisingEntity/2"
        }
    ],
    "buyers": [
        {
            "id": 1,
            "name": "Buyer 1",
            "uri": "$URI_PREFIX/buyer/1"
        },
        {
            "id": 2,
            "name": "Buyer 2",
            "uri": "$URI_PREFIX/buyer/2"
        },
        {
            "id": 3,
            "name": "Buyer 3",
            "uri": "$URI_PREFIX/buyer/3"
        },
        {
            "id": 4,
            "name": "Buyer 4",
            "uri": "$URI_PREFIX/buyer/4"
        }
    ],
    "advertisers": [
        {
            "id": 1,
            "name": "Advertiser 1",
            "uri": "$URI_PREFIX/advertiser/1"
        },
        {
            "id": 2,
            "name": "Advertiser 2",
            "uri": "$URI_PREFIX/advertiser/2"
        }
    ]
}

Special Handling for 'ALL' Use Case

For the dsps,buyers and advertisers fields the following handling is done:

 

Request

dsps : [ 0 ] will be considered as ALL dsps
buyers : [ 0 ]  will be considered as ALL buyers
advertisers : [ 0 ] will be considered as ALL advertisers 

 

Response

The dsps/buyers/advertisers field in Response in ALL use case will be shown as:


"dsps": [

{
"id": 0,
"name": null,
"uri": "$URI_PREFIX/advertisingEntity/0"
} ]

"buyers": [
{
"id": 0,
"name": null,
"uri": "$URI_PREFIX/buyer/0"
} ]

"advertisers": [
{
"id": 0,
"name": null,
"uri": "$URI_PREFIX/advertiser/0"
} ]

"advertisers": [

   {

      "id": 0,

      "name": null,

      "uri": "$URI_PREFIX/advertiser/0"

} ]
 

HTTP Response Status Codes

For the list of HTTP status codes, refer to the HTTP Status Codes section.

Error Codes

                                                                                                                                                                                                                                        

Error code
Error description
PKG_002_0053Invalid Offer name.
PKG_002_0011Offer name is not provided.
PKG_002_0054Error occurred while setting Offer owner information.
PKG_002_0055Offer name already exists. Please use another name.
PKG_002_0056Error occurred while validating Offer Category.
PKG_002_0057Invalid Offer category.
PKG_002_0058Product ID is not passed.
PKG_002_0059eCPM can have values between $0 to $999 only.
PKG_002_0060Value for Offer Spend cannot be not less than $0.
PKG_002_0061Value for Offer Minimum Spend cannot be not less than $0.
PKG_002_0062Invalid Currency ID passed.
PKG_002_0063End date for Offer not specified.
PKG_002_0064Invalid start date passed. Start date cannot be earlier than today.
PKG_002_0065Invalid start and end dates. End date cannot be earlier than start date.
PKG_002_0066Invalid Offer name. Following characters are not allowed : |!{}[]^"~*?:;+\\
PKG_002_0067Invalid Offer description. Following characters are not allowed : |!{}[]^"~*?:;+\\
PKG_002_0068Keywords can have upto 255 characters only.
PKG_002_0069Invalid keywords specified. Only alpha-numeric characters are allowed. Multiple keywords should be comma separated.
PKG_002_0070Start date for Offer not specified.
PKG_002_0071Invalid end date passed. End date cannot be earlier than today.
PKG_002_0072Invalid DSP IDs passed.
PKG_002_0073Invalid Buyer IDs passed.
PKG_002_0074Start and End Dates are mandatory, if offer is to be made discoverable.
PKG_002_0047Maximum length allowed for logo path is 256 characters.
PKG_002_0040Maximum length allowed for name is 256 characters.
PKG_002_0041Maximum length allowed for description is 512 characters.
PKG_002_0076Error occurred while validating Product ID.
PKG_002_0078Invalid Product ID passed.
PKG_002_0077Value for Impressions cannot be not less than 0.
PKG_002_0079Error occurred while validating Targeting ID.
PKG_002_0080Invalid Targeting ID passed.
PKG_002_0081Invalid Timezone ID passed.
PKG_002_0082Error while fetching offer information. Incorrect number of active Offer versions found.
PKG_002_0083Error while fetching offer version information.
PKG_002_0086Invalid logo path URL.
PKG_002_0087User does not have access to given Product ID.
PKG_002_0088User does not have access to given Targeting ID.
PKG_002_0089Invalid channel ID(s) passed.
PKG_002_0090Error occurred while updating Offer info.
PKG_002_0091Offer owner is not the same as Product owner.
PKG_002_0092Offer owner is not the same as Targeting owner.
PKG_002_0093ID field should not be populated in Create or Update Offer request.
PKG_002_0094Publisher ID filter is not available for this user.
PKG_002_0095Incorrect loggedInOwnerTypeId provided in search operation for Admin.
PKG_002_0096Error in validating ad tag information.
PKG_002_0097Selected sites are not RTB enabled.
PKG_002_0098Sites belonging to selected ad tags are not RTB enabled.
PKG_002_0099Mobile targeting parameters cannot be selected for inventory belonging to non-Mobile platform.
PKG_002_0100Video targeting parameters cannot be selected for non-video ad tags.
PKG_002_0101Error in updating offer used count.
PKG_002_0102Invalid Boolean value passed for updating offer used count.
PKG_002_0103Offer used count cannot be decremented further.
PKG_002_0104Maximum length allowed for notes is 512 characters.
PKG_002_0105Invalid Offer notes. Following characters are not allowed : |!{}[]^"~*?:;+\\
PKG_002_0106Invalid Advertiser IDs passed.
PKG_002_0107Invalid value passed in Percentage Avails.
PKG_002_0109Inv

 

 

Retrieving Details of an Offer (for Publishers)

 

Overview

This API allows you to retrieve the details of a specific offer.

Request

         
URI

$URI_PREFIX/offers/{id}


Note: For sandbox testing, $URI_PREFIX should be replaced with "http://api-sandbox.pubmatic.com/v1/inventory".

 

For production, $URI_PREFIX should be replaced with "http://api.pubmatic.com/v1/inventory/".
HTTP MethodGET

Request Headers

                 

Header Name
Type
Value
Required
Description
Authorization
String
Bearer ${access_token}
Yes
Need to send the access token generating for authentication at the place of ${access_token}.
For more information about access tokens, refer to Getting Started with PubMatic APIs

Path Parameters

               
Parameter Name
Type
Required
Description
id
Long 
Yes 
ID of the offer whose details need to be fetched.
For example, 123

Sample Request JSON

 

GET $URI_PREFIX/offers/123

Response

Response Body

           
Type
Description
Offer objectDetails of the Offer object in JSON format

Offer

                                                                                                                                                         

Parameter

Type

Description

id

Number

Identifier of the offer

name

String

Name of the offer

description

String

Description of the offer

notes

 String

Additional notes regarding the offer

tags

List of String

Keywords / Hashtags associated with the offer

logoPath

String

URL/Path for the offer's logo

deleted

Boolean

Indicates whether the offer is deleted or not

publisherId

Number

Publisher ID of the offer's owner, if the owner is a publisher

product

Product Object

Product associated with the offer

targeting

Targeting Object

Targeting associated with the offer

timezone

Timezone Object

Timezone which is used to define startDate and endDate of the offer

offerStartDate

ISO Date

Date from which the offer is available/discoverable

offerEndDate

ISO Date

Date till which the offer is available/discoverable

transactionStartDate

ISO Date

Date from which offer can be bought or transacted

transactionEndDate

ISO Date

Date till which offer can be bought or transacted

impressions

Number

Impressions available in the offer

percentageAvails

Number

Percentage of the avails defined by the publisher that will be used in this offer

cpm

Number

eCPM at which the offer is available

spend

Number

Spend expected for the offer

minSpend

Number

Minimum spend expected for the offer

currency

Currency Object

Currency used to define the spend in the offer

oneClickBuy

Boolean

Indicates whether the offer is available for one-click buy or not

featured

Boolean

Indicates whether the offer is marked as featured or not

channels

List of Channel Objects

Channels for which the offer can be used.

advertisers

List of Advertiser objects

Advertisers to whom this offer is available / discoverable

dspsList of DSP objectsDSPs to whom this offer is available / discoverable.
buyersList of ATD/Buyer objectsBuyers to whom this offer is available / discoverable.

creationTime

ISO Date

Time at which the offer was created.

modificationTime

ISODate

Time at which the offer was last modified.

ATD/Buyer

                       
Body Parameters
Type
Description
idNumberID of the ATD/buyer
nameStringName of the ATD
uriStringURI to fetch details of the ATD.

DSP

                       
Body Parameters
Type
Description
idNumberID of the DSP
nameStringName of the DSP
uriStringURI to fetch details of the DSP

Channel Type

                  
Body Parameters
Type
Description
idNumberID of the channel
nameStringName of the channel

Timezone

                  
Body Parameters
Type
Description
idNumberID of the timezone
nameStringName of the timezone

Product

                       
Body Parameters
Type
Description
idNumberID of the product
nameStringName of the product
uriStringURI to fetch any further details of the product

Targeting

                       
Body Parameters
Type
Description
idNumberID of the targeting unit
nameStringName of the targeting unit
uriStringURI to fetch any further details of the targeting unit

Category

                       
Body Parameters
Type
Description
idNumberID of the category/vertical
nameStringName of the category/vertical
uriStringURI to fetch any further details of the category/vertical

Sample Reponse for an IAB-enabled User

{
    "name": "test offer 123",
    "description": "test description",
    "notes": "test notes",
    "tags": "test hashtag, hastag123",
    "id": 123,
    "logoPath": "test logo path",
    "publisherId": 1234,
    "deleted": false,
    "creationTime": "2014-08-30T19:16:58Z",
    "modificationTime": "2014-08-30T19:16:58Z",
    "product": {
        "id": 10,
        "name": "test inventory unit 1",
        "uri": "$URI_PREFIX/products/10",
        "productCategory": [
            {
                "id": 52,
                "name": "Automotive",
                "iabCategoryId": "IAB1"
            },
            {
                "id": 76,
                "name": "Business",
                "iabCategoryId": "IAB2"
            }
        ],
        "platforms": [
            {
                "id": 1,
                "name": "Web"
            },
            {
                "id": 2,
                "name": "Mobile Web"
            },
            {
                "id": 4,
                "name": "Mobile App IOS"
            }
        ],
        "iabEnabled": true
    },
    "targeting": {
        "id": 14,
        "name": "test targeting unit 1",
        "uri": "$URI_PREFIX/targeting/14"
    },
    "timezone": {
        "id": 1,
        "name": "PST"
    },
    "offerStartDate": "2014-08-30T12:00:00Z",
    "offerEndDate": "2014-12-31T12:00:00Z",
    "transactionStartDate": "2014-11-01T00:00:00Z",
    "transactionEndDate": "2014-11-30T10:00:00Z",
    "impressions": 1500000,
    "percentageAvails": 30,
    "cpm": 4.5,
    "spend": 75000,
    "minSpend": 50000,
    "currency": {
        "id": 1,
        "name": "USD"
    },
    "oneClickBuy": true,
    "featured": true,
    "channels": [
        {
            "id": 1,
            "name": "PMP"
        }
    ],
    "dsps": [
        {
            "id": 1,
            "name": "DSP 1",
            "uri": "$URI_PREFIX/advertisingEntity/1"
        },
        {
            "id": 2,
            "name": "DSP 2",
            "uri": "$URI_PREFIX/advertisingEntity/2"
        },
        {
            "id": 3,
            "name": "DSP 3",
            "uri": "$URI_PREFIX/advertisingEntity/3"
        }
    ],
    "buyers": [
        {
            "id": 1,
            "name": "Buyer 1",
            "uri": "$URI_PREFIX/buyer/1"
        },
        {
            "id": 2,
            "name": "Buyer 2",
            "uri": "$URI_PREFIX/buyer/2"
        },
        {
            "id": 3,
            "name": "Buyer 3",
            "uri": "$URI_PREFIX/buyer/3"
        },
        {
            "id": 4,
            "name": "Buyer 4",
            "uri": "$URI_PREFIX/buyer/4"
        }
    ],
    "advertisers": [
        {
            "id": 1,
            "name": "Advertiser 1",
            "uri": "$URI_PREFIX/advertiser/1"
        },
        {
            "id": 2,
            "name": "Advertiser 2",
            "uri": "$URI_PREFIX/advertiser/2"
        }
    ]
}

Sample Response for a Non-IAB User

{
    "name": "test offer 123",
    "description": "test description",
    "notes": "test notes",
    "tags": "test hashtag, hastag123",
    "id": 123,
    "logoPath": "test logo path",
    "publisherId": 1234,
    "deleted": false,
    "creationTime": "2014-08-30T19:16:58Z",
    "modificationTime": "2014-08-30T19:16:58Z",
  "product": {
    "id":