Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kibocommerce.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks through how to safely delete inventory records in bulk using Kibo’s Inventory APIs — including how to structure your requests, validate before executing, monitor deletion jobs, and self-throttle your requests to avoid HTTP 429 Too Many Requests errors.

Inventory API Overview

Best practices, job management, and segmentation via the Inventory API

Inventory Export File

Use Location Export files to build a complete inventory deletion list

API Best Practices

Rate limiting, retry logic, and request patterns for Kibo APIs

Get Inventory (POST)

Look up current inventory by product identifier before deleting

​
Overview

Bulk inventory deletion in Kibo is handled through two API endpoints that share the same asynchronous job-based execution model. Both endpoints return immediately — the actual deletion work happens in the background via Kibo’s job queue. This means there is no risk of HTTP timeouts for large deletions, and you can track progress through the job IDs returned in the response. When you should use these APIs:
  • Removing discontinued product lines across all or selected locations
  • Clearing out inventory for a tenant migration or re-platforming effort
  • Deleting a large set of SKUs identified by a known naming convention
Deletion is permanent. Always use dryRun: true first to verify scope before executing a live deletion.

​
The Two Deletion Endpoints

​
Option 1: Delete — Single-Product Pattern

POST /api/commerce/inventory/v5/inventory/delete Use this endpoint when targeting one product identifier — a single partNumber, upc, or sku — across one or all locations. It supports basic regex operators in the identifier field (.*+?^$[]), making it well-suited for pattern-based deletion (e.g., all products whose part number starts with a given prefix).

​
Request Body

{
  "dryRun": true,
  "allLocations": true,
  "partNumber": "DISC-2023-.*",
  "locationCodes": [],
  "explicit": false
}

​
Field Reference

FieldTypeDescription
dryRunbooleanWhen true, reports what would be deleted without making any changes. Always start here.
allLocationsbooleanWhen true, targets all locations for the tenant. Overrides locationCodes.
locationCodesarray of stringsScope the deletion to a specific set of location codes. Ignored when allLocations is true.
partNumberstringThe product part number. Supports basic regex operators: .*+?^$[]
upcstringAlternative identifier. Supports the same regex operators.
skustringAlternative identifier. Supports the same regex operators.
explicitbooleanWhen true, the response includes full per-item detail (inventory IDs, location IDs, audit IDs). Useful for auditing.
Provide only one of partNumber, upc, or sku per request. This endpoint is designed for single-product targeting.

​
Option 2: Delete Items — Multi-Product Bulk Pattern

POST /api/commerce/inventory/v5/inventory/deleteItems Use this endpoint when you have a list of multiple products to delete in one operation. The items array accepts individual product identifiers — each specified by partNumber, upc, or sku. Regex operators are supported per item.

​
Request Body

{
  "dryRun": false,
  "allLocations": true,
  "items": [
    { "upc": "UPC-001" },
    { "upc": "UPC-002" },
    { "partNumber": "PART-003" },
    { "sku": "SKU-004" }
  ]
}

​
Field Reference

FieldTypeDescription
dryRunbooleanWhen true, reports what would be deleted without making changes.
allLocationsbooleanWhen true, targets all locations. Overrides locationCodes.
locationCodesarray of stringsScope to specific locations when not using allLocations.
itemsarrayList of products to delete. Each item may specify partNumber, upc, or sku. Regex operators are supported.
explicitbooleanWhen true, returns full per-item deletion detail.

​
How Deletion Actually Works (Async Job Model)

Both endpoints operate asynchronously. When you submit a deletion request, Kibo:
  1. Validates the request.
  2. Enqueues one background job per location affected by the deletion.
  3. Returns immediately with a response — no waiting for the deletion to complete.
This architecture is why these endpoints are safe to use for large-scale operations involving millions of records or hundreds of locations. There is no HTTP timeout risk on the deletion request itself.

​
Example Response

