API Reference
Welcome to the Synccentric API documentation! Our API is organized around REST. It has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
https://app.synccentric.com/api/v3
Authentication
Synccentric uses API keys to allow access to the API. You can register a new Synccentric API key while logged into https://app.synccentric.com.
Synccentric expects for the API key to be included in all API requests to the server in a Bearer Token.
curl "https://app.synccentric.com/api/v3/products/29054000682" \
-H "Authorization: Bearer your-api-token" \
API Rate Limits
Limits are based on successful items returned per day. This resets at 12am Central Time (America / Chicago).
Plan | Search Amazon API | Search Synccentric API |
---|---|---|
Basic Plan | API is not avaliable | API is not avaliable |
Standard Plan | 2,000 | 1,000 |
Premium Plan | 10,000 | 5,000 |
Enterprise 10K Plan | 10,000 | 10,000 |
Enterprise 20K Plan | 20,000 | 20,000 |
Enterprise 30K Plan | 30,000 | 30,000 |
Enterprise 40K Plan | 40,000 | 40,000 |
Enterprise 50K Plan | 50,000 | 50,000 |
Enterprise 100K Plan | 100,000 | 100,000 |
Enterprise API | Contact for details | Contact for details |
Example [Search Amazon API]: If you are on the Premium Plan, your GUI storage limit is 5000 products (items you can have in your account at any given time). If you import 5000 products, run a search and all products come back successful, then you will have 5000 successful product results left that you can retrieve in 24 hours - for a total of 10000.
Example [Search Synccentric API]: If you are on the Premium Plan, your limit for this endpoint is 5000 results in 24 hours. If you search for "New Balance Running Shoe" and our system finds 10000 results, we'll return this in the response in pagination with the first page of 10 results. These 10 results will count towards your limit, leaving you with 4990 remaining credits. In this example, you could return up to 500 pages worth of data, totaling 5000 products for the day.
When sending a request to the Synccentric Search and the Amazon Search endpoints, the response headers will contain info on your remaining requests, and number of requests used. This info can be used to create a 'back off' option in your script.
Response Header
{
Connection : 'keep-alive'
Content-Type : "application/json"
X-Amz-Search-Limit : "2000",
X-Amz-Search-Used : "80",
X-Amz-Search-Remaining : "1920",
X-Sync-Search-Limit : "1000",
X-Sync-Search-Used : "80",
X-Sync-Search-Remaining : "920"
}
Fields Available
List of fields available in our product data object. Specify to include respective field on export or search.
actor
additional_image_1
additional_image_2
additional_image_3
additional_image_4
additional_image_5
all_categories
amazon_landed_price
artist
asin
aspect_ratio
audience_rating
author
band_material_type
bb_new_landed_price_avg_1mo
bb_new_landed_price_avg_3mo
bb_new_landed_price_avg_6mo
bb_new_landed_price_avg_12mo
binding
blueray_region
brand
category
cero_age_rating
chain_type
child_asins
clasp_type
color
cpu_manufacturer
cpu_speed
cpu_type
creator
description
director
display_size
ean
edition
eisbn
energy_efficiency_rating
episode_sequence
esrb_age_rating
fba_monthly_storage
features
format
genre
hard_disk_interface
hard_disk_size
hardware_platform
has_super_saver_shipping
hazardous_material_type
highest_new_fulfillment_channel
highest_new_price
highest_new_shipping
highest_new_feedback_rating
highest_new_feedback_count
highest_new_price_fba
highest_new_shipping_fba
highest_new_feedback_rating_fba
highest_new_feedback_count_fba
highest_new_price_merchant
highest_new_shipping_merchant
highest_new_feedback_rating_merchant
highest_new_feedback_count_merchant
is_adult_product
is_eligible_for_prime
isbn
item_dimensions_height
item_dimensions_length
item_dimensions_weight
item_dimensions_width
keyword_match_percentage
label
languages
large_image
list_price_amount
list_price_currency_code
listing_url
lowest_new_feedback_count
lowest_new_feedback_count_fba
lowest_new_feedback_count_merchant
lowest_new_feedback_rating
lowest_new_feedback_rating_fba
lowest_new_feedback_rating_merchant
lowest_new_fulfillment_channel
lowest_new_price
lowest_new_price_fba
lowest_new_price_merchant
lowest_new_shipping
lowest_new_shipping_fba
lowest_new_shipping_merchant
lowest_offer_listings
lowest_refurbished_price
lowest_used_feedback_count
lowest_used_feedback_count_fba
lowest_used_feedback_count_merchant
lowest_used_feedback_rating
lowest_used_feedback_rating_fba
lowest_used_feedback_rating_merchant
lowest_used_fulfillment_channel
lowest_used_price
lowest_used_price_fba
lowest_used_price_merchant
lowest_used_shipping
lowest_used_shipping_fba
lowest_used_shipping_merchant
manufacturer
maximum_resolution
media_type
medium_image
metal_stamp
metal_type
model
mpn
node_id
nodeid_tree
number_of_discs
number_of_issues
number_of_items
number_of_pages
number_of_tracks
operating_system
optical_zoom
package_dimensions_height
package_dimensions_length
package_dimensions_weight
package_dimensions_width
package_quantity
parent_asin
part_num
pegi_rating
platform
processor_count
product_group
product_type_name
product_type_subcategory
publication_date
publisher
referral_fee
region_code
release_date
repairability_index
ring_size
running_time
sales_rank
sales_rank_avg_1mo
sales_rank_avg_3mo
sales_rank_avg_6mo
sales_rank_avg_12mo
sales_rank_category
sales_rank_summary
scent
season_sequence
second_lowest_landed_price
shaft_material
size
sku
small_image
studio
subcategory
system_memory_size
system_memory_type
theatrical_release_date
title
total_new_sellers
total_new_sellers_fba
total_new_sellers_merchant
total_refurbished_sellers
total_used_sellers
total_used_sellers_fba
total_used_sellers_merchant
trade_in_value
upc
variable_closing_fee
warranty
buybox_seller
buybox_new_landed_price
buybox_new_listing_price
buybox_new_shipping_price
buybox_new_subcondition
buybox_used_landed_price
buybox_used_listing_price
buybox_used_shipping_price
buybox_used_subcondition
fba_fee_total
fba_order_handling
fba_pick_pack
fba_tier_level
fba_weight_handling
reviews_average
reviews_total
total_fees_estimate
Errors
Synccentric uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Synccentric's servers (these are rare).
Some 4xx errors that could be handled programmatically (e.g., You have a job already running) include an error code that briefly explains the error reported.
attributes
-
id string
The type of error returned.
-
status string
The type of error returned.
-
title string
The title of the error
-
detail string
The details of the error
Search Amazon
Search Amazon by importing your identifiers to your Synccentric account, queue a search, poll the status, and export the results when the search is complete. These endpoints mimic the GUI of Synccentric and collect data in real-time. This is a bulk search and requires the search to be queued and all results returned on a separate request after the search is complete. For ‘on the fly’ product data request/response, see Search Synccentric API.
We have a step by step guide to the process of Searching through Amazon via API.
Manage Products
These endpoints allow you to Import, Export, and/or Delete Identifiers/Products from your Synccentric campaign. Identifiers/Products can be managed individually or in bulk. These endpoints are used before and after you queue an Amazon search.
Import Identifiers
To import products, send a POST
request to the /products
endpoint and include the product attributes as JSON format in the request body.
Arguments
curl "https://app.synccentric.com/api/v3/products" \
-H "Authorization: Bearer your-api-token" \
-d "identifiers[0][identifier]=B00YECW5VM" \
-d "identifiers[0][type]=asin" \
-XPOST
Export all products
Retrieve products within your campaign by sending a GET
request to the /products
endpoint.
Arguments
curl -X GET 'https://app.synccentric.com/api/v3/products' \
-H "Authorization: Bearer your-api-token" \
-d "campaign_id=<your-campaign-id>" \
-d "fields[]=upc" \
-d "fields[]=ean" \
-d "filters[sales_rank][]=1" \
-d "filters[sales_rank][]=999" \
-d "filters[duplicates]=best_ranked" \
-G
Export product by ID
Retrieve a specific product within your campaign by sending a GET
request to the /products/:id
endpoint.
Replace :id with the identifier of the product you want to retrieve.
arguments
curl "https://app.synccentric.com/api/v3/products/id" \
-H "Authorization: Bearer your-api-token" \
-d "fields[]=upc" \
-d "fields[]=ean" \
-d "campaign_id=<your-campaign-id>" \
-G
Delete all products
To delete all products within a campaign, send a DELETE
request to the /products/
endpoint.
NOTE:
Caution is advised with this endpoint as this is an irreversible operation.
Arguments
curl "https://app.synccentric.com/api/v3/products/" \
-H "Authorization: Bearer your-api-token" \
-d "campaign_id=<your-campaign-id>" \
-XDELETE
Delete by id
To delete a specific product, send a DELETE
request to the /products/:id
endpoint, replacing :id with the identifier of the product you want to delete.
Arguments
curl "https://app.synccentric.com/api/v3/products/:id" \
-H "Authorization: Bearer your-api-token" \
-d "campaign_id=<your-campaign-id>" \
-XDELETE
Product Search
Product Search allows you to initiate (queue) a search, cancel a search, or check the status of a search to monitor progress. Starting a search will begin the mapping process between the identifiers in your account and products on Amazon.
Queue a search
To start a product search send a POST
request to the /product_search
endpoint. Aside from the campaign id, other parameters not specified will default to using the existing campaign settings.
Arguments
curl "https://app.synccentric.com/api/v3/product_search" \
-H "Authorization: Bearer your-api-token" \
-d "campaign_id=<your-campaign-id>" \
-d "retrieve_secondary_listings=true" \
-d "retrieve_buybox_seller=1" \
-d "search_only_new=false" \
-XPOST
Cancel a search
To cancel a search in progress send a POST
request to the /product_search/cancel
endpoint.
Arguments
curl "https://app.synccentric.com/api/v3/product_search/cancel"\
-H "Authorization: Bearer your-api-token" \
-d "campaign_id=<your-campaign-id>" \
-XPOST
Poll Status
To get the current status of your search, send a GET
request to the /status
endpoint.
Arguments
curl "https://app.synccentric.com/api/v3/product_search/status" \
-H "Authorization: Bearer your-api-token" \
-d "campaign_id=<your-campaign-id>" \
-G
Search Synccentric
Search our massive database to map identifiers or retrieve products based on a relevancy search. This is an 'on the fly' type of search where you retrieve results directly from the response instead of queuing a search. The results from this search contain data from the last time our system updated the product - it is not real time (i.e. real time pricing or sales rank). For real time data, queue a Amazon search.
You can checkout out our quick guides on how to search by identifier types or searching by keyword types.
Search (Synccentric Database)
Send a GET
request to the /products/search
endpoint with identifiers to search the Synccentric database.
Arguments
curl "https://app.synccentric.com/api/v3/products/search" \
-H "Authorization: Bearer your-api-token" \
-d "identifier[]=B07QN8PDKL" \
-d type=asin \
-d locale=US \
-d "fields[]=asin" \
-d "fields[]=title" \
-d "fields[]=upc" \
-d "fields[]=buybox_new_landed_price" \
-d "fields[]=lowest_new_price" \
-G