Inventory Validation and Reservation Strategies

When integrating Walley Checkout, preventing overselling while maintaining a good customer experience is critical. This guide explains different strategies for validating stock availability and reserving inventory during the checkout process.

Overview of Approaches

There are three main approaches to handle inventory during checkout:

Approach	When to Validate	Best For
No Validation	After payment	Digital products, low-traffic stores
Pre-Payment Validation	Before payment	Standard e-commerce, stock checking
Advanced Validation	Before payment, Failed payment	Complex rules, Inventory reservation, Gift cards

Comparison Matrix

Choose the right approach based on your requirements:

Criteria	No Validation	Pre-Payment Validation	Advanced Callbacks
Overselling Prevention	❌ None	✅ Good	✅ Excellent
Checkout Speed	⚡ Fastest	🐌 Slower (+10s max)	🐌 Slower (+10s max)
Implementation Complexity	✅ Simple	✅ Simple	⚠️ Medium
Conversion Rate Impact	✅ None	⚠️ Potential negative	⚠️ Potential negative
Custom Validation	❌ No	⚠️ Limited	✅ Full support
Rollback Support	N/A	❌ No	✅ Yes (PaymentFailed)
HTTP Method	N/A	GET	POST with body

Approach 1: No Validation (Notification Only)

Overview

The simplest approach relies solely on the notification callback to process orders after payment completion. No pre-payment validation is performed.

Configuration

{
  "storeId": 123,
  "countryCode": "SE",
  "notificationUri": "https://api.myshop.com/notifications/{checkout.id}",
  "cart": {
    "items": [...]
  }
}

When to Use

• Digital products - No physical inventory to manage
• Made-to-order products - Items created after purchase
• Low-traffic stores - Minimal risk of simultaneous purchases
• Services - No stock limitations

Pros and Cons

✅ Advantages:

• Fastest checkout experience
• Simplest implementation
• No timeout concerns
• Highest conversion rate

❌ Disadvantages:

• Risk of overselling
• Customer disappointment if items unavailable
• Manual handling of out-of-stock situations

How It Works

1. Customer completes payment through Walley Checkout
2. Walley sends GET request to your notificationUri
3. Your backend receives the notification
4. Check if order was already processed (idempotency)
5. Retrieve checkout information using the checkout ID
6. If status is PurchaseCompleted:
   • Deduct inventory from stock
   • Create the order in your system
   • Send confirmation email to customer
7. Respond with 200 OK to confirm receipt

---

Approach 2: Pre-Payment Validation

Overview

Validate stock availability just before payment is processed using the validationUri. This provides a final check to ensure items are in stock before the customer's payment is authorized.

Architecture

Customer completes checkout form
    ↓
Customer clicks "Complete Purchase"
    ↓
Walley calls validationUri (GET)
    ↓
Your backend checks stock availability
    ↓
Response: Success or Error
    ↓
If success → Process payment
    ↓
If payment succeeds → Notification callback

Configuration

{
  "storeId": 123,
  "countryCode": "SE",
  "notificationUri": "https://api.myshop.com/notifications/{checkout.id}",
  "validationUri": "https://api.myshop.com/validate/{checkout.id}",
  "cart": {
    "items": [...]
  }
}

When to Use

• Standard e-commerce - Typical online stores with inventory management
• Medium traffic - Moderate number of concurrent users
• Simple validation - Primary need is stock availability checking
• Quick implementation - Simpler than reservation systems

Pros and Cons

✅ Advantages:

• Prevents overselling at point of payment
• No reservation state to manage
• Simple to implement
• Works with existing inventory systems

❌ Disadvantages:

• Adds latency to checkout (up to 10 seconds)
• No rollback mechanism if payment fails
• Customer may lose item during checkout
• Multiple validation calls possible

How It Works

1. Customer completes checkout form and clicks "Complete Purchase"
2. Walley calls your validationUri with a GET request
3. Your validation endpoint:
   • Retrieves checkout information using the checkout ID
   • Checks stock availability for all items
   • Returns success (200 OK) or error (400/500) response
