Searching products

POST /publisher/products/ searches the product feeds of the offers you can promote. The filters go in a JSON body. Give the search one of your websites, and each product in the response carries a tracking link for it.

The search is a POST, so it needs a token with the write scope. A token with only read gets 403 Forbidden.

A first search

Products with "macbook" in the title, best matches first, with tracking links for one of your websites:

curl -X POST "https://api.convertiser.com/publisher/products/?key=your-website-key"
     -H "Authorization: Token your-personal-secret-token-here"
     -H "Content-Type: application/json"
     -d '{
           "filters": [
             {"title": {"lookup": "contains", "value": "macbook"}}
           ],
           "ordering": "-score",
           "page": 1,
           "page_size": 20
         }'

The URL needs its trailing slash. GET on it answers 405 Method Not Allowed.

The website key

key is your website's guid, which GET /publisher/websites/ returns for each website. It is not the website id. Pass it in the query string, as above, or as "key" in the body.

With a key:

link in each product is a tracking link for that website.
Only offers you can promote on that website are searched.
Only products in the website's language are searched, unless you filter by offer_id.

Without a key, link and mobile_link are null. A key that matches none of your websites is treated as no key, without an error, so null links usually mean the key is wrong.

Filters

filters is a list. Each item names a field, a lookup and a value, and a product has to match every item:

{"title": {"lookup": "contains", "value": "macbook"}}

Text fields:

Field	Searches
`title`	The product title
`brand`	The brand
`description`	The description
`category`	`product_type` and `google_product_category` together
`product_type`	The advertiser's own category path
`google_product_category`	The Google product category
`gtin`, `mpn`	The product codes
`offer`	The offer title
`any`	Title, description, brand, categories, codes, colour, size, material, pattern, gender and age group

Lookup	Matches
`contains`	Products with the words, in any order. Case does not matter. Products with more of the words score higher.
`phrase`	Products with the words together, in that order. Case does not matter.
`exact`	Products whose whole field equals the value. Case matters.
`starts_with`	Products whose field starts with the value. Case matters. Not available on `any` and `category`.

To require every word, use phrase, or one contains filter for each word.

Number fields take the lookups exact, lt, gt and range:

Field	Value
`price`	The regular price
`sale_price`	The promotional price
`discount`	The discount in percent, from 0 to 100
`cpc_rate`	What you earn per click on a product that pays per click

range takes [min, max] and includes both ends. lt and gt leave the value itself out. Prices are in each product's own currency, so combine a price filter with currency.

Other fields take only exact:

Field	Value
`currency`	A currency code in capitals, such as `PLN`
`offer_id`	An offer `id` from `GET /publisher/offers/`, or `offer_id` from a product
`is_cpc`	`true` for products that pay per click

Two more rules apply to every field:

A list as value matches any of its values: {"brand": {"lookup": "exact", "value": ["Apple", "Lenovo"]}}.
A ~ before the lookup turns it into an exclusion: {"title": {"lookup": "~contains", "value": "case"}} drops products with "case" in the title.

A lookup the field does not take, or a value of the wrong type, returns 400 Bad Request.

Ordering

ordering takes one of score, price, sale_price, discount, cpc_rate and updated_at. A - in front reverses it.

Send "ordering": "-score" to get the best matches first. Without ordering, the default is score, which lists the weakest matches first. A search with no text filter has no relevance to sort by, so score and -score return its products in random order.

Pages

page starts at 1. Send it with every search, the first one included: without it, next_page points at the page you already have. page_size is 50 by default and at most 1000. The response says where you are:

{
  "count": 312,
  "pagination": {
    "page": 1,
    "page_size": 20,
    "previous_page": 0,
    "next_page": 2
  },
  "data": [
    {
      "id": "...",
      "title": "Apple MacBook Air 13 M3 16GB 512GB",
      "price": "PLN 5499.00",
      "sale_price": "PLN 4999.00",
      "offer": "...",
      "offer_id": "...",
      "link": "...",
      ...
    }
  ]
}

For the next page, send the same body again with page set to next_page. On the last page next_page is null. price and sale_price are strings with the currency code in front.

Examples

Laptops from one offer between 2000 and 4000 PLN, cheapest first:

{
  "filters": [
    {"offer_id": {"lookup": "exact", "value": "your-offer-id"}},
    {"category": {"lookup": "contains", "value": "laptops"}},
    {"currency": {"lookup": "exact", "value": "PLN"}},
    {"price": {"lookup": "range", "value": [2000, 4000]}}
  ],
  "ordering": "price",
  "page": 1
}

Xbox One consoles, without games, controllers or 500GB models:

{
  "filters": [
    {"title": {"lookup": "phrase", "value": "Xbox One"}},
    {"title": {"lookup": "~contains", "value": ["gra", "controller", "500GB"]}}
  ],
  "ordering": "-score",
  "page": 1
}

Discounts of more than 30 percent, biggest first:

{
  "filters": [
    {"discount": {"lookup": "gt", "value": 30}}
  ],
  "ordering": "-discount",
  "page": 1
}

A tracking link for one product

PUT /publisher/products/{id}/tracking_link/ makes a tracking link for a product id from the search. website is required and takes the website id, not its guid:

curl -X PUT "https://api.convertiser.com/publisher/products/product-id/tracking_link/"
     -H "Authorization: Token your-personal-secret-token-here"
     -H "Content-Type: application/json"
     -d '{"website": "your-website-id", "sid": "newsletter-october"}'

sid is an optional SubID that the link carries: up to 32 letters, digits, _ and -.

{
  "tracking_link": "...",
  "short_link": null
}

Limits

You can send 5000 searches an hour. The product search reference lists every parameter.

A first search​

The website key​

Filters​

Ordering​

Pages​

Examples​

A tracking link for one product​

Limits​