Default buyer catalog

In the previous section, you established API access for a new organization. During that process, you created a seller and buyer perspective. Throughout this section, remain in the seller perspective that you authenticated with while in the Making your first request guide.

What is a catalog?

Catalogs are containers of products and, optionally, categories. As a seller, your role is to sell products to your buyers through one or more catalogs. To do so, your catalog must be active and assigned to a buyer organization or user group.

When a buyer organization is created, a default catalog is automatically created along with it. You can find the ID of this catalog on the buyer organization model under DefaultCatalogID. The buyer you created in the last section should look something like this:

{
	"ID": "BUYER_ORGANIZATION",
	"Name": "Example Buyer",
	"DefaultCatalogID": "BUYER_ORGANIZATION",
	"Active": true,
	"DateCreated": "2021-02-08T23:01:03.57+00:00",
	"xp": null
}

Notice that DefaultCatalogID matches the buyer organization ID. OrderCloud matches IDs when possible.

Retrieve the default buyer catalog and look at its properties:

Get the default catalog by ID

GET https://sandboxapi.ordercloud.io/v1/catalogs/BUYER_ORGANIZATION HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8

{
  "ID": "BUYER_ORGANIZATION",
  "OwnerID": "xxxxxxxxxxxxxxxxxx",
  "Name": "Example Buyer",
  "Description": "Default catalog for Example Buyer",
  "Active": true,
  "CategoryCount": 0,
  "xp": null
}

Here are some properties worth noting at this time:

• OwnerID - The ID of the organization that owns the catalog (our seller organization ID)
• Name - The catalog name, based on the name of the buyer organization
• Active - Whether the catalog is accessible to the parties it is assigned to

Our catalog is currently active, which is what we want. If it were inactive, it would be inaccessible to our buyer organization. We will not be creating any categories for this example, as that can complicate our visibility rules. So CategoryCount should remain at 0.

Catalog assignments

Because our buyer organization uses this catalog as the DefaultCatalogID, a catalog assignment was automatically created for us. The catalog assignment plays a major role in controlling the visibility of products to your buyers. These visibility rules are intentionally flexible and can get complicated quickly; therefore, we cover them in a separate guide. For now, we will focus on the most straightforward way of getting a product in front of your buyers.

See Catalog visibility rules for more information.

List the assignments for this catalog to see what OrderCloud created on our behalf:

List catalog assignments for the default catalog

GET https://sandboxapi.ordercloud.io/v1/catalogs/assignments?catalogID=BUYER_ORGANIZATION HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8

{
	"Meta": {
		"Page": 1,
		"PageSize": 20,
		"TotalCount": 1,
		"TotalPages": 1,
		"ItemRange": [
			1,
			1
		]
	},
	"Items": [
		{
			"CatalogID": "BUYER_ORGANIZATION",
			"BuyerID": "BUYER_ORGANIZATION",
			"ViewAllCategories": true,
			"ViewAllProducts": true
		}
	]
}

The response shows the relationship between the buyer organization and its default catalog. This assignment model includes additional configuration properties. OrderCloud sets both settings to true by default, which provides the most inclusive catalog visibility configuration for a buyer.

• ViewAllCategories - When set to true, every category in the catalog is visible to the assigned party without a category assignment.
• ViewAllProducts - When set to true, every product assigned to the catalog is visible to the assigned party without a product assignment.

For catalogs where some buyer users should see categories or products that are hidden for others, turn off these settings and create more granular assignments between the buying parties and the products/catalogs they should see. For this example, we keep these settings at true.