---
title: Ad-hoc products
slug: ad-hoc-products
abstract: OrderCloud provides a complete set of features for creating, organizing, and presenting product catalogs. This system supports both traditional catalog.
content_type: concept
audience: \[architect, developer]
---
# Ad-hoc products

OrderCloud provides a complete set of features for creating, organizing, and presenting product catalogs. This system supports both traditional catalog management and a flexible ad-hoc product integration approach to meet diverse business needs.

## Integration scenarios

For most implementations, OrderCloud serves as a synchronized product catalog system, requiring ongoing data maintenance. However, some organizations maintain their product data and search capabilities in external systems. These scenarios benefit from OrderCloud's Ad-Hoc Products feature, which enables:

- On-demand product data retrieval
- Elimination of catalog synchronization overhead
- Integration with existing product management systems
- Simplified order management workflows

The system supports hybrid catalog management, combining OrderCloud Products with Ad-hoc products from external systems. When processing requests, OrderCloud:

1. Checks for product existence in OrderCloud
2. Verifies user visibility permissions
3. Calls configured middleware if needed

## The AddToCart integration event

The AddToCart integration event enables seamless external product catalog integration with OrderCloud orders. This feature requires:

1. HTTP service implementation
2. RESTful API endpoint configuration
3. Integration event setup

### Implementation steps

1. [Create the integration event](https://api-docs.sitecore.com/ordercloud/integration-events/integrationevents.create)
2. [Connect it to an](https://api-docs.sitecore.com/ordercloud/api-clients/apiclients.patch) `ApiClient` using `AddToCartIntegrationEventID`
3. Configure endpoint handling

When a Buyer User adds items to an unsubmitted order, OrderCloud sends a `POST` request to your endpoint with this payload:

```json
{
  "ProductID": "XYZ-123",
  "Quantity": 2,
  "BuyerID": "BUYER-X",
  "BuyerUser": { ... },
  "SellerID": "SELLER-Y",
  "Environment": "Production",
  "OrderCloudAccessToken": "6MNTg0TM3Cwi...",
  "ConfigData": { }
}
```

### Payload field usage

- `ProductID` and `Quantity`: Core fields for product lookup and pricing
- Authentication fields: Enable secure system integration
- `BuyerUser`: Contains complete [buyer user data](https://api-docs.sitecore.com/ordercloud/users/users.get) for context

### Response requirements

Your endpoint must return an HTTP 200 response with this structure:

```json
{
  "Product": {
    "ID": "XYZ-123",
    "Name": "My Ad-Hoc Product",
    "Description": "blah blah blah",
    "QuantityMultiplier": 1,
    "ShipWeight": 123,
    "ShipHeight": 456,
    "ShipWidth": 123,
    "ShipLength": 456,
    "DefaultSupplierID": null,
    "Returnable": false,
    "xp": { }
  },
  "UnitPrice": 9.99
}
```

### Response handling rules

1. Product fields:
   - Most fields are optional
   - Follow [standard product creation](https://api-docs.sitecore.com/ordercloud/products/products.create) validation rules
   - Required fields and length restrictions apply

2. Product not found:
   - Return HTTP 200 with `Product: null`
   - OrderCloud returns 404 with product not found message
   - Endpoint errors (4xx/5xx) indicate configuration issues
   - OrderCloud returns 400 for endpoint problems

3. Pricing:
   - `UnitPrice` required when returning product
   - Must be valid numerical value

## Keeping products up to date in unsubmitted orders

Ad-hoc product management requires special consideration for unsubmitted orders. While submitted orders maintain static product snapshots, unsubmitted orders need synchronization with external system changes.

### Synchronization mechanism

The enhanced [Order Checkout integration event](https://doc.sitecore.com/ordercloud/en/developers/platform/order-checkout.html) provides synchronization capabilities through the [Order Calculate step](https://doc.sitecore.com/ordercloud/en/developers/platform/order-checkout.html#ordercalculate):

1. Product updates:
   - Return `Product` object in `LineItemOverrides`
   - Supports partial updates (PATCH-like operation)
   - Maintains data consistency

2. Product removal:
   - Use `Remove: true` in response
   - Silently removes unavailable items
   - Matches standard OrderCloud behavior

Example Order Calculate response with all available fields:

```json
{
  "LineItemOverrides": [
    {
      "LineItemID": "SampleLineItemID",
      "Product": {},
      "UnitPrice": 6.0,
      "PromotionOverrides": [],
      "Remove": false
    }
  ]
}
```

Note: Only `LineItemID` is required in practice. Include other fields as needed for your implementation.

## Additional capabilities

Ad-Hoc products support includes:

- Full subscription integration
- Automated order processing
- Recurring order management

## Related reading

- [Product synchronization](https://doc.sitecore.com/ordercloud/en/developers/platform/productsync.html)
- [Child products and variants](https://doc.sitecore.com/ordercloud/en/developers/platform/child-products-and-variants.html)