Automated Guaranteed (AG) Orders API

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

Orders are the collection of line items that are being purchased by a buyer from a seller. The order is an ultimate agreement between the two parties as to what is being purchased at what price and with what details. Orders are collections of line items (or a single line item), that will all be trafficked within each line item's specified details.

 

To create an order, line items are added by picking offers and refining the offer with any further refinements, or left as is. For example, if an offer is an on-going offer with no end date, the line item must refine the date range down to have an end date. Additionally, further targeting can be narrowed down such as geography or platforms/devices. However, a line item cannot go beyond the available targeting specified in the offer. For example, if an offer was created for availability with the United States, a line item may refine that down to the state of California, but it may not expand it to Australia. 

 

Orders may be created and proposed by publishers or by buyers. Upon creation, the order is assigned a state. The state of the order is what controls the resulting negotiation process. Refer to the Order Negotiation Workflow Diagram.

 

Methods

                                                                                 

Method Path
HTTP Method Type
Description
Link to Definition
/agorders
POST
Create a new offer in PubMatic
Creating an AG Order 
/agorders/{id}PUTUpdate the details of a specific offerUpdating an AG Order
/agorders/{id}
GET
Retrieve the details of a specific offer
Retrieving Details of an AG Order
/agorders/{id}PATCHPatch an order using RFC 6902. Currently only order status can be patchedPatching an AG Order
/agorders

GET

Retrieve a page of orders

Retrieving a List of AG Orders

/agorders/{id}/revision/{revId}

GET

Retrieve an order revision by ID

Retrieving an order revision by Revision ID

/agorders/{id}/revisions

GET

Retrieve a paged list of order revisions by order id

Retrieve a list of order revisions by order ID

/agorders/changerequests

POST

Create a Change Request

Adding a change request

/agorders/{id}/changerequests

GET

Retrieve an order's in-progress change request by order ID. Returns null if such a change request does not exist or is not visible to the requesting party

Retrieve an Order's In-Progress Change Request

/agorders/cancellation

POST

Create an order cancellation request

Canceling an Order

/agorders/cancellation/{id}

PUT

Update an order cancellation request

Updating an Order Cancellation

/agorders/{id}/notes

POST

Add a note to an order

Add a Note to an Order

 

Creating an AG Order

Overview

This API allows you to create an AG Order in PubMatic. Line Items may be created at the time of Order Creation or through an Order Update.

Request

           
URIHTTP Method
$URI_PREFIX/agordersPOST

