Inventory Packages API

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

Description

These APIs allows a partner to create and manage inventory packages in the PubMatic system.

Methods

                                 

Method Path
HTTP Method
Type
Description
Link to Definition
/packages
POST
Create a package in the PubMatic system, and also configure it to be discoverable by other partners in the system.
Creating a Package
/packagesGETRetrieve the list of packages from the PubMatic system. This API will also take filter conditions, to limit and filter packages based on various parameters.

Retrieving List of Packages (For publishers)

 

Retrieving List of Packages (For Demand Partners)

/packages/{id}
GET
Fetch the details of a specific package from the PubMatic system as specified in the URI of the request.
Retrieving Details of a Package
/packages/{id}
PATCH
Update a package's details in the PubMatic system.
Updating a Package

 

Error Codes and Descriptions can be found below in the Inventory-Specific Error Codes section.

 

 

Creating a Package

Overview

This API allows you to create a package in the PubMatic system, and also configure it to be discoverable by other partners in the system.

Request

         

URI$URI_PREFIX/v1/inventory/packages
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 ParameterTypeRequiredValidationsDescription
nameStringYes YesName of the package.
descriptionStringYesYesDescription of the package.
start_dateDateYes Start date from which the package will be applicable.
end_DateDateYes End date till which the package will be applicable.
impressionsIntegerYes Monthly iImpressions available in the package.
ecpmDoubleYes eCPM (in USD) of the impressions available in the package.
notesStringNo Notes about the package.
min_spendDoubleNo Minimum spend required for the package, in case of any minimum spend constraint applied to the offer.
inventory_unit_idIntegerYes ID of the inventory unit to be included in the package.
discoveryDiscoveryYes Discovery parameters associated with the package.

Discovery

                                                                         
Body Parameter
TypeRequiredValidationsDescription
channelJSON array of IntegersYesYesID of the channel for which this package is applicable.
one_click_buyStringYesYesIndicates whether this package is applicable for a one-click buy or not.
discoverableStringYesYesIndicates whether this package can be discovered by other partners in the PubMatic system or not.
advertiser_idJSON array of IntegersNoYesIDs of the advertisers to whom this package is discoverable.
advertiser_category_idJSON array of IntegersNoYesIDs of the advertiser categories for which this package is discoverable.
advertiser_domain_idJSON array of IntegersNoYesIDs of the advertiser domains for which this package is discoverable.
demand_partner_idJSON array of IntegersNoYesIDs of the DSPs to whom this package is discoverable.
atd_idJSON array of IntegersNoYesIDs of the ATDs to whom this package is discoverable.
publisher_idJSON array of IntegersNoYesIDs of the publisher to whom this package is discoverable.

Sample Request JSON

{
     "name": "Name of the package",
     "description": "This is the description for the package",
     "start_date": "2014-01-01T00:00:00Z",
     "end_Date": "2014-01-01T00:00:00Z",
     "impressions": 600000,
     "ecpm": 2.3,
     "notes": "Free text notes here",
     "min_spend": 1000000,
     "inventory_unit_id": 4,
     "discovery": {
          "channel": [
               1,
               2,
               3
          ],
          "one_click_buy": true,
          "discoverable": true,
          "advertiser_id": [
               23,
               234,
               22
          ],
          "advertiser_category_id": [
               324,
               23,
               342
          ],
          "advertiser_domain_id": [
               34,
               2,
               341
          ],
          "demand_partner_id": [
               12,
               23422
          ],
          "atd_id": [
               12434,
               2342
          ],
          "publisher_id": [
               123,
               1212,
               2324
          ]
     }
}

Response

Response Body

                       
Response Body Parameter
Type
Description
idNumberID of the package in the PubMatic system.
nameStringName of the package.
uriNumberURI used to fetch the details of the package.

Sample Response JSON


{
     "id" :8787,
     "name":"Package Name",
     "uri" : "http://api.pubmatic.com/inventory/packages/8787"
}

HTTP Response Status Codes

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

 

Retrieving List of Packages (For publishers)

 

Overview

This API allows you to fetch the list of packages present in the PubMatic system.

Request

         

URI$URI_PREFIX/v1/inventory/packages
HTTP MethodGET

Request

         

Response

Response Body

                                                                                                                                          
Response Body Parameter
Type
Description
id
Number
ID of the package in the PubMatic system.
name
String
Name of the package.
uri
URL
Link to obtain the details for this package.
For example, {uri-prefix}/inventory/packages/94
description
String
Description of the package
ecpm
Decimal
eCPM (in USD) of the impressions available in the package.
impressions
Number
Monthly iImpressions available in this package.
minSpend
Number
Minimum spend required for the package, in case of any minimum spend constraint applied to the offer.
startDate
Date
Start date (in ISO format) after which the package will be applicable.
For example, 2014-06-01T00:00:00Z
endDate
Date
End date (in ISO format) till which the package will be applicable.
For example, 2014-08-01T00:00:00Z
notes
String
Notes about the package.
featured
Number
Indicates whether the package is a featured package or not.
ownerId
Number
ID of the package's owner.
This parameter is set internally.
logoPath
String/URL
File path of the logo associated with this package.
ownerTypeId
Number
ID of the owner's type.
For example, Publisher, DSP, ATD, etc.
ownerName
String
Name of the owner.
multiPubSupported
Boolean
Indicates whether the package is supported for PubConnect.
oneClickBuy
Boolean
Indicates whether the package is applicable for a one-click buy (that is, without any negotiations) or not.
discoverable
Boolean
Indicates whether the package is visible to other partners in the PubMatic system or not.
packageCategory
Number
Category to which this package belongs.
channel
List<Channel>
Channels for which this package is made visible.
For example, PMP/RTB/SpotBuys/CrossExchange.
This parameter is displayed only to the package's owner.
inventory_unit
Inventory unit associated with this package.
atd
List<ATD>
Buyers to whom this package is visible.
This parameter is displayed only to the package's owner.
publisher
List<Publisher>
Publishers to whom this package is visible.
This parameter is displayed only to the package's owner.
demandPartner
Demand Partners to whom this package is visible.
This parameter is displayed only to the package's owner.
advertiserCategory
Category of advertisers to whom this package is visible.
This parameter is displayed only to the package's owner.
created_by
Details of the user who created the package. This parameter is always null as the ownerId is provided in the package.

