Catalog API

Endpoints

The products endpoint retrieves a list of all catalog categories with the products in each category.

The offers endpoint retrieves a list of all offers for a given product including the pricing plan with all of the offer resources and parameters.

The price endpoint retrieves an in-price and retail price for a given offer configuration. This allows you to estimate the monthly cost of an offer configuration before placing an order.

Products Endpoint

Endpoint to retrieve a list of categories from the catalog including all products inside the categories.

The endpoint for this is: /api/v1/products

Example response (JSON format)

JSON

[
  {
    "categoryId": ".....",
    "categoryName": ".....",
    "products": [
      {
        "productId": ".....",
        "productName": ".....",
        "productDescription": ".....",
        "productVendorName": ".....",
        "productVendorId": "....."
      }
    ]
  }
]

main element

Field	Data type	Description
categoryId	string(UUID)	Unique ID of the category
categoryName	string	Name of the category
products	array(`products`)	List of products in a category

products element

Field	Data type	Description
productId	string(UUID)	Unique ID of the product container
productName	string	Name of the product
productDescription	string	Description of the product
productVendorName	string	Name of the Vendor of the product
productVendorId	string(UUID)	Unique ID of the Vendor of the product

Offers Endpoint

To retrieve offers for a given product, you need to pass in the request the productId and customerId. The system can then respond with a list of available offers.

The endpoint for this is: /api/v1/products/{productId}/offers

Example response (JSON format)

JSON

[
  {
    "offerId": ".....",
    "offerName": ".....",
    "offerIndustryTypes": [
      "....."
    ],
    "offerIsTrail": .....,
    "offerBillingModel": ".....",
    "offerPricingPlan": {
      "pricingPlanFormElements": [
        {
          "elementId": ".....",
          "elementKey": ".....",
          "elementType": ".....",
          "elementIsQuantity": .....,
          "elementIsRequired": .....,
          "elementAffectsPrice": .....,
          "elementTitle": ".....",
          "elementMinValue": .....,
          "elementMaxValue": .....,
          "elementDefaultValue": .....,
          "elementOptions": [
            {
              "elementOptionId": ".....",
              "elementOptionType": "......",
              "elementOptionTitle": ".....",
              "elementOptionValue": "....."
            }
          ]
        }
      ],
      "pricingPlanAvailableBillingCycles": [
        "....."
      ]
    }
  }
]

offers element

Field	Data type	Description
offerId	string	Unique ID of the offer
offerName	string	Name of the offer
offerIndustryTypes	array(`offerIndustryTypes`)	List of one or more industries that this offer is available to.
offerIsTrail	string	If this offer is marked a trial (true/false)
offerBillingModel	string	Billing model associated with the offer
offerPricingPlan	array(`offerPricingPlan`)	contains a list of pricing plans available for an offer.

offerPricingPlan element

Field	Data type	Description
pricingPlanFormElements	Array(`pricingPlanFormElements`)	List of pricing plan elements
pricingPlanAvailableBillingCycles	Array	List of possible billing cycles available for this offer.

pricingPlanFormElements element

Field	Data type	Description
elementId	string	The unique id of the element
elementKey	string	The key of the element (unique identifier based on name)
elementType	string	The type of element (Like a text field, number field, dropdown list or checkbox)
elementIsQuantity	string	If this element determines the “quantity“ of the subscription on invoice lines. (true/false)
elementIsRequired	string	If this element is required (must always be passed for a valid configuration)
elementAffectsPrice	boolean	If this element affects the price of the offer when purchased (true/false)
elementTitle	string	The name of the element
elementMinValue	number	The minimum quantity you need to purchase of this element.
elementMaxValue	number	The maximum quantity you need to purchase of this element.
elementDefaultValue	number	The default quantity for this element.
elementOptions	array(`elementOptions`)	A list of values that you can choose from for this element

elementOptions element

Field	Data type	Description
elementOptionId	string	The unique id of the element option
elementOptionType	string	The type of element option (Like a text field, number field, dropdown list or checkbox)
elementOptionTitle	string	The name of the element option
elementOptionValue	string	The value of the element option

Price Endpoint

To retrieve a price for your offer configuration, you need to pass in the request headers the pricing plan components from the offer with the values you would like to purchase. You also specify the productId, offerId and customerId. The system can then respond with a price for your given configuration.

The endpoint for this is: /api/v1/products/{productId}/offers/{offerId}/price

Example request Body (JSON format)

JSON

{
  "priceDate": ".....",
  "formData": [
    {
      "elementKey": ".....",
      "elementValue": "....."
    }
  ]
}

request body element

Field	Data type	Description
priceDate	string	Timestamp you want to get the price for eg`2024-07-18T09:32:49.744Z`
formData	array(formData)	List of all the elements (resources and parameters) from the pricing plan with your offer configuration.

formData element

Field	Data type	Description
elementKey	string	inset the key value of the pricing plan element
elementValue	string	inset your value for the element key you want to provide or purchase.

Example response (JSON format)

JSON

{
  "customerUnitPrice": .....,
  "customerTotalPrice": .....,
  "currencyCode": ".....",
  "hasUsage": .....,
  "billingFrequency": ".....",
  "partnerDiscount": .....,
  "partnerTotalPrice": .....
}

price element

Field	Data type	Description
customerUnitPrice	string	unit price per quantity the customer will need to pay for the subscription (retail price)
customerTotalPrice	string	Total price the customer will need to pay for the subscription (retail price)
currencyCode	string	Currency (euro)
hasUsage	string	Identifies with true/false value if this offer could incur additional costs based on usage that is not estimated by the returned price.
billingFrequency	string	Identifies if a given price is charged for a specific interval eg monthly or yearly.
partnerDiscount	string	The discount amount for the reseller on the customer price.
partnerTotalPrice	string	The total price for this subscription that the reseller will be charged.