4. If validation succeeds:
   • Payment is processed
   • Order can optionally be created in pending state
5. If validation fails:
   • Customer sees error message
   • Purchase is not completed
6. After successful payment:
   • Walley sends notification to notificationUri
   • Your backend finalizes the order
   • Inventory is deducted
   • Confirmation email is sent

Key Considerations

• 10-Second Timeout: Validation must complete within 10 seconds
• Multiple Calls: Validation may be called multiple times if customer retries
• Idempotency: Handle duplicate validation requests gracefully
• Error Messages: Provide clear feedback about unavailable items

Important

Even if validation succeeds, the purchase may still fail due to credit checks or payment issues. Always treat the order as pending until receiving the notificationUri callback with PurchaseCompleted status.

---

Approach 3: Advanced Validation with Callbacks

Overview

Use the callback object with ValidateOrder and PaymentFailed callback types for advanced validation scenarios with built-in rollback support.

Configuration

{
  "storeId": 123,
  "countryCode": "SE",
  "notificationUri": "https://api.myshop.com/notifications/{checkout.id}",
  "callback": {
    "callbackUri": "https://api.myshop.com/callbacks/{checkout.id}",
    "callbackTypes": ["ValidateOrder", "PaymentFailed"]
  },
  "cart": {
    "items": [...]
  }
}

When to Use

• Complex validation rules - Multiple checks beyond stock (customer eligibility, regional restrictions)
• Rollback requirements - Need to handle payment failures gracefully
• Multiple validation steps - Customer verification, business rules, inventory reservation, gift cards

Pros and Cons

✅ Advantages:

• Prevents overselling
• Supports complex business logic
• Built-in rollback via PaymentFailed callback
• Structured request/response format

❌ Disadvantages:

• Adds latency to checkout (up to 10 seconds)
• More complex than validationUri
• Requires fast backend response
• May lower conversion rate if slow

Callback Flow

Customer completes checkout form
    ↓
Customer clicks "Complete Purchase"
    ↓
Walley calls ValidateOrder callback (POST)
    ↓
Your backend: Check stock, validate rules
    ↓
Response: Success or Error
    ↓
If success → Process payment
    ↓
If payment fails → PaymentFailed callback
    ↓
If payment succeeds → Notification callback

How It Works

ValidateOrder Callback:

1. Walley sends POST request to your callbackUri with type ValidateOrder
2. Request body includes checkoutId and publicToken for verification
3. Your backend:
   • Retrieves checkout information
   • Checks stock availability
   • Validates customer eligibility (if needed)
   • Validates business rules (regional restrictions, etc.)
   • Optionally reserves inventory
   • Creates pending order
4. Response options:
   • Success (200 OK): Return { orderReference: "ORDER-123" } (optional)
   • Error (400): Return { title: "...", message: "...", clientPayload: {...} }
   • Timeout/Error (500): Customer sees generic error

PaymentFailed Callback:

1. Triggered when payment fails after successful validation
2. Your backend:
   • Finds the pending order by checkoutId
   • Cancels the order
   • Releases any inventory reservations
   • Cleans up any other resources
