1. Product catalogs

Product visibility requirements

Overview

The OrderCloud API provides product access through two routes: /products and /me/products. This guide explains the available product visibility options to help you choose the best method for your marketplace. We'll explore product visibility in three ways:

Administrative access

Seller or supplier users with ProductAdmin or ProductReader roles can view products through the /products route. This route returns all products regardless of assignments, including inactive ones. Supplier users only see supplier-owned products.

Shopper access

Buyer users access products through the /me/products route. Product visibility requires proper catalog, price schedule, and product assignments. The following sections explain the options for managing /me/products visibility.

Visibility rules checklist

A Buyer User can see a Product (via me routes) when all these conditions are met:

  • Product.Active = true
  • Catalog exists where:
    • Catalog.Active = true
    • Buyer is assigned via CatalogAssignment
    • Product is assigned via ProductCatalogAssignment
  • One of the following is true:
    • CatalogAssignment.ViewAllProducts = true, OR
    • Category exists in Catalog where
      • Active = true
      • Product assigned via CategoryProductAssignment
      • CategoryAssignment exists where
        • Buyer, User, or Group matches the user
        • ViewAllProducts = true for first non-null setting up the tree
    • ProductAssignment exists for Buyer or any Group the user belongs to (PriceScheduleID not required)

Components of product visibility

Product visibility for buyers uses assignments. Users start with no assignments and see no products. Three assignment types are needed for product visibility:

  1. Product to catalog assignment
  2. User to catalog assignment
  3. Price schedule to product/user assignment

Product to catalog assignment

Two assignment options are available:

  • Direct product to catalog assignment
  • Product assignment to a category in the catalog

Both options make products visible. Direct assignment enables category-less presentation.

User to catalog assignment

http
POST api.ordercloud.io/v1/catalogs/assignments HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
Content-Type: application/json; charset=UTF-8
json
{
  "CatalogID": "MyCatalogName",
  "BuyerID": "MyBuyerID",
  "ViewAllCategories": true,
  "ViewAllProducts": true
}

Users access products when their buyer company is assigned to a catalog. Setting ViewAll configurations to true grants access to all categories or products. Setting them to false requires more specific assignments.

Category level assignments provide additional control:

http
POST https://api.ordercloud.io/v1/catalogs/{catalogID}/categories/assignments HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
Content-Type: application/json; charset=UTF-8
json
{
  "CategoryID": "MyCategoryID",
  "BuyerID": "MyBuyerID",
  "UserGroupID": "MyUserGroupID",
  "Visible": true,
  "ViewAllProducts": true
}

CategoryAssignment.Visible and CategoryAssignment.ViewAllProducts can be true, false, or null. Null inherits settings from the parent category or catalog. Category-level settings override catalog-level settings.

Price schedule assignment

A product needs a price schedule to be orderable. Two options are available:

  1. Define DefaultPriceScheduleID on the product
  2. Create a product assignment linking the product, price schedule, and party

Default price schedules simplify product management. Product assignments can override default prices for specific users.

Exploring product visibility by use case

Scenario 1

"I want control over who sees what, but pricing usually doesn't vary from buyer to buyer."

Use default price schedules by setting DefaultPriceScheduleID on products. ProductAssignment's optional PriceScheduleID can override defaults when needed.

Scenario 2

"I want to allow some users to see certain products but not buy them."

Omit both Product.DefaultPriceSchedule and ProductAssignment.PriceScheduleID. Products will be visible but not purchasable.

Scenario 3

"When I assign a catalog to a buyer organization, I want everybody in that organization to see everything in the catalog."

Set CatalogAssignment.ViewAllCategories and CatalogAssignment.ViewAllProducts to true. This works well with default price schedules.

Scenario 4

"I want to control visibility at the category level, but when I assign a category, I want all products and subcategories within it to be visible to the assigned party automatically."

Set CatalogAssignment.ViewAllCategories and CatalogAssignment.ViewAllProducts to false. Set CategoryAssignment.Visible and CategoryAssignment.ViewAllProducts to true as needed.

Scenario 5

"I want everybody to see everything except a specific category."

Use null values in CategoryAssignment.Visible and CategoryAssignment.ViewAllProducts to inherit parent settings. Enable visibility at the catalog level and disable specific categories.

Scenario 6

"I want to temporarily hide an entire catalog from all buyers it's assigned to."

Use the Active property at the Catalog level to control visibility.

Scenario 7

"I want a search-driven catalog where products do not belong to categories."

Products only need CatalogProductAssignment when CatalogAssignment.ViewAllProducts is true. Category assignments are optional.

Validation rules

ProductAssignment requires the Buyer and Product to be assigned to a common Catalog through CatalogAssignment and CatalogProductAssignment.

If you have suggestions for improving this article, let us know!