Getting Started with Syncing Your Products
The Products API allows you to submit product data for extraction, transformation, and loading (ETL) with Bulk Product uploads into the Clearity platform. This endpoint specifically handles the submission of product information via a CSV file.
Note, the Sync Products API is always treated as a full sync, and does not support an upsert. Any products that are removed from the file will be removed from the manager and no longer considered eligible in your campaign. Including products before they are available on your site is advised as this will enable you to create campaigns with specific products or categories/collections, before they are available for purchase – ensuring that when the product launches, the donation is already configured on the given product.
Setting your Products to Automatically "Include" vs "Exclude"
Within the Products Manager with your Clearity portal you can set your products to automatically "Include" or "Exclude" when new products are synced.
When "Included" - If you created a campaign that set all products in "Category A" to donate $5 when purchased, when they product sync is processed, if a new product is ingested that includes "Category A" that product would automatically be Included in the campaign, and therefor create a $5 donation when purchased.
When Excluded - If you created a campaign that set all products in "Category A" to donate $5 when purchased, when they product sync is processed, if a new product is ingested that includes "Category A" that product would automatically be Excluded in the campaign, and therefor no $5 donation would be created, and this product would not be included in the campaign. You would manually be required to "Include" the specific product to become eligible for a donation when purchased.
File Convention and Naming
- Ensure that the CSV file includes headers as provided in the example fields listed below.
- When providing any objects that include multiple values such as groupingIds (Categories) or subgroupIds (subcategories), ensure to separation of with commas or pipe-separators.
- This endpoint processes the submitted data for ETL and may take up to 10 minutes per 500MB for completion.
- File name for the CSV needs to include the given EntityId surrounded by underscores, followed by UTC timestamp.
- For example: "domain.com_61234abcd-5dbc-5678-abcd-efcg101124345_2024-11-05T13.csv"
The following CSV Fields are required to be mapped for ingestion:
| ShoppingGives Column Header | Similar Merchant Column Header | Format | Description | Required |
|---|---|---|---|---|
| productGroupId | Style Id | string | The product grouping Id is the parent Id of a group of similar products with different variants. Often referred to as the Style Id. For example, this would be the Id of a t-shirt with four (4) different sizes. When the customer lands on the page, and no variant is selected, this Id groups the products. | Required |
| productId | Variant Id | string | Unique product identifier for your system. Can be filled with either a Product CMS ID if generated by a CMS or a SKU. | Required |
| sku | SKU | string | Store Keeping Unit, Unique identifier for the product. | Required |
| name | Name | string | Name of the product. | Required |
| description | description | string | Description of the product. | Optional |
| images | Product Image | URL | Url of the image desired to associate the product with. | Optional |
| basePrice USD | Product MSRP USD | number | The full price of the item in USD. It should not include any currency symbol. | Required |
| basePrice CAD | Product MSRP CAD | number | The full price of the item in CAD. It should not include any currency symbol. | Optional |
| tags | tag | Pipe Separated Strings | List of tags associated with the product. If more than one, pipes will be used to separate the list. | Optional |
| productUri | product URL | URL | URL of the web page the product is displayed. | Optional |
| groupingIds | Categories | Pipe Separated Strings | List of Groupings or Collections the product is associated with. If more than one, pipes will be used to separate the list. | Required |
| subGroupIds | Sub-Categories | Pipe Separated Strings | List of Groupings or Collections the product is associated with. If more than one, pipes will be used to separate the list. | Optional |