Request Headers

                               
Header Name
Type
Value
Required
Description
pubTokenString${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

resourceIdLong YesResource ID (Owner ID)
resourceTypeIdLong YesType of Resource (e.g., Publisher = 1, Demand Partner = 5)

Request Body Parameters

                                                                                                                                                                                                                     
Body Parameter
Type
Required
Validations
Description
adServerOrderIdIntegerNo 

Ad Server Order ID

advertiserStringYes Advertiser Name
agencyStringNo Agency Name
associateIdIntegerYesAssociate ID should be validAssociate ID
associateTypeIdIntegerYes

Restricted to Publishers,

Resource Type ID should be valid

Resource Type ID

(e.g., Publisher=1; Demand Partner=5)

brandIdIntegerNo Brand ID
brandTypeIntegerNo Brand Type ID
buyerCampaignStringNo Campaign Name
buyerContactContactInfoNoValid email formatContact Email for the buyer
buyerIdIntegerNo Buyer ID
buyerTypeShortNo Buyer Type
creativeContactContactInfoNovalid emailContact email for the owner of the creative
descriptionStringNo  
extOrderIdIntegerNo External Order ID
idIntegerYes Order ID
internalNoteStringNo Notes added for internal purposes
lineItemsArray of JSON ObjectYes See Line Items section for details
nameString  Order Name
nameOfSignatureStringNo Name of Signature
ownerIdInteger Yes Owner ID should be validOwner ID
ownerTypeIdIntegerYes

Valid Resource Type ID. 

Restricted to demand partners

Resource Type ID

Example, For Demand Partner resource type

ownerTypeId=5

publisherContactContactInfoNoValid email formatContact Email for the Publisher
signatureDateStringNo Signature Date
termUrlURLNo URL of terms and conditions
timezoneIdIntegerNo Time Zone ID
descriptionStringNo Order description
buyerTypeShortNo Buyer Type
buyerIdIntegerYes Buyer ID
statusStringYesDRAFT

Status of order.

Sample Request JSON

    

{
    "adServerOrderId": null,
    "advertiser": "MY RUNNER\u0027S UNIVERSE",
    "agency": "Demo - PM General",
    "associateId": 31445,
    "associateTypeId": 1,
    "buyerId":6516,
    "buyerCampaign": "Offers Demo 2015",
    "deleted": false,
    "description": "Test Description",
    "lineItems": [
    {
      "associateId": 31445,
      "associateTypeId": 1,
      "costType": "CPC",
      "creativeRequired": true,
      "creatives": [],
      "endDate": "2016-09-05",
      "name": "new test line item 8-16-444",
      "offer": null,
      "offerId": 18,
      "optlock": 0,
      "ownerId": 737,
      "ownerTypeId": 5,
      "predecessorId": null,
      "priceAmount": 6,
      "priceCurrency": "USD",
      "quantity": 50000,
      "startDate": "2016-08-29",
      "status": null,
      "targeting": "",
      "timezone": 0
    }
    ],
    "name": "new test order 8-16-444",
    "nameOfSignature": "John the Signer",
    "ownerId": 737,
    "ownerTypeId": 5,
    "status": "DRAFT",
    "timezoneId": null
}

Response

 

Sample Response JSON

    

{
  "acceptedTime": null,
  "adServerOrderId": null,
  "advertiser": "MY RUNNER'S UNIVERSE",
  "associateId": 31445,
  "associateTypeId": 1,
  "brandId": null,
  "brandType": null,
  "buyerCampaign": "Offers Demo 2015",
  "buyerContact": null,
  "buyerId": 6516,
  "buyerType": 0,
  "changeRequest": false,
  "changeRequests": [],
  "creationTime": "2016-08-16T18:25:23.692Z",
  "creativeContact": null,
  "description": "Test Description",
  "draftEditedByOtherSide": false,
  "endDate": "2016-09-05",
  "extOrderId": null,
  "hasInProgressChangeRequest": false,
  "id": 239,
  "internalNote": null,
  "lineItems": [
    {
      "adServerLiId": null,
      "assocAdvertisers": null,
      "assocDemandPartners": null,
      "associateId": 31445,
      "associateTypeId": 1,
      "costType": "CPC",
      "creationTime": "2016-08-16T18:25:23.699Z",
      "creativeRequired": true,
      "creatives": [],
      "endDate": "2016-09-05",
      "id": 232,
      "modificationTime": "2016-08-16T18:25:23.699Z",
      "name": "new test line item 8-16-555",
      "offer": {
        "id": 18,
        "name": "145885582",
        "description": "145885582",
        "ownerId": 31445,
        "ownerTypeId": 1,
        "associateId": null,
        "associateTypeId": null,
        "tags": "145885582",
        "currency": "USD",
        "priceAmount": 12,
        "minSpendAmount": 6000,
        "publicRateCardAmount": 15,
        "costType": "CPM",
        "status": "ACTIVE",
        "productId": 15300,
        "product": {
          "id": 15300,
          "name": "QQQQ",
          "description": "QQQQ",
          "deleted": false,
          "adSizes": [
            {
              "id": 7,
              "name": "Leaderboard-728X90",
              "width": 728,
              "height": 90,
              "uri": "http://localhost:7070/common/adSize/7"
            }
          ],
          "adServerInventoryUnits": [
            {
              "id": 12,
              "name": "ca-pub-4798227666512375:",
              "uri": "http://localhost:7070/inventory/adserverinventory/12",
              "adserverConfId": 1,
              "iuType": 1,
              "externalId": "14671365"
            }
          ]
        },
        "maxDailyImpressions": 10000,
        "url": "google.com",
        "logoPath": "http://apps.pubmatic.com/AdGainMgmt/publisher/images/31445.png",
        "userGeneratedContent": false,
        "creativeTypes": [
          "JPG",
          "GIF"
        ],
        "creationTime": "2016-03-24T21:44:06Z",
        "modificationTime": "2016-03-24T21:44:06Z",
        "viewStartDate": "2016-03-24",
        "viewEndDate": "2018-01-01",
        "runStartDate": "2016-03-24",
        "runEndDate": "2018-01-01",
        "notes": null,
        "publisherEmail": "test_lpederson@triadretail.com",
        "targeting": "",
        "offerVisibilityMapping": [
          {
            "demandPartner": {
              "id": 737,
              "name": "Adazzle",
              "uri": "http://localhost:7070/common/advertisingEntity/737"
            },
            "buyers": [
              {
                "id": 0,
                "name": null,
                "uri": null,
                "dspBuyerId": null
              }
            ]
          }
        ]
      },
      "offerId": 18,
      "optlock": 0,
      "orderId": 239,
      "ownerId": 737,
      "ownerTypeId": 5,
      "predecessorId": null,
      "priceAmount": 6,
      "priceCurrency": "USD",
      "quantity": 50000,
      "startDate": "2016-08-29",
      "status": null,
      "targeting": "",
      "timezone": 0
    }
  ],
  "live": false,
  "majorVersion": 0,
  "modificationTime": "2016-08-16T18:25:23.692Z",
  "name": "new test order 8-16-555",
  "nameOfSignature": "John the Signer",
  "notes": [],
  "optlock": 0,
  "orderCancellations": [],
  "ownerId": 737,
  "ownerTypeId": 5,
  "predecessorId": null,
  "publisherContact": {
    "id": 396,
    "optlock": 0,
    "type": "PUBLISHER",
    "name": "",
    "email": "test_lpederson@triadretail.com",
    "phone": null,
    "creationTime": "2016-08-16T18:25:23.696Z",
    "modificationTime": "2016-08-16T18:25:23.696Z"
  },
  "replacingOrderId": null,
  "revisionId": null,
  "rootId": null,
  "sellerId": null,
  "sellerType": 0,
  "signatureDate": null,
  "startDate": "2016-08-29",
  "status": "DRAFT",
  "statusReason": null,
  "successors": [],
  "termUrl": null,
  "timezoneId": null,
  "totalCostAmount": 300000,
  "totalCostCurrency": "USD",
  "updatingOwnerTypeId": 5
}

Response Code

           

TypeDescription
200OK

Error Codes

                       

Status

Error Message

Description

400

Bad Request

There is some validation failure; check the response body for error details.

401

Unauthorized

Authentication or Authorization failure. Check the response body for specific details.

403

Forbidden

You are not subscribed to this feature of the Platform.

 

 

Updating an AG Order

Overview

This API allows you to update details of an existing order, including adding Line Items.

 

Request

           

URI
HTTP Method
$URI_PREFIX/agorders/{id}
PUT

Request Headers

                               

Header Name
Type
Value
Required
Description
pubToken
String
${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

resourceIdInteger YesResource ID
resourceTypeIdInteger YesType of Resource (Publisher = 1, Demand Partner = 5)

Path Parameters

               

Parameter Name

Type

Required

Description

id

Long

Yes

ID of the Order to be updated

Request

Request Body Parameters

                                                                                                                                        

Body Parameter
Type
Required
Validations
Description
ownerId
Integer
 Yes
Owner ID should be valid. Value should already exist in the system.
ID of the owner.
ownerTypeId
Integer
Yes
Publishers = 1, Demand Partners = 5
Type of Owner
associateId
Integer
Yes 
Associate ID should be valid
Associate ID
associateTypeId
Integer
Yes
ID should be valid
Resource Type ID of the other party 
Example:
If the update is being made by the publisher (Type = 1) then the associateTypeId will be for the Demand Partner (Type = 5)
name
String
Yes
 
Name of the order
description
String
No
 
Description of the order
sellerId
Integer
No
 
Seller ID
buyerId
Integer
Yes 
Buyer ID
brandId
Integer
No
 
Brand ID
optlockIntegerYes 

Used in update operation. Number represents version and prevents overriding other edits during update.

status
String
Yes
DRAFT, PROPOSED, APPROVED
Status of order.
agency
String
No
 
Agency Name
advertiser
String
No
 
Advertiser Name
buyerCampaign
String
No
 
 
signatureDate
String
No
 
Signature date
nameOfSignature
String
No
 
Name of signature
termUrlURLYesURL of Terms & Conditions that apply to the OrderTerms of the Order
lineItemsArray of JSON ObjectYesArray of valid Line Item DetailsLine Item(s) associated with the Order

Sample Request JSON

    

{
  "adServerOrderId": null,
  "advertiser": "RUNNER'S UNIVERSE",
  "associateId": 737,
  "associateTypeId": 5,
  "brandId": null,
  "brandType": null,
  "buyerCampaign": "Campaign 1234",
  "buyerContact": null,
  "buyerId": 6516,
  "buyerType": 0,
  "creativeRequired": true,
      "creatives": [{
          "creativeId": 35
      }],
  "creativeContact": null,
  "description": "Test Description",
  "endDate": "2016-07-15",
  "extOrderId": null,
  "id": 189,
  "internalNote": null,
  "lineItems": [
    {
      "adServerLiId": null,
      "assocAdvertisers": null,
      "assocDemandPartners": null,
      "associateId": 737,
      "associateTypeId": 5,
      "costType": "CPC",
      "creativeRequired": true,
      "creatives": [],
      "id": 189,
      "name": "Runners Line Item",
      "offer": null,
      "offerId": 18,
      "optlock": 0,
      "orderId": 189,
      "ownerId": 31445,
      "ownerTypeId": 1,
      "priceAmount": 1,
      "priceCurrency": "USD",
      "quantity": 6000,
      "status": null,
      "targeting": "",
      "timezone": 0
    }
  ],
  "name": "CR Order",
  "nameOfSignature": "John Signer",
  "notes": [],
  "optlock": 0,
  "orderCancellations": [],
  "ownerId": 31445,
  "ownerTypeId": 1,
  "publisherContact": {
    "id": 331,
    "optlock": 0,
    "type": "PUBLISHER",
    "name": "",
    "email": "test_lpederson@triadretail.com",
    "phone": null
  },
  "replacingOrderId": null,
  "revisionId": null,
  "sellerId": null,
  "sellerType": 0,
  "status": "PROPOSED",
  "statusReason": null,
  "successors": [],
  "termUrl": "http://www.mydomain.com",
  "timezoneId": null,
  "updatingOwnerTypeId": 1

}

Response

Response Body

           

Type
Description
AG Order Object
JSON response of newly created AG Order.

Sample Response JSON

    

{
  "acceptedTime": null,
  "adServerOrderId": null,
  "advertiser": "RUNNER'S UNIVERSE",
  "associateId": 737,
  "associateTypeId": 5,
  "brandId": null,
  "brandType": null,
  "buyerCampaign": "Campaign 1234",
  "buyerContact": null,
  "buyerId": 6516,
  "buyerType": 0,
  "changeRequest": false,
  "changeRequests": [],
  "creationTime": "2016-07-14T19:57:32Z",
  "creativeContact": null,
  "description": "New Description",
  "draftEditedByOtherSide": false,
  "endDate": "2016-07-15",
  "extOrderId": null,
  "hasInProgressChangeRequest": false,
  "id": 189,
  "internalNote": null,
  "lineItems": [
    {
      "adServerLiId": null,
      "assocAdvertisers": null,
      "assocDemandPartners": null,
      "associateId": 737,
      "associateTypeId": 5,
      "costType": "CPC",
      "creationTime": "2016-07-14T19:57:32Z",
      "creativeRequired": true,
     "creatives": [
        {
          "id": 42,
          "optlock": 0,
          "creationTime": "2016-07-11T20:31:04Z",
          "modificationTime": "2016-07-11T20:31:04Z",
          "height": 0,
          "width": 0,
          "creativeId": 35
        }
      ],
      "endDate": "2016-07-15",
      "id": 189,
      "modificationTime": "2016-07-14T19:57:32Z",
      "name": "Runners Line Item",
      "offer": null,
      "offerId": 18,
      "optlock": 0,
      "orderId": 189,
      "ownerId": 31445,
      "ownerTypeId": 1,
      "predecessorId": null,
      "priceAmount": 1,
      "priceCurrency": "USD",
      "quantity": 6000,
      "startDate": "2016-07-14",
      "status": null,
      "targeting": "",
      "timezone": 0
    }
  ],
  "live": false,
  "majorVersion": 2,
  "modificationTime": "2016-07-14T19:59:45.923Z",
  "name": "CR Order",
  "nameOfSignature": "John Signer",
  "notes": [],
  "optlock": 1,
  "orderCancellations": [],
  "ownerId": 31445,
  "ownerTypeId": 1,
  "predecessorId": null,
  "publisherContact": {
    "id": 331,
    "optlock": 0,
    "type": "PUBLISHER",
    "name": "",
    "email": "test_lpederson@triadretail.com",
    "phone": null,
    "creationTime": "2016-07-14T19:57:32Z",
    "modificationTime": "2016-07-14T19:57:32Z"
  },
  "replacingOrderId": null,
  "revisionId": null,
  "rootId": null,
  "sellerId": null,
  "sellerType": 0,
  "signatureDate": "2016-06-28T10:40:52Z",
  "startDate": "2016-07-14",
  "status": "PROPOSED",
  "statusReason": null,
  "successors": [],
  "termUrl": "http://www.google.com",
  "timezoneId": null,
  "totalCostAmount": 6000,
  "totalCostCurrency": "USD",
  "updatingOwnerTypeId": 5
}

Response Code

           

TypeDescription
200OK

Error Codes

                       

Status

Error Message

Description

400

Bad Request

There is some validation failure; check the response body for error details.

401

Unauthorized

Authentication or Authorization failure. Check the response body for specific details.

403

Forbidden

You are not subscribed to this feature of the Platform.

 

Retrieving Details of an AG Order

Overview

This API allows you to retrieve details of a specific order.

Request

           
URIHTTP Method
$URI_PREFIX/agorders/{id}GET

Request Headers

                               
Header Name
Type
Value
Required
Description
pubTokenString${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

resourceIdInteger YesResource ID (Owner ID)
resourceTypeIdInteger YesType of Resource (e.g., Publisher = 1, Demand Partner = 5)

Path Parameters

               
Parameter Name
Type
Required
Description
 idLong Yes Order ID for which details need to extracted 

Sample Request URL:

GET $URI_PREFIX/agorders/{id}

Response

Sample Response JSON

{
  "acceptedTime": null,
  "adServerOrderId": null,
  "advertiser": " 24",
  "associateId": 737,
  "associateTypeId": 5,
  "brandId": null,
  "brandType": null,
  "buyerCampaign": "buyer1_campaign",
  "buyerContact": {
    "id": 287,
    "optlock": 0,
    "type": "BUYER",
    "name": "BUYER",
    "email": null,
    "phone": null,
    "creationTime": "2016-06-28T14:34:41Z",
    "modificationTime": "2016-06-28T14:34:41Z"
  },
  "buyerId": 6516,
  "buyerType": 0,
  "changeRequest": false,
  "changeRequests": null,
  "creationTime": "2016-06-28T14:34:41Z",
  "creativeContact": null,
  "description": null,
  "draftEditedByOtherSide": false,
  "endDate": "2016-06-30",
  "extOrderId": null,
  "hasInProgressChangeRequest": false,
  "id": 154,
  "internalNote": null,
  "lineItems": [
    {
      "adServerLiId": null,
      "assocAdvertisers": null,
      "assocDemandPartners": null,
      "associateId": 737,
      "associateTypeId": 5,
      "costType": "CPM",
      "creationTime": "2016-06-28T14:35:36Z",
      "creativeRequired": true,
      "creatives": [],
      "endDate": "2016-06-30",
      "id": 170,
      "modificationTime": "2016-06-30T12:14:35Z",
      "name": "hiohio$#^#:\"\"P{WEQR()",
      "offer": null,
      "offerId": 39,
      "optlock": 2,
      "orderId": 154,
      "ownerId": 31445,
      "ownerTypeId": 1,
      "predecessorId": null,
      "priceAmount": 200.88,
      "priceCurrency": "USD",
      "quantity": 78998,
      "startDate": "2016-06-30",
      "status": null,
      "targeting": "(country = (2840)) & (os = (501012,501013)) & (bandwidth = (1,2,3,4,5,6,7,8,9,10))",
      "timezone": 0
    }
  ],
  "live": false,
  "majorVersion": 0,
  "modificationTime": "2016-06-28T22:08:08Z",
  "name": "hiohoi#!@@!$#@!%#@%#@",
  "nameOfSignature": null,
  "notes": [],
  "optlock": 1,
  "orderCancellations": [],
  "ownerId": 31445,
  "ownerTypeId": 1,
  "predecessorId": null,
  "publisherContact": {
    "id": 286,
    "optlock": 0,
    "type": "PUBLISHER",
    "name": "PUBLISHER",
    "email": null,
    "phone": null,
    "creationTime": "2016-06-28T14:34:41Z",
    "modificationTime": "2016-06-28T14:34:41Z"
  },
  "replacingOrderId": null,
  "revisionId": null,
  "rootId": null,
  "sellerId": null,
  "sellerType": 0,
  "signatureDate": null,
  "startDate": "2016-06-30",
  "status": "DRAFT",
  "statusReason": null,
  "successors": [],
  "termUrl": null,
  "timezoneId": null,
  "totalCostAmount": 15869.11824,
  "totalCostCurrency": "USD",
  "updatingOwnerTypeId": 1
}

Response Code

           

TypeDescription
200OK

Response Header

             
Response Header Name
Type
Description
content-Typeapplication/jsonMedia type that is to be returned in search/sort operation

Error Codes

                       

Status

Error Message

Description

 400

Bad Request

There is some validation failure; check the response body for error details.

 401

Unauthorized

Authentication or Authorization failure. Check the response body for specific details.

 403

Forbidden

You are not subscribed to this feature of the Platform.

 

 

Patching an AG Order

Overview

This API allows you to do a partial update of an Order. Currently, only status can be patched using this API. 

Request

           
URIHTTP Method
$URI_PREFIX/agordersPATCH

Request Headers

                               
Header Name
Type
Value
Required
Description
pubTokenString${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

resourceIdLong YesResource ID (Owner ID)
resourceTypeIdLong YesType of Resource (e.g., Publisher = 1, Demand Partner = 5)

Path Parameter

               

ParameterTypeValidationsDescription
idIntegerValid Order IDID of the Order to be updated

Request Body Parameters

                               
Body Parameter
Type
Required
Validations
Description
opStringYesreplaceOperation to be performed
pathStringYes/statusField for which the value will be updated
valueStringYes

Valid value for the path (e.g., "PROPOSED")

Value to be entered in the path

Sample Request JSON

 [
{ "op": "replace",
"path": "/status",
"value": "PROPOSED" }
]

Response

 

Sample Response JSON

no content

Response Code

           

TypeDescription
200OK

Error Codes

                       

Status

Error Message

Description

400

Bad Request

There is some validation failure; check the response body for error details.

401

Unauthorized

Authentication or Authorization failure. Check the response body for specific details.

403

Forbidden

You are not subscribed to this feature of the Platform.

 

 

Retrieving a List of AG Orders

Overview

This API provides a list of Orders from PubMatic.

Request

           

URI
HTTP Method
$URI_PREFIX/agorders/
GET

Request Headers

                               

Header Name
Type
Value
Required
Description
pubToken
String
${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

resourceIdInteger YesResource ID (Owner ID)
resourceTypeIdInteger YesType of Resource (e.g., Publisher = 1, Demand Partner = 5) 

Request Query Parameters

                                 

Parameter Name

Type

Required

Description

filters

Array [String]

No

Filters list, filter syntax:[field operation value], valid operations: eq noteq like notlike. See Filter Parameter Details for more information.

sortArray [String]Nosyntax: -?(,-?properyName)* where propertyName := name|description|creationTime|modificationTime|acceptedTime|status|advertiser|buyerCampaign|signatureDate|nameOfSignature

pageNumber

Integer

No

The page number the response should begin (in the case of multiple pages). Default value is 1.

pageSize

Integer

No

Maximum number of records to be included in the response. Its default value is 100.

Sample Request URL

GET $URI_PREFIX/agorders/?{pageNumber}&{pageSize}&{sort}&{filters}

Response

Sample Response JSON

    

{
  "items": [
    {
      "acceptedTime": null,
      "adServerOrderId": null,
      "advertiser": "Advert_Co",
      "associateId": 737,
      "associateTypeId": 5,
      "brandId": null,
      "brandType": null,
      "buyerCampaign": "ABC_Campaign",
      "buyerContact": {
        "id": 305,
        "optlock": 0,
        "type": "BUYER",
        "name": "Kantar_Buyer1",
        "email": null,
        "phone": null,
        "creationTime": "2016-07-06T17:34:28Z",
        "modificationTime": "2016-07-06T17:34:28Z"
      },
      "buyerId": 6516,
      "buyerType": 0,
      "changeRequest": false,
      "changeRequests": [],
      "creationTime": "2016-07-06T17:34:28Z",
      "creativeContact": null,
      "description": null,
      "draftEditedByOtherSide": false,
      "endDate": null,
      "extOrderId": null,
      "hasInProgressChangeRequest": false,
      "id": 166,
      "internalNote": null,
      "lineItems": [],
      "live": false,
      "majorVersion": 0,
      "modificationTime": "2016-07-06T17:34:28Z",
      "name": "ABC_Campaign",
      "nameOfSignature": null,
      "notes": [],
      "optlock": 0,
      "orderCancellations": [],
      "ownerId": 31445,
      "ownerTypeId": 1,
      "predecessorId": null,
      "publisherContact": {
        "id": 306,
        "optlock": 0,
        "type": "PUBLISHER",
        "name": "PUBLISHER",
        "email": null,
        "phone": null,
        "creationTime": "2016-07-06T17:34:28Z",
        "modificationTime": "2016-07-06T17:34:28Z"
      },
      "replacingOrderId": null,
      "revisionId": null,
      "rootId": null,
      "sellerId": null,
      "sellerType": 0,
      "signatureDate": null,
      "startDate": null,
      "status": "DRAFT",
      "statusReason": null,
      "successors": [],
      "termUrl": null,
      "timezoneId": null,
      "totalCostAmount": 0,
      "totalCostCurrency": null,
      "updatingOwnerTypeId": 1
    }
  ],
  "metaData": {
    "endIndex": 1,
    "startIndex": 1,
    "totalRecords": 150
  }
}

Response Code

           

TypeDescription
200OK

Response Headers

             

Response Header NameTypeDescription
content-typeapplication/jsonMediatype that is to be returned in search/sort operation
 

Error Codes

                       

Status
Error Message
Description
400
Bad Request
There is some validation failure; check the response body for error details.
401
Unauthorized
Authentication or Authorization failure. Check the response body for specific details.
403
Forbidden
You are not subscribed to this feature of the Platform.

 

 

Retrieving an order revision by Revision ID

 

Overview

This API allows you to retrieve an Order revision by Revision ID

Request

           

URIHTTP Method
$URI_PREFIX/agorders/{id}/revision/{revid}GET

Request Headers

                               

Header NameTypeValueRequiredDescription
pubTokenString${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

resourceIdInteger YesResource ID (Owner ID)
resourceTypeIdInteger YesType of Resource (e.g., Publisher = 1, Demand Partner = 5)

Path Parameters

                     

Parameter TypeType RequiredDescription
idLongYesOrder ID
revIdIntegerYesOrder Revision ID

Sample Request URL

GET $URI_PREFIX/agorders/{id}/revision/{revId}

Response

Sample Response JSON

    

{
  "acceptedTime": null,
  "adServerOrderId": null,
  "advertiser": " American Book Company, Inc",
  "associateId": 737,
  "associateTypeId": 5,
  "brandId": null,
  "brandType": null,
  "buyerCampaign": "CR-CampaignName-1",
  "buyerContact": {
    "id": 315,
    "optlock": null,
    "type": "BUYER",
    "name": "BUYER",
    "email": "buyer.contact@domain.com",
    "phone": null,
    "creationTime": "2016-07-13T15:52:03Z",
    "modificationTime": "2016-07-13T15:52:03Z"
  },
  "buyerId": 6516,
  "buyerType": 0,
  "changeRequest": false,
  "changeRequests": [],
  "creationTime": "2016-07-13T15:52:03Z",
  "creativeContact": null,
  "description": null,
  "draftEditedByOtherSide": false,
  "endDate": null,
  "extOrderId": null,
  "hasInProgressChangeRequest": false,
  "id": 180,
  "internalNote": "These are internal notes",
  "lineItems": [],
  "live": false,
  "majorVersion": 0,
  "modificationTime": "2016-07-13T15:52:03Z",
  "name": "CR-OrderName-1",
  "nameOfSignature": null,
  "notes": [],
  "optlock": null,
  "orderCancellations": [],
  "ownerId": 31445,
  "ownerTypeId": 1,
  "predecessorId": null,
  "publisherContact": {
    "id": 316,
    "optlock": null,
    "type": "PUBLISHER",
    "name": "PUBLISHER",
    "email": "publisher.contact@domain.com",
    "phone": null,
    "creationTime": "2016-07-13T15:52:03Z",
    "modificationTime": "2016-07-13T15:52:03Z"
  },
  "replacingOrderId": null,
  "revisionId": 685,
  "rootId": null,
  "sellerId": null,
  "sellerType": 0,
  "signatureDate": null,
  "startDate": null,
  "status": "DRAFT",
  "statusReason": null,
  "successors": [],
  "termUrl": null,
  "timezoneId": null,
  "totalCostAmount": 0,
  "totalCostCurrency": null,
  "updatingOwnerTypeId": 1
}

Response Code

           

TypeDescription
200OK

Response Header

             
Response Header Name
Type
Description
content-Typeapplication/jsonMedia type that is to be returned in search/sort operation

Error Codes

                       

Status

Error Message

Description

 400

Bad Request

There is some validation failure; check the response body for error details.

 401

Unauthorized

Authentication or Authorization failure. Check the response body for specific details.

 403

Forbidden

You are not subscribed to this feature of the Platform.

Retrieve a List of Order Revisions by Order ID

Overview

This API allows you to retrieve a list of revisions for a specific Order.

Request

           

URIHTTP Method
$URI_PREFIX/agorders/{id}/revisions GET

Request Headers

                               
Header Name
Type
Value
Required
Description
pubTokenString${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

resourceIdInteger YesResource ID (Owner ID)
resourceTypeIdInteger YesType of Resource (e.g., Publisher = 1, Demand Partner = 5)
 

Path Parameters

               
Parameter Name
Type
Required
Description
 idLong Yes Order ID for which revisions need to extracted 

Request Query Parameters

                           
ParameterTypeRequiredDescription
pageNumberIntegerNoThe page number the response should begin (in the case of multiple pages). Default value is 1.

pageSize

IntegerNoMaximum number of records to be included in the response. Its default value is 100.
filtersArray[string]NoFilters list, filter syntax:[field operation value], valid operations: eq noteq like notlike. See Filter Parameter Details for more information.

Sample Request URL

GET $URI_PREFIX/agorders/{id}/revisions?{pageNumber}&{pageSize}

Response

Sample Response JSON

    


{
  "items": [
    {
      "acceptedTime": null,
      "adServerOrderId": null,
      "advertiser": " American Book Company, Inc",
      "associateId": 737,
      "associateTypeId": 5,
      "brandId": null,
      "brandType": null,
      "buyerCampaign": "CR-CampaignName-1",
      "buyerContact": null,
      "buyerId": 6516,
      "buyerType": 0,
      "changeRequest": false,
      "changeRequests": [],
      "creationTime": "2016-07-13T15:52:03Z",
      "creativeContact": null,
      "description": null,
      "draftEditedByOtherSide": false,
      "endDate": null,
      "extOrderId": null,
      "hasInProgressChangeRequest": false,
      "id": 180,
      "internalNote": "These are internal notes",
      "lineItems": [],
      "live": false,
      "majorVersion": 0,
      "modificationTime": "2016-07-13T15:52:03Z",
      "name": "CR-OrderName-1",
      "nameOfSignature": null,
      "notes": [],
      "optlock": null,
      "orderCancellations": [],
      "ownerId": 31445,
      "ownerTypeId": 1,
      "predecessorId": null,
      "publisherContact": null,
      "replacingOrderId": null,
      "revisionId": 685,
      "rootId": null,
      "sellerId": null,
      "sellerType": 0,
      "signatureDate": null,
      "startDate": null,
      "status": "DRAFT",
      "statusReason": null,
      "successors": [],
      "termUrl": null,
      "timezoneId": null,
      "totalCostAmount": 0,
      "totalCostCurrency": null,
      "updatingOwnerTypeId": 1
    }
  ],
  "metaData": {
    "endIndex": 1,
    "startIndex": 1,
    "totalRecords": 3
  }
}




Response Code

           

TypeDescription
200OK

Response Header

             
Response Header Name
Type
Description
content-typeapplication/jsonMedia type that is to be returned in search/sort operation

Error Codes

                       

Status

Error Message

Description

 400

Bad Request

There is some validation failure; check the response body for error details.

 401

Unauthorized

Authentication or Authorization failure. Check the response body for specific details.

 403

Forbidden

You are not subscribed to this feature of the Platform.

 

 

Adding a Change Request

Change requests allow an order to be changed after both parties have approved the order and the contract is effectively signed. 

Change requests apply to elements of an order's line items that need re-approval from both parties before they can be solidified. Such as, price, quantity, start/end date, and targeting. As described on the Creatives page, creatives do not need a change request to be edited since they do not impact the terms agreed upon by both parties. Instead, if the buyer wants to change an already approved and trafficking creative, they need to upload and assign a new creative which will begin trafficking once approved by the publisher. 

For all other elements of an order to be changed, a change request has to occur. A change request goes through the same negotiation process as the original order since all terms have to be re-agreed upon by both parties. 

 

Refer to the diagram, Adding a Change Request in AG, for more information on the flow of a change request.

Overview

This API allows you add a change request to an existing order. To create the change request (CR):

  1. Fetch the live order (PUSHED or ACTIVE status).
  2. Make required modifications but do not modify the order, line item or creative IDs.
  3. Set status to DRAFT or PROPOSED.
  4. Ensure the CR's ownerId and ownerTypeId match the request headers resourceId and resourceTypeId, respectively.
  5. POST the CR to /agorders/changerequests.
  • The response is a new order (including line items, creatives etc) which is linked with the currently live order. This order (CR) will follow through a workflow similar to the one used by the original order. In case it receives approval from both parties it will be pushed into the ad server, effectively updating the live order. In case the CR gets rejected the live order remains unaffected. 
  • Subsequent CRs may be created off of the currently live order (which itself may correspond to a CR). In general, when referring to an order, it can be assumed that it is really an order family which includes the original order and 0 or more CRs, some of which being approved and others rejected.
  • There can only be one in-progress (not pushed yet or rejected) CR at a time, for a given order.
  • There can only be one live order/CR at a time.

Request

           

URIHTTP Method
$URI_PREFIX/agorders/changerequestsPOST

Request Headers

                               

Header NameTypeValueRequiredDescription
pubTokenString${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

resourceIdInteger YesResource ID
resourceTypeIdInteger YesType of Resource (Publisher = 1, Demand Partner = 5)

Path Parameters

               

Parameter Name

Type

Required

Description

id

Long

Yes

ID of the Order the change request applies to

Request

Request Body Parameters

                                                                                              

Body ParameterTypeRequiredValidationsDescription
ownerIdIntegerYesOwner ID should be valid. Value should already exist in the system.ID of the owner.
ownerTypeIdIntegerYes
Valid Owner Type ID. 
Type of Owner (Resource Type ID)  (Publisher = 1, Demand Partner = 5)
associateIdIntegerYes Associate ID should be validAssociate ID
associateTypeIdIntegerYes
Associate Type ID should be valid
Associate Type ID of the other party 
Example: If the update is being made by the publisher (Type = 1) then the associateTypeId will be for the Demand Partner (Type = 5)
nameStringYes Name of the order
descriptionStringNo Description of the order
buyerIdIntegerYes Buyer ID
statusStringYesPENDING or DRAFT
Status of order.
advertiserStringYes Advertiser Name
buyerCampaignStringNo Buyer Campaign Name
termUrlURLYesURL of Terms & Conditions that apply to the OrderTerms of the Order
lineItemsArray of JSON ObjectYesArray of valid Line Item DetailsLine Item(s) associated with the order

Sample Request JSON

    


{
  "adServerOrderId": null,
  "advertiser": " 24",
  "associateId": 737,
  "associateTypeId": 5,
  "buyerContact": {
    "id": 336,
    "type": "BUYER",
    "name": "BUYER",
    "email": "email@pubmatic.com",
    "phone": null
  },
  "buyerId": 6516,
  "creativeContact": null,
  "description": null,
  "extOrderId": null,
  "id": 193,
  "internalNote": null,
  "lineItems": [
    {
      "adServerLiId": null,
      "assocAdvertisers": null,
      "assocDemandPartners": null,
      "associateId": 737,
      "associateTypeId": 5,
      "costType": "CPM",
      "creativeRequired": false,
      "creatives": [
        {
          "id": 50,
          "width": 0,
          "height": 0,
          "creativeId": 36
        }
      ],
      "endDate": "2018-01-01",
      "id": 193,
      "name": "146420908",
      "offer": null,
      "offerId": 36,
      "orderId": 193,
      "ownerId": 31445,
      "ownerTypeId": 1,
      "predecessorId": 157,
      "priceAmount": 678.66,
      "priceCurrency": "USD",
      "quantity": 678667,
      "status": null,
      "targeting": ""
   }
  ],
  "name": "146420908...",
  "notes": [],
  "ownerId": 31445,
  "ownerTypeId": 1,
  "publisherContact": {
    "id": 337,
    "optlock": 0,
    "type": "PUBLISHER",
    "name": "PUBLISHER",
    "email": null,
    "phone": null
  },
  "sellerId": null,
  "sellerType": 0,
  "status": "DRAFT",
  "statusReason": null,
  "termUrl": "http://url.com",
  "updatingOwnerTypeId": 1
}



Response

Sample Response JSON

    

{
  "acceptedTime": "2016-07-18T18:27:01Z",
  "adServerOrderId": null,
  "advertiser": " 24",
  "associateId": 737,
  "associateTypeId": 5,
  "brandId": null,
  "brandType": null,
  "buyerCampaign": "146420908...",
  "buyerContact": {
    "id": 369,
    "optlock": 0,
    "type": "BUYER",
    "name": "BUYER",
    "email": "email@pubmatic.com",
    "phone": null,
    "creationTime": "2016-07-20T17:33:41.463Z",
    "modificationTime": "2016-07-20T17:33:41.463Z"
  },
  "buyerId": 6516,
  "buyerType": 0,
  "changeRequest": true,
  "changeRequests": [],
  "creationTime": "2016-07-20T17:33:41.459Z",
  "creativeContact": null,
  "description": null,
  "draftEditedByOtherSide": false,
  "endDate": "2018-01-01",
  "extOrderId": null,
  "hasInProgressChangeRequest": false,
  "id": 209,
  "internalNote": null,
  "lineItems": [
    {
      "adServerLiId": null,
      "assocAdvertisers": null,
      "assocDemandPartners": null,
      "associateId": 737,
      "associateTypeId": 5,
      "costType": "CPM",
      "creationTime": "2016-07-20T17:33:41.464Z",
      "creativeRequired": false,
      "creatives": [
        {
          "id": 63,
          "optlock": 0,
          "predecessorId": 50,
          "creationTime": "2016-07-20T17:33:41.465Z",
          "modificationTime": "2016-07-20T17:33:41.465Z",
          "rootId": 50,
          "width": 0,
          "height": 0,
          "creativeId": 36
        }
      ],
      "endDate": "2018-01-01",
      "id": 210,
      "modificationTime": "2016-07-20T17:33:41.464Z",
      "name": "146420908",
      "offer": null,
      "offerId": 36,
      "optlock": 0,
      "orderId": 209,
      "ownerId": 31445,
      "ownerTypeId": 1,
      "predecessorId": 157,
      "priceAmount": 678.66,
      "priceCurrency": "USD",
      "quantity": 678667,
      "startDate": "2016-05-25",
      "status": null,
      "targeting": "",
      "timezone": 0
    }
  ],
  "live": false,
  "majorVersion": 0,
  "modificationTime": "2016-07-20T17:33:41.459Z",
  "name": "146420908...",
  "nameOfSignature": null,
  "notes": [],
  "optlock": 0,
  "orderCancellations": [],
  "ownerId": 31445,
  "ownerTypeId": 1,
  "predecessorId": 193,
  "publisherContact": {
    "id": 368,
    "optlock": 0,
    "type": "PUBLISHER",
    "name": "PUBLISHER",
    "email": null,
    "phone": null,
    "creationTime": "2016-07-20T17:33:41.461Z",
    "modificationTime": "2016-07-20T17:33:41.461Z"
  },
  "replacingOrderId": null,
  "revisionId": null,
  "rootId": 137,
  "sellerId": null,
  "sellerType": 0,
  "signatureDate": null,
  "startDate": "2016-05-25",
  "status": "DRAFT",
  "statusReason": null,
  "successors": [],
  "termUrl": "http://url.com",
  "timezoneId": null,
  "totalCostAmount": 460584.14622,
  "totalCostCurrency": "USD",
  "updatingOwnerTypeId": 1
}

Response Code

           

TypeDescription
200OK

Error Codes

                       

Status

Error Message

Description

400

Bad Request

There is some validation failure; check the response body for error details.

401

Unauthorized

Authentication or Authorization failure. Check the response body for specific details.

403

Forbidden

You are not subscribed to this feature of the Platform.

 

 

Retrieve an Order's In-Progress Change Request

Overview

This API allows you to retrieve an order's in-progress change request by Order ID. It will return null if a change request does not exist or is not visible to the requesting party.

Request

           
URIHTTP Method
$URI_PREFIX/agorders/{id}/changerequestsGET

Request Headers

                               
Header Name
Type
Value
Required
Description
pubTokenString${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

resourceIdInteger YesResource ID (Owner ID)
resourceTypeIdInteger YesType of Resource (e.g., Publisher = 1, Demand Partner = 5)

Path Parameters

               
Parameter Name
Type
Required
Description
 idLong Yes Order ID for which details need to extracted 

Sample Request URL:

GET $URI_PREFIX/agorders/{id}/changerequests

Response

Sample Response JSON

{
  "acceptedTime": "2016-04-25T12:39:27Z",
  "adServerOrderId": null,
  "advertiser": " 24",
  "associateId": 737,
  "associateTypeId": 5,
  "brandId": null,
  "brandType": null,
  "buyerCampaign": null,
  "buyerContact": {
    "id": 147,
    "optlock": 0,
    "type": "BUYER",
    "name": "BUYER",
    "email": null,
    "phone": null,
    "creationTime": "2016-04-25T12:39:43Z",
    "modificationTime": "2016-04-25T12:39:43Z"
  },
  "buyerId": 6516,
  "buyerType": 0,
  "changeRequest": true,
  "changeRequests": null,
  "creationTime": "2016-04-25T12:39:43Z",
  "creativeContact": null,
  "description": null,
  "draftEditedByOtherSide": false,
  "endDate": null,
  "extOrderId": null,
  "hasInProgressChangeRequest": false,
  "id": 76,
  "internalNote": null,
  "lineItems": [],
  "live": false,
  "majorVersion": 0,
  "modificationTime": "2016-05-09T15:34:39Z",
  "name": "AMG-1947-Order-1",
  "nameOfSignature": null,
  "notes": [],
  "optlock": 8,
  "orderCancellations": [],
  "ownerId": 31445,
  "ownerTypeId": 1,
  "predecessorId": 74,
  "publisherContact": {
    "id": 146,
    "optlock": 0,
    "type": "PUBLISHER",
    "name": "PUBLISHER",
    "email": null,
    "phone": null,
    "creationTime": "2016-04-25T12:39:43Z",
    "modificationTime": "2016-04-25T12:39:43Z"
  },
  "replacingOrderId": null,
  "revisionId": null,
  "rootId": 74,
  "sellerId": null,
  "sellerType": 0,
  "signatureDate": null,
  "startDate": null,
  "status": "DRAFT",
  "statusReason": null,
  "successors": [],
  "termUrl": "http://www.mydomain.com",
  "timezoneId": null,
  "totalCostAmount": 0,
  "totalCostCurrency": null,
  "updatingOwnerTypeId": 1
}

Response Code

           

TypeDescription
200OK

Response Header

             
Response Header Name
Type
Description
content-typeapplication/jsonMedia type that is to be returned in search/sort operation

Error Codes

                       

Status

Error Message

Description

 400

Bad Request

There is some validation failure; check the response body for error details.

 401

Unauthorized

Authentication or Authorization failure. Check the response body for specific details.

 403

Forbidden

You are not subscribed to this feature of the Platform.

 

 

Canceling an Order

Overview

This API allows you to create an Order Cancellation Request for an AG order in PubMatic. The Cancellation Process includes the following guidelines:

  • To cancel an order, a cancellation request is first be made. Once created by one party (publisher or buyer) it is then subject to approval by the other party. In case it is approved the order is cancelled and the inventory is released, otherwise the order remains unchanged.
  • Only a live (pushed to the ad server and not terminated yet) can be cancelled.
  • Only one in-progress cancellation request can exist at a time. If rejected, another cancellation request can be issued.

Request

           
URIHTTP Method
$URI_PREFIX/agorders/cancellationPOST

Request Headers

                               
Header Name
Type
Value
Required
Description
pubTokenString${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

resourceIdLong YesResource ID (Owner ID)
resourceTypeIdLong YesType of Resource (e.g., Publisher = 1, Demand Partner = 5)

Request Body Parameters

                                                                                
Body Parameter
Type
Required
Validations
Description
idIntegerNoValid Cancellation IDCancellation Request ID
associateIdIntegerYesAssociate ID should be validAssociate ID
associateTypeIdIntegerYes

Resource Type ID should be valid

Resource Type ID

(e.g., Publisher=1; Demand Partner=5)

orderidIntegerYesValid Order IDOrder ID
nameStringYes Order Name
ownerIdIntegerYesOwner ID should be validOwner ID
ownerTypeIdIntegerYes

Valid Resource Type ID

Owner Type ID (e.g., Publisher = 1, Demand Partner = 5)

reasonStringYes Reason for the cancellation request
OrderCancellationStringYes Order Cancellation Name
statusStringNonull

Status of order

Sample Request JSON

 {
      "associateId": 737,
      "associateTypeId": 5,
      "id": null,
      "name": "cancellation",
      "orderId": 96,
      "ownerId": 31445,
      "ownerTypeId": 1,
      "reason": "Cancellation Requested by Publisher ",
      "status": null
    }

Response

Sample Response JSON

{
  "associateId": 737,
  "associateTypeId": 5,
  "creationTime": "2016-07-19T17:52:47.073Z",
  "id": 95,
  "modificationTime": "2016-07-19T17:52:47.073Z",
  "name": "cancellation",
  "optlock": 0,
  "orderId": 96,
  "ownerId": 31445,
  "ownerTypeId": 1,
  "reason": "Cancellation Requested by Publisher ",
  "status": "AWAITING_APPROVAL"
}

Response Code

TypeDescription
200OK

Error Codes

                       

Status

Error Message

Description

400

Bad Request

There is some validation failure; check the response body for error details.

401

Unauthorized

Authentication or Authorization failure. Check the response body for specific details.

403

Forbidden

You are not subscribed to this feature of the Platform.
 

 

 

Updating an Order Cancellation

Overview

This API allows you to create an Update a Cancellation Request for an AG order in PubMatic. The Cancellation process includes the following guidelines:

  • To cancel an order, a cancellation request must first be made. Once created by one party (publisher or buyer) it is then subject to approval by the other party. In case it is approved the order is cancelled and the inventory is released, otherwise the order remains unchanged.
  • Only a live (pushed to the ad server and not terminated yet) can be cancelled.
  • Only one in-progress cancellation request can exist at a time. If rejected, another cancellation request can be issued.

Request

           
URIHTTP Method
$URI_PREFIX/agorders/cancellation/{id}PUT

Request Headers

                               
Header Name
Type
Value
Required
Description
pubTokenString${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

resourceIdLong YesResource ID (Owner ID)
resourceTypeIdLong YesType of Resource (e.g., Publisher = 1, Demand Partner = 5)

Path Parameter

               

ParameterTypeValidationsDescription
idIntegerValid Order Cancellation IDOrder Cancellation ID to be updated

Request Body Parameters

                                                                                
Body Parameter
Type
Required
Validations
Description
idIntegerNoValid Cancellation IDCancellation Request ID
associateIdIntegerYesAssociate ID should be validAssociate ID
associateTypeIdIntegerYes

Resource Type ID should be valid

Resource Type ID

(e.g., Publisher=1; Demand Partner=5)

orderidIntegerYesValid Order IDOrder ID
optlockIntegerYes 

Used in update operation. Number represents version and prevents overriding other edits during update.

nameStringYes Order Name
ownerIdIntegerYesOwner ID should be validOwner ID
ownerTypeIdIntegerYes

Valid Resource Type ID

Resource Type ID (e.g., Publisher = 1, Demand Partner = 5)

reasonStringYes Reason for the cancellation request
statusStringNoAPPROVED, REJECTED

Status of order.

Sample Request JSON

    

{
      "associateId": 737,
      "associateTypeId": 5,
      "id": 95,
      "name": "cancellation",
      "optlock": 0,
      "orderId": 96,
      "ownerId": 31445,
      "ownerTypeId": 1,
      "reason": "Cancellation Requested by Publisher ",
      "status": "APPROVED"
    }

Response

Sample Response JSON

    

{
  "associateId": 737,
  "associateTypeId": 5,
  "creationTime": "2016-07-19T17:52:47Z",
  "id": 95,
  "modificationTime": "2016-07-19T17:57:06.413Z",
  "name": "cancellation",
  "optlock": 1,
  "orderId": 96,
  "ownerId": 31445,
  "ownerTypeId": 1,
  "reason": "Cancellation Requested by Publisher ",
  "status": "APPROVED"
}



Response Code

           

#e3e4e5
200OK

Error Codes

                       

Status

Error Message

Description

400

Bad Request

There is some validation failure; check the response body for error details.

 401

Unauthorized

Authentication or Authorization failure. Check the response body for specific details.

403

Forbidden

You are not subscribed to this feature of the Platform.
 

 

 

Add a Note to an Order

Overview

This API allows you to add a note to an Order.

Request

           

URIHTTP Method
$URI_PREFIX/agorders/{id}/notesPOST

Request Headers

                               
Header Name
Type
Value
Required
Description
pubTokenString${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

resourceIdInteger YesResource ID (Owner ID)
resourceTypeIdInteger YesType of Resource (e.g., Publisher = 1, Demand Partner = 5)

Path Parameter

               
Parameter Name
Type
Required
Description
 idLong Yes The Order ID for which the note will be appended. 

Request Body Parameter

               

Body ParameterTypeRequiredDescription
textStringYesText to be added to an Order

Sample Request URL

GET$URI_PREFIX/agorders/{id}/notes

Sample Request JSON

{
"text":  "Please note updated Cost Type"
}

Response

Sample Response JSON

 

{
  "acceptedTime": null,
  "adServerOrderId": null,
  "advertiser": " American Book Company, Inc",
  "associateId": 737,
  "associateTypeId": 5,
  "brandId": null,
  "brandType": null,
  "buyerCampaign": "CR-Campaign-718-1",
  "buyerContact": {
    "id": 334,
    "optlock": 0,
    "type": "BUYER",
    "name": "Kantar_Buyer1",
    "email": "joe.smith@buyer.com",
    "phone": null,
    "creationTime": "2016-07-18T12:53:18Z",
    "modificationTime": "2016-07-18T12:53:18Z"
  },
  "buyerId": 6516,
  "buyerType": 0,
  "changeRequest": false,
  "changeRequests": null,
  "creationTime": "2016-07-18T12:53:18Z",
  "creativeContact": null,
  "description": null,
  "draftEditedByOtherSide": false,
  "endDate": "2016-08-06",
  "extOrderId": null,
  "hasInProgressChangeRequest": false,
  "id": 192,
  "internalNote": null,
  "lineItems": [
    {
      "adServerLiId": null,
      "assocAdvertisers": null,
      "assocDemandPartners": null,
      "associateId": 737,
      "associateTypeId": 5,
      "costType": "CPM",
      "creationTime": "2016-07-18T12:54:12Z",
      "creativeRequired": true,
      "creatives": [],
      "endDate": "2016-08-06",
      "id": 192,
      "modificationTime": "2016-07-18T12:54:12Z",
      "name": "CR-Line-Item-718-1",
      "offer": null,
      "offerId": 51,
      "optlock": 0,
      "orderId": 192,
      "ownerId": 31445,
      "ownerTypeId": 1,
      "predecessorId": null,
      "priceAmount": 5,
      "priceCurrency": "USD",
      "quantity": 1000000,
      "startDate": "2016-07-25",
      "status": null,
      "targeting": "(country = (2840)) & (browserLang = (504000))",
      "timezone": 0
    }
  ],
  "live": false,
  "majorVersion": 1,
  "modificationTime": "2016-07-18T12:57:09Z",
  "name": "CR-718-1",
  "nameOfSignature": null,
  "notes": [
    {
      "creationTime": "2016-07-18T15:52:37Z",
      "id": 2,
      "modificationTime": "2016-07-18T15:52:37Z",
      "optlock": 0,
      "text": "Please not updated Cost Type"
    },
    {
      "creationTime": "2016-07-18T17:05:33.545Z",
      "id": 3,
      "modificationTime": "2016-07-18T17:05:33.545Z",
      "optlock": 0,
      "text": "Please note updated description"
    }
  ],
  "optlock": 1,
  "orderCancellations": [],
  "ownerId": 31445,
  "ownerTypeId": 1,
  "predecessorId": null,
  "publisherContact": {
    "id": 335,
    "optlock": 0,
    "type": "PUBLISHER",
    "name": "PUBLISHER",
    "email": "jane.doe@publisher.com",
    "phone": null,
    "creationTime": "2016-07-18T12:53:18Z",
    "modificationTime": "2016-07-18T12:53:18Z"
  },
  "replacingOrderId": null,
  "revisionId": null,
  "rootId": null,
  "sellerId": null,
  "sellerType": 0,
  "signatureDate": null,
  "startDate": "2016-07-25",
  "status": "PROPOSED",
  "statusReason": null,
  "successors": [],
  "termUrl": null,
  "timezoneId": null,
  "totalCostAmount": 5000,
  "totalCostCurrency": "USD",
  "updatingOwnerTypeId": 1
}

Response Code

TypeDescription
200OK

Response Header

             
Response Header Name
Type
Description
content-typeapplication/jsonMedia type that is to be returned in search/sort operation

Error Codes

                            

Status

Error Message

Description

400

Bad Request

There is some validation failure; check the response body for error details.

401

Unauthorized

Authentication or Authorization failure. Check the response body for specific details.

403

Forbidden

You are not subscribed to this feature of the Platform.
404Not FoundThe server does not have this resource

Attachments

    Outcomes