REST API Documentation

Authentication

Add ‘API key’ http get parameter (key) to every request to verify your application:

&key=da8cshSBDjsabdhb

API key can be found in Merchant Admin > Settings > API.

Note

Only share your API key with people you trust.

Shop ID

Shop ID is a unique key that identifies your shop, it is a required parameter in all queries:

&shopId=4e68f7ab2ca35f12c0000011

Shop ID can be found in Merchant Admin > Settings > Shops.

Note

Shop ID cannot be changed.

Data format

All API responses are in JSON format.

/products

Returns products tracked in specified shop.

/products

obligatory parameters

shopId:shop ID

additional parameters

time:time selection [ All Time, Today, Yesterday, Last 7 Days, Last 30 Days, Current Week, Last Week, Current Month, Last Month ]
sortedBy:sorting column [ name | opens | shares | clicks | sales | revenue ]
sortedDesc:sort descending [ true | false ]
limit:number of products returned at once [ default 10, range: 0..200 ]
offset:offset of products returned [ default 0 ]

returns

products:

ordered array of products (json objects) matching all given parameters:

[{ "productId": "uniq51515",
   "name": "Product name #1",
   "image_url": "http://example.com/product_image_1.jpg",
   "opens": 8,
   "shares": 3,
   "clicks": 2,
   "sales": 1,
   "revenue": 2000, ... }, ... ]

Note

revenue is given in the basic monetary unit (cents for instance)

Note

productId (given in a schema.org on product site or ‘product_id’ in AddShoppersTracking)

count:

number of all products matching selected shopId and time

time:

time selection [ All Time, Today, Yesterday, Last 7 Days, Last 30 Days, Current Week, Last Week, Current Month, Last Month ]

sortedBy:

sorting column [ name | opens | shares | clicks | sales | revenue ]

sortedDesc:

sort descending [ true | false ]

limit:

number of products returned at once [ default 10, range: 0..200 ]

offset:

offset of products returned [ default 0 ]

Example query:

http://api.addshoppers.com/1.0/products?shopId=4f6724485b3a426c50000146&sortedBy=shares&offset=10&key=JnLbm-7PXTWbLnOajg-MhP2L6rFf44SM

Response:

{"count": 24, "sortedDesc": true, "time": "All Time", "sortedBy": "shares", "limit": 10, "offset": 10, "products":
    [{"productId": "pd-83232234sa", "name": "Product name #1", "revenue": 14200, "clicks": 43, "opens": 190, "shares": 95, "sales": 40, ... },
     {"productId": "pw-911266631p", "name": "Sample Product", "revenue": 0, "clicks": 0, "opens": 2, "shares": 36, "sales": 0, ... },
     {"productId": "pd-216166841w", "name": "Product name #18", "revenue": 58000, "clicks": 32, "opens": 52, "shares": 25, "sales": 27, ... },
     {"productId": "pa-2991818244", "name": "Product name #5", "revenue": 102600, "clicks": 4, "opens": 29, "shares": 17, "sales": 20, ... },
     {"productId": "pa-325726661m", "name": "Home Site", "revenue": 4255, "clicks": 1, "opens": 12, "shares": 14, "sales": 2, ... },
     {"productId": "ua-812174718x", "name": "Standard 7", "revenue": 0, "clicks": 3, "opens": 17, "shares": 6, "sales": 0, ... },
     {"productId": "pa-2111246644", "name": "Sample Product #2", "revenue": 47120, "clicks": 7, "opens": 8, "shares": 4, "sales": 10, ... },
     {"productId": "ww-6638777125", "name": "PROD 9", "revenue": 0, "clicks": 3, "opens": 5, "shares": 4, "sales": 0, ... },
     {"productId": "pd-128927895s", "name": "help", "revenue": 0, "clicks": 0, "opens": 15, "shares": 3, "sales": 0, ... },
     {"productId": "ps-569842121k", "name": "Custom product", "revenue": 0, "clicks": 0, "opens": 4, "shares": 3, "sales": 0, ... }
    ]}

/products/(shares|clicks)

Returns products shares/clicks sources in specified shop.

/products/(shares|clicks)

obligatory parameters

shopId:shop ID