ATD

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

Publisher

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

DemandPartner

                       
Body Parameters
Type
Description
idNumberID of the demand partner/DSP.
nameStringName of the demand partner/DSP.
uriStringURI to fetch the details of the demand partner/DSP.

AdvertiserCategory

                       
Body Parameters
Type
Description
idNumberID of the advertiser category.
nameStringName of the advertiser category.
uriStringURI to fetch the details of the advertiser category.

Channel Type

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

InventoryUnit

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

Users

                       
Body Parameters
Type
Description
idNumberID of the user.
nameStringUser name of the user.
uriStringURI to fetch any further details of the user.

Examples

Request


{uri-prefix}/inventory/packages/200

Response

 

{
"id": 200,
"name": "Desc Creation Time",
"uri": "$URI_PREFIX/inventory/packages/200",
"description": "Package For Desc CreationTime",
"ecpm": 8,
"impressions": 600,
"minSpend": 1000,
"startDate": "2014-05-01T12:00:00Z",
"endDate": "2014-05-30T12:00:00Z",
"notes": "Free text notes here",
"featured": true,
"ownerId": 1,
"creationTime": "2014-05-26T09:25:58Z",
"modificationTime": "2014-05-26T09:25:58Z",
"deleted": false,
"logoPath": null,
"isConsumed": null,
"ownerTypeId": 1,
"ownerName": "",
"multiPubSupported": false,
"oneClickBuy": true,
"discoverable": true,
"packageCategory": 2,

"channel":
[
{
"id": 1,
"name": "PMP",
"uri": null
},
{
"id": 2,
"name": "AdFlex",
"uri": null
},
{
"id": 3,
"name": "RTB",
"uri": null
}
],

"inventoryUnit":
{
"id": 38337,
"name": "Desc Creation Time",
"uri": "$URI_PREFIX/inventory/inventoryUnits/38337"
},

"atd":
[
{
"id": 2342,
"name": "Unique Digital UK",
"uri": "$URI_PREFIX/common/buyer/2342"
}
],
"publisher": null,
"demandPartner":
[
{
"id": 12,
"name": "Takkle",
"uri": "$URI_PREFIX/common/demandpartner/12"
},
{
"id": 234,
"name": "Gorilla Nation_deleted_id_234",
"uri": "$URI_PREFIX/common/demandpartner/234"
}
],

"advertiserCategory":
[
{
"id": 23,
"name": "Tobacco",
"uri": "$URI_PREFIX/common/advertisingEntity/23"
}
],
"createdBy": null
}

Error Codes

For more information about error codes, refer the Packages and Inventory Units-related Error Codes section below.

 

 

Retrieving List of Packages (For Demand Partners)

Overview

This API allows you to fetch the list of packages from the PubMatic system.

Request

         
URI$URI_PREFIX/inventory/packages
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.

Request Body

                                             
Request Body Parameter
Type
Required
Validation
Description
fromDateDateNo Used for the reporting call. If you need to search using startDate/endDate, use the filters mentioned below instead.
pageSizeIntegerNo 

Maximum number of rows to be included in the response.

Default value: 25

pageNumberIntegerNo 

Page number to be fetched in case of multiple pages.

Default value:1

filtersStringNo

Values must be from those mentioned below in the supported Dimensions section.

Filters that restrict the data returned for your request.
For more details, refer the Reporting and Listing API Request Details section.
sortStringNo

Values must be from those mentioned below in the supported Dimensions section.

A list of comma-separated dimensions indicating the sorting order and sorting direction for the returned data.
For more details, refer the Reporting and Listing API Request Details section.

Searchable Fields

                                                                                                                                 
Name
Data Type
Summary
Sample Filter Data
Sample Sort Data
id
Long
Searching and sorting is supported. Plain search is deprecated as there is an end point for it.
?filters=id gtEq 298&filters=id lt 301
For ascending: ?sort=id
For descending: ?sort=--id
name
String
Searching and sorting is supported on this field.
?filters=name like test
For ascending: ?sort=name
For descending: ?sort=-name
description
String
Searching is supported. Sorting is deprecated for this field.
?filters=description like test
Deprecated
keyWords
String
Searching is supported. Sorting is deprecated for this field.
?filters=keyWords like test
Deprecated
ownerId
Long
Searching and sorting is supported.
Though supported, this field should not be used for search on its own and must be accompanied by search for ownerType.
?filters=ownerId eq 1
?sort=ownerId
ownerType
Long
Type of the owner for package. Currently only 1 (for publisher) is allowed. Though supported, this field should not be used for search on its own and must be accompanied by search for ownerId.
?filters=ownerType eq 1
 
