Managing Products and Variants in Ordermentum API

Introduction

The Ordermentum API provides functionality to manage products and their variants, enabling suppliers to offer a diverse range of product options to retailers. Products represent items available for order, including attributes such as name, price, SKU, and unit of measure.

What are Product Variants?
Product variants represent different versions of a product that share common attributes but differ in specific characteristics such as size, packaging, pricing, or other options. Variants allow suppliers to offer multiple options of a single product without creating separate product listings.

Example:

"Coffee Beans" could have the following variants:

• 250g Pack (unique SKU and price)
• 500g Pack
• 1kg Pack

Endpoints

The following endpoints are available for managing products and their variants:

1. List Products

   • Endpoint: GET /v2/products
   • Description: Retrieve a summarized list of products, including filtering and search options.
   • Example Request:
     Bash

     curl -X GET "https://api.ordermentum.com/v2/products?search=tea&pageSize=10" \
          -H "Authorization: Bearer YOUR_API_TOKEN"

2. Get Product Details

   • Endpoint: GET /v1/products/{productId}
   • Description: Retrieve full details of a specific product, including attributes, categories, and variants.
   • Example Request:
     Bash

     curl -X GET "https://api.ordermentum.com/v1/products/34cd12ab-7890-efab-1234-567890abcdef" \
          -H "Authorization: Bearer YOUR_API_TOKEN"

3. List All Variants

   • Endpoint: GET /v1/variants
   • Description: Retrieve a complete list of all product variants without requiring a product ID.
   • Example Request:
     Bash

     curl -X GET "https://api.ordermentum.com/v1/variants?pageSize=10" \
          -H "Authorization: Bearer YOUR_API_TOKEN"

Common Filters

4. Get Variants for a Specific Product

   • Endpoint: GET /v1/products/{productId}/variants
   • Description: Retrieve all variants associated with a specific product.
   • Example Request:
     Bash

     curl -X GET "https://api.ordermentum.com/v1/products/34cd12ab-7890-efab-1234-567890abcdef/variants" \
          -H "Authorization: Bearer YOUR_API_TOKEN"

5. Get Details of a Specific Variant

   • Endpoint: GET /v1/products/{productId}/variants/{variantId}
   • Description: Retrieve detailed information about a specific variant, given the product ID and variant ID.
   • Example Request:
     Bash

     curl -X GET "https://api.ordermentum.com/v1/products/34cd12ab-7890-efab-1234-567890abcdef/variants/ef901234-ab56-7890-cd12-34567890abcd" \
          -H "Authorization: Bearer YOUR_API_TOKEN"

Retrieving Product Prices

To determine the correct pricing for a product or its variants, follow these steps:

1. Retrieve the Purchaser's Assigned Price Group:
   Use the purchaser’s details to obtain the priceGroupId.

2. Query Product and Variant Details:
   Retrieve product details using /v1/products/{productId}. If the product has variants, use /v1/products/{productId}/variants to list them and check for the relevant pricing.

3. Retrieve Specific Variant Details:
   If both product and variant IDs are available, use /v1/products/{productId}/variants/{variantId} to obtain detailed pricing and attribute information for that variant.

Updating Prices

For products without variants, update the price via the /v1/price-groups/{priceGroupId} endpoint. For products with variants, update pricing by PATCHing to /v1/variants/{variantId}/prices.

Example Request to Update Variant Prices:

curl -X PATCH "https://app.ordermentum.com/v1/variants/738bbbde-babb-41a6-9cf0-4568aa670196/prices" \
 -H "Authorization: Bearer YOUR_API_TOKEN" \
 -H "Content-Type: application/json" \
 --data '[
   {
     "priceGroupId": "1b57f416-765c-4ecb-bae6-b3cf38897158",
     "type": "fixed",
     "action": "set",
     "value": "1100.0000"
   }
]'\)

Best Practices

• Use /v2/products for bulk retrieval and reporting purposes.
• Retrieve detailed product data via /v1/products/{productId} when managing specific product attributes.
• Ensure correct pricing by validating against the purchaser’s assigned price group.
• Regularly update product and variant data to reflect current stock and pricing.