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

POST

ecommerce

products

{id}

stock

transfer

Traspasar stock entre bodega y sucursales

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

import requests

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

payload = {
    "quantity": 2,
    "variant_id": "<string>",
    "from_branch_id": "<string>",
    "to_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({
    quantity: 2,
    variant_id: '<string>',
    from_branch_id: '<string>',
    to_branch_id: '<string>',
    note: '<string>'
  })
};

fetch('https://api.keebai.com/v1/ecommerce/products/{id}/stock/transfer', 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/transfer",
  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([
    'quantity' => 2,
    'variant_id' => '<string>',
    'from_branch_id' => '<string>',
    'to_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/transfer"

	payload := strings.NewReader("{\n  \"quantity\": 2,\n  \"variant_id\": \"<string>\",\n  \"from_branch_id\": \"<string>\",\n  \"to_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/transfer")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"quantity\": 2,\n  \"variant_id\": \"<string>\",\n  \"from_branch_id\": \"<string>\",\n  \"to_branch_id\": \"<string>\",\n  \"note\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"quantity\": 2,\n  \"variant_id\": \"<string>\",\n  \"from_branch_id\": \"<string>\",\n  \"to_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
        }
      ]
    }
  ]
}

Moves units from one place to another. Without from_branch_id they leave the warehouse; without to_branch_id they go back to the warehouse. Between two branches, pass both. The master total stays the same: only where the units sit changes. The move leaves a transfer entry in the stock movements.

Endpoint

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

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
`quantity`	`integer`	Yes	Units to move. At least `1`.
`variant_id`	`string`	Conditional	`ObjectId` of the variant. Required on products with variants.
`from_branch_id`	`string`	No	Origin branch. Without it, the units leave the warehouse.
`to_branch_id`	`string`	No	Destination branch. Without it, the units go back to the warehouse.
`note`	`string`	No	Reason for the transfer, kept on the movement.

Where the units go

`from_branch_id`	`to_branch_id`	Move
—	Set	Warehouse → branch.
Set	—	Branch → warehouse.
Set	Set	Branch → branch. Must be different branches.
—	—	Fails with `TRANSFER_BRANCH_REQUIRED`.

Example request

curl -X POST https://api.keebai.com/v1/ecommerce/products/65d3e4f5a6b7c8d9e0f1a2b3/stock/transfer \
  -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 3,
    "variant_id": "65d3e4f5a6b7c8d9e0f1a2c1",
    "from_branch_id": "br_01",
    "to_branch_id": "br_02",
    "note": "Reposición fin de semana"
  }'

const response = await fetch(
  `https://api.keebai.com/v1/ecommerce/products/${productId}/stock/transfer`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.KEEBAI_API_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ quantity: 5, variant_id: variantId, to_branch_id: "br_01" }),
  },
);
const stock = await response.json();

import os, requests

resp = requests.post(
    f"https://api.keebai.com/v1/ecommerce/products/{product_id}/stock/transfer",
    headers={"Authorization": f"Bearer {os.environ['KEEBAI_API_TOKEN']}"},
    json={"quantity": 5, "variant_id": variant_id, "to_branch_id": "br_01"},
    timeout=10,
)
resp.raise_for_status()
stock = resp.json()

Response

200 OK

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

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

400 Bad Request

The body does not match the schema — for example quantity below 1 — or one of these:

`code`	Meaning
`TRANSFER_BRANCH_REQUIRED`	Neither `from_branch_id` nor `to_branch_id` was sent.
`TRANSFER_SAME_BRANCH`	Origin and destination are the same branch.
`STOCK_INSUFFICIENT_IN_WAREHOUSE`	The warehouse does not have that many units to send.
`STOCK_INSUFFICIENT_IN_BRANCH`	The origin branch does not have that many units to send.
`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 total never changes. A transfer only moves units between the warehouse and branches. To add or remove stock, adjust it.
This call is not idempotent. Retrying after a timeout moves the units twice. Check the stock movements before retrying.

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

quantity

number

required

Unidades a traspasar

Required range: x >= 1

variant_id

string

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

from_branch_id

string

Sucursal de origen. Sin ella, sale de la bodega

to_branch_id

string

Sucursal de destino. Sin ella, vuelve a la bodega

note

string

Motivo del traspaso

Maximum string length: 500

Response

200 - application/json

product_id

string

required

variants

object[]

required

Show child attributes

Traspasar stock entre bodega y sucursales

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

import requests

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

payload = {
    "quantity": 2,
    "variant_id": "<string>",
    "from_branch_id": "<string>",
    "to_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({
    quantity: 2,
    variant_id: '<string>',
    from_branch_id: '<string>',
    to_branch_id: '<string>',
    note: '<string>'
  })
};

fetch('https://api.keebai.com/v1/ecommerce/products/{id}/stock/transfer', 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/transfer",
  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([
    'quantity' => 2,
    'variant_id' => '<string>',
    'from_branch_id' => '<string>',
    'to_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/transfer"

	payload := strings.NewReader("{\n  \"quantity\": 2,\n  \"variant_id\": \"<string>\",\n  \"from_branch_id\": \"<string>\",\n  \"to_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/transfer")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"quantity\": 2,\n  \"variant_id\": \"<string>\",\n  \"from_branch_id\": \"<string>\",\n  \"to_branch_id\": \"<string>\",\n  \"note\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"quantity\": 2,\n  \"variant_id\": \"<string>\",\n  \"from_branch_id\": \"<string>\",\n  \"to_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/transfer

Endpoint

Required scope

Headers

Path parameters

Body

Where the units go

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

​Where the units go

​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

Where the units go

Example request

Response

200 OK

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

502 Bad Gateway

Operational notes