iuId
Long
Enables searching of packages based on the inventory units. Sorting is deprecated for this field.
?filters=iuId eq 38337
Deprecated
ecpm
Float
Provided as a sorting option in the UI. Searching and sorting are both supported for this field.
?filters=ecpm eq 0.4
?sort=ecpm
impression
Long
Packages can be searched and sorted by impressions. Equality search is deprecated for this field.
You may use range search using ?filters=impression lt 1000&
Deprecated
?sort=-impression
spend
Double
Packages can be searched and sorted by impressions. Equality Search is deprecated for this field.
Deprecated
 
startDate
Date
Searching and sorting is supported. Between is currently not supported. But, you can use filters like
?filters=startDate gtEq 2014-06-12T17:00:00Z&filters=startDate lt 2014-06-16T17:00:00Z.
 
?sort=-startDate
endDate
Date
Searching and sorting is supported.
 
 
oneClickBuy
Boolean
Searching and sorting is supported.
?filters=oneClickBuy eq false&filters=id gt 300
To sort packages which have not been enabled for one-click buy (that is, oneClickBuy=false) at the top:
?sort=oneClickBuy, -id&filters=id gtEq 184&filters=id lt 280
 
To sort packages which have been enabled for one-click buy (that is, oneClickBuy=true) at the top:
?sort=-oneClickBuy, -id&filters=id gtEq 184&filters=id lt 280
discoverable
Boolean
Searching and sorting is supported. Please note that only packages which can be discovered by you are returned in the Search or Sort operations.
?filters=discoverable eq false
To sort packages which are not discoverable (that is, discoverable=false) at the top:
?sort=discoverable
 
To sort packages which are discoverable (that is, discoverable=true) at the top:
?sort=-discoverable
featured
Boolean
Searching and sorting is supported.
?filters=featured eq false
To sort packages which are not featured (that is, featured=false) at the top:
?sort=featured
 
To sort featured packages (that is, featured=true) at the top:
?sort=-featured
packageCategory
Integer
Searching and sorting is supported. Range-based searching and sorting is deprecated.
?filters=packageCategory eq 2
Deprecated
platFormIds
Integer
Searching is supported.
?filters=platFormIds eq 1
Deprecated

Response

Response Headers

                                 
Response Header Name
Value
Description
Status Code
200
OK
Content-Type
application/json
Media type that is to be returned in the search/sort operation.
Date
Fri, 30 May 2014 06:45:05 GMT
 
Server
Apache-Coyote/1.1
 
Transfer-Encoding
chunked
 

Response Body

                                                                                                                                          

Response Body Parameter
Type
Description
id
Number
ID of the package in the PubMatic system.
name
String
Name of the package.
uri
URL
Link to obtain the details for this package.
For example, {uri-prefix}/inventory/packages/94
description
String
Description of the package
ecpm
Decimal
eCPM (in USD) of the impressions available in the package.
impressions
Number
Monthly iImpressions available in this package.
minSpend
Number
Minimum spend required for the package, in case of any minimum spend constraint applied to the offer.
startDate
Date
Start date (in ISO format) after which the package will be applicable.
For example, 2014-06-01T00:00:00Z
endDate
Date
End date (in ISO format) till which the package will be applicable.
For example, 2014-08-01T00:00:00Z
notes
String
Notes about the package.
featured
Number
Indicates whether the package is a featured package or not.
ownerId
Number
ID of the package's owner.
This parameter is set internally.
logoPath
String/URL
File path of the logo associated with this package.
ownerTypeId
Number
ID of the owner's type.
For example, Publisher, DSP, ATD, etc.
ownerName
String
Name of the owner.
multiPubSupported
Boolean
Indicates whether the package is supported for PubConnect.
oneClickBuy
Boolean
Indicates whether the package is applicable for a one-click buy (that is, without any negotiations) or not.
discoverable
Boolean
Indicates whether the package is visible to other partners in the PubMatic system or not.
packageCategory
Number
Category to which this package belongs.
channel
List<Channel>
Channels for which this package is made visible.
For example, PMP/RTB/SpotBuys/CrossExchange.
This parameter is displayed only to the package's owner.
inventory_unit
Inventory unit associated with this package.
atd
List<ATD>
Buyers to whom this package is visible.
This parameter is displayed only to the package's owner.
publisher
List<Publisher>
Publishers to whom this package is visible.
This parameter is displayed only to the package's owner.
demandPartner
Demand Partners to whom this package is visible.
This parameter is displayed only to the package's owner.
advertiserCategory
Category of advertisers to whom this package is visible.
This parameter is displayed only to the package's owner.
created_by
Details of the user who created the package. This parameter is always null as the ownerId is provided in the package.

ATD

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

Publisher

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

DemandPartner

                       
Body Parameters
Type
Description
idNumberID of the demand partner/DSP.
nameStringName of the demand partner/DSP.
uriStringURI to fetch the details of the demand partner/DSP.

AdvertiserCategory

                       
Body Parameters
Type
Description
idNumberID of the advertiser category.
nameStringName of the advertiser category.
uriStringURI to fetch the details of the advertiser category.

