Pricefy API API Reference

Pricefy API

API Endpoint
https://api.pricefy.io/api/v1/
Schemes: https
Version: 1.0.0

Authentication

Bearer

name
x-access-token
in
header
description
    For accessing the API a valid API Key token must be passed in all the queries in
    the 'x-access-token' header.

Catalog

Catalog management

importProducts

POST /catalog/import

Import a list of products

Request Example
{
  "append_only": "integer",
  "products": [
    {
      "name": "Test",
      "price": 10,
      "sku": "test1234",
      "ean": "1234567812",
      "status": "ready"
    }
  ]
}
200 OK

Import summary

401 Unauthorized

invalid token

500 Internal Server Error

unexpected failure

Response Content-Types: application/json
Response Example (200 OK)
{
  "imported": "integer",
  "skipped": "integer",
  "name_error": "integer",
  "price_error": "integer",
  "cost_error": "integer",
  "tax_value_error": "integer",
  "missing_barcode": "integer",
  "invalid_ean": "integer",
  "invalid_upc": "integer"
}
Response Example (401 Unauthorized)
{
  "status": "integer",
  "message": "string"
}
Response Example (500 Internal Server Error)
{
  "status": "integer",
  "message": "string",
  "error": "object"
}

importProduct

POST /catalog

Import a product in user catalog

Products data

Request Example
{
  "name": "Test",
  "price": 10,
  "sku": "test1234",
  "ean": "1234567812",
  "status": "ready"
}
200 OK

Generic success response

400 Bad Request

invalid request

401 Unauthorized

invalid token

500 Internal Server Error

unexpected failure

Response Content-Types: application/json
Response Example (200 OK)
{
  "status": "integer",
  "message": "string"
}
Response Example (400 Bad Request)
{
  "status": "integer",
  "message": "string",
  "errors": [
    {
      "property_key": "string",
      "error_message": "string"
    }
  ]
}
Response Example (401 Unauthorized)
{
  "status": "integer",
  "message": "string"
}
Response Example (500 Internal Server Error)
{
  "status": "integer",
  "message": "string",
  "error": "object"
}

getProducts

GET /catalog

Catalog products

page

Page number

type
integer
in
query
limit

Number of records

type
integer
in
query
200 OK

get catalog products

401 Unauthorized

invalid token

500 Internal Server Error

unexpected failure

Response Content-Types: application/json
Response Example (200 OK)
{
  "total": "integer",
  "page": "integer",
  "products": [
    {
      "id": 216410,
      "name": "Mellin Omogeneizzato alle Zucchine 80 g x 2 - Default Title",
      "price": 10,
      "cost": 0,
      "tax_value": 0,
      "map": "",
      "sku": "",
      "ean": "5900852021817",
      "upc": "",
      "mpn": "",
      "asin": "B015G1ZB74",
      "gtin": "",
      "picture_url": "https://cdn.shopify.com/s/files/1/2297/9893/products/ecb92d38bf8a21c7bda51f3594559f5a.jpg?v=1503496020",
      "composite_id": "EAN:5900852021817",
      "status": "ready",
      "account_id": 1,
      "created_at": "2017-08-26T11:28:07.000Z",
      "updated_at": "2017-08-26T11:31:07.000Z"
    }
  ]
}
Response Example (401 Unauthorized)
{
  "status": "integer",
  "message": "string"
}
Response Example (500 Internal Server Error)
{
  "status": "integer",
  "message": "string",
  "error": "object"
}

deleteProduct

DELETE /catalog/{code}

Delete a product from catalog. Note: the product will be set as deleted and not physically removed.

code

Product code (EAN or UPC)

type
string
in
path
200 OK

Generic success response

401 Unauthorized

invalid token

500 Internal Server Error

unexpected failure

Response Content-Types: application/json
Response Example (200 OK)
{
  "status": "integer",
  "message": "string"
}
Response Example (401 Unauthorized)
{
  "status": "integer",
  "message": "string"
}
Response Example (500 Internal Server Error)
{
  "status": "integer",
  "message": "string",
  "error": "object"
}

getProduct

GET /catalog/{code}

Get product details.

code

Product code (EAN or UPC)

type
string
in
path
200 OK

Product data

401 Unauthorized

invalid token

500 Internal Server Error

