- 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 to requirements in our Knowledge Center, but this will require some research.
- Digital Marketing Data Feed Requirements
- Different feed providers have varying data requirements.
- Requirements will vary widely based on the Digital Marketing product purchased from ChannelAdvisor.
- Requirements can be found under the specific products on the Digital Marketing page in the ChannelAdvisor Knowledge Center.
- 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|
Important Note: Only applies to accounts in Variations v2 design - not required to build parents in relationships.
Important Note: Applies only to existing sellers providing this data. New sellers should use VaryBy.
|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|
- For Variations v1 Sellers: this field does not apply - it can be sent in a request, and it will not fail, but the value will not be displayed or stored.
- For Variations v2 Sellers: this field is optional. Supply a comma separated list of attributes that will vary for the specified Parent/Child relationship.
- Find more information on the new Variation design in the Knowledge Center (login required).
- For Variations v1 Sellers: this field is REQUIRED. This request will FAIL if the specified Variation Relationship DOES NOT exist.
- For Variations v2 Sellers: if an existing integration supplies this data, continue supplying it. New integrations should NOT supply this value.
- Find more information on the new Variation design in the Knowledge Center (login 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.
- 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
- (Applicable to Variations v1 Only) Relationship Names - 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'.
- If an integration previously supplied this data and the account was moved to Variations v2, continue to supply this data to avoid interruption.
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