Channel Type

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

InventoryUnit

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

Users

                       

Body Parameters
Type
Description
idNumberID of the user.
nameStringUser name of the user.
uriStringURI to fetch any further details of the user.

Sample Search Request for platFormIds



{uri-prefix}/inventory/packages/?filters=platFormIds eq 1

Sample Response JSON

 

{
    "metaData": {
        "startIndex": 1,
        "request": {
            "pageSize": 15,
            "pageNumber": 1,
            "metrics": null,
            "dimensions": null,
            "sort": null,
            "filters": [
                "platFormIds eq 1"
            ],
            "fromDate": null,
            "toDate": null,
            "useAllDimensions": true
        },
        "totalRecords": 2,
        "endIndex": 2
    },
    "items": [
        {
            "id": 94,
            "name": "Stable Package 1",
            "uri": "$URI_PREFIX/inventory/packages/94",
            "description": "Package1",
            "ecpm": 4.46,
            "impressions": 2000,
            "minSpend": 0,
            "startDate": "2014-06-01T00: 00: 00Z",
            "endDate": "2014-08-01T00: 00: 00Z",
            "notes": null,
            "featured": false,
            "ownerId": 31445,
            "creationTime": "2014-05-29T00: 36: 01Z",
            "modificationTime": "2014-05-29T00: 36: 01Z",
            "deleted": false,
            "logoPath": "",
            "isConsumed": null,
            "ownerTypeId": 1,
            "ownerName": "eBay, Inc.",
            "multiPubSupported": false,
            "oneClickBuy": true,
            "discoverable": true,
            "packageCategory": 1,
            "channel": null,
            "inventoryUnit": {
                "id": 38337,
                "name": "DescCreationTime",
                "uri": "$URI_PREFIX/inventory/inventoryUnits/38337"
            },
            "atd": null,
            "publisher": null,
            "demandPartner": null,
            "advertiserCategory": null,
            "createdBy": null
        },
        {
            "id": 166,
            "name": "testpackage3",
            "uri": "$URI_PREFIX/inventory/packages/166",
            "description": "test",
            "ecpm": 10,
            "impressions": 100,
            "minSpend": 1,
            "startDate": "2014-05-22T00: 00: 00Z",
            "endDate": "2014-05-31T00: 00: 00Z",
            "notes": null,
            "featured": false,
            "ownerId": 31445,
            "creationTime": "2014-05-21T22: 17: 57Z",
            "modificationTime": "2014-05-21T22: 17: 57Z",
            "deleted": false,
            "logoPath": "",
            "isConsumed": null,
            "ownerTypeId": 1,
            "ownerName": "eBay, Inc.",
            "multiPubSupported": false,
            "oneClickBuy": false,
            "discoverable": true,
            "packageCategory": 2,
            "channel": null,
            "inventoryUnit": {
                "id": 38411,
                "name": "testpackage3",
                "uri": "$URI_PREFIX/inventory/inventoryUnits/38411"
            },
            "atd": null,
            "publisher": null,
            "demandPartner": null,
            "advertiserCategory": null,
            "createdBy": null
        }
    ]
}

 

HTTP Response Status Codes

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

 

Error Codes

For more information about error codes, refer to the Packages and Inventory Unit-related Error Codes section below.

 

Retrieving Details of a Package

Overview

This API allows you to fetch the details of a specific package from the PubMatic system as specified in the URI of the request.

Request

         
URI$URI_PREFIX/inventory/packages/{id}
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
idIntegerYesID of the package whose details need to be fetched.

Response

Response Body

                                                                                                                                        

Response Body Parameter
Type
Description
id
Number
ID of the package in the PubMatic system.
name
String
Name of the package.
uri
URL
Link to obtain the details for this package.
For example, {uri-prefix}/inventory/packages/94
description
String
Description of the package
ecpm
Decimal
eCPM (in USD) of the impressions available in the package.
impressions
Number
Monthly iImpressions available in this package.
minSpend
Number
Minimum spend required for the package, in case of any minimum spend constraint applied to the offer.
startDate
Date
Start date (in ISO format) after which the package will be applicable.
For example, 2014-06-01T00:00:00Z
endDate
Date
End date (in ISO format) till which the package will be applicable.
For example, 2014-08-01T00:00:00Z
notes
String
Notes about the package.
featured
Number
Indicates whether the package is a featured package or not.
ownerId
Number
ID of the package's owner.
This parameter is set internally.
logoPath
String/URL
File path of the logo associated with this package.
ownerTypeId
Number
ID of the owner's type.
For example, Publisher, DSP, ATD, etc.
ownerName
String
Name of the owner.
multiPubSupported
Boolean
Indicates whether the package is supported for PubConnect.
oneClickBuy
Boolean
Indicates whether the package is applicable for a one-click buy (that is, without any negotiations) or not.
discoverable
Boolean
Indicates whether the package is visible to other partners in the PubMatic system or not.
packageCategory
Number
Category to which this package belongs.
channel
List<Channel>
Channels for which this package is made visible.
For example, PMP/RTB/SpotBuys/CrossExchange.
This parameter is displayed only to the package's owner.
inventory_unit
Inventory unit associated with this package.
atd
List<ATD>
Buyers to whom this package is visible.
This parameter is displayed only to the package's owner.
publisher
List<Publisher>
Publishers to whom this package is visible.
This parameter is displayed only to the package's owner.
demandPartner
Demand Partners to whom this package is visible.
This parameter is displayed only to the package's owner.
advertiserCategory
Category of advertisers to whom this package is visible.
This parameter is displayed only to the package's owner.
created_by
Details of the user who created the package. This parameter is always null as the ownerId is provided in the package.

