> For the complete documentation index, see [llms.txt](https://docs.partssource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.partssource.com/api/domain-concepts/price-option-id.md).

# 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:

```json
{
  "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

{% hint style="warning" %}
**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.
{% endhint %}

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:

```json
{
  "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)             |

{% hint style="info" %}
**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`.
{% endhint %}

***

## Multiple Options, Multiple Vendors

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

```json
{
  "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

```csharp
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](/api/cookbooks/search-to-order.md) - Complete workflow using priceOptionId
* [Idempotency](/api/core-concepts/idempotency.md) - Preventing duplicate orders
* [Error Handling](/api/core-concepts/error-handling.md) - Handling API errors


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.partssource.com/api/domain-concepts/price-option-id.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.