Default Buyer Catalog

In the previous chapter, you established API access for a new organization. During that process, you were asked to create a seller and buyer perspective. Throughout this chapter you should remain in the seller perspective that we authenticated with while in the "Making Your First Request" guide.

What is a Catalog?

Catalogs are a container 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 chapter 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 will match IDs when possible.

Let's retrieve the default buyer catalog and look at it's 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 or not the catalog is accessible to the parties it's assigned to

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

Catalog Assignments

Since 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.

Let's 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
		}
	]
}

We get back a single result that shows the relationship between our buyer organization and its default catalog. This is one of few assignment models in the API that have additional configuration properties. OrderCloud defaults both of these settings to true because this is the most inclusive way of defining catalog visibility for a buyer.

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

• ViewAllProducts - When set to true, every product assigned to the catalog will be visible to the assigned party without a product assignment.

When creating a more finely tuned catalog, where some buyer users should see categories or products that are hidden for others, these settings are usually turned off and more granular assignments are made between the buying parties and the products/catalogs they should see. For the purposes of keeping this example simple, we will keep these set to true and move on.

Still have questions?
Ask in our Community Channel

Content Powered By