Auctions

Usage

The Auction API runs an auction on a SmartLink and returns an updated destination URL for the link. You can use this API to write your own custom publisher Javascript tags. Be sure to read through the tutorial before proceeding.

Note

The Auction API does not require client authentication, but may be subject to rate-limiting if called an extreme number of times from the same origin.

Run Auction

Request

GET /api/v1/auction/

Query Param

Type

Description

a

string

Auction ID. This is the number at the end of your SmartLink. For example, the SmartLink https://shop-links.co/1522995078114976993 has the Auction ID 1522995078114976993.

t

integer

Cache-busting parameter. Set this to a randomly-generated number to prevent HTTP caching of the auction request and response.

uuid

string

Page Session UUID. The UUID v4 value that your client has generated for the current page session.

Response

Auction result data

Field Name

Type

Description

auction_result . id

string

A unique identifier for the result of the auction.

auction_result . product

object

Product information for the advertiser that won the auction.

auction_result . redirect_url

string

The new destination URL for the SmartLink.

auction_result . tracker_urls

object

Third-party event tracker URLs for this SmartLink placement. Your client is responsible for firing all trackers listed here when the applicable event(s) occur.

impression_pixel_url

string

The primary impression event tracker URL for this SmartLink placement. Your client is responsible for firing this tracker after receiving the auction response.

Product information (auction_result.product)

Auction API responses may provide the following information about the advertiser (retailer/merchant) and the product page that will be receiving the click on the rewritten SmartLink:

Field Name

Type

Description

id

integer

A unique identifier for the product that the destination URL refers to.

name

string

The name of the product being sold.

price

string

The price of the product being sold, in USD.

url

string

The raw URL of the product page, for display purposes. (Do not rewrite the SmartLink with this URL.)

image_url

string

The image URL of the product being sold, for display purposes.

is_in_stock

boolean

The stock status of the product being sold.

merchant . id

integer

A unique identifier for the advertiser.

merchant . canonical_host

string

The host part of the advertiser’s website URL, for display purposes.

merchant . name

string

The name of the advertiser.

merchant . url

string

The full URL for the advertiser’s home page.

Third-party event trackers (auction_result.tracker_urls)

Auction API responses may include the following set of third-party event trackers that apply to your SmartLink placement:

Event Tracker Type

Event Description

impression

Signals that at least one occurrence of this SmartLink has been loaded on the page. You may fire this event tracker immediately after receiving the auction response.

viewable_impression

Fire this event tracker once any occurrence of this SmartLink is scrolled into view on the page.

Tracker URLs may include the template parameter {RAND}, which must be replaced with a randomly-generated number for cache-busting prior to firing the tracker.

Do NOT fire a third-party event tracker more than once per page for the same event, even if the same SmartLink appears multiple times on that page.

Example

GET https://api.bam-x.com/api/v1/auction/
    ?a=1629223267830557131
    &t=1517261651
    &uuid=8132ac19-109a-466e-8037-540a9bd12798
HTTP/1.1 200 OK
Content-Type: application/json

{
  "info": {
    "error": false,
    "status": 200
  },
  "data": [
    {
      "auction_result": {
        "id": "1629224701990881693",
        "auction_id": "1629223267830557131",
        "redirect_url": "https://api.bam-x.com/api/v1/redirect/?a=1629223267830557131&uid_bam=1629224701957143181&ar=1629224701990881693&url=https%3A%2F%2Fwww.amazon.com.example%2F&uuid=8132ac19-109a-466e-8037-540a9bd12798",
        "product": {
          "merchant": {
            "url": "https://www.amazon.com/",
            "canonical_host": "amazon.com",
            "id": 2186,
            "name": "Amazon"
          },
          "bamx_product_category_id": 3,
          "name": "Designer Handbag",
          "url": "https://www.amazon.com.example/product/1234",
          "image_url": "https://www.static.amazon.example/image/path/1234",
          "is_in_stock": true,
          "price": "299.99",
          "id": 8030310
        },
        "tracker_urls": {
          "viewable_impression": [
            "https://ad.doubleclick.net.example/ddm/trackimp/N1234.1234567NARRATIV/B12345678.123456789;dc_trk_aid=123456789;dc_trk_cid=12345678;kw=lv;ord=1629147433127336253;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=?",
            "https://ad.atdmt.com.example/1111?r={RAND}"
          ],
          "impression": [
            "https://ad.doubleclick.net.example/ddm/trackimp/N1234.1234567NARRATIV/B12345678.123456789;dc_trk_aid=123456789;dc_trk_cid=12345678;kw=li;ord=1629147433127336253;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=?",
            "https://ad.atdmt.com.example/2222?r={RAND}"
          ]
        }
      },
      "impression_pixel_url": "https://ad.doubleclick.net.example/ddm/trackimp/N1234.1234567NARRATIV/B12345678.123456789;dc_trk_aid=123456789;dc_trk_cid=12345678;ord=1629147433127336253;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=?"
    }
  ]
}