What is Sitecore OrderCloud ?

OrderCloud is an API-first headless based cloud platform for B2B, B2C and B2X. It offers Order Management, also to build custom e-Commerce experiences.

It also offers sandbox environments to play around in it. So if you do not have an account yet, you can go and create one here.

Once you are done with creating an account, you can create your first marketplace in the sandbox environment to play around. Please follow this link to get it done – Creating a marketplace. Take a note of the API Server url which will be used as the base API url for different API calls.

Once the market place is created, the API Console can be used to communicate with the OrderCloud. And using this we are able to interact with the OrderCloud as if we are doing in the e-Commerce websites

Creating an API Client

The API Client is used for all sort of workflows in the OrderCloud. This also acts as an access point to all the data in the OrderCloud and also defines what access to be given, what data is accessed and who can access what data etc.,

You can follow this link you create a simple shared API client. This API client and its secret we will be using to generate the access tokens.

Setting up the Postman

As we will be using Postman to test out the different APIs, let us set up import the OrderCloud’s Open API specifications – https://api.ordercloud.io/v1/openapi/v3 into Postman.

Once this is done and you will be having all the API info like below.

Creating Seller and Buyer Admin Users

Let us see how to create a Seller admin user. As a first step, we will be using the OrderClouds API console to create the admin users. At the left side menu, navigate to Seller -> Admin Users and choose the POST/adminusers method to create a seller admin. You can paste the below json into the Json field and execute it. Once it gets successfully executed, the results can be seen at the right side panel like below.

Now we have created a seller admin user. Take a note of the username and password of it, we will be using this to create access token.

Let us see how we will be creater a buyer organization and buyer user. Left side, nagivate to Buyers->Buyers and choose POST/buyers API. Copy paste the below Json data and click the send button.

Now let us create a buyer admin user under this buyer organization. Navigate to Buyers->Users and choose /buyers/{buyerID}/users. And in the ID mention the previous buyer organization ID that we created. Also paste the below Json. Then click the Send button.

Now we have created Seller admin user, Buyer Organization and a Buyer admin user also. Note down these seller, buyer admin usernames and passwords as we will be using them to generate the access tokens.

Now let us play around the different OrderCloud APIs to create the Products Catalogues, Buyers Perspective and Order fulfillment.

Generating the Access Token

OrderCloud uses OAuth 2.0 token based authentication. So we need to create the access tokens and the subsequent API calls should use the authentication token. Let us see how to use Postman to retrieve the authentication token.

We need use the seller admin user and password, scope of this user etc., that we created in the above steps. Along with them we also need to pass the Shared Client ID and Secret.

We need to use the API {sandboxurl}/oauth/token to get the access token like below. It will return the bearer token which you can copy and use it for the subsequent requests.

Please be note we are now authenticated as a Seller admin and let us remain same as now we will be creating Product Catalogs and Products.

Creating Product Catalog

Catalogs are the containers of products i.e., products can be mapped to catalogs . And the Catalogs may contain catégories also. When we created a buyer organization in the previous step, the Ordercloud by defaults takes the name of the buyer orgnaization as the default Catalogs id as below.

The /v1/catalogs/{Catalog_ID} API can be used to filter the catalog based on the catalog id.

Catalog Assignments

Catalog assignments are important to make the products available for the buyers. Let us try to fetch the catalog assignment and check its properties. The API /v1/catalogs/assignments?catalogID={Catalog_ID} can be used for this and notice that the property ‘ViewAllCatagories‘ and ‘ViewAllProducts‘ are set to true. That means the Category and Products under this catalog are visible to allassigned buyers without any Product Catalogs defined.

We have seen the creation of Catalogs and Catalog assignments. Let us create a Product next.

OrderCloud Product

Product is a physical, digital object that can be sold to buyers by the Sellers via an Order. When creating a Order Cloud Product, the Name is mandatory and everything else is optional.

How the Product Prices are managed in OrderCloud ?

The OrderCloud product prices are managed via Price Schedules. This is to allow the products to be sold in different prices across different channel with different taxes, offers etc.,

