POST /v1/ecommerce/products/:id/stock/adjust

POST

ecommerce

products

{id}

stock

adjust

Ajustar el stock de un producto

curl --request POST \
  --url https://api.keebai.com/v1/ecommerce/products/{id}/stock/adjust \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "delta": -2,
  "variant_id": "<string>",
  "branch_id": "<string>",
  "note": "<string>"
}
'

import requests

url = "https://api.keebai.com/v1/ecommerce/products/{id}/stock/adjust"

payload = {
    "delta": -2,
    "variant_id": "<string>",
    "branch_id": "<string>",
    "note": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({delta: -2, variant_id: '<string>', branch_id: '<string>', note: '<string>'})
};

fetch('https://api.keebai.com/v1/ecommerce/products/{id}/stock/adjust', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.keebai.com/v1/ecommerce/products/{id}/stock/adjust",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'delta' => -2,
    'variant_id' => '<string>',
    'branch_id' => '<string>',
    'note' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.keebai.com/v1/ecommerce/products/{id}/stock/adjust"

	payload := strings.NewReader("{\n  \"delta\": -2,\n  \"variant_id\": \"<string>\",\n  \"branch_id\": \"<string>\",\n  \"note\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.keebai.com/v1/ecommerce/products/{id}/stock/adjust")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"delta\": -2,\n  \"variant_id\": \"<string>\",\n  \"branch_id\": \"<string>\",\n  \"note\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.keebai.com/v1/ecommerce/products/{id}/stock/adjust")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"delta\": -2,\n  \"variant_id\": \"<string>\",\n  \"branch_id\": \"<string>\",\n  \"note\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "product_id": "<string>",
  "variants": [
    {
      "variant_id": "<string>",
      "name": "<string>",
      "total": 123,
      "allocated": 123,
      "warehouse_available": 123,
      "branches": [
        {
          "branch_id": "<string>",
          "quantity": 123
        }
      ]
    }
  ]
}

Records a stock entry or exit. A positive delta adds stock, a negative one removes it. Without branch_id the change happens in the warehouse; with it, in that branch. The change is synced to the stores you have connected, and it leaves an adjustment entry in the stock movements.

Endpoint

POST https://api.keebai.com/v1/ecommerce/products/{id}/stock/adjust

Required scope

ecommerce:stock:write

The scope comes from your role. Minting a token with ecommerce:stock:write requires the permission to adjust and transfer stock in your Keebai role, unless you are the company owner or a superuser. See scopes.

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer kbai_pk_<token>`
`Content-Type`	Yes	`application/json`

Path parameters

Field	Type	Required	Description
`id`	`string`	Yes	`ObjectId` of the product.

Body

Field	Type	Required	Description
`delta`	`integer`	Yes	Units to add or remove. Not `0`. Positive is an entry, negative is an exit.
`variant_id`	`string`	Conditional	`ObjectId` of the variant. Required on products with variants.
`branch_id`	`string`	No	Branch to adjust. Without it, the warehouse is adjusted.
`note`	`string`	No	Reason for the adjustment, kept on the movement.

Example request

curl -X POST https://api.keebai.com/v1/ecommerce/products/65d3e4f5a6b7c8d9e0f1a2b3/stock/adjust \
  -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "delta": -2,
    "variant_id": "65d3e4f5a6b7c8d9e0f1a2c1",
    "branch_id": "br_01",
    "note": "Producto dañado"
  }'

const response = await fetch(
  `https://api.keebai.com/v1/ecommerce/products/${productId}/stock/adjust`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.KEEBAI_API_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ delta: 10, variant_id: variantId, note: "Recepción de proveedor" }),
  },
);
const stock = await response.json();

import os, requests

resp = requests.post(
    f"https://api.keebai.com/v1/ecommerce/products/{product_id}/stock/adjust",
    headers={"Authorization": f"Bearer {os.environ['KEEBAI_API_TOKEN']}"},
    json={"delta": 10, "variant_id": variant_id, "note": "Recepción de proveedor"},
    timeout=10,
)
resp.raise_for_status()
stock = resp.json()

Response

200 OK

The product’s stock after the adjustment, in the same shape as GET /v1/ecommerce/products/{id}/stock.

{
  "product_id": "65d3e4f5a6b7c8d9e0f1a2b3",
  "variants": [
    {
      "variant_id": "65d3e4f5a6b7c8d9e0f1a2c1",
      "name": "42 / Negro",
      "total": 10,
      "allocated": 6,
      "warehouse_available": 4,
      "branches": [
        { "branch_id": "br_01", "quantity": 3 },
        { "branch_id": "br_02", "quantity": 3 }
      ]
    }
  ]
}

