Update Bulk Quantities

This endpoint allows you to update bulk quantities by providing the IDs or Skus of the products you want to update its quantity in your body request

Modes

Mode	Best Used For	Example Use Cases
`increment`	Adding stock	• Receiving new inventory • Restocking returned items • Correcting undercounted stock
`decrement`	Removing stock	• Processing sales • Handling damaged goods • Inventory adjustments
`overwrite`	Initial setup only	• Setting initial stock levels • Complete inventory resets • Syncing with external systems (use with caution)

When updating product quantities, we strongly recommend using the increment and decrement modes instead of the overwrite mode for better inventory management and data integrity.

Why Choose Increment/Decrement Modes?

1. Concurrency Safety

When multiple systems or users update inventory simultaneously, increment/decrement operations provide better concurrency control:

Safe: "mode": "decrement", "quantity": 5 removes exactly 5 units regardless of concurrent operations

Risky: "mode": "overwrite", "quantity": 95 might overwrite changes made by other processes

2. Prevents Race Conditions

In high-traffic scenarios where inventory updates happen frequently:

// Scenario: Current stock is 100 units
// Two simultaneous operations occur:

// Operation A (GOOD - using decrement)
{
  "mode": "decrement",
  "quantity": 3  // Safely removes 3 units
}

// Operation B (GOOD - using decrement) 
{
  "mode": "decrement", 
  "quantity": 2  // Safely removes 2 units
}
// Final result: 95 units (100 - 3 - 2) ✅

// VS

// Operation A (RISKY - using overwrite)
{
  "mode": "overwrite",
  "quantity": 97  // Sets to 97 (100-3)
}

// Operation B (RISKY - using overwrite)
{
  "mode": "overwrite",
  "quantity": 98  // Sets to 98 (100-2), overwrites Operation A
}
// Final result: 98 units (incorrect, should be 95) ❌

3. Better Audit Trail

Increment/decrement operations provide clearer tracking of inventory changes:

Clear intent: "Decremented by 10 due to lost" vs "Set to 40 for unknown reason"

Easier debugging: You can trace each quantity change and its impact

Better reporting: Sum all increments/decrements to understand total movement

4. Improved Data Integrity

Atomic operations: Each increment/decrement is a single, indivisible operation

Consistent state: Inventory levels remain accurate even with concurrent updates

Error recovery: Easier to reverse specific operations if needed

Implementation Example

{
  "products": [
    {
      "identifer_type": "id",
      "identifer": "613398835",
      "quantity": 5,
      "mode": "decrement",  // ✅ Recommended: Remove 5 units from current stock
      "branch": "349994915",
      "reason_id": 566146469
    },
    {
      "identifer_type": "id", 
      "identifer": "9834759404",
      "quantity": 20,
      "mode": "increment",  // ✅ Recommended: Add 20 units to current stock
      "branch": "349994915",
      "reason_id": 566146469
    }
  ]
}

Scopes

products.read_write- Products Read & Write

Request

Authorization

Add the parameter

Authorization

to Headers，whose value is to concatenate the Token after the Bearer.

Example:

Authorization: Bearer ********************

Body Params application/json

products

array [object {7}]

required

identifer_type

enum<string>

required

Identifier Type. Value can either be id , variant_id or sku

Allowed values:

idvariant_idsku

identifer

string

required

Identifier Value, such as Product ID or and sku

Example:

1210921

quantity

integer

required

Quantity Value

mode

enum<string> | enum<null>

optional

Mode of quantity update; one of the allowed enum values

Allowed values:

overwriteincrementdecrement

Default:

overwrite

unlimited_quantity

boolean

optional

Option to indicate the product is of unlimited quantity

branch

integer

optional

Branch ID

reason_id

integer

optional

Reason ID for the update

Example

{
    "products": [
        {
            "identifer_type": "id",
            "identifer": "613398835",
            "quantity": 60,
            "mode": "increment",
            "branch": "349994915",
            "reason_id": 566146469,
            "unlimited_quantity": true
        },
                {
            "identifer_type": "id",
            "identifer": "9834759404",
            "quantity": 80,
            "mode": "overwrite",
            "branch": "349994915",
            "reason_id": 566146469,
            "unlimited_quantity": true
        },
        {
            "identifer_type": "variant_id",
            "identifer": "3498732894",
            "quantity": 14,
            "mode": "decrement",
            "branch": "349994915",
            "reason_id": 566146469
        },
        {
            "identifer_type": "variant_id",
            "identifer": "8439405958",
            "quantity": 140,
            "branch": "349994915",
            "reason_id": 566146469
        }
    ]
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢201Created

application/json

Body

status

number

optional

Response status code, a numeric or alphanumeric identifier used to convey the outcome or status of a request, operation, or transaction in various systems and applications, typically indicating whether the action was successful, encountered an error, or resulted in a specific condition.

success

boolean

optional

Response flag, boolean indicator used to signal a particular condition or state in the response of a system or application, often representing the presence or absence of certain conditions or outcomes.

data

object

optional

message

string

optional

A text or data communication generated by a system or application in response to a request.

code

number

optional

A numerical or alphanumeric identifier used in various systems and protocols to indicate the status or outcome of a specific request.

Example

{
    "status": 201,
    "success": true,
    "data": {
        "message": "The details has been queued to update, it may take several minutes to finish the process",
        "code": 201
    }
}

🟠422Error Validation

🟠401unauthorized

Modes#

Why Choose Increment/Decrement Modes?#

1. Concurrency Safety#

2. Prevents Race Conditions#

3. Better Audit Trail#

4. Improved Data Integrity#

Implementation Example#

Request

Request samples

Responses

Modes

Why Choose Increment/Decrement Modes?

1. Concurrency Safety

2. Prevents Race Conditions

3. Better Audit Trail

4. Improved Data Integrity

Implementation Example