unexpected failure

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 216410,
  "name": "Mellin Omogeneizzato alle Zucchine 80 g x 2 - Default Title",
  "price": 10,
  "cost": 0,
  "tax_value": 0,
  "map": "",
  "sku": "",
  "ean": "5900852021817",
  "upc": "",
  "mpn": "",
  "asin": "B015G1ZB74",
  "gtin": "",
  "picture_url": "https://cdn.shopify.com/s/files/1/2297/9893/products/ecb92d38bf8a21c7bda51f3594559f5a.jpg?v=1503496020",
  "composite_id": "EAN:5900852021817",
  "status": "ready",
  "account_id": 1,
  "created_at": "2017-08-26T11:28:07.000Z",
  "updated_at": "2017-08-26T11:31:07.000Z"
}
Response Example (401 Unauthorized)
{
  "status": "integer",
  "message": "string"
}
Response Example (500 Internal Server Error)
{
  "status": "integer",
  "message": "string",
  "error": "object"
}

Account

Account management

getAccount

GET /account/me

Provides the account details together with enabled countries and sources

200 OK
Me

Account information together with allowed sources and countries

401 Unauthorized

invalid token

500 Internal Server Error

unexpected failure

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1,
  "email": "accountemail@domain.com",
  "picture_path": "https://s3.amazonaws.com/img.pricefy.io/avatar/default_profile_img.png",
  "firstname": "Fabrizio",
  "lastname": "D'Ammassa",
  "country": "",
  "currency": "EUR",
  "tax_value": 0,
  "country_code": "",
  "zip": "",
  "address": "",
  "city": "",
  "company_name": "",
  "website_name": "",
  "website_type": "",
  "phone_prefix": "+39",
  "phone": "",
  "created_at": "2016-11-28T20:59:19.000Z",
  "sources": [],
  "countries": []
}
Response Example (401 Unauthorized)
{
  "status": "integer",
  "message": "string"
}
Response Example (500 Internal Server Error)
{
  "status": "integer",
  "message": "string",
  "error": "object"
}

Common

Common API

getBestsellerCategories

GET /common/categories/{country_code}

Provides the list of Amazon bestesellers categories for a specific country

country_code

Country ISO Code

type
string
in
path
200 OK

Contains the list of categories by country

401 Unauthorized

invalid token

500 Internal Server Error

unexpected failure

Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "id": "string",
    "name": "string"
  }
]
Response Example (401 Unauthorized)
{
  "status": "integer",
  "message": "string"
}
Response Example (500 Internal Server Error)
{
  "status": "integer",
  "message": "string",
  "error": "object"
}

Query

Prices query

catalogAnalysisList

GET /query/analysis

Provides the analysis result for the entire catalog

page

Result page to return

type
number
in
query
country_code

Country ISO Code to restrict the analysis to

type
string
in
query
source_code

Data source code to restrict the analysis to

type
string
in
query
200 OK

Product Analysis List

401 Unauthorized

invalid token

500 Internal Server Error

unexpected failure

Response Content-Types: application/json
Response Example (200 OK)
{
  "count": "number",
  "filters": {
    "page": "number",
    "country_code": "string",
    "source_code": "string"
  },
  "pages": "number",
  "records": [
    {
      "composite_id": "EAN:5900852021817",
      "asin": "B015G1ZB74",
      "name": "Mellin Omogeneizzato alle Zucchine 80 g x 2 - Default Title",
      "cost": 0,
      "price": 10,
      "ean": "5900852021817",
      "upc": "",
      "picture_url": "https://cdn.shopify.com/s/files/1/2297/9893/products/ecb92d38bf8a21c7bda51f3594559f5a.jpg?v=1503496020",
      "avg_rank": 315036.5,
      "min_price": 2.98,
      "max_price": 7.97,
      "avg_price": 5.39,
      "avg_offers": 1,
      "avg_rating": 5,
      "sum_reviews": 16,
      "min_check_ts": "2017-07-27T05:26:46.000Z",
      "max_check_ts": "2017-07-27T05:26:46.000Z"
    }
  ]
}
Response Example (401 Unauthorized)
{
  "status": "integer",
  "message": "string"
}
Response Example (500 Internal Server Error)
{
  "status": "integer",
  "message": "string",
  "error": "object"
}

catalogAnalysis

GET /query/analysis/{code}

Provides the catalog anaylsis for a product by EAN/UPC

code

Product code (EAN or UPC)

type
string
in
path
country_code

Country ISO Code to restrict the analysis to

type
string
in
query
source_code

Data source code to restrict the analysis to

type
string
in
query

Product Analysis

401 Unauthorized

invalid token

500 Internal Server Error

unexpected failure

