Batch Item Updates

The App API now supports updating multiple items in a single PATCH /item request. Each item in the batch receives its own result, making it straightforward to identify successes and failures without additional lookups. The endpoint includes request-size and rate limits to protect platform stability.

Proposed placement

App API section, after the existing Item endpoints reference.

When to use batch updates

Use the batch endpoint when you need to update attributes, status, or other properties on multiple items at once — for example:

• Synchronising price or stock changes from an ERP system.
• Bulk-toggling item visibility after a scheduled promotion.
• Applying attribute corrections across a product range.

For single-item updates, the existing individual PATCH /item/{itemId} endpoint remains available and unchanged.

Request

Send a PATCH request to the /item endpoint with an array of item update objects in the request body.

Example: updating pricing for multiple products

PATCH /item HTTP/1.1
Host: app-api.tweakwise.com
Content-Type: application/json
TWN-InstanceKey: YOUR_INSTANCEKEY
TWN-Authentication: YOUR_SECRET_TOKEN

[
    {
        "ArticleNumber": "87534829905_nl_52239908438353",
        "Patch": {
            "Price": 7999,
            "Attributes": [
                {
                    "Key": "compare-at-price",
                    "Values": [
                        "8999"
                    ]
                }
            ]
        }
    },
    {
        "ArticleNumber": "87534829905_nl_52239908405585",
        "Patch": {
            "Price": 7999,
            "Attributes": [
                {
                    "Key": "compare-at-price",
                    "Values": [
                        "8999"
                    ]
                }
            ]
        }
    }
]

Note: ArticleNumber is the item item.

Response

The response contains a result for each item in the same order as the request. Each result indicates whether the update succeeded or failed, along with any error details:

{
    "TotalCount": 2,
    "SucceededCount": 2,
    "FailedCount": 0,
    "Results": [
        {
            "Index": 0,
            "Key": "87534829905_82389172561_nl_52239908438353",
            "Status": "Succeeded"
        },
        {
            "Index": 1,
            "Key": "87534829905_82389172561_nl_52239908405585",
            "Status": "Succeeded"
        }
    ]
}

A batch request is not transactional. Successful items are applied even if other items in the same batch fail. Always inspect the per-item results to confirm which updates were applied.

Limits

If you exceed the rate limit, the API returns 429 Too Many Requests. Implement exponential back-off and retry logic in your integration.

Implementation notes

• Partial success: The endpoint processes each item independently. A failure on one item does not roll back other items in the batch. Design your integration to handle mixed results.
• Idempotency: Sending the same update twice produces the same result. If an attribute value is already set to the requested value, the item is reported as successful.
• Ordering: Results are returned in the same order as the request array. Use the ArticleNumberin each result to correlate responses if needed.
• Publish: Batch updates modify the item data in the App API layer. Changes become visible in the Delivery API after the next publish cycle, just like individual item updates.

FAQ

Q: Is the batch update transactional?
No. Each item is processed independently. If one item fails (e.g. item not found), the other items in the batch are still applied. Check the per-item success field in the response.

Q: How many items can I include in a single batch request?
The endpoint is subject to the standard App API request-size limit. In practice, batches of a few hundred items work well. For very large updates, split them into multiple requests with appropriate rate-limit handling.

Q: Do batch updates trigger an automatic publish?
No. Like individual item updates, batch changes are staged in the App API. They become available in the Delivery API after the next publish, either scheduled or manually triggered.