Guides
Start typing to search…

Single Order Upsell Processing

Add upsells to authorized orders for combined transactions with single customer charges and integrated checkout experiences.

Overview

This guide explains how to process upsells within a single order in the Vrio API. This approach allows you to add additional offers to orders and process them together, creating a single transaction on the customer's card that combines the initial purchase and all upsells.

Core Concept: Single Order Upselling

Single order upselling can be implemented in two ways:

Option 1: Authorization-First Flow

  1. Initial Authorization: Create and authorize an order without capturing payment
  2. Upsell Presentation: Present additional offers to the customer
  3. Offer Addition: Add accepted upsells to the existing authorized order
  4. Re-authorization: Re-authorize the order with the complete offer list (including upsells)
  5. Final Capture: Capture the complete order including all upsells

Payment Method Compatibility: Authorization is supported for Credit Cards, Apple Pay, Google Pay, PayPal, and Payment Tokens only.

Critical: Vrio captures the most recent successful authorization and voids previous ones. You must re-authorize after adding upsells to ensure the correct total is captured.

Option 2: All-at-Once Processing

  1. Order Creation: Create an order with initial offers
  2. Upsell Addition: Add upsell offers to the order
  3. Single Processing: Process the complete order with all offers at once using action: "process"

This approach is ideal when you want to have only one captured transaction on the customer's card, combining the initial purchase and all upsells into a single charge.

Implementation Workflows

Workflow 1: Authorization-First Flow

Step 1: Create and Authorize Initial Order

First, create an order with action: "authorize" to authorize payment without capturing:

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}]",
    "action": "authorize",
    "email": "[email protected]",
    "bill_fname": "John",
    "bill_lname": "Doe",
    "bill_phone": "+1234567890",
    "bill_address1": "123 Main St",
    "bill_city": "Anytown",
    "bill_state": "NY",
    "bill_zipcode": "12345",
    "bill_country": "US",
    "ship_fname": "John",
    "ship_lname": "Doe",
    "ship_address1": "123 Main St",
    "ship_city": "Anytown",
    "ship_state": "NY",
    "ship_zipcode": "12345",
    "ship_country": "US",
    "card_number": "4111111111111111",
    "card_exp_month": "12",
    "card_exp_year": "2025",
    "card_cvv": "123"
  }'

Expected Response

{
  "success": true,
  "response_code": 100,
  "transaction_id": 6501056,
  "customer_id": 470177,
  "order_id": 1114897,
  "merchant_id": 6,
  "order": {
    "order_id": 1114897,
    "customer_card_id": 980231,
    "customer_id": 470177,
    "status_type_id": 2
  }
}

Key Response Fields:

  • order_id: Use this to add upsells to the authorized order
  • customer_card_id: Payment information is stored for future use
  • merchant_id: Recommended to use the same merchant for re-authorization to avoid payment issues

Important: Check Response Code

If the initial authorization returns response_code: 101 (for example, when using PayPal), you will need to complete the order using the POST /orders/{id}/complete API method before moving on to upsells. For more information about handling 101 response codes, see our detailed guide.

Example 101 Response:

{
  "success": true,
  "response_code": 101,
  "transaction_id": 6501056,
  "customer_id": 470177,
  "order_id": 1114897,
  "merchant_id": 6,
  "order": {
    "order_id": 1114897,
    "customer_card_id": 980231,
    "customer_id": 470177
  }
}

Required Action for 101 Response:

curl -X POST "https://api.vrio.app/orders/1114897/complete" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{}'

Only proceed with adding upsells after successfully completing the order for 101 responses.

Step 2: Add Upsell Offers to Authorized Order

Add upsell offers to the existing authorized order:

curl -X POST "https://api.vrio.app/order_offers" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "offers": ["{\"offer_id\": 92, \"order_offer_quantity\": 1, \"order_offer_price\": 15.00, \"order_offer_upsell\": true, \"parent_offer_id\": 89}"],
    "order_id": 1114897
  }'

Step 3: Re-authorize Order with All Offers

Critical: After adding upsells, you must re-authorize the order before capture:

curl -X POST "https://api.vrio.app/orders/{order_id}/authorize" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "customer_card_id": "980231",
    "merchant_id": 6,
    "payment_method_id": 1
  }'