Response Content-Types: application/json
Response Example (200 OK)
{
  "composite_id": "EAN:5900852021817",
  "asin": "B015G1ZB74",
  "name": "Mellin Omogeneizzato alle Zucchine 80 g x 2 - Default Title",
  "cost": 0,
  "price": 10,
  "ean": "5900852021817",
  "upc": "",
  "picture_url": "https://cdn.shopify.com/s/files/1/2297/9893/products/ecb92d38bf8a21c7bda51f3594559f5a.jpg?v=1503496020",
  "avg_rank": 315036.5,
  "min_price": 2.98,
  "max_price": 7.97,
  "avg_price": 5.39,
  "avg_offers": 1,
  "avg_rating": 5,
  "sum_reviews": 16,
  "min_check_ts": "2017-07-27T05:26:46.000Z",
  "max_check_ts": "2017-07-27T05:26:46.000Z"
}
Response Example (401 Unauthorized)
{
  "status": "integer",
  "message": "string"
}
Response Example (500 Internal Server Error)
{
  "status": "integer",
  "message": "string",
  "error": "object"
}

priceAnalysisList

GET /query/price

Provides the price analysis result for the entire catalog

page

Result page to return

type
number
in
query
country_code

Country ISO Code to restrict the analysis to

type
string
in
query
source_code

Data source code to restrict the analysis to

type
string
in
query
200 OK

Product Price List

401 Unauthorized

invalid token

500 Internal Server Error

unexpected failure

Response Content-Types: application/json
Response Example (200 OK)
{
  "count": "number",
  "pages": "number",
  "filters": {
    "page": "number",
    "country_code": "string",
    "source_code": "string"
  },
  "records": [
    {
      "composite_id": "EAN:5900852021817",
      "name": "Mellin Omogeneizzato alle Zucchine 80 g x 2 - Default Title",
      "picture_url": "https://cdn.shopify.com/s/files/1/2297/9893/products/ecb92d38bf8a21c7bda51f3594559f5a.jpg?v=1503496020",
      "price": 10,
      "cost": 0,
      "ean": "5900852021817",
      "upc": "",
      "source_code": "amazon",
      "price_type": "NEW",
      "offers": 7,
      "avg_price": 5.216667,
      "min_price": 2.98,
      "max_price": 7.97,
      "min_check_ts": "2017-07-24T20:49:02.000Z",
      "max_check_ts": "2017-07-27T05:26:46.000Z"
    }
  ]
}
Response Example (401 Unauthorized)
{
  "status": "integer",
  "message": "string"
}
Response Example (500 Internal Server Error)
{
  "status": "integer",
  "message": "string",
  "error": "object"
}

priceAnalysis

GET /query/price/{code}

Provides the price analysis for a specific product identified by EAN/UPC

code

Product code (EAN or UPC)

type
string
in
path
country_code

Country ISO Code to restrict the analysis to

type
string
in
query
source_code

Data source code to restrict the analysis to

type
string
in
query
200 OK

Price comparison

401 Unauthorized

invalid token

500 Internal Server Error

unexpected failure

Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "composite_id": "EAN:5900852021817",
    "name": "Mellin Omogeneizzato alle Zucchine 80 g x 2 - Default Title",
    "picture_url": "https://cdn.shopify.com/s/files/1/2297/9893/products/ecb92d38bf8a21c7bda51f3594559f5a.jpg?v=1503496020",
    "price": 10,
    "cost": 0,
    "ean": "5900852021817",
    "upc": "",
    "source_code": "amazon",
    "price_type": "NEW",
    "offers": 7,
    "avg_price": 5.216667,
    "min_price": 2.98,
    "max_price": 7.97,
    "min_check_ts": "2017-07-24T20:49:02.000Z",
    "max_check_ts": "2017-07-27T05:26:46.000Z"
  }
]
Response Example (401 Unauthorized)
{
  "status": "integer",
  "message": "string"
}
Response Example (500 Internal Server Error)
{
  "status": "integer",
  "message": "string",
  "error": "object"
}

getOpportunities

GET /query/opportunities/{country_code}/{category}

Provides the list of Amazon bestesellers for a specific country

country_code

Country ISO code

type
string
in
path
category

Category ID to restrict the bestesellers list to; you can obtain the categories list from /api/v1/common/categories

type
string
in
path
200 OK

Bestsellers by category and country code

401 Unauthorized

invalid token

500 Internal Server Error

unexpected failure

Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "asin": "B074JKWV6Q",
    "picture_url": "https://images-na.ssl-images-amazon.com/images/I/81aAIhiPqVL._SL500_SR160,160_.jpg",
    "title": "Confort fasciatoio",
    "score": 4.1,
    "reviews_count": 88,
    "woc": 4,
    "demand": 81,
    "position": 81,
    "old_pos": 0,
    "link_prod": "https://www.amazon.it/Confort-fasciatoio/dp/B074JKWV6Q/ref=zg_bs_baby_81?_encoding=UTF8&refRID=TCKHGM1YP1Q6FJT2J5MP",
    "price": 15.5,
    "date": "2017-01-01 00:00:00"
  }
]
Response Example (401 Unauthorized)
{
  "status": "integer",
  "message": "string"
}
Response Example (500 Internal Server Error)
{
  "status": "integer",
  "message": "string",
  "error": "object"
}