{
  "dryRun": false,
  "totalProductsDeleted": 312,
  "totalInventoryEntriesDeleted": 4245251,
  "totalLocationsAffected": 312,
  "totalAuditsDeleted": 0,
  "totalPickWavesDeleted": 0,
  "itemsDeleted": [...],
  "jobIDs": [12345, 12346, 12347]
}
The jobIDs array contains one job ID per affected location. For large tenants with many locations, this list can be long. Store all job IDs returned — you will use them to monitor progress.

​
Monitoring Deletion Progress

Since deletion runs in the background, use the Get Job API to poll each job until it reaches a terminal status. 
GET /api/commerce/inventory/v1/queue/{jobID}
To retrieve all jobs at once (useful when you have many job IDs to review), use the Get Jobs API: 
GET /api/commerce/inventory/v1/queue

​
Job Status Values

StatusMeaning
PENDINGJob is queued and has not started yet.
WORKINGJob is actively being processed.
SUCCESSJob completed successfully.
FAILEDJob encountered an error. Check the messages field for details.

​
Example Polling Approach (Pseudocode)

for each jobID in jobIDs:
    repeat:
        response = GET /api/commerce/inventory/v1/queue/{jobID}
        if response.status == "SUCCESS" or response.status == "FAILED":
            log result and stop polling this job
        else:
            wait 10–30 seconds before polling again
Do not poll at a rapid fixed interval. Poll every 10–30 seconds per job using exponential backoff, particularly if you have many jobs to track simultaneously. Excessive polling of the job endpoint itself consumes your API rate limit quota.

​
Step 1 — Identify Your Scope

Decide which products need to be deleted and how to identify them:
  • Do they share a naming pattern (prefix, suffix, regex match)? → Use the Delete endpoint with a partNumber/upc/sku regex.
  • Do you have a discrete list of product identifiers? → Use the Delete Items endpoint with an items array.
  • Are you deleting across all locations, or specific ones? → Set allLocations: true or populate locationCodes.

​
How to Get a Reliable Full Inventory List Before a Bulk Deletion

There are several paths available, depending on your current tenant configuration and baseline data set:
SituationRecommended approach
The full list of the tenant’s product IDs is known (API-only path)Use Get Inventory (POST) per location with pagination, scoped to known identifiers
The tenant already receives daily inventory export filesUse the most recent Location Export file — it is the authoritative full-tenant inventory list
The tenant does not have exports set up yetContact Kibo Support to enable exports, or use your own catalog/ERP as the source of product identifiers to query the Get Inventory API
The cleanest path for a bulk deletion project is: get the Location Export file → parse all UPC/PartNumber/SKU values from it → use that list as the input to the bulk delete operation. This gives you a provable, timestamped snapshot of exactly what was in inventory at the time of deletion, and a clean audit record.
Option A: The Inventory Export File
Inventory Export File documentation The Location Export is the most reliable way to get a complete, authoritative list of every item at every location across your entire tenant. It includes key fields such as PartNumber, UPC, SKU, quantity on hand, quantity available, safety stock, floor quantity, and locationCode for every record. The tradeoff: The export is not on-demand via API. It is a scheduled daily file delivered by Kibo to your configured drop point (such as an SFTP site or cloud storage destination). You cannot trigger it yourself via an API call.
  • If your tenant already has inventory exports enabled and is receiving daily files, the most recent Location Export file is the best starting point — it gives you a clean, parseable list of all product identifiers per location.
  • If the tenant does not have exports enabled, you need to contact Kibo Support to enable the feature and set up a delivery destination.
