> ## Documentation Index > Fetch the complete documentation index at: https://docs.nymblecommerce.com/llms.txt > Use this file to discover all available pages before exploring further. # Product Catalog, Pricing, and Categories in Nymble Commerce > Learn how Nymble Commerce structures products, categories, images, and tier-based pricing to serve the right price to every customer automatically. Nymble Commerce's catalog is built for B2B complexity. Products have SKUs, rich attributes, quantity controls, multiple images, and customer-specific pricing that resolves automatically based on the authenticated user's tier. You get a fully structured catalog API that drives both your customer-facing storefront and your internal ordering tools. ## Products Each product in your catalog is identified by a `ProductId` and a `Sku`. The table below covers the key fields returned on product responses. | Field | Type | Description | | ---------------------- | -------- | ------------------------------------------------------------------------------------ | | `ProductId` | string | Nymble Commerce's internal unique identifier for this product. | | `Sku` | string | Your product SKU. Used for line item matching on orders. | | `Name` | string | Display name of the product. Searchable. | | `Description` | string | Full product description. Supports rich text. Searchable. | | `Category` | string | The primary category name for this product. | | `Price` | decimal | The resolved price for the authenticated user's tier. | | `PriceFormatted` | string | Formatted price string including currency symbol (e.g. `"$24.99"`). | | `CurrencyCode` | string | ISO currency code (e.g. `"USD"`, `"CAD"`). | | `Prices` | array | Full list of `ProductPrice` objects — one per tier. See [Price tiers](#price-tiers). | | `QuantityOnHand` | integer | Current inventory quantity. | | `MinimumOrderQuantity` | integer | Minimum quantity a customer must order. Enforced at checkout. | | `QuantityIncrement` | integer | Quantity step size (e.g. `6` means orders must be in multiples of 6). | | `Weight` | decimal | Product weight. | | `WeightUnit` | string | Unit of weight (e.g. `"kg"`, `"lb"`). | | `Dimensions` | string | Product dimensions as a formatted string. | | `DimensionsUnit` | string | Unit for dimensions (e.g. `"cm"`, `"in"`). | | `UPC` | string | Universal Product Code (barcode). | | `Active` | boolean | Whether the product appears in standard catalog listings. | | `ProductType` | string | Type classification for the product. | | `ProductAttributes` | object | Custom key-value attributes defined at the organization level. | | `ExternalId` | string | Your identifier for this product in an external system (ERP, PIM). | | `CreatedAt` | datetime | When the product was created. | | `UpdatedAt` | datetime | When the product was last updated. | ### Example: product response ```json theme={null} { "ProductId": "prod_a1b2c3", "Sku": "WDG-100-BLU", "Name": "Widget 100 — Blue", "Description": "Industrial-grade widget, 100mm, blue anodized finish.", "Category": "Widgets", "Price": 24.99, "PriceFormatted": "$24.99", "CurrencyCode": "USD", "Prices": [ { "Tier": "Wholesale", "Price": 18.50, "PriceFormatted": "$18.50", "AtQuantity": 1 }, { "Tier": "Retail", "Price": 24.99, "PriceFormatted": "$24.99", "AtQuantity": 1 } ], "QuantityOnHand": 250, "MinimumOrderQuantity": 12, "QuantityIncrement": 12, "Active": true, "ExternalId": "ERP-SKU-00441" } ``` ## Price tiers Nymble Commerce's pricing system is tier-based and token-driven. Each product carries a `Prices` array — a list of `ProductPrice` objects, one per tier defined in your organization. Each `ProductPrice` has: | Field | Type | Description | | ---------------- | ------- | -------------------------------------------------------------------------------------- | | `Tier` | string | The tier name this price applies to (e.g. `"Wholesale"`, `"Retail"`, `"Distributor"`). | | `Price` | decimal | The numeric price for this tier. | | `PriceFormatted` | string | Formatted price string with currency symbol. | | `AtQuantity` | integer | The quantity threshold at which this price applies (for volume pricing). | **How tier resolution works:** when an authenticated customer calls any catalog endpoint, Nymble Commerce reads the `PriceTier` claim from their JWT and returns the matching price in the top-level `Price` and `PriceFormatted` fields. The full `Prices` array is also included in the response so your storefront can display tiered or volume pricing tables. ```text theme={null} Customer JWT contains: PriceTier = "Wholesale" ↓ GET /api/products → Price: 18.50, PriceFormatted: "$18.50" (Wholesale tier price resolved automatically) ``` Unauthenticated requests (e.g. public catalog browsing) return the default tier price configured on your organization. ## Categories Products are organized into a hierarchy of categories and subcategories. Use the categories API to build navigation menus, filter panels, and breadcrumb trails in your storefront. Each category has: | Field | Type | Description | | --------------- | ------- | ---------------------------------------------------------------------------------------- | | `Name` | string | Display name of the category. | | `Breadcrumb` | string | Full path string (e.g. `"Hardware > Fasteners > Bolts"`). Useful for navigation display. | | `Active` | boolean | Whether the category is visible in the catalog. | | `ImageUrl` | string | CDN URL for the category image. | | `SubCategories` | array | Nested list of child category objects — recursive for unlimited depth. | **Root categories** have no parent. **Subcategories** are nested within their parent's `SubCategories` array. A single API call to `GET /api/categories` returns the full tree. ```json theme={null} // Example category tree { "Name": "Hardware", "Breadcrumb": "Hardware", "Active": true, "SubCategories": [ { "Name": "Fasteners", "Breadcrumb": "Hardware > Fasteners", "Active": true, "SubCategories": [ { "Name": "Bolts", "Breadcrumb": "Hardware > Fasteners > Bolts", "Active": true, "SubCategories": [] } ] } ] } ``` ## Images Products support multiple images, served through Cloudflare's CDN for fast, globally-distributed delivery. Image URLs are included in the `Images` array on product responses. Each image object contains a URL and metadata. Images are managed via the Cloudflare Images integration configured at the organization level — you upload once and Nymble Commerce handles resizing and CDN distribution automatically. Category images follow the same CDN pattern, with the URL constructed from your `OrganizationId` and the category's `Breadcrumb`. ## Product states | State | Description | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Active** (`Active: true`) | The product appears in standard catalog listings and search results. Customers can add it to their cart. | | **Inactive** (`Active: false`) | The product is hidden from all standard catalog endpoints. It does not appear in listings or search. Admins can still access inactive products directly by ID. | Use inactive state for seasonal items, discontinued products, or anything you want to retain in the system without surfacing to customers. ## Searching and filtering The product search endpoint supports: * **Full-text search** across `Name` and `Description`. * **Category filter** — return products belonging to a specific category. * **Price range filter** — filter by minimum and/or maximum price (resolved to the authenticated user's tier). * **Active status filter** — include or exclude inactive products (admin only). ```bash theme={null} # Search for active widgets under $50 in the Hardware category GET https://api.achievemomentum.com/api/products?search=widget&category=Hardware&maxPrice=50&active=true ``` Results are paginated. Use `PageNumber` and `PageSize` query parameters to navigate pages. Set `ExternalId` on each product to match your ERP or PIM system's product ID. This gives you a reliable cross-reference key for syncing inventory updates, price changes, and product data without relying on Nymble Commerce's internal `ProductId`.