Shopello Tech Documentation
Shopello Docs

Introduction

What is Shopello API?

Hundreds of stores and millions of products are collected in Shopello API that allow customers to integrate and list products in various ways

How to get access to the Shopello API:

  1. Apply to become a Shopello partner here: https://www.shopelloapi.com/
  2. Once approved, you get a unique API key which gives access to the API
  3. You'll also get login information to your own partner interface where you can view statistics and your revenue

Get access to online retailers and their products through Shopello API. Integrate them easily on your site or in your web service and get revenue for all the clicks generated from the products. It's quick to apply for an API key and if your site is relevant it will be approved quickly. The Shopello API also have ready solutions such as widgets, banners, white label and even a Wordpress plugin so you can easily create product listings in Wordpress. You will obtain technical support directly from our experts when implementing the API. In our documentation, you will find guides and help to integrate the products easily. For feedback and questions please contact us at partner@shopello.se.

News

Depreciation of product price history 2017-08-09

This part of the API will be removed within the upcoming weeks.
If you depend on this API endpoint we recommend that you store this information locally.

New product attributes 2017-07-04

We added four new product attributes; Color, Size, Gender and GTIN.

Feeds and products now available at Datafeedr 2016-06-27

All feeds and products from Shopello are now available for Datafeedr. If you use Wordpress or plan to now you got all our products available in their plugins to create awesome ecommerce sites.

Deeplink enabled and disabled stores 2016-06-07

It's now possible to retrieve all enabled and disabled deeplink stores. Please check https://docs.shopelloapi.com/#Deeplink-enabled-stores section for more information.

Shipping cost and stock in Product Search API and Static Feeds

Shipping cost and stock values is now available. For the Product Search API please check the "attributes" field and for Static feeds new fields are added <ShippingCost> and <stock>. Beware of that the data is not always available, the data is only imported for those that have this information.
Field values:
Shipping cost: 0 for free shipping cost and > 0 is amount of cost for shipping
Stock: 0 for not in stock and 1 for in stock and empty for unknown.

Store status log 2016-03-30

It's now possible to get a status log for stores when they are added, activated and inactivated.

Partners can now set an URI for channels 2016-03-15

The purpose of this field is mainly for statistics purposes to make it possible to detect from which site/user the traffic from and to specific places comes.

Partners that make heavy use of channels should try to set the URI field of all their channels. This can be done with both an update method and also on creation of a channel.

Atom feed available for news 2015-11-25

Since today there's an atom-feed available for these news articles. You can find it at https://docs.shopelloapi.com/atom.xml and subscribe with your feedreader of choice.

Category filter on static feeds 2015-10-27

It's now possible to filter on categories in static feeds, for the moment it's only possible to exclude categories. You can find more info here: https://docs.shopelloapi.com/#Static-Feeds

Keyword mapping tool in partner admin 2015-10-26

It's now possible to make your own keyword mapping to optimize your earnings.
You can easily map keyword to keyword, keyword to one or more categories or map to both keyword and categories. Matching types is also introduced for exact matching, start with, end with or broad matching.

Revenue Segment in API 2015-10-09

We added a field on all products in the API-Result named revenue_segment with can contain one of the following three strings: low, medium or high.

This approximates the revenue from clicks on this product. The limits of how this segment is calculated might change in time. These changes will be minor and will be done to balance so the three segments will be approximately the same size.

Old deeplink solution depricated

The old deeplink solution is now depricated and will stop working 2015-10-30. Please make sure to use the deeplink generator as soon as possible.

Channel management in partner admin 2015-08-11

We have now optimized (made it faster) the statistics in channel management page and possibility to filter statistics by date range.

It's now possible to add multiple uris in one singel request. Se section: https://docs.shopelloapi.com/#Deep-Link-Generator of the documentation to see the guidelines.

Support for multiple uris in deeplink generator 2015-07-31

It's now possible to add multiple uris in one singel request. Se section: https://docs.shopelloapi.com/#Deep-Link-Generator of the documentation to see the guidelines.