Two export types:
Export TypeWhat it containsBest for
Location ExportEvery item at every location, with location codesBuilding a per-location deletion list
Aggregate ExportTotal quantities across all locations, no location breakdownUnderstanding overall scope
For building a deletion list you will use against the bulk delete endpoint, the Location Export is what you want — it gives you the product identifiers and the location codes together.
Option B: The Get Inventory (POST) API
Get Inventory (POST) API The Get Inventory API supports pagination (pageSize) and location filtering. However, there is a critical constraint: the items array in the request body is required, and it specifies which products you want to look up. This is an inquiry/lookup API — not a “dump everything” API. You cannot submit an empty request and get all inventory back.
  • If you already know the product identifiers (e.g., from your ERP or catalog system), you can paginate through the Get Inventory API per location to confirm what exists in Kibo before building your deletion list.
  • If you do not have a known product list, the API alone cannot enumerate all inventory records without already knowing what to query for.

​
Step 2 — Run a Dry Run First

Always submit your request with dryRun: true before any live execution. 
{
  "dryRun": true,
  "allLocations": true,
  "partNumber": "DISC-2023-.*"
}
Review the response carefully:
  • totalProductsDeleted — confirms how many products match.
  • totalInventoryEntriesDeleted — shows the volume of records that will be removed.
  • totalLocationsAffected — tells you how many location-level jobs will be created.
  • itemsDeleted — if explicit: true was set, inspect individual matches before proceeding.
Do not proceed to Step 3 until the dry run results match your expectations.

​
Step 3 — Batch Your Live Requests (If Using Delete Items)

If you are using the Delete Items endpoint /api/commerce/inventory/v5/inventory/deleteItems with a large list of products, do not send all items in a single request. Break your list into batches.
Recommended batch size: 500 items per request.The request returns immediately once jobs are enqueued, but the enqueuing itself is synchronous and bounded by database and process timeout limits. Staying at or below 500 items per batch keeps your requests well within the timeout ceiling, even on tenants with a large number of locations.
Hard maximum: 1,000 items per request. The Delete Items endpoint will reject requests that exceed this ceiling under any circumstances.
Between batches, add a deliberate delay of at least 5–10 seconds. This serves two purposes: it gives the job queue time to begin processing the previous batch, and it keeps your sustained request rate below the per-minute API rate limit. Recommended approach:
  • Split your full product list into batches of 500 items per request.
  • Do not exceed 1,000 items per batch under any circumstances.
  • Submit one batch at a time. Collect all jobIDs returned in the response before proceeding.
  • Wait at least 5–10 seconds between batches.
  • Do not use batch completion (all jobs at SUCCESS) as a gate before submitting the next batch — the jobs run asynchronously and may take time to work through the queue. Pace by time delay, not by job status.

​
Step 4 — Submit the Live Deletion with dryRun: false

Once the dry run is validated and your batch strategy is in place, submit with dryRun: false. Collect and store all jobIDs returned. 
{
  "dryRun": false,
  "allLocations": true,
  "partNumber": "DISC-2023-.*"
}

​
Step 5 — Monitor All Jobs to Completion

Poll each job ID using the Get Job API. Log all FAILED jobs and their messages for investigation. A failed job does not automatically retry — you will need to re-submit a targeted deletion request for any failed scope.

​
Self-Throttling to Avoid HTTP 429 Errors

Kibo enforces rate limiting per API route to protect platform stability for all tenants. If you exceed the allowed request rate, subsequent requests will be rejected with an HTTP 429 Too Many Requests response until the restriction window expires.

​
Understanding the 429 Response

HTTP/1.1 429 Too Many Requests
Retry-After: 60
The Retry-After response header tells you exactly how many seconds to wait before making another request. Possible values are 60, 900, 1800, 2700, or 3600 seconds (1 minute up to 60 minutes). Do not continue making requests during this window — they will also be rejected, and sustained violations can extend the restriction period.

​
How Rate Limits Work

Kibo applies limits at both the per-minute (RPM) and per-hour (RPH) level for each API route. Both limits count against the same requests:
  • Minute limits reset at the start of each new minute.
  • Hourly limits operate on a rolling 60-minute window divided into 15-minute buckets.