ATD

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

Publisher

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

DemandPartner

                       
Body Parameters
Type
Description
idNumberID of the demand partner/DSP.
nameStringName of the demand partner/DSP.
uriStringURI to fetch the details of the demand partner/DSP.

AdvertiserCategory

                       
Body Parameters
Type
Description
idNumberID of the advertiser category.
nameStringName of the advertiser category.
uriStringURI to fetch the details of the advertiser category.

Channel Type

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

InventoryUnit

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

Users

                       

Body Parameters
Type
Description
idNumberID of the user.
nameStringUser name of the user.
uriStringURI to fetch any further details of the user.

Examples

Request 


{uri-prefix}/inventory/packages/200

Response

{
    "id": 200,
    "name": "Desc Creation Time",
    "uri": "$URI_PREFIX/inventory/packages/200",
    "description": "Package For Desc CreationTime",
    "ecpm": 8,
    "impressions": 600,
    "minSpend": 1000,
    "startDate": "2014-05-01T12:00:00Z",
    "endDate": "2014-05-30T12:00:00Z",
    "notes": "Free text notes here",
    "featured": true,
    "ownerId": 1,
    "creationTime": "2014-05-26T09:25:58Z",
    "modificationTime": "2014-05-26T09:25:58Z",
    "deleted": false,
    "logoPath": null,
    "isConsumed": null,
    "ownerTypeId": 1,
    "ownerName": "",
    "multiPubSupported": false,
    "oneClickBuy": true,
    "discoverable": true,
    "packageCategory": 2,
    "channel": null,
    "inventoryUnit": {
        "id": 38337,
        "name": "Desc Creation Time",
        "uri": "$URI_PREFIX/inventory/inventoryUnits/38337"
    },
    "atd": null,
    "publisher": null,
    "demandPartner": null,
    "advertiserCategory": null,
    "createdBy": null
}

HTTP Response Status Codes

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

Error Codes

For more information about error codes, refer the Packages and Inventory Units-related Error Codes section below.

 

 

Updating a Package

Overview

This API allows you to update a package's details in the PubMatic system.

Request

         
URI$URI_PREFIX/v1/inventory/packages/{id}
HTTP MethodPATCH

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
idIntegerYesID of the package whose details need to be edited.

Request Body

                                                                                
Body ParameterTypeRequiredValidationsDescription
nameStringYes YesName of the package.
descriptionStringYesYesDescription of the package.
start_dateDateYes Start date from which the package will be applicable.
end_DateDateYes End date till which the package will be applicable.
impressionsIntegerYes Monthly iImpressions available in the package.
ecpmDoubleYes eCPM (in USD) of the impressions available in the package.
notesStringNo Notes about the package.
min_spendDoubleNo Minimum spend required for the package, in case of any minimum spend constraint applied to the offer.
inventory_unit_idIntegerYes ID of the inventory unit to be included in the package.
discoveryDiscoveryYes Discovery parameters associated with the package.

Discovery

                                                                         

Body Parameter
TypeRequiredValidationsDescription
channelJSON array of IntegersYesYesID of the channel for which this package is applicable.
one_click_buyStringYesYesIndicates whether this package is applicable for a one-click buy or not.
discoverableStringYesYesIndicates whether this package can be discovered by other partners in the PubMatic system or not.
advertiser_idJSON array of IntegersNoYesIDs of the advertisers to whom this package is discoverable.
advertiser_category_idJSON array of IntegersNoYesIDs of the advertiser categories for which this package is discoverable.
advertiser_domain_idJSON array of IntegersNoYesIDs of the advertiser domains for which this package is discoverable.
demand_partner_idJSON array of IntegersNoYesIDs of the DSPs to whom this package is discoverable.
atd_idJSON array of IntegersNoYesIDs of the ATDs to whom this package is discoverable.
publisher_idJSON array of IntegersNoYesIDs of the publisher to whom this package is discoverable.

Sample Request JSON

 

{
    "name": "Name of the package",
    "description": "This is the description for the package",
    "start_date": "2014-01-01T00:00:00Z",
    "end_Date": "2014-01-01T00:00:00Z",
    "impressions": 600000,
    "ecpm": 2.3,
    "notes": "Free text notes here",
    "min_spend": 1000000,
    "inventory_unit_id": 4,
    "discovery": {
        "channel": [
            1,
            2,
            3
        ],
        "one_click_buy": true,
        "discoverable": true,
        "advertiser_id": [
            23,
            234,
            22
        ],
        "advertiser_category_id": [
            324,
            23,
            342
        ],
        "advertiser_domain_id": [
            34,
            2,
            341
        ],
        "demand_partner_id": [
            12,
            23422
        ],
        "atd_id": [
            12434,
            2342
        ],
        "publisher_id": [
            123,
            1212,
            2324
        ]
    }
}

Response

Response Body

                       
Response Body Parameter
Type
Description
idNumberID of the package in the PubMatic system.
nameStringName of the package.
uriNumberURI to fetch the details of the package.

Sample Response JSON

 