Schema Definitions

OkResponse:

status: integer

will be always 1

message: string

Success message

Example
{
  "status": "integer",
  "message": "string"
}

ImportSummary:

imported: integer

imported products

skipped: integer

skipped products (due to validation failure)

name_error: integer

skipped products due to name validation error

price_error: integer

skipped products due to price validation error

cost_error: integer

skipped products due to cost validation error

tax_value_error: integer

skipped products due to tax value validation error

missing_barcode: integer

skipped products due to missing EAN and UPC

invalid_ean: integer

skipped products due to invalid EAN

invalid_upc: integer

skipped products due to invalid UPC

Example
{
  "imported": "integer",
  "skipped": "integer",
  "name_error": "integer",
  "price_error": "integer",
  "cost_error": "integer",
  "tax_value_error": "integer",
  "missing_barcode": "integer",
  "invalid_ean": "integer",
  "invalid_upc": "integer"
}

ProductAnalysis:

composite_id: string

Internal Pricefy ID

asin: string

product ASIN

name: string

product name

cost: number

catalog product cost

price: number

catalog product price

ean: string

EAN

upc: string

UPC

picture_url: string

Product picture url

avg_rank: number

average position in Amazon bestsellers

min_price: number

minimum price detected

max_price: number

maximum price detected

avg_price: number

average price detected

avg_offers: number

average offers number

avg_rating: number

average rating

sum_reviews: number

number of reviews

min_check_ts: string

minimum check date

max_check_ts: string

maximum check date

Example
{
  "composite_id": "EAN:5900852021817",
  "asin": "B015G1ZB74",
  "name": "Mellin Omogeneizzato alle Zucchine 80 g x 2 - Default Title",
  "cost": 0,
  "price": 10,
  "ean": "5900852021817",
  "upc": "",
  "picture_url": "https://cdn.shopify.com/s/files/1/2297/9893/products/ecb92d38bf8a21c7bda51f3594559f5a.jpg?v=1503496020",
  "avg_rank": 315036.5,
  "min_price": 2.98,
  "max_price": 7.97,
  "avg_price": 5.39,
  "avg_offers": 1,
  "avg_rating": 5,
  "sum_reviews": 16,
  "min_check_ts": "2017-07-27T05:26:46.000Z",
  "max_check_ts": "2017-07-27T05:26:46.000Z"
}

PriceAnalysis:

composite_id: string

Internal Pricefy ID

name: string

product name

cost: number

catalog product cost

price: number

catalog product price

ean: string

EAN

upc: string

UPC

picture_url: string

Product picture url

source_code: string

data source code

price_type: string

price type: NEW for new offers, FRON for cover price (used by Amazon only)

num_offers: number

offers number

min_price: number

minimum price detected

max_price: number

maximum price detected

avg_price: number

average price detected

min_check_ts: string

minimum check date

max_check_ts: string

maximum check date

Example
{
  "composite_id": "EAN:5900852021817",
  "name": "Mellin Omogeneizzato alle Zucchine 80 g x 2 - Default Title",
  "picture_url": "https://cdn.shopify.com/s/files/1/2297/9893/products/ecb92d38bf8a21c7bda51f3594559f5a.jpg?v=1503496020",
  "price": 10,
  "cost": 0,
  "ean": "5900852021817",
  "upc": "",
  "source_code": "amazon",
  "price_type": "NEW",
  "offers": 7,
  "avg_price": 5.216667,
  "min_price": 2.98,
  "max_price": 7.97,
  "min_check_ts": "2017-07-24T20:49:02.000Z",
  "max_check_ts": "2017-07-27T05:26:46.000Z"
}

BestSeller:

asin: string

ASIN

picture_url: string

product picture

title: string

product title

score: integer

product rating

reviews_count: number

reviews count

woc: string

number of consecutive weeks the product is in top 100

position: string

current position in top 100

old_pos: string

position of last best sellers scan

link_prod: string

product link on Amazon website

price: number

product price

created_at: string

collection date

