The Order Item Substitution feature allows sellers to replace ordered items with alternative products when the original items are unavailable, discontinued, or need to be swapped for business reasons. This is particularly useful for managing inventory shortages and maintaining customer satisfaction by providing suitable alternatives.

Key Capabilities

Business Use Cases

• Out of Stock Management: Replace unavailable items with similar products that are in stock
• Product Discontinuation: Substitute discontinued items with current alternatives
• Quality Control: Replace items that don't meet quality standards
• Upgraded Substitutions: Provide better alternatives at the same or lower price
• Size/Color Variations: Replace items when specific variants are unavailable

Technical Features

• Flexible Item Identification: Identify items to substitute using either OrderItemID or SKU
• Partial Quantity Substitution: Substitute a portion of an item's quantity while keeping the remainder
• Multiple Replacement Items: Replace a single item with multiple different products
• Custom Pricing: Specify custom pricing for replacement items (UnitPrice, TaxPrice, ShippingPrice, etc.)
• Shipping Override Control: Control fulfillment details including distribution center, carrier, class, and tracking information
• Bundle Support: Substitute both individual items and bundle products
• Partial Shipment Handling: Substitute only unshipped quantities when items have been partially fulfilled

Important Considerations

Marketplace Support

Order item substitution is not supported for all marketplaces. Currently, substitutions are only available for:

• Checkout Direct Orders (orders created through the API)
• Select Marketplace Orders (contact Rithum for Brands support to confirm marketplace compatibility)

Attempting to substitute items from unsupported marketplaces will result in an error indicating that "Substitutions are not supported for this Marketplace."

Order State Requirements

• Items must not be fully shipped to be eligible for substitution
• If an item has been partially shipped, only the unshipped quantity can be substituted
• Attempting to substitute a fully shipped item will result in an error

Item Identification

• OrderItemID: Recommended for precise targeting of specific order items
• SKU: Can be used when SKU is unique within the order. If multiple items have the same SKU, the request will fail with an error suggesting the use of OrderItemID

Pricing Behavior

• UnitPrice: Required for each replacement item
• TaxPrice, ShippingPrice, ShippingTaxPrice, RecyclingFee: Optional - will default to 0 if not specified
• Replacement item pricing is independent of the original item's pricing

Shipping Overrides

• Optional: If not specified, the system will use default distribution center selection logic
• DistributionCenterID: Required if using shipping overrides
• Quantity: The quantity in shipping overrides must not exceed the replacement item's total quantity
• Multiple Replacements: Each replacement item can have its own shipping override configuration

Workflow

1. Identify the Order: Specify the Order ID in the request URI: POST v1/Orders({OrderID})/SubstituteItems
2. Specify Original Item: Identify the item to substitute using either OrderItemID or Sku in the OriginalItem object
3. Define Replacement Items: Provide at least one replacement item with required pricing information
4. Configure Shipping (Optional): Add ShippingOverrides to control fulfillment details
5. Submit Request: The API will validate the request and process the substitution
6. Verify Results: Check the order to confirm the original item has been replaced with the new item(s)

Validation Rules

The API performs the following validations:

• At least one substitution must be specified in the request
• Either OrderItemID or Sku must be specified for the original item
• Each replacement item must have either ProductID or Sku specified
• Replacement item Quantity must be greater than 0
• UnitPrice is required for each replacement item
• Original item must exist in the order and must not be fully shipped
• If using SKU to identify the original item, it must match exactly one item in the order
• If using shipping overrides, DistributionCenterID must be valid and accessible
• Shipping override quantities must not exceed replacement item quantities
• The order must be from a supported marketplace or be a Checkout Direct order

Response Codes

• 204 No Content: Substitution completed successfully
• 400 Bad Request: Validation error (check error message for details)
• 401 Unauthorized: Missing or invalid authentication token
• 404 Not Found: Order not found or original item not found
• 500 Internal Server Error: System error occurred (contact Rithum for Brands support)

Examples

See the examples in the API documentation for common substitution scenarios including:

• Basic item substitution using SKU
• Partial quantity substitution
• Multiple replacement items
• Substitution with shipping overrides

{
  "Value": {
    "Substitutions": [
      {
        "@odata.type": "ChannelAdvisor.RestApi.V1.Models.OrderItemSubstitution"
      }
    ]
  }
}