The API /v1/priceschedules (POST) can be used create the Price Schedules. Let us create a Price schedule as below,

Creating a Product

The api /v1/products (POST) can be used to create the products in OrderCloud system. We can use the below json to create the first OrderCloud product. By default the Price Schedule field for this product will be null.

We can use the API /v1/products/{Product_ID} can be used to assign the price schedules like below. Once its executed, we can notice that the Summar-Shirt product has been assigned with the Product Schedule we created before.

So far what we have done,

• Created Shared API Client
• Admin Seller and buyers users are created
• Have seen how to generated the Access Tokens as OrderCloud uses OAuth 2.0 for authentication
• Created Product Catalog
• And have seen what is Catalog Assignment
• We also learnt what is a Product
• And Price Schedule and why its needed
• And have created the Product and assigned the Price Schedule to the product

At a last step, let us see how to make the Product available ?

Any guess ???? As stated earlier, the products are mapped to the Product Catalogs. So if we assign the catalog to the created Product, that is the final step in the cycle.

The API /v1/catalogs/productassignments can be used to achieve this.

Now we are having a working product. Keep in mind that so far we have been doing everything as a Seller perspective. Now we will be working towards Buyer perspective.

Let us switch as a Buyer…!!!

The first step is to generate the access token using the buyer credentials. We need to follow the same steps in the section Generating the Access Token but with buyer credentials. Generate the access token and note it.

Note that the Scope has changed in the below requests as it will be an access token for buyer profile.

After this if we check for currently authenticated user using /v1/me api, then it will be a buyer user as below.

Now let us check the list of products which are available for this buyer user using the api /v1/me/products. We will be seeing the below response,

Placing an Order in OrderCloud

We will be using OrderResource to place the order and the flow of the order will be Buyer -> Seller. So here the order direction will be “Outgoing”. Let us create one empty order using the api /v1/orders/Outgoing.

The response will be looking like this and make a note of the OrderID.

Now we have placed an emptyorder. In the response you can observe the buyer user info, FromCompanyID, ToCompanyID which are buyer organization and seller organization ids respectively. Also note the OrderStatus and it will be “Unsubmitted” in this case, as we have just opened the order and have not placed anything yet.

The below are the list of Order Status from the documentation.

Adding the Products to the Order

Now we know our OrderID and we have browse for the Products to add them into the order. We can use the Product ID we created earlier and add them into the current order. For this, we need to use the API /v1/orders/Outgoing/{INSERT_ORDER_ID_HERE}/lineitems (POST) with the below json,

The response will be looking like this and take a look at the total price, quantity etc., This is the LineItemResponseModel from OrderCloud.

Submitting the Order

We have not yet Submit the order. We can use the api /v1/orders/Outgoing/{INSERT_ORDER_ID_HERE}/submit. Once you execute this API, the response will be like below. Check the Status is changed from “Unsubmitted” to “Open” and the “IsSubmitted” is set to “true”.

Fulfilling the Order

Now again we need to switch back to the Seller profile as the buyer has submitted the order and it has to be further processed. So generate the access token with the seller credentials.

As a seller, to see the list of the orders, the api /v1/orders/incoming?Status=Open will be used.

Did you notice onething ? Even for the Seller, we will be using the Orders resource and only the direction is changed here and that is “Incoming”. Once you execute this, the response will be looking like this and note down the ID.

Once the Order is reviewed, next it has to be completed. The api /v1/orders/Outgoing/{INSERT_ORDER_ID_HERE}/complete can be used for this. Once you execute this with the order id, now the order is completed and we can notice that the Status is updated accordingly.

Next step would be to ship the order and /v1/orders/Outgoing/{INSERT_ORDER_ID_HERE}/ship api has to be used for this. The status of the shipments can be seen using the Shipments resources with correct order id.

Huff… So much theory right ????????

Next I will be keep exploring to set up an e-commerce solution with Sitecore OrderCloud Integration. Stay tuned….