Widget generator 2015-07-02

We added a public tool for creating widgets that you can include into your website. It is somewhat context sensetive, it reads the ?q= parameter and looks for the first <h1> in the page. But it also accepts queries so you can provide your own query-string.

You can find the widget-generator here: https://docs.shopelloapi.com/widget_generator

Fetch Revenue for all channels at once 2015-05-07

Using the string all as {channel_id} will return a list of all channels and their revenue. The key in this list is the {channel_id}.

New click-page live 2015-04-07

We released a new landingpage for clicks today which is part of the new API. The old API and Static Feeds is ported to use this as well, so everyone benefits from it. All the URI's in the new API is signed using our PHP-Library SignUri found here.

The links contains a GET-Parameter named clickdata, do not try to change this, it will end up as an Invalid Link.

As a partner, you can add your own signed data to the link to prevent users and others to alter this data before it is sent to us. At the moment, the only data you can add and sign is channel.

Examplecode:

<?php

require('vendor/autoload.php');

$signUri = new \Shopello\API\SignUri();

$uri = $signUri->signUri(
    '<link that we provide from API or static feeds>',
    '<pre-shared secret>',
    'partnerdata',
    array(
        'channel' => '<channel id of choice>'
    )
);

The pre-shared secret is available through the API from today. If you lost your secret and want a new one, we added a method for that in the API as well. Be aware that changing your secret will break old links that you have signed on your own.

APIv3 is taking shape 2015-03-24

