New Product Importer API
Introduction
One of the easiest ways to integrate a 3rd party application to manage your inventory is to POST a CSV to your SiteManager import API. This involves using a REST-like POST call to update and add products as well as categorize them and attribute them to existing brands. You can also specify that the CSV represents all items, which will delete all products not present in the file. This is our simplest form of product integration, and requires the API client to perform all mapping between the 3rd party application's categories and vendors with those of the website.
Two Methods of Import
CSV Method: Recommended because of its smaller input post body since headers are only included once. Simply add the CSV file as a file parameter.
JSON Method: Recommended when JSON format is easier to export from any software you’re integrating.
Post Variables
All parameters below are optional unless otherwise stated. The default value will be used if the parameter is excluded.
pos_import=1 Use
pos_import=1if these products are from a POS or inventory software, and you want to use category and vendor mapping pages in SiteManager. You can manage POS items and regular items separately in different imports, but always keep POS items separate by including this parameter. Default: 0skip_first_row=1: to skip the header row of the CSV while processing. Default: 0
ignore_blank_inputs=1: means it won't overwrite new values that are blank. Default: 0
use_ladies_for_blank_gender=1: uses "Ladies'" as the default if no gender is specified. Default: 0
use_item_title_for_description=1: inserts the item title as the description (if you don't have descriptions). Default: 0
replace_all_items=1: consider this CSV file the master, and delete any items from the website that are not in this CSV. (Note that the old parameter 'replace_all_items_with_csv' still works.) Default: 0
keep_zero_stock_visible=1: If you have items with a stockLevel value of 0, and want to keep them shown on the website, use this parameter. Default: 0
replace_line_breaks=1: Take any line breaks in the description, and convert them to HTML line breaks. Default: 0
updateOnly=1: If you’re only updating a few fields, pass this in. Don’t forget to use pos_import if updating POS items. This parameter takes away the minimum column restriction, and because of that, doesn’t allow inserts. Style number (“styleNo”) is required as the item key. Default: 0
csv_file (Required if using CSV method): file parameter
Images
This API requires you to have your images formatted as URLs that can be reached via HTTP.
The alternative for images is that you push them to our image upload endpoint, or upload them manually. Let us know if you would like any information on the latter 2, as they are not currently being used.
Authentication
Calls to your API will require a query string parameter authKey=. Please contact us for an API key
End Points
The following endpoint URLs will require you to change the {DOMAIN} portion with your domain. Note that if your site isn't live and is on a staging URL (*.shopfinejewelry.com), your domain will change once your site goes live.
CSV Method:
https://{DOMAIN}/api/async/sitemanager/import_jewelry_data/import_csv?authKey={AUTHKEY}JSON Method
https://{DOMAIN}/api/async/sitemanager/import_jewelry_data/import_json?authKey={AUTHKEY}Image CDN Push
https://{DOMAIN}/api/async/sitemanager/s3/sync_local_folder?folder=images/items&authKey={AUTHKEY}
This happens automatically upon import, but sometimes on the first upload with 1,000s of images, it times out and needs to be called again. POS items are handled differently. Consult with Punchmark before using this endpoint.
CSV Format
A link to the valid CSV format can be found here. For more advanced options, contact us.
Valid Values
Each column type has a list of valid values that will need to be mapped from your 3rd party application in order to be used.
Metal Types
Jewelry Types
Styles
Gemstone Types
Gemstone Shapes
Diamond Shapes
Diamond Shape Map
Ring Settings
Metal Finishes
Custom Fields (optional)
The SiteManager Product CSV format allows up to 17 (current maximum) custom fields to be used for various purposes. Note that these fields won’t automatically be mapped to the front end, but can be mapped by our front end team.
Adding Custom Fields
To add custom fields, begin after the last column in the import CSV. Each custom field requires a separate column for name and value named with the format below.
Format
Naming convention of these fields follows the format detail1Name, detail1Value, detail2Name, detail2Value. You can use any number of these fields up to the maximum.