{
    "id": 8787,
    "name": "Package Name",
    "uri": "http://api.pubmatic.com/inventory/packages/8787"
}

HTTP Response Status Codes

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

 

Inventory-Specific Error Codes

This API contains the following:

Error Messages

The Inventory API returns error messages in the following format:

[
     {
         "errorCode": "IU_001_0001",
         "errorMessage": "Invalid product ID"
     },
     {
         "errorCode": "IU_001_0002",
         "errorMessage": "Invalid user ID"
     }
]

 

Error Codes

In addition to descriptive error text, error messages contain specific error codes. While the text for an error message may change, the codes will stay the same.

 

Common Error Codes:

Following is a list of common error codes:

Error Codes
Error Messages
IU_001_0001
Invalid product ID.
IU_001_0002
Invalid user ID.
IU_001_0003
Invalid name.
IU_001_0004
Invalid owner ID.
IU_001_0005
Invalid product type specified.
IU_001_0006
Error in deleting product entities.
IU_001_0008
Invalid description.
IU_001_0017
Invalid or null value for Owner Type field.
IU_001_0018
Product name cannot be null or empty.
IU_001_0019
Product name cannot exceed 250 characters.
IU_001_0023
Internal error in validating selected Ad Tags.
IU_001_0024
Selected AdTags are invalid.
IU_001_0026
Selected sites are invalid or Given sites do not belong to the input platforms.
IU_001_0030
Failed to locate a dozer file.
IU_001_0031
Error in fetching publisher site details.
IU_001_0033
Invalid product entity IDs.
IU_001_0037
Invalid Product category IDs passed.
IU_001_0038
Invalid Ad Size IDs passed.
IU_001_0039
Invalid Fold Placement IDs passed.
IU_001_0051
Invalid Publisher section IDs passed.
IU_001_0052
Unable to retrieve details for adtag.
IU_001_0053
Unable to filter adtags.
IU_001_0054
No AdTags found for the matching filters.
IU_001_0055
Internal error in validating AdTags.
IU_001_0056
Invalid Resource Type found for logged in user.
IU_001_0061
Error in fetching product details.
IU_001_0062
No product found for given product ID.
IU_001_0063
User does not have access to update product.
IU_001_0066
No sites are associated for given user.
IU_001_0068
The package creation failed since the package contains both Banner and Video ad tags.
IU_001_0070
Product name already exists. Please use another name.
IU_001_0071
Invalid Ad Code Type IDs passed.
IU_001_0072
At least one site or Ad Tag should be selected.
IU_001_0073
Invalid Product name. Following characters are not allowed : |!{}[]^"~*?:;+\
IU_001_0074
Invalid Product description. Following characters are not allowed : |!{}[]^"~*?:;+\
IU_001_0075
Product creation failed.
IU_001_0076
Product description cannot exceed 250 characters.
IU_001_0077
Invalid Site group inclusion IDs passed.
IU_001_0078
Invalid Site group exclusion IDs passed.
IU_001_0079
Product update failed.
IU_001_0080
Product cannot be updated as it is being used in a transaction entity.
IU_001_0081
Transaction count cannot be decremented as it is already Zero.
IU_001_0082
Used count cannot be decremented as it is already Zero.
IU_001_0083
Both sites and Ad Tags cannot be specified.
IU_001_0084
Error in fetching Ad Tags for Sites.
IU_001_0085
No AdTag found for the given filters.
IU_001_0087
ID cannot be given in the input while Creating/Updating a product.
IU_001_0088
Invalid site names.
IU_001_0089
Site names cannot exceed 255 characters.
IU_001_0090
Invalid Site names specified.
IU_001_0091
Invalid Tags.
IU_001_0092
Tags cannot exceed 255 characters.
IU_001_0093
Invalid Tags specified. Only alpha-numeric characters are allowed.
IU_001_0095
Error in validating Platforms.
IU_001_0096
Invalid Platforms passed.
IU_001_0097
Invalid VAST versions passed.
IU_001_0098
Invalid Minimum Ad duration passed.
IU_001_0099
Invalid Maximum Ad duration passed.
IU_001_0100
Maximum Ad duration cannot be less than Minimum Ad duration.
IU_001_0101
Invalid VPAID compliance versions passed.
IU_001_0102
Publisher ID filter is not applicable for this user.
IU_001_0103
Incorrect loggedInOwnerTypeId provided in search operation for Admin
IU_001_0104
Display URL cannot be null or empty.
IU_001_0105
Product category cannot be null or empty.
IU_001_0106
Video filters
IU_001_0107
Each site should contain at least one active ad tag.
IU_001_0108
Multiple Channel types selected or channel type is other than PMP.
IU_001_0109
Platform filter cannot be applied, if ALL sites are selected.
IU_001_0110
Ad Tag filters cannot be applied, if ALL ad tags are selected.
PP_001_0001
Error in fetching Publisher details.
PRD_001_0001
Error while listing products.
CC03_0008
Admin or multiple resource access users need to provide account details. Pass ownerId and ownerType in request body.
CC03_0007
Multiple associated resources found during search operation. Pass loggedInOwnerId and loggedInOwnerTypeId in query parameters.
PKG_002_0001
Null value for package.
PKG_002_0002
Invalid value for Package ID.
PKG_002_0003
Invalid value for ID.
PKG_002_0004
Invalid value for Package Owner Type.
PKG_002_0005
Invalid value for Package Owner ID.
PKG_002_0006
Error while fetching data for product.
PKG_002_0007
No data available for given product.
PKG_002_0008
Package owner type is not same as that of inventory unit owner.
PKG_002_0009
Package owner is not same as that of inventory unit.
PKG_002_0010
Error occurred while saving the package.
PKG_002_0011
Offer name is not provided.
PKG_002_0012
End date is not provided for package.
PKG_002_0013
Start date is not provided for package.
PKG_002_0014
Owner type is not provided for package.
PKG_002_0015
Owner id is not provided for package.
PKG_002_0016
Entity type ID is required to create relation between entity and package.
PKG_002_0017
Package ID is required to create relation between entity and package.
PKG_002_0018
Entity ID is required to create relation between entity and package.
PKG_002_0019
Package ID is required to create relation between package and channel.
PKG_002_0020
Channel ID is required to create relation between package and channel.
PKG_002_0021
Description is required to create package. It is not provided.
PKG_002_0022
Positive eCPM must be provided for a package.
PKG_002_0023
Positive impressions must be provided for a package.
PKG_002_0024
Error occurred while getting package details.
PKG_002_0025
Invalid user ID is passed.
PKG_002_0026
Invalid ID passed for the package. It is required to edit it.
PKG_002_0027
End date is not provided for the package.
PKG_002_0028
End date cannot be before Start date.
PKG_002_0029
Internal error occurred. Please contact support@pubmatic.com.
PKG_002_0030
No data available for package with given ID.
PKG_002_0031
Start date cannot be modified once it is already passed. Consider shortning the end date.
PKG_002_0032
Error in package update operation.
PKG_002_0033
IU ID cannot be changed.
PKG_002_0034
Owner ID and type for the package cannot be changed.
PKG_002_0035
No associated resources found for the user.
PKG_002_0036
Required package data was not received with the request.
PKG_002_0037
Package category is not passed in the request. It is required.
PKG_002_0038
Error occurred while deleting package.
PKG_002_0039
Positive minimum spend must be provided for a package.
PKG_002_0040
Maximum length allowed for name is 256 characters.
PKG_002_0041
Maximum length allowed for description is 512 characters.
PKG_002_0042
Package category cannot be less than 1. Please assign 1 (Not Applicable) if don't want any category assigned to this package.
PKG_002_0043
Notes cannot have more than 45 characters.
PKG_002_0044
KeyWords cannot have more than 255 characters.
PKG_002_0045
Maximum eCPM allowed is 999.99.
PKG_002_0046
End date is already gone.
PKG_002_0047
Maximum length allowed for logo path is 256 characters.
PKG_002_0048
Invalid user type.
PKG_002_0049
Start date is already gone.
PKG_002_0050
Invalid value for keywords.
PKG_002_0051
Please pass valid resource type for the user.
PKG_002_0052
Error in fetching publishers having packages.
PKG_002_0053
Invalid Offer name.
PKG_002_0054
Error occurred while setting Offer owner information.
PKG_002_0055
Offer name already exists. Please use another name.
PKG_002_0056
Error occurred while validating Offer Category.
PKG_002_0057
Invalid Offer category.
PKG_002_0058
Product ID is not passed.
PKG_002_0059
eCPM can have values between $0 to $999.99 only.
PKG_002_0060
Value for Offer Spend cannot be not less than $0.
PKG_002_0061
Value for Offer Minimum Spend cannot be not less than $0.
PKG_002_0062
Invalid Currency ID passed.
PKG_002_0063
End date for Offer not specified.
PKG_002_0064
Invalid start date passed. Start date cannot be earlier than today.
PKG_002_0065
Invalid start and end dates. End date cannot be earlier than start date.
PKG_002_0066
Invalid Offer name. Following characters are not allowed : |!{}[]^"~*?:;+\\
PKG_002_0067
Invalid Offer description. Following characters are not allowed : |!{}[]^"~*?:;+\\
PKG_002_0068
Keywords can have upto 255 characters only.
PKG_002_0069
Invalid keywords specified. Only alpha-numeric characters are allowed. Multiple keywords should be comma separated.
PKG_002_0070
Start date for Offer not specified.
PKG_002_0071
Invalid end date passed. End date cannot be earlier than today.
PKG_002_0072
Invalid DSP IDs passed.
PKG_002_0073
Invalid Buyer IDs passed.
PKG_002_0074
Please mention Offer Start and End Dates.
PKG_002_0075
Targeting ID is not passed.
PKG_002_0076
Error occurred while validating Product ID.
PKG_002_0077
Value for Impressions cannot be not less than 0.
PKG_002_0078
Invalid Product ID passed.
PKG_002_0079
Error occurred while validating Targeting ID.
PKG_002_0080
Invalid Targeting ID passed.
PKG_002_0081
Invalid Timezone ID passed.
PKG_002_0082
Error while fetching offer information. Incorrect number of active Offer versions found.
PKG_002_0083
Error while fetching offer version information.
PKG_002_0084
No Offer found for given ID.
PKG_002_0085
Error occurred in fetching Offer details.
PKG_002_0086
Invalid logo path URL.
PKG_002_0087
User does not have access to given Product ID.
PKG_002_0088
User does not have access to given Targeting ID.
PKG_002_0089
Invalid channel ID(s) passed.
PKG_002_0090
Error occurred while updating Offer info.
PKG_002_0091
Offer owner is not the same as Product owner.
PKG_002_0092
Offer owner is not the same as Targeting owner.
PKG_002_0093
ID field should not be populated in Create or Update Offer request.
PKG_002_0094
Publisher ID filter is not available for this user.
PKG_002_0095
Incorrect loggedInOwnerTypeId provided in search operation for Admin.
PKG_002_0096
Error in validating product for PMP channel.
PKG_002_0097
All the sites or Ad Tags in the selected Product are not RTB enabled.
PKG_002_0098
Sites belonging to selected ad tags are not RTB enabled.
PKG_002_0099
Mobile targeting parameters cannot be selected for inventory belonging to non-Mobile platform.
PKG_002_0100
Video targeting parameters cannot be selected for non-Video Ad tags.
PKG_002_0101
Error in updating Offer used count.
PKG_002_0102
Invalid Boolean value passed for updating Offer used count.
PKG_002_0103
Offer used count cannot be decremented further.
PKG_002_0104
Maximum length allowed for notes is 512 characters.
PKG_002_0105
Invalid Offer notes. Following characters are not allowed : |!{}[]^"~*?:;+\\
PKG_002_0106
Invalid Advertiser IDs passed.
PKG_002_0107
Invalid value passed in Percentage Avails.
PKG_002_0109
Invalid transaction end date passed. End date cannot be earlier than today.
PKG_002_0111
Invalid transaction start and end dates. End date cannot be earlier than start date.
PKG_002_0112
Invalid transaction start date passed. Start date cannot be earlier than today.
PKG_002_0113
Transaction start date cannot be earlier than Offer start date.
PKG_002_0115
Error fetching Ad Tags information for Offer.
PKG_002_0116
Error while fetching inventory estimated impressions.
PKG_002_0117
Channel is not provided. Please provide the same.
PKG_002_0118
Invalid number of channels passed. Please select a channel.
PKG_002_0119
All type of channels are not allowed. Please select a valid channel.
PKG_002_0120
Please mention Transaction Start and End Dates.
PKG_002_0121
Please mention ecpm for the offer.
TU_001_0001
Invalid targeting ID.
TU_001_0002
Invalid user ID.
TU_001_0003
Name cannot exceed 250 characters.
TU_001_0004
Description cannot exceed 250 characters.
TU_001_0005
Invalid or null value for Owner Type field.
TU_001_0006
Invalid owner ID.
TU_001_0007
Invalid or null value for Publisher ID.
TU_001_0008
Error in validating publisher information.
TU_001_0009
Invalid or null value for Owner Type field.
TU_001_0010
Invalid Audience Segments selected.
TU_001_0011
Invalid Geos selected.
TU_001_0012
Internal error in validating selected Geos.
TU_001_0013
Invalid Browser IDs passed.
TU_001_0014
Invalid Mobile OS IDs passed.
TU_001_0015
Invalid Platform IDs passed.
TU_001_0016
Invalid Connection type IDs passed.
TU_001_0017
Invalid Mobile Device Type IDs passed.
TU_001_0018
Invalid Mobile Carrier IDs passed.
TU_001_0019
Invalid Phone Type IDs passed.
TU_001_0020
Invalid Video Playback Method IDs passed.
TU_001_0021
Invalid Video Position IDs passed.
TU_001_0022
Invalid Mobile OS type IDs passed.
TU_001_0023
Invalid Geo IDs passed.
TU_001_0024
Invalid Mobile Device IDs passed.
TU_001_0025
Invalid Video Type IDs passed.
TU_001_0026
Invalid Resource Type found for logged in user.
TU_001_0027
Mobile OS IDs are not mapped to Mobile OS Type IDs.
TU_001_0028
Mobile Device IDs are not mapped to Mobile device Type IDs.
TU_001_0029
Invalid Days Of Week IDs passed.
TU_001_0030
Invalid Device ID Types passed.
TU_001_0031
Targeting creation failed
TU_001_0032
End time parting cannot be before start time parting.
TU_001_0033
Targeting name already exists. Please use another name.
TU_001_0034
Demand Partner/ATD not supported.
TU_001_0035
Invalid Targeting name. Following characters are not allowed : |!{}[]^"~*?:;+\\
TU_001_0036
Invalid Targeting description. Following characters are not allowed : |!{}[]^"~*?:;+\\
TU_001_0037
Invalid Pixels passed.
TU_001_0038
Targeting name cannot be null.
TU_001_0039
No targeting found for given targeting ID.
TU_001_0040
Error in fetching targeting details.
TU_001_0041
User does not have access to update targeting.
TU_001_0042
ID should not be a part of create/update targeting request.
TU_001_0043
Publisher ID filter is not applicable for this user.
TU_001_0044
Incorrect loggedInOwnerTypeId provided in search operation for Admin.
TU_001_0045
Invalid Rich Media Technology ID passed.
TU_001_0046
Targeting cannot be edited as it is already used in a transaction entity.
TU_001_0047
Some audience IDs are disabled. Please contact the support team to resolve the same.
TU_001_0048
Invalid Smartphone IDs passed.
TU_001_0049
Invalid Tablets IDs passed.
DC_002_0001
Invalid DSP IDs passed
DC_002_0002
Invalid Buyer IDs passed

Attachments

    Outcomes