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.

base url 
							

									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.

Sample Request with Auth 
							
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

    HTTP STATUS CODE SUMMARY
    200 - OK
    Everything worked as expected.
    400 - Bad Request
    The request was unacceptable, often due to missing a required parameter.
    401 - Unauthorized
    No valid API key provided.
    402 - Request Failed
    The parameters were valid but the request failed.
    403 - Forbidden
    The API key doesn't have permissions to perform the request.
    404 - Not Found
    The requested resource doesn't exist.
    429 - To Many Requests
    Too many requests hit the API too quickly. We recommend an exponential backoff of your requests

    ERROR TYPES
    campaign_not_found
    Campaign not found with the campign id sent in the parameters
    search_limit_reached
    Search limit reached on account. This resets at 12am Central Time (America / Chicago).
    import_limit_reached
    You have reached your import limit. If you need more storage you can upgrade.
    job_already_running
    You currently have a job running for the specified campaign.
    invalid_keys
    amazon MWS credentials in your campaign settings not valid.
    needs_credentials
    You need MWS credentials to continue for this operation.
    something_went_wrong
    Covers any other type of problem (e.g., a temporary problem with Synccentric's servers).
    no_products
    There are no products in the campaign you passed.

    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
    POSThttps://app.synccentric.com/api/v3/products 
                        
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
    gethttps://app.synccentric.com/api/v3/products 
                        
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
    gethttps://app.synccentric.com/api/v3/products/:id 
                        
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
    deletehttps://app.synccentric.com/api/v3/products 
                        
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
    deletehttps://app.synccentric.com/api/v3/products/ 
                        
curl "https://app.synccentric.com/api/v3/products/:id" \
    -H "Authorization: Bearer your-api-token" \
    -d "campaign_id=<your-campaign-id>" \
    -XDELETE

    Poll Status

    To get the current status of your search, send a GET request to the /status endpoint.

    Arguments
    gethttps://app.synccentric.com/api/v3/product_search/status 
                        
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 Database)

    Send a GET request to the /products/search endpoint with identifiers to search the Synccentric database.

    Arguments
    gethttps://app.synccentric.com/api/v3/products/search 
                        
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