1. Product catalogs

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
  2. Connect it to an 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:

{
  "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 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:

  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 provides synchronization capabilities through the Order Calculate step:

  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
If you have suggestions for improving this article, let us know!