API: Orders

An Order resource represents an insertion order, which is a contract to show an ad campaign on an insertion order over a period of time. It describes the details of the contract such as the total volume (of impressions, clicks or days) ordered, daily budget, bid price, priority start and end time (if any) etc.

Orders that are created through the Ad Store API do not require online payment because they are created with administrator privileges.

Supported Methods

List insertion orders

• URL - http://<subdomain>.trafficspaces.com/resources/orders/
• Method - GET
• Parameters -
  • username - (string, optional) the username of the user whose orders are required.
  • zoneid - (string, optional) the id of the ad zone whose orders are required.
  • contactid - (string, optional) the id of the managed advertiser whose orders are required.
  • campaignid - (string, optional) the id of the ad campaign whose orders are required.
  • page - (unsigned, optional) an integer value that specifies which page of results to fetch, starting at 1. Default: 1. Minimum: 1.
  • pagesize - (unsigned, optional) how many results to fetch in each request. Default: 25. Maximum: 100
• Response
  • Status - 200, if successful.
  • Body - A collection of up to pagesize insertion orders in the requested format

Read an insertion order

• URL - http://<subdomain>.trafficspaces.com/resources/orders/<order_id>.<format>
• Method - GET
• Parameters - None
• Response
  • Status - 200, if successful.
  • Body - The requested insertion order in the requested format

List insertion order stats

• URL - http://<subdomain>.trafficspaces.com/resources/orders/statistics/<order_id>.<format>
• Method - GET
• Parameters -
  • fromdate - (date, optional) the date from which the stats are fetched
  • todate - (date, optional) the date to which the stats are fetched.
  • page - (unsigned, optional) an integer value that specifies which page of results to fetch, starting at 1. Default: 1. Minimum: 1.
  • pagesize - (unsigned, optional) how many results to fetch in each request. Default: 25. Maximum: 100
    Note: If the fromdate and todate parameters are not specified, the latest stats will be fetched instead.
• Response
  • Status - 200, if successful.
  • Body - A collection of up to pagesize insertion order statistics in the requested format.

Create a new insertion order

• URL - http://<subdomain>.trafficspaces.com/resources/orders/
• Method - POST
• Parameters - XML or JSON data. See the Attributes below
• Response
  • Status - 201, if successful.
  • Body - The created insertion order in the requested format.
  • Headers
    • Location - A relative URL for the newly created insertion order

Update an existing insertion order

• URL - http://<subdomain>.trafficspaces.com/resources/orders/<order_id>.<format>
• Method - PUT
• Parameters - XML or JSON data. See the Attributes below
• Response
  • Status - 200, if successful.
  • Body - The updated insertion order in the requested format

Process an existing order

• URL - http://<subdomain>.trafficspaces.com/resources/orders/process/.
• Method - POST
• Parameters -
  • action - (string, required) indicates the action to perform. Valid values include
    • play - starts the linked campaign. All approved ads in the campaign will become eligible to be shown by the ad servers
    • pause - pauses the linked campaign. The campaign will be suspended until the play action is invoked.
    • stop - stops the linked campaign permanently.
    • refund - refunds any outstanding credits on an order that has been stopped but not completely fulfilled.
    • archive - archives the order. The order will no longer be visible in the default lists.
  • orderid - (string, required) a comma separated list of identifiers for the orders upon which the action should be performed
    Note: It takes up to 15 minutes for a play, pause, stop action to take effect on the ad servers.
• Response
  • Status - 200, if successful.

Attributes

• order - (object, rwa)
  • id - (string, r) the alphanumeric unique identifier
  • name - (string, r) the display name in the ad store.
  • status - (string, r) the status of the order in its life cycle. Valid values include
    • pending - the order has been created but it has not been started. This may be due to payment issues or simply that the start date has not fallen due.
    • playing - the order is currently live.
    • pausing - the order is about to be paused.
    • paused - the order is currently paused
    • stopping - the order is about to be stopped
    • stopped - the order has been stopped. It will still be visible in the default view of the dashboard
    • refunded - the order has been stopped and an outstanding credit has been refunded to the advertiser. It is visible in the default view of the dashboard
    • archived - the order has been stoppedn and is no longer visible in the default view of the dashboard
  • priority - (string, rwa, optional) the priority of the order in the ad servers. Valid values include
    • very_low - 1x priority multiple
    • low - 2x priority multiple
    • normal - 3x priority multiple
    • high - 4x priority multiple
    • very_high - 5x priority multiple
    • exclusive - Road block. No other orders will show except those in this priority.

      The default value is normal.

  • model - (string, rw) specifies the pricing method used for the ad zone. Valid values include
    • cpm - cost per thousand impressions
    • cpc - cost per click
    • cpd - cost per day (tenancy)
  • gross_purchase_price - (double, rw) the gross (pre-discount) price at which the order was created. It must be greater than zero.
  • net_purchase_price - (double, rw) the net (post-discount) price at which the order was created. It must be greater than or equal to zero.
  • maximum_bid_price - (double, rwa, optional) the maximum bid price at which the order will be fulfilled if it participates in an auction
  • average_bid_price - (double, r) the average price at which the order was fulfilled
  • total_volume - (unsigned, rw) the total number of units that was purchased in the order
  • daily_volume - (unsigned, rwa, optional) the total number of units that can be fulfilled in a single day
  • filled_volume - (unsigned, r) the total number of units that have been fulfilled
  • realm - (string, r) the subdomain name of the ad store
  • start_date - (datetime, rw) the date on which the order is scheduled to start.
  • end_date - (datetime, rwa, optional) the date on which the order is scheduled to end.
  • last_modified_date - (datetime, r) the date on which the order was last modified.
  • linked_user - (object, rw)
    • id - (string, rw) the alphanumeric unique identifier of the user that created the order
    • name - (string, r) the username of the user that created the order
  • linked_campaign - (object, rw)
    • id - (string, rw) the alphanumeric unique identifier of the campaign for which the order was created
    • name - (string, r) the username of the order's campaign
  • linked_zone - (object, rw)
    • id - (string, rw) the alphanumeric unique identifier of the ad zone on which the order's campaign will run
    • name - (string, r) the username of the order's ad zone
  • order_statistic - (object, r) the latest traffic stats.
    • hits - (double, r) the total number of ad calls
    • uniques - (double, r) the total number of unique visitors making ad calls
    • clicks - (double, r) the total number of valid clicks on ads
    • conversions - (double, r) the total number of valid conversions from ads that have been shown previously
    • views - (double, r) the total number of ad playbacks (video and audio ads only)..
    • duration - (double, r) the average time spent per ad playback video and audio ads only.
    • average_conversion_amount - (double, r) the average monetary value of the conversions record for the order
    • days - (double, r) the total number of days on which the order was run
    • date - (datetime, r) the time for which the the statistic was calculated
    • linked_order - (object, r)
      • id - (string, r) the alphanumeric unique identifier of order for which this stat was calculated
      • name - (string, r) the name of the order for which this stat was calculated