Why Re-authorization is Required:

  • Vrio captures the most recent successful authorization
  • Previous authorizations are automatically voided when a new authorization succeeds
  • This ensures the captured amount matches the complete order total including upsells

Step 4: Capture the Complete Order

Once the order is re-authorized with all offers, capture the complete order:

curl -X POST "https://api.vrio.app/orders/{order_id}/capture" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{}'

Workflow 2: All-at-Once Processing

For scenarios where you want to add upsells and process everything in one step:

Step 1: Create Order with Initial Offers

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}]",
    "email": "[email protected]",
    "bill_fname": "John",
    "bill_lname": "Doe",
    "bill_phone": "+1234567890",
    "bill_address1": "123 Main St",
    "bill_city": "Anytown",
    "bill_state": "NY",
    "bill_zipcode": "12345",
    "bill_country": "US",
    "ship_fname": "John",
    "ship_lname": "Doe",
    "ship_address1": "123 Main St",
    "ship_city": "Anytown",
    "ship_state": "NY",
    "ship_zipcode": "12345",
    "ship_country": "US",
    "card_number": "4111111111111111",
    "card_exp_month": "12",
    "card_exp_year": "2025",
    "card_cvv": "123"
  }'

Step 2: Add Upsell Offers to Order

curl -X POST "https://api.vrio.app/order_offers" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "offers": ["{\"offer_id\": 92, \"order_offer_quantity\": 1, \"order_offer_price\": 15.00, \"order_offer_upsell\": true, \"parent_offer_id\": 89}"],
    "order_id": ORDER_ID_FROM_STEP_1
  }'

Step 3: Process Complete Order

Process the entire order (initial offers + upsells) in one transaction:

curl -X POST "https://api.vrio.app/orders/{order_id}/process" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "action": "process"
  }'

Advanced Scenarios

Multiple Upsell Rounds

You can add multiple rounds of upsells before final capture. Re-authorization after each round is optional, but you must re-authorize before final capture:

# Round 1: Add first upsell
curl -X POST "https://api.vrio.app/order_offers" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "offers": ["{\"offer_id\": 92, \"order_offer_quantity\": 1, \"order_offer_price\": 15.00, \"order_offer_upsell\": true, \"parent_offer_id\": 89}"],
    "order_id": 1114897
  }'

# Optional: Re-authorize after first upsell (recommended for large amounts)
curl -X POST "https://api.vrio.app/orders/1114897/authorize" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "customer_card_id": "980231",
    "merchant_id": 6,
    "payment_method_id": 1
  }'

# Round 2: Add second upsell
curl -X POST "https://api.vrio.app/order_offers" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "offers": ["{\"offer_id\": 93, \"order_offer_quantity\": 1, \"order_offer_price\": 10.00, \"order_offer_upsell\": true, \"parent_offer_id\": 89}"],
    "order_id": 1114897
  }'

# Required: Final re-authorization before capture
curl -X POST "https://api.vrio.app/orders/1114897/authorize" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "customer_card_id": "980231",
    "merchant_id": 6,
    "payment_method_id": 1
  }'

# Final: Capture complete order
curl -X POST "https://api.vrio.app/orders/1114897/capture" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{}'

Error Handling

Authorization Failures

If the initial authorization fails, handle the error before presenting upsells:

{
  "success": false,
  "response_code": 201,
  "error_message": "Payment authorization declined",
  "order_id": 1114897
}

Response Strategy:

  • Do not present upsells if initial authorization fails
  • Offer alternative payment methods
  • Consider lower-value initial offers

Upsell Addition Failures

If adding upsells to an authorized order fails:

{
  "success": false,
  "error_message": "Order not in valid state for modifications",
  "order_id": 1114897
}

Common Causes:

  • Order already captured
  • Invalid offer configuration

Capture Failures

If the final capture fails:

{
  "success": false,
  "response_code": 201,
  "error_message": "Capture failed - authorization expired"
}

Recovery Options:

  • Re-authorize the complete order with all offers
  • Process with updated payment information
  • Contact customer for payment update

Related Documentation

For complete upsell implementation, see these related guides:

This approach provides maximum flexibility for sophisticated upsell flows while maintaining payment security and customer experience.

Updated 6 days ago