Skip to main content
The Smart Inventory APIs provide an optimized way to update inventory by automatically routing requests to either synchronous or asynchronous processing based on payload size. This eliminates the need to manually choose between sync and async endpoints, providing better performance while simplifying your integration.

​
Overview

Kibo offers two smart endpoints that intelligently determine the most efficient processing method:
MethodEndpointDescription
POST/commerce/inventory/v5/inventory/smart-adjust/Dynamically routes inventory adjustment requests
POST/commerce/inventory/v5/inventory/smart-refresh/Dynamically routes inventory refresh requests
These endpoints use the same request schemas as the standard Adjust and Refresh APIs, but automatically select the optimal processing method.

​
Dynamic Routing Logic

The API automatically determines the most efficient processing method based on the size of your request payload:
  • Synchronous Processing: Used for smaller payloads. Provides immediate processing and returns inventory results directly.
  • Asynchronous Processing: Used for larger payloads. Utilizes the job queue to handle batch updates and returns a job ID for tracking.
Kibo determines the routing threshold dynamically, though smaller requests (around 25 items or fewer) are generally processed synchronously. Your integration should always check the method field in the response to determine how the request was handled.

​
When to Use Smart APIs

Use the Smart Inventory APIs when:
  • You have variable batch sizes and want Kibo to optimize automatically
  • You want to simplify your integration by using a single endpoint instead of managing sync/async logic
  • You need to process mixed workloads ranging from single-item updates to bulk operations
Continue using the standard sync or async APIs directly when:
  • You always need synchronous responses regardless of batch size (use the sync APIs)
  • You always want job-based processing for audit trails (use the async APIs)
  • You have specific latency requirements that require explicit control

​
Request Schema

The request body is identical to the existing Adjust and Refresh APIs.

​
Smart Adjust Request Example

{
  "type": "ADJUST",
  "items": [
    {
      "locationCode": "WAREHOUSE-01",
      "items": [
        {
          "upc": "PRODUCT-123",
          "quantity": 10
        },
        {
          "upc": "PRODUCT-456",
          "quantity": -2
        }
      ]
    }
  ]
}

​
Smart Refresh Request Example

{
  "type": "REFRESH",
  "items": [
    {
      "locationCode": "WAREHOUSE-01",
      "items": [
        {
          "upc": "PRODUCT-123",
          "quantity": 50
        }
      ]
    }
  ]
}

​
Response Schema

The response includes metadata indicating how the request was processed:
FieldTypeDescription
methodstringProcessing method used: "sync" or "async"
jobIDstring or nullJob identifier for async requests; null for sync requests

​
Synchronous Response Example

When Kibo routes the request synchronously, you receive an immediate response: 
{
  "method": "sync",
  "jobID": null
}

​
Asynchronous Response Example

When Kibo routes the request asynchronously, you receive a job ID for tracking: 
{
  "method": "async",
  "jobID": "789456123"
}

​
Handling Responses

Your integration should check the method field to determine how to proceed: 
const response = await fetch('/commerce/inventory/v5/inventory/smart-adjust/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`
  },
  body: JSON.stringify(payload)
});

const result = await response.json();

if (result.method === 'sync') {
  // Inventory was updated immediately
  console.log('Inventory updated synchronously');
} else {
  // Poll for job completion
  console.log(`Job created: ${result.jobID}`);
  // Use the Get Job API to check status
}
For asynchronous responses, use the Get Job API to monitor the job status until completion.

​
Best Practices

  1. Design for both response types: Your integration should handle both sync and async responses gracefully, even if you expect most requests to fall into one category.
  2. Batch strategically: While the API handles routing automatically, consider your use case. If you need immediate confirmation, keep batches small. For bulk operations where immediate confirmation is not critical, larger batches are more efficient.
  3. Implement job polling for async: When you receive an async response, implement polling with exponential backoff to check job status rather than polling at a fixed rapid interval.
  4. Log the processing method: Track which method was used for your requests to understand your workload patterns and optimize batch sizes if needed.

Adjust Inventory API

Standard API for incremental inventory changes

Refresh Inventory API

Standard API for setting absolute inventory levels

Get Job API

Check the status of async inventory jobs

Inventory API Overview

General inventory API best practices and patterns