Examples

Order - JSON

{
    "id": "16211a68",
    "name": "Featured Text Ads (Dec 01, 2010)",
    "status": "stopped",
    "priority": "normal",
    "model": "cpd",
    "gross_purchase_price": 15,
    "net_purchase_price": 10,
    "maximum_bid_price": 10,
    "average_bid_price": 10,
    "total_volume": 30,
    "daily_volume": 1,
    "filled_volume": 30,
    "realm": "fresh",
    "start_date": "2010-12-01T00:00:00",
    "end_date": "2010-12-30T23:59:59",
    "last_modified_date": "2010-12-18T16:35:57",
    "linked_zone": {
        "id": "1481c281",
        "name": "Featured Text Ads"
    },
    "linked_campaign": {
        "id": "16310e6b",
        "name": "Classic CD Campaign",
    },
    "linked_user": {
        "id": "0937111d0e6b33150a0e6f66",
        "name": "admin@mywebsite.com"
    },
    "order_statistic": {
        "hits": 10373,
        "uniques": 2453,
        "clicks": 121,
        "conversions": 0,
        "views": 0,
        "duration": 0,
        "average_conversion_amount": 2.50,
        "days": 30,
        "date": "2010-12-31T00:00:01",
        "linked_order": {
            "id": "16211a68",
            "name": "Featured Text Ads (Dec 01, 2010)"
        }
    }
}

Order - XML

<?xml version="1.0" encoding="UTF-8"?>
<order>
    <id>1631386b</id>
    <name>Top Leaderboard Display Ads (May 18, 2010)</name>
    <status>playing</status>
    <priority>normal</priority>
    <model>cpm</model>
    <gross_purchase_price>5.0</gross_purchase_price>
    <net_purchase_price>4.0</net_purchase_price>
    <maximum_bid_price>4.0</maximum_bid_price>
    <average_bid_price>3.78</average_bid_price>
    <total_volume>10000</total_volume>
    <daily_volume>10000</daily_volume>
    <filled_volume>441.0</filled_volume>
    <realm>demo</realm>
    <start_date>2010-05-18T00:00:00</start_date>
    <last_modified_date>2010-05-18T16:35:57</last_modified_date>
    <linked_zone>
        <id>151f0269</id>
        <name>Top Leaderboard Display Ads</name>
    </linked_zone>
    <linked_campaign>
        <id>160f1a6e</id>
        <name>Sound City Ads</name>
    </linked_campaign>
    <linked_user>
        <id>0937111d0e6b33150a0e6f66</id>
        <name>admin@mywebsite.com</name>
    </linked_user>
    <order_statistic>
        <hits>441</hits>
        <uniques>134</uniques>
        <clicks>3</clicks>
        <conversions>0</conversions>
        <views>0</views>
        <duration>0.0</duration>
        <average_conversion_amount>0.0</average_conversion_amount>
        <days>0</days>
        <date>2010-05-19T16:15:01</date>
        <linked_order>
            <id>1631386b</id>
            <name>Top Leaderboard Display Ads (May 18, 2010)</name>
        </linked_order>
    </order_statistic>
</order>

Order Statistics - JSON

[
    {
        "hits": 10373,
        "uniques": 2453,
        "clicks": 121,
        "conversions": 0,
        "views": 0,
        "duration": 0,
        "average_conversion_amount": 2.50,
        "days": 30,
        "date": "2010-12-31T00:00:01",
        "linked_order": {
            "id": "16211a68",
            "name": "Featured Text Ads (Dec 01, 2010)"
        }
    }
]

Order Statistics - XML

<?xml version="1.0" encoding="UTF-8"?>
<order_statistics>
    <order_statistic>
        <hits>441</hits>
        <uniques>134</uniques>
        <clicks>3</clicks>
        <conversions>0</conversions>
        <views>0</views>
        <duration>0.0</duration>
        <average_conversion_amount>0.0</average_conversion_amount>
        <days>0</days>
        <date>2010-05-19T16:15:01</date>
        <linked_order>
            <id>1631386b</id>
            <name>Top Leaderboard Display Ads (May 18, 2010)</name>
        </linked_order>
    </order_statistic>
</order_statistics>