Guides
Start typing to search…

Single Order Upsell Processing

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/orders/{order_id}/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}]"
  }'

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/orders/{order_id}/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}]"
  }'

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/orders/1114897/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}]"
  }'

# 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/orders/1114897/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}]"
  }'

# 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 21 days ago