3. Always respond with 200 OK (failures here don't affect customer)

Notification Callback:

1. Triggered when payment succeeds
2. Your backend:
   • Updates order from pending to completed
   • Confirms inventory reservation (converts to sale)
   • Sends confirmation email
   • Triggers fulfillment process

Key Considerations

• 10-Second Timeout: Validation must complete within 10 seconds
• Idempotency: Implement caching to handle duplicate calls
• Error Handling: Provide clear error messages to customers
• Rollback: Always handle PaymentFailed to release reservations

---

Decision Guide

Use this flowchart to choose the right approach:

Do you sell physical products with limited stock?
│
├─ NO (digital/services) → Use No Validation
│
└─ YES → Need to prevent overselling?
    │
    ├─ Simple stock checking only?
    │   └─ YES → Use Pre-Payment Validation (validationUri)
    │
    ├─ Need rollback if payment fails?
    │   └─ YES → Use Advanced Callbacks (ValidateOrder + PaymentFailed)
    │
    └─ Complex validation rules?
        (customer eligibility, regional restrictions, gift cards, release inventory reservations)
        └─ YES → Use Advanced Callbacks

Migration from validationUri to Callbacks

If you're currently using validationUri and want to add rollback support, migrate to the callback object:

Before (validationUri):

{
  "notificationUri": "https://api.myshop.com/notifications/{checkout.id}",
  "validationUri": "https://api.myshop.com/validate/{checkout.id}"
}

After (callback object):

{
  "notificationUri": "https://api.myshop.com/notifications/{checkout.id}",
  "callback": {
    "callbackUri": "https://api.myshop.com/callbacks/{checkout.id}",
    "callbackTypes": ["ValidateOrder", "PaymentFailed"]
  }
}

Key Differences:

• Request Method: GET (validationUri) → POST (callback)
• Request Body: None → JSON with type and checkout details
• Rollback: Not available → PaymentFailed callback
• Authentication: None → checkoutId and publicToken provided

tip

You cannot use both validationUri and callback.ValidateOrder simultaneously. Choose one validation method.

Best Practices

All Approaches

• Implement Idempotency: Always check if a notification/callback was already processed
• Comprehensive Logging: Log all inventory operations for debugging and auditing
• Monitor Performance: Track validation times and reservation expiry rates
• Error Handling: Gracefully handle timeouts, connection failures, and partial stock

Pre-Payment Validation (validationUri)

• Response Time: Must complete within 10 seconds
• Idempotency: Handle duplicate validation requests (customer may retry)
• Error Messages: Provide clear, specific reasons for validation failures
• Pending Orders: Optionally create pending orders during validation

Advanced Validation (Callbacks)

• Response Time: Must complete within 10 seconds (set internal timeout at 8-9 seconds)
• Optimization: Use caching, batch queries, and parallel execution
• Clear Errors: Provide specific, actionable error messages to customers
• Always Rollback: Handle PaymentFailed callback to release resources

Testing Considerations

Key Test Scenarios

1. Happy Path: Successful purchase with stock available
2. Out of Stock: Item becomes unavailable during checkout
3. Reservation Expiry: User abandons checkout, reservation is released
4. Payment Failure: Payment declined, rollback occurs correctly
5. Concurrent Purchases: Multiple users buying last available item
6. Timeout Handling: Validation takes too long, proper error shown

What to Verify

• Inventory is correctly reserved/deducted
• No overselling occurs under concurrent load
• Expired reservations are released
• PaymentFailed callback releases resources
• Idempotency works for duplicate notifications
• Error messages are clear and helpful

Troubleshooting

Issue	Possible Cause	Solution
Overselling occurs	Race conditions	Implement database locks/transactions
"Reservation expired"	Checkout takes too long	Increase expiry duration (30 min)
"Validation timeout"	Slow backend	Optimize queries, add caching
Inventory remains locked	Cleanup job not running	Verify background job is active
Duplicate orders	Missing idempotency	Always check if already processed

Related Documentation

• Initialize Checkout - Setup callbacks and configuration
• Validate Order Callback - Detailed callback documentation
• Notification Callback - Purchase completion handling
• Gift Cards Use Case - Another callback example

Summary

Choose your inventory validation strategy based on:

• Product type - Digital → No Validation
• Validation needs - Simple stock check → Pre-Payment Validation
• Rollback requirements - Need cleanup → Advanced Callbacks
• Business rules - Complex logic → Advanced Callbacks

Remember that the notification callback is always required and is the only reliable confirmation of purchase completion, regardless of which validation approach you choose.

For questions or assistance, contact Walley Merchant Services at help@walley.se.