Get Catalog and Prices
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 firstname.lastname@example.org.
Audience: integration developers, business analysts, and software architects.
Getting Catalog, Products, Offers, and Prices:
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.
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.
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.
Returns all offers associated with the selected product.
Returns offer names and descriptions in different languages (if any).
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.)
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.
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.
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.