Get Catalog and Prices

Introduction

This article explains how partners can retrieve their platform catalog of offers, including: "Categories", "Products", "Offers", and "Prices".

By following the steps below partners will be able to use their own marketplace as a customer-facing UI with the catalog of offers being displayed and available for purchase, whereas the platform will be used as a back-end functionality. The purchase flow APIs are described in Place and Provision Orders.

API Documentation is available in the Developer Portal. In addition, we have created the Postman collection, which contains templates for partners to create API requests for all endpoints supported by AppXite. To request a copy of the collection please contact api@appxite.com.

Audience: integration developers, business analysts, and software architects.

 

Getting Catalog, Products, Offers, and Prices:

Screenshot_2022-11-21_121211.png

 

APIs in scope:

No.1. List all Customers

Returns details of all customers associated with the selected seller (Seller Platform URL in the X-Referer section). Id returned by this API is used as the "X-on-behalf-of" header in the List all catalogs to retrieve the catalog id associated with a selected customer.

Id is used as a parameter in the following APIs:

Partners can utilize Customer Segments to have different catalogs for different customers. To reflect the same model on its marketplace, whereby customers will get access to their specific catalog, Partner can design its integration in the following manner:

  • Customer links marketplace users with their organizations based on the customer id.
  • "List all customers" returns all customer Ids;
  • When a user logs in marketplace recognizes that the user is associated with a specific organization.

Note: Partner can define the user mapping logic, including the scenarios in which a user is linked to multiple organizations.

No.2. List all catalogs

Returns all catalogs associated with the selected customer organization. If a customer organization id is incorrect or missing, the Default Seller Catalog will be returned.

ProductCatalogID is used as a parameter in the following APIs:

  • List all categories for the catalog;
  • List all offers for the product;
  • List all products for the category;
  • Retrieve a pricing plan for the offer;
  • Retrieve an offer for the product;
  • Retrieve localized offer details.

Partner can design its integration in the following manner:

  • Based on the Customer id, List all catalogs will return the catalog associated with the customer organization the user belongs to;
  • If a user is not linked to a particular organization, the user gets access to a default catalog.

No.3. List all categories for the catalog

Returns all categories associated with the selected catalog. 

CategoryId is used as a parameter in the following APIs:

  • List all products for the category.

Integration Pattern: Partner can customize its catalog by grouping products into different categories (e.g. "Featured", "Office", "Security, etc.)". For more information, please read How to customize Catalog?

List all products for the category will retrieve the products that are associated with the selected category. By doing so, Partners may reflect the same product categorization on their marketplace, or incorporate the entire categories into a different structure.

No.4. List all products for the category

Returns all products associated with the selected category. The response contains the primary offer properties, such as Industry Type, creation date, availability, type, etc.

CategoryId is used as a parameter in the following APIs:

  • List all offers for the product.

No.5. List all offers for the product

Returns all offers associated with the selected product. 

No.6. Retrieve localized offer details

Returns offer names and descriptions in different languages (if any). 

No.7. Retrieve a pricing plan for the offer

The Pricing Plan API allows you to retrieve the pricing plan for a specific offer using a GET request. The pricing plan provides details about the offer, including the currency, effective date, and offer form configuration that is used for price calculation (see. No.8.Calculate Price for a Pricing Plan.)

Note: Please note that different offers can have different forms that are used for configuring those offers. Hence, the integration logic must address the differences in offer configurability. To avoid doing that, it is possible to use Form Presenter control which can work in any modern browser with any JavaScript framework.

It can be installed as an npm package and seamlessly embedded into an existing web store or landing page.

The Form Presenter takes care of all aspects of form rendering, such as showing/hiding different controls based on user selections, performing validation, etc. It also supports custom CSS, so it is possible to adjust styles in a way that fully matches the design guidelines and requirements of the partner's own marketplace.

AppXite can provide a demo JavaScript/NodeJs project that contains simple examples of how to install, embed, and configure Form Presenter control, as well as technical documentation of the control, fields it supports as well as how to work with CSS. Please send your request to api@appxite.com to get the demo JavaScript/NodeJs project.

Handling 204 No Content Response

You may receive a 204 No Content response when requesting a pricing plan. This response indicates that there is no pricing plan available for the given offer and currency combination. It is crucial to provide the correct currency code when making the request. To determine the currency code associated with a specific offer plan, you can use the "Retrieve currency for the pricing plan" API. This endpoint will help you verify the correct currency code for your request, ensuring accurate pricing information is returned.

No.8. Calculate Price for a Pricing Plan

The Pricing API endpoint allows you to calculate the price of an offer based on a pricing plan (see. Retrieve a pricing plan for the offer). This endpoint considers various factors such as quantity, pricing rules, special markups, and vendor recommendations to determine the price. The API response provides detailed pricing information, including unit prices, total prices, currency codes, and more.

When using the Pricing API endpoint, it's important to note that the currency used for price calculations will be based on the platform currency rather than the currency of the pricing plan retrieved via the "Retrieve a pricing plan for the offer".

The platform currency refers to the default currency set within the Platform (see. Currency & Payments).  Regardless of the currency associated with the pricing plan, the Pricing API will calculate prices in the platform currency.

This means that if you have a pricing plan available in multiple currencies, the Pricing API will always provide the price in the platform currency, as indicated by the "CurrencyCode" field in the API response. The "CurrencyCode" value represents the currency code of the platform currency.

 

Was this article helpful?

1 out of 3 found this helpful

Add comment

Please sign in to leave a comment.