Burst behavior: You can send requests up to the maximum RPM rate, but only for as long as your hourly budget allows. For example, if the inventory route allows 50 RPM and 200 RPH, you can sustain 50 RPM for a maximum of 4 minutes before exhausting your hourly budget. Plan accordingly — do not use your entire hourly quota in a short burst.
To view the exact rate limits for your tenant per API route, go to Dev Center > API > Limits. If you are within limits, the status shows OK in green. If throttled, it shows Throttled in red.

​
Practical Self-Throttling Rules for Bulk Deletion

RuleWhy It Matters
Send one batch at a time. Never fire multiple deletion requests simultaneously.Each request to delete or deleteItems generates jobs and counts against your per-minute and hourly API rate limits.
Add deliberate delays between batches. Wait at least a few seconds between requests, longer for large lists.This keeps your sustained request rate below the per-minute limit without exhausting your hourly budget too quickly.
Honor the Retry-After header immediately. If you receive a 429, stop all requests and wait the full duration.Continuing to send requests during a restriction window will not succeed and may extend the throttle period.
Poll job status at low frequency. Poll each job every 10–30 seconds, not continuously.Job status poll requests count against the same /api/commerce/inventory/* rate limit pool as your deletion requests.
Schedule large deletions during non-peak hours.For US tenants, non-peak hours are 05:00–11:00 UTC. For EU tenants, 22:00–04:00 UTC. Running bulk operations during these windows reduces contention. Non-peak hours are calculated in UTC — schedule jobs in UTC to avoid Daylight Saving Time shifting your window.

​
Handling a 429 — Retry Logic Pattern (Pseudocode)

function submitWithRetry(requestPayload):
    attempt = 0
    while attempt < MAX_RETRIES:
        response = POST /api/commerce/inventory/v5/inventory/deleteItems (requestPayload)

        if response.status == 200:
            return response

        if response.status == 429:
            retryAfterSeconds = response.headers["Retry-After"]
            log("Rate limited. Waiting " + retryAfterSeconds + " seconds before retry.")
            wait(retryAfterSeconds)     // Respect the exact header value
            attempt += 1

        if response.status == 500 or other error:
            wait(exponentialBackoff(attempt))   // Add delay before retrying non-429 errors
            attempt += 1

    raise Error("Max retries exceeded")
Per the API Best Practices, always add delay before retrying on non-200 responses. Use exponential backoff or a similar strategy rather than retrying immediately.

​
Endpoint and Capability Summary

FeatureDelete (Single Pattern)Delete Items (Bulk Pattern)
EndpointPOST /v5/inventory/deletePOST /v5/inventory/deleteItems
Products per request1 (with regex support)Many (array of identifiers)
Execution modelAsync — one job per locationAsync — one job per location
Timeout riskNone — returns immediatelyNone — returns immediately
Dry run supportYesYes
Regex supportYesYes (per item)
Location scopingallLocations or locationCodesallLocations or locationCodes
Progress trackingJob IDs → Get Job APIJob IDs → Get Job API
Best forPattern-based deletion of one product familyDeleting a known list of multiple SKUs
ResourceLink
Delete Inventory (single-product)API Reference
Delete Items (bulk)API Reference
Get Job (monitor a single job)API Reference
Get Jobs (list all jobs)API Reference
Get Inventory (POST)API Reference
API Best Practices (rate limiting)API Best Practices
Inventory Export FileGuide

​
Pre-Deletion Checklist

Before running a bulk inventory deletion, confirm the following:
  • Dry run (dryRun: true) has been executed and the scope has been reviewed.
  • The totalProductsDeleted and totalInventoryEntriesDeleted values in the dry run match expectations.
  • If using Delete Items, the full product list has been split into batches of 500 or fewer.
  • A delay between batch submissions is built into the process.
  • A retry mechanism that respects the Retry-After header is implemented.
  • Job IDs from the live request have been captured and are being monitored via the Get Job API.
  • The deletion is scheduled during non-peak hours where possible (05:00–11:00 UTC for US tenants; 22:00–04:00 UTC for EU tenants).
  • Any jobs returning FAILED status have been reviewed and re-submitted as needed.