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 file or JSON data 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 (replace_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: (CSV Method Only) 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/JSON the master, and delete any items from the website that are not in this CSV/JSON data. (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
item_data: (For JSON method only) JSON item array
vendorGroupID: This parameter sets a groupID on items, so that they can be controlled as a group. replace_all_items=1 will only replace items in this group. Default: 0
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. Note that unlike the CSV Importer in SiteManager, the Product Importer API does not require all fields or that fields be in any specific order.
JSON Format
Place the item data into a POST parameter labeled item_data and include it in the POST body with the other POST parameters. Follow the field names listed on the CSV Format page.
Field Order
Note that, unlike the CSV Importer in SiteManager, the Product Importer API does not require all fields or require that fields be in any specific order.
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
Auto-Generated Item Titles
On new items, if the itemTitle field isn’t provided or is left blank, the importer will attempt to generate an itemTitle from metalType, brand, and itemType. If the import is a pos_import, and pos category mappings are used, the importer will attempt to use the Singular Item Title field at the category level as the itemType. On existing items, itemTitles are not generated.
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.
Response JSON
Success
A typical JSON response looks like this (counts may vary):
{
"status": 200,
"error": "Import Processed",
"data": {
"success": true,
"itemsProcessed": 1,
"newItemsAdded": 1,
"updatedItems": 0,
"deletedItems": 0,
"backedUpItems": 0,
"imagesToDownload": 1,
"imagesDownloaded": 1,
"imagesMatchedByStyle": 0,
"uploadedImagesMatched": 0,
"imagesSkippedExisting": 0,
"imagesFailedToDownload": 0,
"itemsCategorized": 1,
"categoriesRemoved": 0,
"invalidPrimaryCategory": 0,
"invalidSecondaryCategory": 0,
"blankErrors": 0,
"uneditableStyles": 0,
"uncategorizedItems": 0,
"importErrors": [],
"importTimestamp": "2025-07-23_15-36-23",
"s3Results": {
"success": true,
"msg": "Folders synched successfully.",
"results": {
"totalImages": 1,
"totalFiles": 1,
"totalUploaded": 1,
"totalExisting": 0,
"images\/edge": {
"success": true,
"filesFound": 1,
"imagesFound": 1,
"videosFound": 0,
"imagesUploaded": 1,
"existingImages": 0
}
}
}
},
"count": 0
}Error in item
See importErrors object in response below.
Note: Missing or unmatched primaryCategory, first image, description, item title, or metal type will cause that item to be skipped in the import.
{
"status": 200,
"error": "Import Processed",
"data": {
"success": true,
"itemsProcessed": 1,
"newItemsAdded": 0,
"updatedItems": 0,
"deletedItems": 0,
"backedUpItems": 0,
"imagesToDownload": 1,
"imagesDownloaded": 1,
"imagesMatchedByStyle": 0,
"uploadedImagesMatched": 0,
"imagesSkippedExisting": 0,
"imagesFailedToDownload": 0,
"itemsCategorized": 0,
"categoriesRemoved": 0,
"invalidPrimaryCategory": 0,
"invalidSecondaryCategory": 0,
"blankErrors": 0,
"uneditableStyles": 0,
"uncategorizedItems": 0,
"importErrors": [
"Missing description(style: 127\/.5ct) on row 1. Skipping row.",
"Warning: 37-517: Invalid centerGemShape Round Brilliant on row 1",
],
"importTimestamp": "2025-04-23_15-25-04",
"s3Results": null
},
"count": 0
}Error in Import
Import errors can range from missing parameters, invalid JSON, unrecognized field names, or other issues.
{"status":400,"error":"Missing required params","data":null,"count":0}Mistyped Column Name
{
"status": 200,
"error": "Import Processed with errors",
"data": {
"success": false,
"itemsProcessed": 0,
"newItemsAdded": 0,
"updatedItems": 0,
"deletedItems": 0,
"backedUpItems": 0,
"imagesToDownload": 0,
"imagesDownloaded": 0,
"imagesMatchedByStyle": 0,
"uploadedImagesMatched": 0,
"imagesSkippedExisting": 0,
"imagesFailedToDownload": 0,
"itemsCategorized": 0,
"categoriesRemoved": 0,
"invalidPrimaryCategory": 0,
"invalidSecondaryCategory": 0,
"blankErrors": 0,
"uneditableStyles": 0,
"uncategorizedItems": 0,
"importErrors": [
"Invalid headers: Invalid column: \"Item Type\"(0)",
"Error parsing row 1",
"Processing halted at row 1"
],
"importTimestamp": "2025-07-23_15-54-18",
"s3Results": null
},
"count": 0
}