additional parameters

time:time selection [ All Time, Today, Yesterday, Last 7 Days, Last 30 Days, Current Week, Last Week, Current Month, Last Month ]
sortedBy:sorting column [ name | twitter | wall | like | want | own | google | kaboodle | wishpot | pinterest | stumbleupon | email | polyvore ]
sortedDesc:sort descending [ true | false ]
limit:number of products returned at once [ default 10, range: 0..200 ]
offset:offset of products returned [ default 0 ]

returns

products:

ordered array of products (json objects) matching all given parameters:

[{ "productId": "uniq51515",
   "name": "product name #1",
   "url": "http://your.shop.com/products/product_name_1",
   "image_url": "http://example.com/product_image_1.jpg",
   "twitter": 44,
   "wall": 15,
   "like": 2,
   "want": 3, ... }, ... ]

Note

wall = facebook wall

Note

productId (given in a schema.org on product site or ‘product_id’ in addshopperstracking)

Note

sum of :limit: and :offset: couldn’t exceed 500

count:

number of all products matching selected shopId and time

time:

time selection [ All Time, Today, Yesterday, Last 7 Days, Last 30 Days, Current Week, Last Week, Current Month, Last Month ]

sortedBy:

sorting column [ name | opens | shares | clicks | sales | revenue ]

sortedDesc:

sort descending [ true | false ]

limit:

number of products returned at once [ default 10, range: 0..200 ]

offset:

offset of products returned [ default 0 ]

example query:

GET http://api.addshoppers.com/1.0/products/shares?shopId=4f6724485b3a426c50000146&sortedby=wall&limit=2&key=jnlbm-7pxtwblnoajg-mhp2l6rff44sm

response:

