- For large catalogs (> 250,000 products), creating products individually via API is NOT recommend as it is generally a slower method of generating products compared to file uploads.
- If generating a large number of products via API, we recommend spreading the requests over the course of a number of hours or even days to stay below the REST API Request Limits.
Marketplace Data Requirements
Different marketplaces have varying data requirements based on the category/categories under which the products will be listed.
- Requirements can be found at each marketplace site, and in some cases, ChannelAdvisor has links under the specific Marketplace sub-section of the Community, but this will require some research.
- Digital Marketing Data Feed Requirements
- Required Properties to Create Products in ChannelAdvisor
- Only SKU is technically required to create a product via API, but we advise sending at least 'Sku' and 'Title' to ensure any users accessing products through the user interface don't receive errors if they are updating data manually, since Title is required through the UI.
- Many POST/PATCH endpoints only require the data point(s) intended for update, so there may be very few required fields in examples.
- See the Product Entity tables for POST and PATCH requirements.
- Requirements for creation of various product types will vary - see Creating Products and Updating Products for more information.
Most property types (e.g. string length, integer as 32 bit) in the system are much longer than values we typically expect to see or send to a marketplace or digital marketing feed in order to accommodate changes that the marketplaces and feed providers may potentially make.
It is recommended for clients to be similarly flexible because marketplaces and marketing feed providers can change the values/formats they use at any time without notice.
- Distribution Center IDs
- Quantity is defined by distribution center ID - therefore the ID is critical to quantity updates.
- See how to add distribution centers at the links below:
- See how to retrieve Distribution Center info via API.
- Classifications exists as a way to limit the attributes that exist across products. The field has a limited length (string (35)), and isn't always a good way to cordon off the attributes.
- Labels are often used to trigger a product to be sent to a marketplace or digital marketing feed. Naming is critical and advise coordination with business partner to ensure all parties are ready for products to be labelled.
General Expected Behavior
- Product Creation Timing Inbound
- When requests are submitted to create products, the amount of time it takes to process will vary based on a number of factors, including but not limited to the number of properties included in the request and the current processing load of the server.
- Once a product is created, some elements may not be available through the UI for up to 20 minutes:
- Processing Frequency Outbound to Marketplaces & Digital Marketing Providers
- See Marketplace Communication Frequency to find out how often updates are sent from ChannelAdvisor to each marketplace.
- Digital Marketing has different timing considerations based on how frequently the feeds are scheduled to send.
Types of Products
A product in the ChannelAdvisor system can be one of the following types:
|Standalone||The default type of product. Self-contained and without any relationship to other products, it can be listed and purchased.||Yes||Yes|
|Parent||A container for one or more child items that vary by one or more attributes such as size or color. A parent does not have quantity and is not purchasable.||No||No|
|Child||A child product can be purchased and is always related to a single parent product. A child product usually exists for each variation of a parent product.||Yes||Yes|
|Bundle||Bundles are a virtual container for one or more other buyable items. For example, a bundle may contain one camera and two memory cards. Each bundle component, which can be either a standalone or child product, has a component multiplier quantity, which is used to calculate the bundle's overall quantity.||Yes||Yes (calculated)|
Product Creation Process
Creation of all parts of a product will require a minimum of four separate requests to create the product, set values, add quantity, and add images:
- POST /v1/Products - to create the product and attributes
- GET /v1/Products - to get the ProductID that will be used in the next two requests
- PATCH or PUT /v1/Products(id)/Images - to add images to the product. See Images page to find Placement Names information and examples.
- Add quantity (the endpoint used can vary based on requirements) - see more on the Quantity page.
- Optionally - Labels can be added after product creation with a different endpoint. See Labels page for examples.
Basics of Creating a Product in the ChannelAdvisor System
There are key properties within the entities for products - these properties will differ based on the product type being created.
Important and/or Required Parameters for Specific Product Types
|Property||Type (Max Length)||Note||Standalone||Parent||Child||Bundle|
|ProfileID||integer (32 bit)||Identifies the ChannelAdvisor profile - required if access multiple profiles from one token||Conditional||Conditional||Conditional||Conditional|
|Sku||string (50)||Unique identifier of the product within the seller's catalog.||Required||Required||Required||Required|
|IsParent||boolean||True if the product is a Parent with children (to be associated).||N/A||Required||Required||N/A|
|IsInRelationship||boolean||Whether or not the product is in a parent/child relationship. Parents and children will be true, standalone products will be false.||N/A||Required||Required||N/A|
|RelationshipName||string (50)||If the product is in a relationship, this value represents the relationship type. The types are user-defined within ChannelAdvisor.||N/A||Required||Required||N/A|
|ParentProductID||integer (32 bit)||The Product ID of the Parent this child should be related to. |
The ChannelAdvisor defined unique ID (not the Sku value) of the product.
|BundleType||enum||None = Not a bundle, BundleComponent = Is a component in at least 1 bundle, BundleItem = Is a bundle||N/A||N/A||N/A||Required|
[ ComponentSku ]
|string (50)||Sku(s) that will be part of this Bundle.||N/A||N/A||N/A||Required|
[ Quantity ]
|integer (32 bit)||Quantity of this Sku that will be part of this Bundle.||N/A||N/A||N/A||Required|
Other Properties to Create a Product
See the Product Entity tables for the properties that are optional for creating a product under the POST column.
Note: some collections may be required based on type of the product being created - the 'BundleComponents' collection is required to create a bundle, and the 'Attributes' collection is required to create a new product with attributes, etc.
There are a few things that need to exist in the ChannelAdvisor System prior to creating a product with these elements. This ensures mistakes during creation don't add excessive unnecessary data to the system.
Note: these values cannot be added via API endpoints.
- Relationship Names (aka Variation Theme) - child products (along with the parent) are related to one-another through one or more attributes. e.g. color, size, finish, metal type, diamond size, etc. We refer to these as 'RelationshipName' values, and they must be pre-created in the system avoid addition of unnecessary values.
- Recommend normalizing these relationship names to keep the count of necessary values down to a minimum. Similarly-named attributes should exist to correlate with these values, and optionally still provide specific field attributes in the event it makes sense to do so.
- Maximum length of a Relationship Name value is 32 characters.
- For example: if sending RelationshipName = Color and Size, have an attribute named 'Color' and another attribute named 'Size', but similar attributes may exist named 'Gemstone Color' and 'Gemstone Size'.
- Distribution Centers - a default Distribution Center is created when ChannelAdvisor generates a profile. If additional locations are needed, they will need to be created in the system prior to adding quantity.
- Supplier Code (not often used) - a vendor to source the products sold by the seller
Product Creation Recommendations
- When creating a product, be sure to add as many attributes as needed. Otherwise attribute values must be set one at a time.
- Adding specific elements of a product will need to be completed with separate requests at this time:
- Add Quantity
- Add Labels
- Add Images
- Add new/additional Attributes