Catalog

This guide walks through the catalog as an integrator meets it: what a product is, how variants and barcodes attach, how to create and update products through the API, and how to keep a catalog imported from your own system correct over time. The endpoint and field detail is in Catalog Endpoints; read Core Concepts first for identifiers, pagination, and idempotency.

Goal and prerequisites

Goal: your products exist on the Platform exactly once each, with content a buyer can trust, prices and stock attached, and a placement where browsing buyers can find them.

Prerequisites: an issued API key with catalog scope (Getting Started), and your product data in your own system with one stable product code per product: that code is how you match your records to Platform records across every later update.

The shape of a product

Keep four ideas separate; confusing them is the root of most catalog defects

Product: the item as described: name, brand, description, images. The product is what a buyer reads about.
Variant: a purchasable difference within the product: size, flavor, count. A product with no meaningful differences has one variant.
Your product code: the identifier from your system, carried on the product so updates find the same record every time. The Platform's id is the Platform's identifier; your code is yours. Keep both, and match on either consistently.
Placement: where the product appears in the marketplace's category structure. A product with no placement exists but cannot be found by browsing; a product with no current price exists but cannot be sold. Both are data-quality problems to detect and fix, not states to leave in place.

Barcodes (GTIN/UPC), where you have them, belong on the variant that is actually sold under that barcode. Accurate barcodes prevent duplicate listings when the same item arrives from more than one source.

Step 1: Create a product

POST https://www.aapawz.com/api/catalog/products
Authorization: Bearer <your-api-key>
Content-Type: application/json
Idempotency-Key: <a-unique-value-for-this-write>

{
  "name": "Example Brand Grain-Free Dog Food, 10 lb",
  "brand": "Example Brand",
  "description": "…",
  "your_product_code": "EB-DOGFOOD-10",
  "variants": [
    { "name": "10 lb bag", "your_variant_code": "EB-DOGFOOD-10-A", "barcode": "000000000000" }
  ]
}

Field requirements, enums, and the full request and response shapes are in Catalog Endpoints and Data Types and Enums. Request and Response Examples shows complete calls. The response returns the created product with its Platform id: store that id against your product code in your system. Creating the same product twice is the defect this step exists to prevent: always send an Idempotency-Key (Idempotency Keys), and always check for an existing product with your product code before creating a new one.

Step 2: Attach price and stock

A product becomes sellable when price and availability arrive through their own resources

Set the selling price through Pricing Endpoints; the Pricing guide covers the rules. A price sent with a product is not a substitute for the pricing resource.
Report availability through Inventory Endpoints; the Inventory guide covers the discipline.
Place the product in the category structure as Catalog Endpoints specifies. Category placement is merchandising: later price or stock updates must never change it as a side effect.

Step 3: Update without duplicating

Updates use the product's Platform id or your product code, exactly as Catalog Endpoints specifies: never a fresh create. The rules that keep a catalog clean over years of updates

Match first. Before any write, resolve the product in your system of record to the Platform product. If the match is missing, treat it as an exception to investigate, not as a cue to create.
Send changes, not churn. Compare the fields you own before writing, and skip products that have not changed. Rewriting identical records wastes your rate budget and creates phantom change downstream.
Keep codes stable. Never change your product code for an existing product, and never reuse a retired code for a different product. Changed codes are how one product becomes two listings with split history.
Discontinue explicitly. When a product ends, mark it discontinued through the API rather than silently dropping it from your data, so it is withdrawn from sale in an orderly way and its order history stays intelligible.

Brands

Every product names its brand, and the name must match the brand record the Platform holds: supply the brand name exactly as it appears in the brand directory available through Brand and Manufacturer Endpoints, and flag a name that does not match rather than submitting a near-duplicate. "Example Brand" and "Example Brand, Inc." submitted as two brands split search facets, dilute brand pages, and defeat brand authorization checks. Which accounts may list which brands is a separate control, covered in Brand and Manufacturer; the catalog's job is to name the brand exactly.

Images and content

Supply at least one clear image per product, plus the description and specifications a buyer needs to choose without guessing. Content you submit must be yours to submit: your own photography and copy, or the manufacturer's, supplied under your authorization. Submitting another seller's images or copied descriptions is an intellectual-property violation; see Security and Compliance.

Failure handling

400 with a validation code: a required field is missing or malformed. Error Codes names the failing field class; fix the record in your system, not just the request, or the next sync reintroduces the defect.
409 or a duplicate warning: a product with your product code, or a matching barcode, already exists. Resolve to the existing product and update it; do not force a second listing.
Partial success on a multi-product submission: record per-product outcomes from the response and retry only the failures, with their original idempotency keys. See Feeds and Bulk Data for volumes where per-product calls stop being the right tool.

Keeping it correct

Reconcile on a schedule: compare your product codes against a catalog walk (Pagination and Filtering (Pagination & Filtering)) or an export (Feeds and Bulk Data), and alert on products that exist on one side only, products without a current price, and products without placement. Subscribe to catalog-relevant events where Webhooks offers them instead of polling for changes. A catalog integration earns its keep quietly: the same products, described the same way, every day.

Core Concepts

Inventory