API Reference
Start typing to search…

Duplicate Prevention

This document explains how VRIO matches both orders and offers during API processing to prevent duplicates and ensure consistent behavior.

Order Matching Logic

When processing an order via API, VRIO attempts to match an existing pending order based on these key attributes:

Order Matching Process

  1. Direct Order ID Match: If an order_id is passed in the request, the system loads that specific order for the customer (the order must be incomplete and belong to the customer identified or the order_id will be ignored)

  2. Automatic Order Search: If no order_id is provided, the system searches for a matching incomplete order based on:

    • Customer identification (customer_id, email, connection_id)
    • Same campaign
    • Created within last 12 hours
    • Matching cart_token
    • Identical offer combinations (see Offer Matching Logic section for details)

Key Behavior

  • If a matching order is found, a new transaction attempt is created instead of generating a completely new order
  • This allows consistent API calls across multiple processing attempts
📘

Creating New Orders

To force a new order even when all other characteristics match (same customer, campaign, offers, etc.), pass a different cart_token during the API call.

Offer Matching Logic

Within each order, VRIO also has sophisticated logic for matching individual offers to prevent duplicate offer entries on the same order.

Offer Matching Criteria

The system matches offers based on several identification methods:

  1. Direct Match: If order_offer_id is provided, the system uses this for direct identification

  2. Cart Offer ID Match: If id is provided in the offer array (mapped to cart_order_offer_id), the system matches based on this cart-specific identifier

  3. Complete Offer Match: If neither ID is provided, the system matches based on:

    • Order ID (must be on the same order)
    • Offer ID (must match exactly)
    • Quantity (must match the requested quantity)
    • Item ID (must match the specific item; if the offer is not dynamic, the item from the offer cycle will be used)
    • Item Options (all option values must match exactly)

Offer Matching Process

  1. Search for Existing Offer: The system searches for existing offers using the matching criteria above
  2. Create New Offer: If no match is found, a new order offer entry is created
  3. Update Existing Offer: If a match is found, the system updates the existing offer with any changes

Update vs Create Logic

When an existing offer is found, the system can update:

  • Price Updates: Compares override prices and shipping costs
  • Quantity Updates: Updates quantity if different
  • Status Updates: Can change status (e.g., from removed back to active)
  • Discount Updates: Applies new discount codes if provided
  • Gift Information: Updates gift-related fields
📘

Creating Duplicate Offers

To force a new offer entry even when all other criteria match (same order, offer_id, item_id, quantity, options, etc.), pass a different id value in the offer array. This works similar to how cart_token works for orders.

Example Scenarios

Order Matching Example

When submitting an order via POST /orders API with:

  • customer_id: 12345
  • campaign_id: 67890
  • cart_token: "abc123"
  • offers: [{"offer_id": 100, "item_id": 200, "quantity": 1}]

If a pending order exists for customer 12345 in campaign 67890 with cart_token "abc123" created within 12 hours AND contains the exact same offer combination (offer_id 100, item_id 200, quantity 1), VRIO will:

  • Attach a new transaction attempt to the existing order
  • Avoid creating a redundant order

Offer Matching Example

When adding an offer to an existing order with:

  • order_id: 54321
  • offer_id: 98765
  • item_id: 11111
  • quantity: 2
  • item_options: [option_value_1, option_value_2]

VRIO searches for an existing offer with the same order_id, offer_id, item_id, quantity, and option combination. If found, it updates the existing offer; if not found, it creates a new offer entry.

Purpose

This dual matching logic provides:

  • Order Level: Prevents duplicate orders for the same customer/campaign/cart combination
  • Offer Level: Prevents duplicate offer entries within the same order
  • Consistency: Ensures API calls behave predictably across multiple attempts
  • Flexibility: Allows for updates and modifications while maintaining data integrity

The system streamlines order processing and provides flexibility in handling both transaction attempts and offer modifications.