Example
{
  "asin": "B074JKWV6Q",
  "picture_url": "https://images-na.ssl-images-amazon.com/images/I/81aAIhiPqVL._SL500_SR160,160_.jpg",
  "title": "Confort fasciatoio",
  "score": 4.1,
  "reviews_count": 88,
  "woc": 4,
  "demand": 81,
  "position": 81,
  "old_pos": 0,
  "link_prod": "https://www.amazon.it/Confort-fasciatoio/dp/B074JKWV6Q/ref=zg_bs_baby_81?_encoding=UTF8&refRID=TCKHGM1YP1Q6FJT2J5MP",
  "price": 15.5,
  "date": "2017-01-01 00:00:00"
}

ProductData:

name: string

product name

price: number

your price

cost: number

your cost

tax_value: integer

tax percentage

map: number

minimum advertised price

sku: string

product SKU

ean: string

product EAN. EAN or UPC required

upc: string

product UPC. EAN or UPC required

asin: string

product ASIN

gtin: string

product GTIN

picture_url: string

product picture url

status: string

any of ready, suspended, or deleted

Example
{
  "name": "Test",
  "price": 10,
  "sku": "test1234",
  "ean": "1234567812",
  "status": "ready"
}

Me:

id: integer

account id

email: string

account email

picture_path: string

account picture

firstname: string

first name

lastname: string

last name

country: string

account country

currency: string

currency code, e.g. USD or EUR

tax_value: integer

tax percentage

country_code: string

country ISO code

zip: string

zip code

address: string

street address

city: string

city

company_name: string

company name

website_name: string

website name

website_type: string

website type, e.g, magento, woocommerce, shopify

phone_prefix: string

phone international prefix

phone: string

phone number

created_at: string

creation date

sources: object[]
countries: object[]
Example
{
  "id": 1,
  "email": "accountemail@domain.com",
  "picture_path": "https://s3.amazonaws.com/img.pricefy.io/avatar/default_profile_img.png",
  "firstname": "Fabrizio",
  "lastname": "D'Ammassa",
  "country": "",
  "currency": "EUR",
  "tax_value": 0,
  "country_code": "",
  "zip": "",
  "address": "",
  "city": "",
  "company_name": "",
  "website_name": "",
  "website_type": "",
  "phone_prefix": "+39",
  "phone": "",
  "created_at": "2016-11-28T20:59:19.000Z",
  "sources": [],
  "countries": []
}

Product:

id: integer

product ID

account_id: integer

account ID

name: string

product name

price: number

your price

cost: number

your cost

tax_value: integer

tax percentage

map: number

minimum advertised price

sku: string

product SKU

ean: string

product EAN

upc: string

product UPC

asin: string

product ASIN

gtin: string

product GTIN

picture_url: string

product picture url

composite_id: string

product internal ID (it uses EAN or UPC)

status: string

any of ready, suspended, or deleted

created_at: string

creation timestamp

updated_at: string

last updated timestamp

Example
{
  "id": 216410,
  "name": "Mellin Omogeneizzato alle Zucchine 80 g x 2 - Default Title",
  "price": 10,
  "cost": 0,
  "tax_value": 0,
  "map": "",
  "sku": "",
  "ean": "5900852021817",
  "upc": "",
  "mpn": "",
  "asin": "B015G1ZB74",
  "gtin": "",
  "picture_url": "https://cdn.shopify.com/s/files/1/2297/9893/products/ecb92d38bf8a21c7bda51f3594559f5a.jpg?v=1503496020",
  "composite_id": "EAN:5900852021817",
  "status": "ready",
  "account_id": 1,
  "created_at": "2017-08-26T11:28:07.000Z",
  "updated_at": "2017-08-26T11:31:07.000Z"
}

UnauthorizedError:

Not authorized error

status: integer

will be always 0

message: string

Authorization error message

Example
{
  "status": "integer",
  "message": "string"
}

ServerError:

Pricefy generic 500 error

status: integer

will be always 0

message: string

Error message

error: object

Error object

Example
{
  "status": "integer",
  "message": "string",
  "error": "object"
}

ValidationError:

Validation error

property_key: string

Property identified (e.g. name or price)

error_message: string

Validation error message

Example
{
  "property_key": "string",
  "error_message": "string"
}

MultipleValidationError:

Validation error for multiple requests

status: integer

will be always 0

message: string

Generic validation message

errors: object
Example
{
  "status": "integer",
  "message": "string",
  "errors": {
    "row": "integer",
    "errors": [
      {
        "property_key": "string",
        "error_message": "string"
      }
    ]
  }
}

SingleValidationError:

Validation error for single product

status: integer

will be always 0

message: string

Generic validation message

errors: ValidationError

List of errors

Example
{
  "status": "integer",
  "message": "string",
  "errors": [
    {
      "property_key": "string",
      "error_message": "string"
    }
  ]
}