{"count": 24, "sortedDesc": true, "time": "All Time", "sortedBy": "wall", "limit": 2, "offset": 0, "products":
    [{"productId: "827262610", "name": "product name #5", "url": "http://your.shop.com/products/product_name_5, "twitter": 15, "wall": 44, "like": 1, ...},
     {"productId: "198472610", "name": "product name #4", "url": "http://your.shop.com/products/product_name_4, "twitter": 55, "wall": 37, "like": 0, ...},
    ]}

/product/stats

Returns social statistics for specific product. Note that either the product ID or both, product name and URL must be specified.

obligatory parameters

shopId:shop ID
productId:product ID (either external ID or product ID returned in /products endpoint)

OR

productName:product name
productURL:product url

additional parameters

time:time selection [ All Time, Today, Yesterday, Last 7 Days, Last 30 Days, Current Week, Last Week, Current Month, Last Month ]

returns

shares:shares counter
opens:opens counter
revenue:revenue counter
sales:sales counter
time:time selection [ All Time, Today, Yesterday, Last 7 Days, Last 30 Days, Current Week, Last Week, Current Month, Last Month ]

/product/influencers

Returns influencers for specific product. Note that either the product ID or both, product name and URL must be specified.

obligatory parameters

shopId:shop ID
productId:product ID (given in Product Schema on product site or ‘product_id’ in AddShoppersTracking)

OR

productName:product name
productURL:product url

additional parameters

time:time selection [ All Time, Today, Yesterday, Last 7 Days, Last 30 Days, Current Week, Last Week, Current Month, Last Month ]

returns

influencers:

array of influencers (JSON objects) matching given parameters:

[{ "name": "user@example.com",
   "email": "user@example.com",
   "lastSource": "Facebook",
   "lastShareDate": "09.01.2012",
   "klout": 0,
   "shares": 13,
   "clicks": 80,
   "sales": 5,
   "revenue": 22040
},...]

Note

revenue is given in the basic monetary unit (cents for instance)

count:

number of all influencers matching given parameters

example query:

GET http://api.addshoppers.com/1.0/product/influencers?shopId=4f6724485b3a426c50000146&productId=r6iOu&key=jnlbm-7pxtwblnoajg-mhp2l6rff44sm

example response:

{"count": 2, "influencers":
   [{ "name": "user@example.com",
       "lastSource": "Facebook",
       "lastShareDate": "09.01.2012",
       "klout": 0,
       "shares": 13,
       "clicks": 80,
       "sales": 5,
       "revenue": 22040
    }, ... ]}

/shares

Returns shares

obligatory parameters

shopId:shop ID

additional parameters

source:display results for particular source [twitter | wall | like | want | own | use | google | kaboodle | wishpot | pinterest | stumbleupon | email | polyvore | tumblr]
time:time selection [ All Time, Today, Yesterday, Last 7 Days, Last 30 Days, Current Week, Last Week, Current Month, Last Month ]
sortedDesc:sort descending [ true | false ] by date
limit:number of shares returned at once [ default 10, range: 0..200 ]
offset:offset of shares returned [ default 0 ]

returns

count:number of all shares matching given parameters
shares:array of shares matching given parameters

Note

In response sources look slightly different than in request, they’re mapped as below:

twitter -> Twitter
wall -> Facebook
like -> Like
want -> FB Want
own -> FB Own
google -> Google+
kaboodle -> Kaboodle
wishpot -> Wishpot
pinterest -> Pinterest
stumbleupon -> StumbleUpon
email -> Email
use -> FB Use
tumblr -> Tumblr
polyvore -> Polyvore

example query:

GET http://api.addshoppers.com/1.0/shares?shopId=4f6724485b3a426c50000146&key=jnlbm-7pxtwblnoajg-mhp2l6rff44sm

example response:

{"count": 45, "shares": [{
    "product": "Example product name",
    "product_url": "http://example.com/my_product",
    "influencer_name": "Example Name",
    "influencer_email": "user@example.com",
    "source": "Facebook",
    "date": "2013-04-01 22:21"
    }, ...]
}

/shares/sources-count

Returns number of shares for sources. Sources without shares aren’t returned.

obligatory parametres

shopId:shop ID

additional parameteres

time:time selection [ All Time, Today, Yesterday, Last 7 Days, Last 30 Days, Current Week, Last Week, Current Month, Last Month ]

returns

object with key-value: <source_name>-<shares_count>

example query:

GET http://api.addshoppers.com/1.0/shares/sources-count?shopId=4f6724485b3a426c50000146&key=jnlbm-7pxtwblnoajg-mhp2l6rff44sm

example response:

{
    "Email": 50,
    "Twitter": 2,
    "Facebook": 3,
    "Like": 8,
    "Pinterest": 7
}

/influencers

Returns all influencers for a site within specified time period.

obligatory parameters

shopId:shop ID

additional parameters

time:time selection [ All Time, Today, Yesterday, Last 7 Days, Last 30 Days, Current Week, Last Week, Current Month, Last Month ]

returns

influencers:

array of influencers (JSON objects) matching given parameters:

[{ "name": "user@example.com",
   "lastSource": "Facebook",
   "lastShareDate": "09.01.2012",
   "klout": 0,
   "shares": 13,
   "clicks": 80,
   "sales": 5,
   "revenue": 22040
},...]

Note

revenue is given in the basic monetary unit (cents for instance)

count:

number of returned influencers

example query:

GET http://api.addshoppers.com/1.0/influencers?shopId=4f6724485b3a426c50000146&key=jnlbm-7pxtwblnoajg-mhp2l6rff44sm

example response:

{"count": 2, "influencers":
   [{ "name": "user@example.com",
       "lastSource": "Facebook",
       "lastShareDate": "09.01.2012",
       "klout": 0,
       "shares": 13,
       "clicks": 80,
       "sales": 5,
       "revenue": 22040
    }, ... ]}

/influencers [POST]

Creates new influencer manually for a site. All parameters described below must be sent via POST request.

obligatory parameters

shopId:shop ID
url:product URL to generate a short link for
product:product name
email:user email

additional parameters

name:user name

returns

shortid:unique code
url:shorted product URL

example query:

POST http://api.addshoppers.com/1.0/influencers

    shopId=4f6724485b3a426c50000146
    key=jnlbm-7pxtwblnoajg-mhp2l6rff44sm
    url=http://example.com/product_url
    product=Example Product
    name=test user
    email=example@user.com

example response:

{
   "url": "http://shop.pe/12345",
   "shortid": "12345"
}

/influencers/list

Returns all influencers for a site within specified time period.

obligatory parameters

shopId:shop ID

additional parameters

time:time selection [ All Time, Today, Yesterday, Last 7 Days, Last 30 Days, Current Week, Last Week, Current Month, Last Month ]
activity:shows influencers activity in response when set to true

returns

influencers:

array of influencers (JSON objects) matching given parameters

Note

“activity” attribute is present only when “activity” request parameter was set to true

{
    "name": "Example User",
    "email": "user@example.com",
    "id": "57b5da43d55930109a1dd595",
    "networks": [
        "facebook",
        ...
    ],
    "opt_out": false,
    "verified": true,
    "activity": [
        {
            "clicks": 1,
            "date": "2016.02.23",
            "product_name": "Example product",
            "product_url": "http://example.com/product/",
            "revenue": 0,
            "sales": 0,
            "shares": 0,
            "source": "FB Referral"
        }
    ]
}
count:

number of returned influencers

Example request:

GET /1.0/influencers/list?shopId=4f6724485b3a426c50000146&key=jnlbm-7pxtwblnoajg-mhp2l6rff44sm HTTP/1.1
Host: api.addshoppers.com
Accept: application/json, text/javascript
HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
    "count": 2,
    "influencers":
    [
        {
            "name": "Example User",
            "email": "user@example.com",
            "id": "57b5da43d55930109a1dd595",
            "networks": [
                "facebook"
            ],
            "opt_out": false,
            "verified": true
        },
    ]
}

/influencers/tracking

Returns a list of all influencers, including their names, emails, opt-out status and unique sharing links that can be distributed to them and then tracked in AddShoppers.

This endpoint is disabled by default (returns code 400 on successful authentication). In order to enable it for your store, the landing page for the sharing links has to be configured first. Please contact info@addshoppers.com with the name and the URL of the landing page you intend to use.

notes

  • anonymous influencers are skipped,
  • email addresses might not be available for all returned influencers (eg. Twitter),
  • email addresses might not be unique in the returned results.

obligatory parameters

shopId:shop ID

returns

influencers:

array of influencers (JSON objects) matching given parameters:

[{ "name": "Example User",
   "email": "user@example.com",
   "share_url": "http://shop.pe/example",
   "opt_out": false
},...]
count:

number of returned influencers

example query:

GET http://api.addshoppers.com/1.0/influencers/tracking?shopId=4f6724485b3a426c50000146&key=jnlbm-7pxtwblnoajg-mhp2l6rff44sm

example response:

{"count": 10, "influencers":
    [{ "name": "Example User",
       "email": "user@example.com",
       "share_url": "http://shop.pe/example",
       "opt_out": false
    }, ... ]}

/influencers/%SOCIAL%-%USERID%/totals

Returns total sales, shares and clicks for selected influencer.

notes

  • %SOCIAL% - social key (id, facebook_id, twitter_id, linkedin_id, google_id, paypal_id)
  • %USERID% - user id on social service

obligatory parameters

shopId:shop ID

additional parameters

time:time selection [ All Time, Today, Yesterday, Last 7 Days, Last 30 Days, Current Week, Last Week, Current Month, Last Month ]

returns

{
    "sales": 0,
    "shares": 0,
    "clicks": 0
}

example query:

GET http://api.addshoppers.com/1.0/influencers/facebook_id-123456/totals?shopId=4f6724485b3a426c50000146&time=Yesterday&key=JnLbm-7PXTWbLnOajg-MhP2L6rFf44SM

example response:

{
   'sales': 0,
   'shares': 0,
   'clicks': 0
}

/influencers/%SOCIAL%-%USERID%/shared_urls

Returns urls shared by selected user.

notes

  • %SOCIAL% - social key (id, facebook_id, twitter_id, linkedin_id, google_id, paypal_id)
  • %USERID% - user id on social service

obligatory parameters

shopId:shop ID

additional parameters

time:time selection [ All Time, Today, Yesterday, Last 7 Days, Last 30 Days, Current Week, Last Week, Current Month, Last Month ]
limit:number of products returned at once [ default 200, range: 0..200 ]
offset:offset of products returned [ default 0 ]

returns

urls:

array of shared urls

[{‘product_url’: ‘%url%’, ‘timestamp’: ‘%datetime%’}, ...]

count:

number of items

example query:

GET http://api.addshoppers.com/1.0/influencers/facebook_id-123456/shared_urls?shopId=4f6724485b3a426c50000146&time=Yesterday&key=JnLbm-7PXTWbLnOajg-MhP2L6rFf44SM

example response:

{
   "count": 10,
   "urls": [{'product_url': '%url%', 'timestamp': '%datetime%'}, ...]
}

/influencers/%SOCIAL%-%USERID%/orders

Returns orders influenced by selected user.

notes

  • %SOCIAL% - social key (id, facebook_id, twitter_id, linkedin_id, google_id, paypal_id)
  • %USERID% - user id on social service

obligatory parameters

shopId:shop ID

additional parameters

time:time selection [ All Time, Today, Yesterday, Last 7 Days, Last 30 Days, Current Week, Last Week, Current Month, Last Month ]
limit:number of products returned at once [ default 200, range: 0..200 ]
offset:offset of products returned [ default 0 ]

returns

orders:

array

[{‘value’: ‘%cents%’, ‘datetime’: ‘%datetime%’ , ‘orderid’: ‘%order_id%’, ‘product_url’: ‘%url%’}, ...]

count:

number of items

example query:

GET http://api.addshoppers.com/1.0/influencers/facebook_id-123456/orders?shopId=4f6724485b3a426c50000146&time=Yesterday&key=JnLbm-7PXTWbLnOajg-MhP2L6rFf44SM

example response:

{
   "count": 10,
   "orders": [{'value': '%cents%', 'datetime': '%datetime%' , 'orderid': '%order_id%', 'product_url': '%url%'}, ...]
}

/influencers/%SOCIAL%-%USERID%/people

Returns people influenced by selected user.

notes

  • %SOCIAL% - social key (id, facebook_id, twitter_id, linkedin_id, google_id, paypal_id)
  • %USERID% - user id on social service
  • 1000 items at max will be returned

obligatory parameters

shopId:shop ID

additional parameters

time:time selection [ All Time, Today, Yesterday, Last 7 Days, Last 30 Days, Current Week, Last Week, Current Month, Last Month ]

returns

people:

array

[{‘name’: ‘name’, ‘email’: ‘email’, ‘social’: (‘facebook_id’, 1234)}, ...]

count:

number of items

example query:

GET http://api.addshoppers.com/1.0/influencers/facebook_id-123456/people?shopId=4f6724485b3a426c50000146&time=Yesterday&key=JnLbm-7PXTWbLnOajg-MhP2L6rFf44SM

example response:

{
   "count": 10,
   "orders": [{'name': 'name', 'email': 'email', 'social': ('facebook_id', 1234)}, ...]
}

/contacts

Returns all influencers and sweepstake’s emails for a site within specified time period.

obligatory parameters

shopId:shop ID

additional parameters

time:time selection [ All Time, Today, Yesterday, Last 7 Days, Last 30 Days, Current Week, Last Week, Current Month, Last Month ]

returns

contacts:

array of emails (JSON objects) matching given parameters

{
    "email": "user@example.com"
}
count:

number of returned contacts

example query:

GET http://api.addshoppers.com/1.0/contacts?shopId=4f6724485b3a426c50000146&key=jnlbm-7pxtwblnoajg-mhp2l6rff44sm

example response:

{"count": 2, "contacts":
   [{ "email": "user@example.com",
    },... ]}

/refer-a-friend/users

Returns a list of users who signed up for ReferAFriend program. Users who opted-out from receiving emails will not be included.

obligatory parameters

shopId:shop ID

additional parameters

limit:number of records returned at once [ default 10, range: 0..200 ]
offset:offset of records returned [ default 0 ]

returns

users:array of users
count:number of returned users

example query:

GET http://api.addshoppers.com/1.0/refer-a-friend/users?shopId=4f6724485b3a426c50000146&key=jnlbm-7pxtwblnoajg-mhp2l6rff44sm

example response:

{
   "count": 1,
   "users": [
       {
           id: "55757e47346e7109cf61f3c9",
           email: "foo@bar.com",
           created_at: "2015-01-01T00:00:00+00:00"
       }
   ]
}

/account/social-analytics/tracking-codes

obligatory parameters

shopId:shop ID
productId:product ID (given in Product Schema on product site or ‘product_id’ in AddShoppersTracking)

returns

platforms:

dictionary of platforms each platform has a following structure:

code:basic tracking code attached to each site for social analytics
roi_code1:ROI tracking code, used to track revenue etc.
roi_code2:second ROI tracking code - some platforms need putting few codes in different places for full integration (PHP in backend, JS in frontend etc.). If there’s more than one code, second is placed here
code_tip:in addshoppers panel, while choosing integration platform, some handfull “pro tips” are shown. The same are returned here.
roi_code_tip:similar as code_tip, but for the roi tracking code
buttons:

dictionary containing codes social buttons. Each element is keyed button<number> and contains code of sharing button. Numbering starts from 1.

/registration

This call does not require Shop ID and API key params. All parameters described below must be sent via POST request.

obligatory parameters

email:email address
url:shop’s domain
password:user’s password
category:shop’s category name, must be one of: Apparel & Clothing, Arts & Antiques, Automotive & Vehicles, Collectibles, Crafts & Hobbies, Baby & Children, Business & Industrial, Cameras & Optics, Electronics, Entertainment & Media, Food, Beverages, & Tobacco, Furniture, General Merchandise, Gifts, Hardware, Health & Beauty, Holiday, Home & Garden, Jewelry, Luggage & Bags, Mature / Adult, Music, Novelty, Office Supplies, Pets & Animals, Software, Sporting Goods & Outdoors, Toys & Games, Travel, Other
platform:shop’s platform, must be one of: other, magento, volusion, bigcommerce, 3dcart, shopify, prestashop, miva, oscommerce, shopsite, pinnacle, shoppingcartelite

additional parameters

phone:user’s phone number
partner_token:oid token of your partner’s program, must be in format XXXX_Y

returns

result:

API call result code, can be one of the following:

  • LOGIN_EXISTS = -1
  • NOT_CREATED = 0
  • CREATED = 1
  • PASSWORD_TOO_SHORT = 2
  • PASSWORD_CONSECUTIVE_CHARS = 8
  • PASSWORD_COMMON = 9
  • PARAM_MISSING = 10
  • WRONG_PLATFORM = 12
  • WRONG_CATEGORY = 19
  • DOMAIN_BANNED = 17
shopid:

id of the created shop (returned only with CREATED status)

api_key:

user’s API key (returned only with CREATED status)

api_secret:

user’s API secret (returned only with CREATED status)

/login

This call does not require Shop ID and API key params. All parameters described below must be sent via POST request.

obligatory parameters

login:user’s login (usually email address)
password:user’s password
url:domain of shop to which user want to log in. If shop with given domain doesn’t exist, new site is created
site_name:site name
category:shop’s category name, must be one of: Apparel & Clothing, Arts & Antiques, Automotive & Vehicles, Collectibles, Crafts & Hobbies, Baby & Children, Business & Industrial, Cameras & Optics, Electronics, Entertainment & Media, Food, Beverages, & Tobacco, Furniture, General Merchandise, Gifts, Hardware, Health & Beauty, Holiday, Home & Garden, Jewelry, Luggage & Bags, Mature / Adult, Music, Novelty, Office Supplies, Pets & Animals, Software, Sporting Goods & Outdoors, Toys & Games, Travel, Other
platform:shop’s platform, must be one of: other, magento, volusion, bigcommerce, 3dcart, shopify, prestashop, miva, oscommerce, shopsite, pinnacle

returns

result:

API call result code, can be one of the following:

  • AUTHENTICATED = 1
  • PARAM_MISSING = 10
  • WRONG_CREDENTIAL = 11
  • WRONG_PLATFORM = 12
  • DOMAIN_EXIST = 15
  • DOMAIN_BANNED = 17
shopid:

shop’s id for this url (returned only with AUTHENTICATED or DOMAIN_EXIST status)

api_key:

user’s API key (returned only with AUTHENTICATED or DOMAIN_EXIST status)

api_secret:

user’s API secret (returned only with AUTHENTICATED or DOMAIN_EXIST status)