400 Bad Request

The body does not match the schema — for example delta is 0 or not an integer — or one of these:

`code`	Meaning
`STOCK_BELOW_ZERO`	The exit would leave the stock below zero.
`STOCK_INSUFFICIENT_IN_WAREHOUSE`	The warehouse does not have that many units to remove.
`STOCK_INSUFFICIENT_IN_BRANCH`	The branch does not have that many units to remove.
`VARIANT_REQUIRED`	The product has variants and no `variant_id` was sent.

401 Unauthorized

Missing, invalid, revoked, or expired token.

403 Forbidden

The token does not have the ecommerce:stock:write scope.

404 Not Found

No product with that id, or it belongs to a different company.

502 Bad Gateway

ECOMMERCE_UPSTREAM_ERROR — the ecommerce service could not answer.

Operational notes

The change reaches your stores. Connected stores receive the new stock, so an adjustment here is what customers see online.
This call is not idempotent. Retrying after a timeout applies the delta twice. Check the stock movements before retrying.
To move stock between branches, transfer it. POST .../stock/transfer keeps the total; two adjustments would record an exit and an entry instead.

Authorizations

Authorization

string

header

required

Personal Access Token con prefijo kbai_pk_. Generar desde el portal con permiso developer.manage_tokens.

Path Parameters

string

required

Body

application/json

delta

number

required

Unidades a sumar (positivo) o restar (negativo). Entero distinto de 0

Example:

-2

variant_id

string

ObjectId de la variante. Obligatorio si el producto tiene más de una

branch_id

string

Sucursal donde se mueve el stock. Sin ella, el ajuste es sobre la bodega

note

string

Motivo del ajuste

Maximum string length: 500

Response

200 - application/json

product_id

string

required

variants

object[]

required

Show child attributes

Ajustar el stock de un producto

curl --request POST \
  --url https://api.keebai.com/v1/ecommerce/products/{id}/stock/adjust \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "delta": -2,
  "variant_id": "<string>",
  "branch_id": "<string>",
  "note": "<string>"
}
'

import requests

url = "https://api.keebai.com/v1/ecommerce/products/{id}/stock/adjust"

payload = {
    "delta": -2,
    "variant_id": "<string>",
    "branch_id": "<string>",
    "note": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({delta: -2, variant_id: '<string>', branch_id: '<string>', note: '<string>'})
};

fetch('https://api.keebai.com/v1/ecommerce/products/{id}/stock/adjust', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.keebai.com/v1/ecommerce/products/{id}/stock/adjust",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'delta' => -2,
    'variant_id' => '<string>',
    'branch_id' => '<string>',
    'note' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.keebai.com/v1/ecommerce/products/{id}/stock/adjust"

	payload := strings.NewReader("{\n  \"delta\": -2,\n  \"variant_id\": \"<string>\",\n  \"branch_id\": \"<string>\",\n  \"note\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.keebai.com/v1/ecommerce/products/{id}/stock/adjust")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"delta\": -2,\n  \"variant_id\": \"<string>\",\n  \"branch_id\": \"<string>\",\n  \"note\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.keebai.com/v1/ecommerce/products/{id}/stock/adjust")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"delta\": -2,\n  \"variant_id\": \"<string>\",\n  \"branch_id\": \"<string>\",\n  \"note\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "product_id": "<string>",
  "variants": [
    {
      "variant_id": "<string>",
      "name": "<string>",
      "total": 123,
      "allocated": 123,
      "warehouse_available": 123,
      "branches": [
        {
          "branch_id": "<string>",
          "quantity": 123
        }
      ]
    }
  ]
}

Get started

Products

Inventory

Carts

Sales

Electronic invoicing

POST /v1/ecommerce/products/:id/stock/adjust

Endpoint

Required scope

Headers

Path parameters

Body

Example request

Response

200 OK

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

502 Bad Gateway

Operational notes

Authorizations

Path Parameters

Body

Response

​Endpoint

​Required scope

​Headers

​Path parameters

​Body

​Example request

​Response

​200 OK

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​502 Bad Gateway

​Operational notes

Authorizations

Path Parameters

Body

Response

Endpoint

Required scope

Headers

Path parameters

Body

Example request

Response

200 OK

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

502 Bad Gateway

Operational notes