Listings
A listing is how a single product shows up on one specific channel. One product in your catalog can have many listings, one for each marketplace where you sell it.
Why listings exist
Every marketplace has its own rules. Etsy wants tags and a handmade story. Amazon wants bullet points and a browse node. eBay wants item specifics. Your Shopify store is probably closer to your brand voice than any of them. If all you had was one product record, you would be stuck writing one description that tried to please every platform at once.
Listings solve that. The product is the shared truth about what the item is. The listing is how that item gets presented on a specific channel, with a title, description, images, and price tuned for that audience.
This separation also keeps inventory honest. When a unit sells on Etsy, the Etsy listing records the sale, the shared product's stock drops, and every other listing pointing at the same product drops at the same time.
The product, listing, channel relationship
One product connects to one or more listings. Each listing belongs to exactly one channel, and each channel is driven by a plugin (Shopify, Etsy, Amazon, eBay, and so on). A t-shirt product might have a Shopify listing, an Etsy listing, and an eBay listing, each with its own title and copy, all tied back to the same internal product and the same inventory.
Listings have a unique constraint on product and channel. The same product cannot be listed twice on the same channel.
Listing fields
Product
The catalog product this listing represents. This link is what ties the listing back to your shared inventory and to other listings for the same item.
Channel
The channel this listing lives on. A listing belongs to exactly one channel. If you want the same item on two channels, you create two listings.
Name
The title shown on the channel. This can be different from the product name in your catalog, which is useful when a marketplace rewards keyword-heavy titles or when you want to adjust wording for a specific audience.
Price
The listed price on this channel. Different marketplaces can have different prices to account for fees, shipping costs, or audience expectations.
Description
The description shown on the channel. Some marketplaces accept HTML, others will strip it. Tailor this per channel. Your Etsy shoppers and your Amazon shoppers are not reading the same thing.
How listings are created
Listings come into Commerce Kitty in two ways. Most commonly a plugin imports them. When you connect a marketplace, the plugin pulls your existing live listings and creates a listing record for each one, linking it to a product by code. If no matching product exists, the plugin creates one too.
The other way is to push a product out to a channel. If you have a product in your catalog that is not yet on Amazon, you can create a new Amazon listing for it and the plugin will publish that listing to the live marketplace.
Whenever possible, Commerce Kitty uses the product code to find a matching item on the third-party platform. If it does not find one, it creates one.