Catalog Endpoints

This document covers the catalog endpoints: creating, reading, updating, and retiring the products and variants your account sells on the marketplace. Prices are managed separately in Pricing Endpoints and stock in Inventory Endpoints; this document covers product content and structure.

Access through the developer API is issued by the Company and is limited by seller type: manufacturer and supplier accounts receive API access for importing data, under the Developer Agreement and the API Access Tiers. Catalog write endpoints require the import entitlement. Nothing in this document grants broader access. Authenticate every request as described in Authentication Endpoints.

Endpoints

Method	Path	Purpose	Access
GET	`/catalog/products`	List your products, paginated	Any API key
GET	`/catalog/products/{id}`	Read one product, with its variants	Any API key
POST	`/catalog/products`	Create a product	Import entitlement
PATCH	`/catalog/products/{id}`	Update product fields	Import entitlement
DELETE	`/catalog/products/{id}`	Retire a product from sale	Import entitlement
GET	`/catalog/products/{id}/variants`	List a product's variants	Any API key
POST	`/catalog/products/{id}/variants`	Add a variant	Import entitlement
PATCH	`/catalog/products/{id}/variants/{variant_id}`	Update a variant	Import entitlement
GET	`/catalog/categories`	List the marketplace categories you may list into	Any API key

All paths are relative to the base URL https://www.aapawz.com/api. Collection responses paginate as specified in Pagination and Filtering (Pagination & Filtering). Writes accept an Idempotency-Key header as specified in Idempotency Keys: send one on every create, so a retried import never creates a duplicate product.

The product object

{
  "id": "prod_8f3ka9",
  "seller_sku": "ACME-DOGFOOD-10LB",
  "title": "Acme Grain-Free Dog Food, 10 lb",
  "description": "A complete dry food for adult dogs.",
  "brand": "Acme",
  "category_id": "cat_pet_food",
  "status": "active",
  "barcode": "012345678905",
  "attributes": {
    "life_stage": "adult",
    "weight": "10 lb"
  },
  "images": [
    { "url": "https://www.aapawz.com/media/acme-dogfood-10lb.jpg", "alt_text": "Bag of Acme dog food" }
  ],
  "variants": [
    {
      "id": "var_51hd02",
      "seller_sku": "ACME-DOGFOOD-10LB",
      "title": "10 lb bag",
      "barcode": "012345678905",
      "attributes": { "size": "10 lb" }
    }
  ],
  "created_at": "2026-09-02T14:03:11Z",
  "updated_at": "2026-10-01T09:41:52Z"
}

Field rules

id is assigned by the Platform and is opaque; treat it as indivisible (see Overview). Field types are defined in Data Types and Enums.
seller_sku is your own stock-keeping unit. It must be unique within your account, and it is the key you match on when re-importing: a create carrying a seller_sku you already use returns 409 with code duplicate_sku rather than a second product. Keep your SKUs stable; changing a SKU creates a new listing identity.
title and category_id are required on create. category_id must come from GET /catalog/categories.
barcode, where provided, must be a valid GTIN (12–14 digits). A barcode already listed by another account may be matched to the existing marketplace product rather than creating a duplicate listing.
status is one of active, inactive, archived. New products are created inactive until a price (Pricing Endpoints) and stock (Inventory Endpoints) exist; set active to offer the product for sale. DELETE sets archived: the product leaves sale, its history is kept, and the action cannot be undone through the API.
attributes holds category-specific values. Send only attributes defined for the category; unknown attribute names are rejected with 422.

Creating a product

POST /catalog/products
Authorization: Bearer <your-api-key>
Idempotency-Key: import-2026-10-14-acme-dogfood
Content-Type: application/json

{
  "seller_sku": "ACME-DOGFOOD-10LB",
  "title": "Acme Grain-Free Dog Food, 10 lb",
  "description": "A complete dry food for adult dogs.",
  "brand": "Acme",
  "category_id": "cat_pet_food",
  "barcode": "012345678905",
  "attributes": { "life_stage": "adult", "weight": "10 lb" }
}

A successful create returns 201 and the product object, including its assigned id. Products with options (size, flavor, count) are one product with variants, not separate products: create the product, then add each variant with its own seller_sku and barcode.

Updating a product

PATCH changes only the fields you send; omitted fields are left unchanged. Send the complete attributes object when changing attributes: it replaces the stored set. Updates return 200 and the full updated product. A product with orders against it keeps its identity: title, description, and image changes apply going forward and do not alter completed orders (Orders Endpoints).

Validation and errors

Status	Code	Cause
400	`malformed_json`	The request body is not valid JSON
404	`not_found`	No product with that `id` exists in your account
409	`duplicate_sku`	`seller_sku` is already in use in your account
422	`validation_failed`	A field is missing, malformed, or not allowed for the category; the error `message` names the field
422	`invalid_barcode`	`barcode` is not a valid GTIN

Error bodies follow Error Codes. Correct the named field and resend; do not resend an unchanged failing request.

Rules for integrators

Import in bulk by creating or updating one product per request, at a pace within the limits in Rate Limit Headers. There is no separate bulk file endpoint in the API.
After changing a product, poll GET /catalog/products/{id} or subscribe to the product.updated event (Webhook Event Schemas) rather than assuming the write is the final state.
Sales of your products settle as described in Payments Endpoints. The machine-readable description of these endpoints is covered in OpenAPI Spec.

Authentication Endpoints

Inventory Endpoints