Upsell Reporting

Overview

This guide explains how to properly flag offers as upsells in the Vrio API for comprehensive tracking and reporting purposes. While upsell flagging is optional, it enables powerful analytics, commission tracking, and business intelligence that can significantly improve your upsell strategy optimization.

Why Flag Upsells?

Properly flagging upsells creates relationships that Vrio uses for:

Business Intelligence

Revenue Attribution: Understand which upsells drive the most revenue
Conversion Analysis: Track upsell acceptance rates across different offers and timing
Customer Lifetime Value: Measure the total value generated from each customer relationship
Campaign Performance: Evaluate the effectiveness of different upsell strategies

Operational Benefits

Commission Tracking: Properly attribute commissions to original sales and upsells
Parent-Child Relationships: Link upsells to their original offers for comprehensive reporting
Customer Journey Mapping: Understand the complete purchase flow and identify optimization opportunities
A/B Testing: Compare different upsell approaches with accurate data

Core Concept: Parent-Child Relationships

Upsell flagging works by creating parent-child relationships between offers. When you flag an offer as an upsell, you're telling Vrio that this offer is related to a previous "parent" offer, enabling the system to:

Group related purchases together in reports
Calculate true conversion rates and customer lifetime value
Properly attribute commissions across the entire customer journey
Provide insights into which initial offers lead to the most valuable upsells

Flagging Methods

Required Field for All Upsells

Field	Type	Description
`order_offer_upsell`	boolean	Set to `true` to mark offer as an upsell

Parent Reference Options

You have two ways to reference the parent offer:

Option 1: Direct Order Offer Reference

Field	Type	Description
`parent_order_offer_id`	integer	Direct reference to the specific order offer ID

Option 2: Offer and Order Reference

Field	Type	Description
`parent_offer_id`	integer	Reference to the offer ID
`parent_order_id`	integer	Reference to the order ID (for cross-order upsells)

Important: You only need one parent reference method. Choose the option that works best with your data structure.

Implementation Scenarios

Same-Order Upsells

For upsells within the same order (e.g., checkout page upsells):

{
  "offers": "[
    {\"offer_id\": 89, \"order_offer_quantity\": 1, \"order_offer_price\": 50.00},
    {\"offer_id\": 90, \"order_offer_quantity\": 1, \"order_offer_price\": 25.00, \"order_offer_upsell\": true, \"parent_offer_id\": 89},
    {\"offer_id\": 91, \"order_offer_quantity\": 1, \"order_offer_price\": 15.00, \"order_offer_upsell\": true, \"parent_offer_id\": 89}
  ]"
}

Key Points:

Use parent_offer_id to reference the original offer within the same order
Vrio automatically finds the corresponding order offer within the same order
Multiple upsells can reference the same parent offer

Cross-Order Upsells

For upsells processed as separate orders (e.g., post-purchase upsells):

Option 1: Using parent_order_offer_id

{
  "offers": "[
    {\"offer_id\": 95, \"order_offer_quantity\": 1, \"order_offer_price\": 29.99, \"order_offer_upsell\": true, \"parent_order_offer_id\": 1659163}
  ]"
}

Option 2: Using parent_offer_id + parent_order_id

{
  "offers": "[
    {\"offer_id\": 95, \"order_offer_quantity\": 1, \"order_offer_price\": 29.99, \"order_offer_upsell\": true, \"parent_offer_id\": 176, \"parent_order_id\": 1114897}
  ]"
}

Key Points:

Use parent_order_offer_id if you have the specific order offer ID from the original order
Use parent_offer_id + parent_order_id if you only have the offer ID and order ID
Vrio will automatically resolve the relationship in both cases

Complete API Examples

Same-Order Upsell Example

curl -X POST "https://api.vrio.app/orders" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "connection_id": 1,
    "campaign_id": 18,
    "offers": "[
      {\"offer_id\": 89, \"order_offer_quantity\": 1, \"order_offer_price\": 25.00},
      {\"offer_id\": 92, \"order_offer_quantity\": 1, \"order_offer_price\": 15.00, \"order_offer_upsell\": true, \"parent_offer_id\": 89}
    ]",
    "action": "process",
    "email": "[email protected]",
    "bill_fname": "John",
    "bill_lname": "Doe"
  }'

Cross-Order Upsell Example

curl -X POST "https://api.vrio.app/orders" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "connection_id": 1,
    "campaign_id": 18,
    "offers": "[
      {\"offer_id\": 95, \"order_offer_quantity\": 1, \"order_offer_price\": 29.99, \"order_offer_upsell\": true, \"parent_order_offer_id\": 1659163}
    ]",
    "action": "process",
    "email": "[email protected]",
    "bill_fname": "John",
    "bill_lname": "Doe"
  }'

Best Practices

1. Consistent Flagging Strategy

Choose One Method: Use either same-order or cross-order consistently within your flow
Document Your Approach: Ensure your team understands which method you're using
Test Thoroughly: Verify flagging works correctly in your reporting

2. Parent Reference Guidelines

Use parent_offer_id: When you know the offer ID and want Vrio to find the order offer automatically
Use parent_order_offer_id: When you have the specific order offer ID and want direct reference
Validate IDs: Ensure parent references point to valid, existing offers/orders

3. Reporting Considerations

Analytics Setup: Configure your analytics to recognize upsell flags
Commission Rules: Align upsell flagging with your commission structure
Performance Tracking: Monitor upsell conversion rates by offer and campaign

Common Use Cases

Checkout Page Upsells

Flag additional offers presented during the checkout process:

{
  "offers": "[
    {\"offer_id\": 89, \"order_offer_quantity\": 1, \"order_offer_price\": 50.00},
    {\"offer_id\": 90, \"order_offer_quantity\": 1, \"order_offer_price\": 25.00, \"order_offer_upsell\": true, \"parent_offer_id\": 89},
    {\"offer_id\": 91, \"order_offer_quantity\": 1, \"order_offer_price\": 15.00, \"order_offer_upsell\": true, \"parent_offer_id\": 89}
  ]"
}

Thank You Page Upsells

Flag offers presented immediately after purchase:

{
  "offers": "[
    {\"offer_id\": 95, \"order_offer_quantity\": 1, \"order_offer_price\": 39.99, \"order_offer_upsell\": true, \"parent_order_offer_id\": 1659163}
  ]"
}

Email Campaign Upsells

Flag offers sent via email campaigns:

{
  "offers": "[
    {\"offer_id\": 98, \"order_offer_quantity\": 1, \"order_offer_price\": 19.99, \"order_offer_upsell\": true, \"parent_offer_id\": 89, \"parent_order_id\": 1114897}
  ]"
}

Bundle Upsells

Flag bundle offers that include the original product plus additional items:

{
  "offers": "[
    {\"offer_id\": 100, \"order_offer_quantity\": 1, \"order_offer_price\": 75.00, \"order_offer_upsell\": true, \"parent_offer_id\": 89}
  ]"
}

Troubleshooting

Common Issues

Upsells Not Showing in Reports

Verify order_offer_upsell is set to true (boolean, not string)
Check that parent references point to valid offers/orders
Ensure your reporting system is configured to recognize upsell flags

Invalid Parent References

Confirm parent_offer_id exists and is accessible
For cross-order upsells, verify parent_order_id and parent_order_offer_id are correct
Check that parent orders belong to the same customer

Commission Tracking Issues

Review your commission rules to ensure they account for upsell flags
Verify parent-child relationships are properly established
Test commission calculations with flagged upsells