Price Option ID

Understanding the priceOptionId as a time-limited quote

The priceOptionId is a unique identifier representing a vendor quote for a specific product configuration. It captures the price, condition, warranty, and vendor at the time of lookup and serves as the link between catalog browsing and order placement.

---

What It Represents

When you call /catalog/detail, the API returns an options array. Each option represents a different way to purchase the product:

{
  "options": [
    {
      "priceOptionId": "OPT-ABC123-XYZ",
      "price": 1250.00,
      "condition": "Refurbished",
      "warranty": "12 Months",
      "purchaseChoice": "Buy"
    },
    {
      "priceOptionId": "OPT-DEF456-UVW",
      "price": 2500.00,
      "condition": "New OEM",
      "warranty": "24 Months",
      "purchaseChoice": "Buy"
    }
  ]
}

Each priceOptionId locks in:

Attribute	Description
Price	The unit price at the time of lookup
Condition	Product condition (New OEM, Refurbished, Aftermarket)
Warranty	Warranty period included with purchase
Vendor	The specific vendor fulfilling the order
Purchase Type	Buy, Exchange, Loan, or other purchase choices

---

Expiration

Price Option IDs expire after 30 days.

If you attempt to create an order with an expired priceOptionId, the request will fail with a 404 Not Found or validation error.

The 30-day validity window ensures that:

• Prices remain accurate and honor the quoted amount

• Inventory availability is reasonably current

• Vendor commitments are still valid

---

Usage in Orders

When creating an order, include the priceOptionId in the quoteItems array:

{
  "quoteItems": [
    {
      "priceOptionId": "OPT-ABC123-XYZ",
      "productId": "CAT-123",
      "quantity": 1,
      "price": 1250.00
    }
  ]
}

Field	Description
priceOptionId	The quote ID from /catalog/detail
productId	The product ID (must match the catalog detail request)
quantity	Number of units to order
price	The price from the option (for validation)

Price Validation: The price field in your order request is validated against the priceOptionId. If they don't match, the order will fail. Always use the exact price returned from /catalog/detail.

---

Multiple Options, Multiple Vendors

A single product can have multiple pricing options from different vendors:

{
  "options": [
    {
      "priceOptionId": "OPT-001",
      "price": 1200.00,
      "condition": "Refurbished",
      "warranty": "12 Months"
    },
    {
      "priceOptionId": "OPT-002",
      "price": 1350.00,
      "condition": "Refurbished",
      "warranty": "24 Months"
    },
    {
      "priceOptionId": "OPT-003",
      "price": 2400.00,
      "condition": "New OEM",
      "warranty": "36 Months"
    }
  ]
}

Different priceOptionId values mean:

• Different vendors may fulfill the order

• Different lead times may apply

• Different return policies may exist

---

Error Handling

Error	Cause	Solution
404 Not Found	priceOptionId doesn't exist or expired	Call /catalog/detail for a fresh quote
422 Unprocessable Entity	Price mismatch	Use the exact price from the option
400 Bad Request	Missing priceOptionId	Include priceOptionId in quoteItems

Handling Expiration

public async Task<OrderResponse> CreateOrderSafely(OrderRequest order)
{
    try
    {
        return await CreateOrder(order);
    }
    catch (ApiException ex) when (ex.StatusCode == 404)
    {
        // priceOptionId likely expired - refresh the quote
        var freshDetail = await GetCatalogDetail(order.ProductId);
        var freshOption = SelectBestOption(freshDetail.Options);

        order.QuoteItems[0].PriceOptionId = freshOption.PriceOptionId;
        order.QuoteItems[0].Price = freshOption.Price;

        return await CreateOrder(order);
    }
}

---

Best Practices

1. Minimize delay between /catalog/detail and order creation to reduce expiration risk

2. Don't cache priceOptionIds long-term; treat them as short-lived tokens

3. Store the full option data (price, condition, warranty) alongside the priceOptionId for display purposes

4. Handle expiration gracefully by re-fetching catalog detail when orders fail

5. Log priceOptionIds with orders for debugging and audit trails

---

Related Concepts

• Search to Order Cookbook - Complete workflow using priceOptionId

• Idempotency - Preventing duplicate orders

• Error Handling - Handling API errors