The documentation is already written and available here. The PHP API-Client also supports this new version of the API. (It's a separate class named Api3Client).

Please note changes in authentication, it uses your username/password to the Partneradmin instead of API-Key due to the availability to sensitive information such as statistics and admin possibilities of channels in the API.

Wordpress plugin 2015-03-03

New release of our Wordpress plugin. You can download it here https://wordpress.org/plugins/shopello

Shopello PHP Client 2015-03-03

Current buildstatus of the client: Status

We released a new Shopello client written in PHP. It's available on github here: https://github.com/Shopello/Shopello-PHP

The client is straightforward to use and the preferred way to install it is to use composer. But since we're not in the main repositorys of composer you have to add the repository to your composer.json by hand. You can read more about this in the README on the project page on github.

API documentation

Products

The Products Service returns products by one or more criterias bellow.

Request Parameters

This service supports the following request parameters:

NameTypeRequiredDescription
product_idNUMBERNo Product ID(s) to search or filter with. Limit by one or more products by ex. "23413,65876,230956" or exclude by ex. "-23413,-65876".
category_idNUMBERNo Category ID(s) to search or filter with. Limit by one or more categories by ex. "1,3,56,7" or exclude by ex. "-1,-4,-67". It's also possible to combine by ex. "-5,1".
has_imagesNUMBERNoGet only products with images. This is done by setting has_images = 1
limitNUMBERNoLimit of products to retrieve
modeSTRINGNo Match mode
  • "pre" : Matching the search phrase by starting with
  • "or" : Matching by or between keywords in a search phrase
  • "fill" : If it's possible, The result is filled by products if the result is less than given limit.
offsetNUMBERNoThe position in the result to return products from.
orderSTRINGNo ASC for ascending order or DESC for descending order. This combines with order_by.
order_bySTRINGNoThe results can be ordered by one on the following criteria:
  • "price" : The current sales price of products.
  • "reduction_percent" : The price reduction in percent of products.
  • "relevance" : (default) How relevant the result is to the query.
All of these criteria can be combined with the ORDER attribute.
price_minNUMBERNoMin product price limit.
price_maxNUMBERNoMax product price limit,
querySTRINGNoKeyword search phrase. Ex. "iphone" or "iMac pro".
store_idNUMBERNo Store ID(s) to search or filter with. Limit by one or more stores by ex. "5,21" or exclude by ex. "-1,-54".
brandSTRINGNobrand name in text to search och filter with with
get_total_foundNUMBERNoTotal products found for the current request.
disseminateNUMBERNoDesseminates the products by grouping the first 3 products from different stores and then fill up with the rest of the result. This is done by setting disseminate = 1.
reduction_percent_minNUMBERNoMin reduction price limit.
reduction_percent_maxNUMBERNoMax reduction price limit.
extraSTRINGNoReturns one or more (comma separated) related properties within the result:
  • "categories": Related categories found products in
  • "stores" : Related stores found products in
  • "brands" : Related brand found products in
  • "max_price" : Max product price found in the result
  • "has_reduction" : If the result contains at least one product with reduction

Categories

The Categories Service returns category information for all categories on Shopello.

Request Parameters

There is no parameters for this service

Category

The Category Service returns category information for a specific category by their ID.

Request Parameters

This service supports the following request parameters:

NameTypeRequiredDescription
category_idNUMBERYesCategory Id for the category to get.

Category parents

The Category Parents Service returns all relations of categories in a hierarchy structure. This is useful when building category relations in a tree view.

Request Parameters

There is no parameters for this service

Category Tree

The Category Tree service returns a tree of all categories or categories below specified category.

Request Parameters

This service supports the following request parameters:

NameTypeRequiredDescription
category_idNUMBERNoCategory Id for the parent category to get.

Product

The Product Service returns product information for a specific product by their ID.

Request Parameters

This service supports the following request parameters:

NameTypeRequiredDescription
product_idNUMBERYesProduct ID for the product to get.

The Related products Service returns related products for a product. The related products is based on the product name.

Request Parameters

This service supports the following request parameters:

NameTypeRequiredDescription
product_idNUMBERYesProduct ID to found related products for.

Stores

The Stores Service returns store information for all stores on Shopello.

Request Parameters

There is no parameters for this service

Store

The Store Service returns store information for a specific store by their ID.

Request Parameters

This service supports the following request parameters:

NameTypeRequiredDescription
store_idNUMBERYesStore Id for the store to get.

Brands

The Brands Service returns brand information for all brands on Shopello.

Request Parameters

There is no parameters for this service

Product price history

Price change history for a product over time.

Request Parameters

This service supports the following request parameters:

NameTypeRequiredDescription
product_idNUMBERYesProduct ID to get price history for.

APIv3 Documentation

Authorization

For authorization we use HTTP Basic authentication.

You just use the same credentials you are using to login to the partner admin. If you don't already have an account, please sign up or contact some of our professional partner managers here

JSONP

API v3 also have support for JSONP. Just append ?callback=my_method in the end of each request.

Response:
Content-Type: application/javascript
my_method(json_response_data);

Consumer

/v3/consumer/revenue/{start_date}/{end_date}/

Allowed Methods: GET
Model: Consumer
Description:
Retrieves clicks and revenue for a given datarange

Fields:
{start_date} (YYYY-mm-dd) required
{end_date} (YYYY-mm-dd) required

/v3/consumer/revenue/store/{storeId}/{start_date}/{end_date}/

Allowed Methods: GET
Model: Consumer
Description:
Retrieves clicks and revenue for a given store and datarange.

Fields:
{storeId} (integer/string) required
{start_date} (YYYY-mm-dd) required
{end_date} (YYYY-mm-dd) required

Note:
This endpoint allows the usage of {storeId}:all, which will return a list of all stores with clicks ordered by the number of clicks.

Channel

/v3/channel/

Allowed Methods: GET, POST
Model: Channel
Description: Lists and create channels

Fields:
name (required on POST, not used on GET)
Response:
channel_id (on POST)

/v3/channel/{channel_id}/
Allowed Methods: POST
Model: Channel
Description: Change channel Name / URI
Fields:name and uri

/v3/channel/{channel_id}/
Allowed Methods: DELETE
Model: Channel
Description: Delete a channel by ID.

Fields:
{channel_id} required

/v3/channel/revenue/{channel_id}/{start_date}/{end_date}/

Allowed Methods: GET
Model: Channel
Description:
Retrieves clicks and revenue for a channel by id and datarange

Fields:
{channel_id} requried
{start_date} (YYYY-mm-dd) required
{end_date} (YYYY-mm-dd) required

Note:
If you use the {channel_id}: all, you will get a list with revenue for all channels.

Consumer Secret

/v3/consumer/secret/

Allowed Methods: GET, PUT
Model: Consumer/Secret
Description:
Display and generate new Secret.

This secret is used when signing data in links for products. The pre-shared secret is a random string we generate for you. Then we use it to verify that the data is signed by you.

Static Feeds

Static feeds is splitted in two parts. First part is The Control Feed and the other part is the Products Feeds.

For static feeds to work, you need to contact the partner support to enable it for your API-Key.

Feeds

Control Feed

The control feed contains all the available stores for your API-Key. It may be limited to a certain set of stores which you can decide when activating Static Feeds.

To access your Static Feed, you have to visit: https://<country>.shopelloapi.com/feeds/<api-key>.xml. This will contain a list of currently active and available stores.

Product Feeds

To access the product feeds, you have to visit: https://<country>.shopelloapi.com/feeds/<api-key>/<store-id>.xml.

This will contain all the products for the store you're visiting.

Filters

Reduced Prices Filter

GET-Parameter name: withReduction
GET-Parameter values: No values needed.
The parameter works on control feed and store feed level. On control feed level the store feed is only listed if it's at least one product with one reduction price. On store feed level only products is listed if the have at lease one reduction price.
Example:
Control feed level:
https://<country>.shopelloapi.com/feeds/<api-key>.xml?withReduction
Store feed level:
https://<country>.shopelloapi.com/feeds/<api-key>/<store-id>.xml?withReduction

Category Filter

GET-Parameter name: categoryIds
GET-Parameter values: -c1,-c2 etc...
The parameters works on store feed level. It's possible to exclude one or more categories at the same time. Observe that the values need to be negative integer numbers and products that belongs to a sub category will also be removed.

For the moment i'ts only possible to exclude categories.

Example:
Store feed level:
https://<country>.shopelloapi.com/feeds/<api-key>/<store-id>.xml?categoryIds=-1,-2,-3

Best practices

Keep feed products up to date

There is an issue that some partners experiencing broken links. The main reason is that the feeds its not updated frequently and products is deleted/inactivated. To avoid this, we recommend to always check the date (at least once an hour) for every feed in the control feed and import the products when the date has changed.

/v3/deepLinkGenerator/

Authentication: Send API-Key in header X-API-KEY to auth for this service.
Allowed Methods: POST
Model: DeepLinkGenerator
Description:
Create direct links to products on other websites. Will only work on stores we support.

Fields:
uri Link you want to create the deeplink to. It's also possible to batch uris with one singel request by adding multiple uri parameters like uri[]=http://www.somesite.com&uri[]=http://www.someothersite.com...
Response:
data will contain the tracker link if successful.

Importance!
Since there is a lot of problem with untrackable links caused by stores getting inactive by different reasons, please make sure that always validate your links regularly, at lease once a day.

Old deeplink solution depricated

The old deeplink solution is now depricated and will stop working 2015-10-30. Please make sure to use the deeplink generator as soon as possible.

Store status log

/v3/store/status_log/

Allowed Methods: GET
Model: Store
Description: Listing status log when a store is added, activated and deactivated

/v3/store/deeplink-stores/{offset}

Allowed Methods: GET
Model: Store
Description:
Retrieves all enabled and disabled deeplink stores. Limit to 50 stores for each request. Use offset to retrieve more stores.

Fields:
{offset} (0-9) optional

Authentication
Api key

Query builder

The Query builder is a powerful tool to test and get real time results for a Service. The real request url is explained in the text field named "Api request url" and the result is shown in the "Result" textarea.

X-API-KEY(Required):
Is the KEY how identifies you as partners so we can track your clicks. The API KEY can be different for different countries.

Country(Required):
Choose Country you want to test the Shopello API for.

Service(Required):
The Service you want to use. If a service have related parameters, they will be shown when you have chosen a service.


API Settings




2018-07-06 14:21:42