Create a replenishment
curl --request POST \
--url https://api.cubbo.com/v1/replenishments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"store_id": 1234,
"warehouse_id": 7,
"expected_arrived_at": "2026-11-02T15:00:00Z",
"notes": "Pallet 2 contains fragile items",
"external_reference": "PO-0001",
"unique_external_reference": true,
"sell_ahead": false,
"inventory_scope": "d2c",
"products": [
{
"sku": "SKU-RED-M",
"quantity": 100,
"unit_value": "12.50"
},
{
"sku": "SKU-BOX-BLUE",
"quantity": 48,
"lots": [
{
"lot_code": "LOT-2026-01",
"quantity": 24,
"external_reference": "LOT-REF-1"
},
{
"lot_code": "LOT-2026-02",
"quantity": 24,
"external_reference": "LOT-REF-2"
}
]
}
]
}
'import requests
url = "https://api.cubbo.com/v1/replenishments"
payload = {
"store_id": 1234,
"warehouse_id": 7,
"expected_arrived_at": "2026-11-02T15:00:00Z",
"notes": "Pallet 2 contains fragile items",
"external_reference": "PO-0001",
"unique_external_reference": True,
"sell_ahead": False,
"inventory_scope": "d2c",
"products": [
{
"sku": "SKU-RED-M",
"quantity": 100,
"unit_value": "12.50"
},
{
"sku": "SKU-BOX-BLUE",
"quantity": 48,
"lots": [
{
"lot_code": "LOT-2026-01",
"quantity": 24,
"external_reference": "LOT-REF-1"
},
{
"lot_code": "LOT-2026-02",
"quantity": 24,
"external_reference": "LOT-REF-2"
}
]
}
]
}
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({
store_id: 1234,
warehouse_id: 7,
expected_arrived_at: '2026-11-02T15:00:00Z',
notes: 'Pallet 2 contains fragile items',
external_reference: 'PO-0001',
unique_external_reference: true,
sell_ahead: false,
inventory_scope: 'd2c',
products: [
{sku: 'SKU-RED-M', quantity: 100, unit_value: '12.50'},
{
sku: 'SKU-BOX-BLUE',
quantity: 48,
lots: [
{lot_code: 'LOT-2026-01', quantity: 24, external_reference: 'LOT-REF-1'},
{lot_code: 'LOT-2026-02', quantity: 24, external_reference: 'LOT-REF-2'}
]
}
]
})
};
fetch('https://api.cubbo.com/v1/replenishments', 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.cubbo.com/v1/replenishments",
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([
'store_id' => 1234,
'warehouse_id' => 7,
'expected_arrived_at' => '2026-11-02T15:00:00Z',
'notes' => 'Pallet 2 contains fragile items',
'external_reference' => 'PO-0001',
'unique_external_reference' => true,
'sell_ahead' => false,
'inventory_scope' => 'd2c',
'products' => [
[
'sku' => 'SKU-RED-M',
'quantity' => 100,
'unit_value' => '12.50'
],
[
'sku' => 'SKU-BOX-BLUE',
'quantity' => 48,
'lots' => [
[
'lot_code' => 'LOT-2026-01',
'quantity' => 24,
'external_reference' => 'LOT-REF-1'
],
[
'lot_code' => 'LOT-2026-02',
'quantity' => 24,
'external_reference' => 'LOT-REF-2'
]
]
]
]
]),
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.cubbo.com/v1/replenishments"
payload := strings.NewReader("{\n \"store_id\": 1234,\n \"warehouse_id\": 7,\n \"expected_arrived_at\": \"2026-11-02T15:00:00Z\",\n \"notes\": \"Pallet 2 contains fragile items\",\n \"external_reference\": \"PO-0001\",\n \"unique_external_reference\": true,\n \"sell_ahead\": false,\n \"inventory_scope\": \"d2c\",\n \"products\": [\n {\n \"sku\": \"SKU-RED-M\",\n \"quantity\": 100,\n \"unit_value\": \"12.50\"\n },\n {\n \"sku\": \"SKU-BOX-BLUE\",\n \"quantity\": 48,\n \"lots\": [\n {\n \"lot_code\": \"LOT-2026-01\",\n \"quantity\": 24,\n \"external_reference\": \"LOT-REF-1\"\n },\n {\n \"lot_code\": \"LOT-2026-02\",\n \"quantity\": 24,\n \"external_reference\": \"LOT-REF-2\"\n }\n ]\n }\n ]\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.cubbo.com/v1/replenishments")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"store_id\": 1234,\n \"warehouse_id\": 7,\n \"expected_arrived_at\": \"2026-11-02T15:00:00Z\",\n \"notes\": \"Pallet 2 contains fragile items\",\n \"external_reference\": \"PO-0001\",\n \"unique_external_reference\": true,\n \"sell_ahead\": false,\n \"inventory_scope\": \"d2c\",\n \"products\": [\n {\n \"sku\": \"SKU-RED-M\",\n \"quantity\": 100,\n \"unit_value\": \"12.50\"\n },\n {\n \"sku\": \"SKU-BOX-BLUE\",\n \"quantity\": 48,\n \"lots\": [\n {\n \"lot_code\": \"LOT-2026-01\",\n \"quantity\": 24,\n \"external_reference\": \"LOT-REF-1\"\n },\n {\n \"lot_code\": \"LOT-2026-02\",\n \"quantity\": 24,\n \"external_reference\": \"LOT-REF-2\"\n }\n ]\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cubbo.com/v1/replenishments")
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 \"store_id\": 1234,\n \"warehouse_id\": 7,\n \"expected_arrived_at\": \"2026-11-02T15:00:00Z\",\n \"notes\": \"Pallet 2 contains fragile items\",\n \"external_reference\": \"PO-0001\",\n \"unique_external_reference\": true,\n \"sell_ahead\": false,\n \"inventory_scope\": \"d2c\",\n \"products\": [\n {\n \"sku\": \"SKU-RED-M\",\n \"quantity\": 100,\n \"unit_value\": \"12.50\"\n },\n {\n \"sku\": \"SKU-BOX-BLUE\",\n \"quantity\": 48,\n \"lots\": [\n {\n \"lot_code\": \"LOT-2026-01\",\n \"quantity\": 24,\n \"external_reference\": \"LOT-REF-1\"\n },\n {\n \"lot_code\": \"LOT-2026-02\",\n \"quantity\": 24,\n \"external_reference\": \"LOT-REF-2\"\n }\n ]\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": 55001,
"status": "REQUESTED",
"store_id": 1234,
"notes": "Pallet 2 contains fragile items",
"created_at": "2026-10-12T14:03:11.512Z",
"expected_arrived_at": "2026-11-02T15:00:00.000Z",
"sell_ahead": false,
"declared_value": null,
"warehouse_id": 7,
"replenishment_products": [
{
"product_id": 9001,
"expected_quantity": 100,
"unit_value": "12.5",
"product": {
"id": 9001,
"name": "Red T-shirt M",
"bar_code": "7501234567890",
"is_scannable": true,
"product_codes": [
{
"id": 31001,
"sku": "SKU-RED-M"
}
]
}
},
{
"product_id": 9002,
"expected_quantity": 48,
"unit_value": null,
"product": {
"id": 9002,
"name": "Blue box",
"bar_code": "7501234567891",
"is_scannable": true,
"product_codes": [
{
"id": 31002,
"sku": "SKU-BOX-BLUE"
}
]
}
}
],
"warehouse": {
"id": 7,
"name": "Mexico City",
"unique_code": "MX-CDMX-1",
"address1": "Av. Ejemplo 123",
"address2": null,
"zip_code": "01000",
"city": "Ciudad de México",
"state": "CDMX",
"country": "MX"
}
}Replenishments
Create a replenishment
Announces an inbound shipment (replenishment) of products to one of your store’s warehouses.
Every line is identified by SKU; all SKUs must already exist in your Cubbo catalog for the store.
The replenishment is created in status REQUESTED, or WITHOUT_SCHEDULING when the target
warehouse books receiving appointments natively (you then schedule the appointment separately;
the replenishment is not visible to the warehouse’s capacity planning until it is scheduled).
warehouse_idis optional; when omitted the store’s first assigned warehouse is used. When sent, the warehouse must be assigned to the store.- Each SKU may appear once. Two different SKUs that point to the same product are refused
(except for certain marketplace integrations, where such lines are merged into one and their quantities
are added; the first declared
unit_valueis kept, and two different declared values for the same product are refused). unit_value(declared unit cost in the store currency) is optional and must be a plain decimal with at most 2 decimal places, greater than 0 and below the supported ceiling. When omitted, Cubbo falls back to the catalog price wherever a cost is needed (for example on the Brazilian NF-e of entry).lotslets you declare, per SKU, the lots (batches) that will arrive and how many units belong to each. The lot quantities must add up to the line quantity, and the SKU must have a master-box configuration in Cubbo. These expected quantities per lot are what the variance report compares against.sell_ahead: truemakes the announced units sellable immediately (before they physically arrive). The warehouse must have a presale location configured; otherwise the request is refused and nothing is created. Sell-ahead replenishments cannot be updated afterwards.unique_external_reference: truemakes the call idempotent on(store_id, external_reference): if a non-canceled replenishment with that reference already exists in the store, the API answers 422 with codeREPLENISHMENT_ALREADY_EXISTSand the existingreplenishment_idinstead of creating a second one. Canceled replenishments do not count. Without the flag, repeated references are accepted (existing behavior).inventory_scope/is_b2bdecide which sales channel the received stock serves. Omit both to use the store’s business model (D2C-only stores receive asd2c, B2B-only asb2b, and stores with both models asshared). A scope incompatible with the store’s model is refused.- Brazil: if your store’s NF-e (Nota Fiscal eletrônica, the Brazilian fiscal invoice) for
inbound stock is issued by your own invoicing provider rather than by Cubbo, you must send
invoicewith the already-issued NF-e (XML and PDF, base64). If Cubbo issues the NF-e for your store, it is generated automatically after the replenishment is created; some marketplace-integrated stores need neither.
POST
/
replenishments
Create a replenishment
curl --request POST \
--url https://api.cubbo.com/v1/replenishments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"store_id": 1234,
"warehouse_id": 7,
"expected_arrived_at": "2026-11-02T15:00:00Z",
"notes": "Pallet 2 contains fragile items",
"external_reference": "PO-0001",
"unique_external_reference": true,
"sell_ahead": false,
"inventory_scope": "d2c",
"products": [
{
"sku": "SKU-RED-M",
"quantity": 100,
"unit_value": "12.50"
},
{
"sku": "SKU-BOX-BLUE",
"quantity": 48,
"lots": [
{
"lot_code": "LOT-2026-01",
"quantity": 24,
"external_reference": "LOT-REF-1"
},
{
"lot_code": "LOT-2026-02",
"quantity": 24,
"external_reference": "LOT-REF-2"
}
]
}
]
}
'import requests
url = "https://api.cubbo.com/v1/replenishments"
payload = {
"store_id": 1234,
"warehouse_id": 7,
"expected_arrived_at": "2026-11-02T15:00:00Z",
"notes": "Pallet 2 contains fragile items",
"external_reference": "PO-0001",
"unique_external_reference": True,
"sell_ahead": False,
"inventory_scope": "d2c",
"products": [
{
"sku": "SKU-RED-M",
"quantity": 100,
"unit_value": "12.50"
},
{
"sku": "SKU-BOX-BLUE",
"quantity": 48,
"lots": [
{
"lot_code": "LOT-2026-01",
"quantity": 24,
"external_reference": "LOT-REF-1"
},
{
"lot_code": "LOT-2026-02",
"quantity": 24,
"external_reference": "LOT-REF-2"
}
]
}
]
}
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({
store_id: 1234,
warehouse_id: 7,
expected_arrived_at: '2026-11-02T15:00:00Z',
notes: 'Pallet 2 contains fragile items',
external_reference: 'PO-0001',
unique_external_reference: true,
sell_ahead: false,
inventory_scope: 'd2c',
products: [
{sku: 'SKU-RED-M', quantity: 100, unit_value: '12.50'},
{
sku: 'SKU-BOX-BLUE',
quantity: 48,
lots: [
{lot_code: 'LOT-2026-01', quantity: 24, external_reference: 'LOT-REF-1'},
{lot_code: 'LOT-2026-02', quantity: 24, external_reference: 'LOT-REF-2'}
]
}
]
})
};
fetch('https://api.cubbo.com/v1/replenishments', 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.cubbo.com/v1/replenishments",
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([
'store_id' => 1234,
'warehouse_id' => 7,
'expected_arrived_at' => '2026-11-02T15:00:00Z',
'notes' => 'Pallet 2 contains fragile items',
'external_reference' => 'PO-0001',
'unique_external_reference' => true,
'sell_ahead' => false,
'inventory_scope' => 'd2c',
'products' => [
[
'sku' => 'SKU-RED-M',
'quantity' => 100,
'unit_value' => '12.50'
],
[
'sku' => 'SKU-BOX-BLUE',
'quantity' => 48,
'lots' => [
[
'lot_code' => 'LOT-2026-01',
'quantity' => 24,
'external_reference' => 'LOT-REF-1'
],
[
'lot_code' => 'LOT-2026-02',
'quantity' => 24,
'external_reference' => 'LOT-REF-2'
]
]
]
]
]),
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.cubbo.com/v1/replenishments"
payload := strings.NewReader("{\n \"store_id\": 1234,\n \"warehouse_id\": 7,\n \"expected_arrived_at\": \"2026-11-02T15:00:00Z\",\n \"notes\": \"Pallet 2 contains fragile items\",\n \"external_reference\": \"PO-0001\",\n \"unique_external_reference\": true,\n \"sell_ahead\": false,\n \"inventory_scope\": \"d2c\",\n \"products\": [\n {\n \"sku\": \"SKU-RED-M\",\n \"quantity\": 100,\n \"unit_value\": \"12.50\"\n },\n {\n \"sku\": \"SKU-BOX-BLUE\",\n \"quantity\": 48,\n \"lots\": [\n {\n \"lot_code\": \"LOT-2026-01\",\n \"quantity\": 24,\n \"external_reference\": \"LOT-REF-1\"\n },\n {\n \"lot_code\": \"LOT-2026-02\",\n \"quantity\": 24,\n \"external_reference\": \"LOT-REF-2\"\n }\n ]\n }\n ]\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.cubbo.com/v1/replenishments")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"store_id\": 1234,\n \"warehouse_id\": 7,\n \"expected_arrived_at\": \"2026-11-02T15:00:00Z\",\n \"notes\": \"Pallet 2 contains fragile items\",\n \"external_reference\": \"PO-0001\",\n \"unique_external_reference\": true,\n \"sell_ahead\": false,\n \"inventory_scope\": \"d2c\",\n \"products\": [\n {\n \"sku\": \"SKU-RED-M\",\n \"quantity\": 100,\n \"unit_value\": \"12.50\"\n },\n {\n \"sku\": \"SKU-BOX-BLUE\",\n \"quantity\": 48,\n \"lots\": [\n {\n \"lot_code\": \"LOT-2026-01\",\n \"quantity\": 24,\n \"external_reference\": \"LOT-REF-1\"\n },\n {\n \"lot_code\": \"LOT-2026-02\",\n \"quantity\": 24,\n \"external_reference\": \"LOT-REF-2\"\n }\n ]\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cubbo.com/v1/replenishments")
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 \"store_id\": 1234,\n \"warehouse_id\": 7,\n \"expected_arrived_at\": \"2026-11-02T15:00:00Z\",\n \"notes\": \"Pallet 2 contains fragile items\",\n \"external_reference\": \"PO-0001\",\n \"unique_external_reference\": true,\n \"sell_ahead\": false,\n \"inventory_scope\": \"d2c\",\n \"products\": [\n {\n \"sku\": \"SKU-RED-M\",\n \"quantity\": 100,\n \"unit_value\": \"12.50\"\n },\n {\n \"sku\": \"SKU-BOX-BLUE\",\n \"quantity\": 48,\n \"lots\": [\n {\n \"lot_code\": \"LOT-2026-01\",\n \"quantity\": 24,\n \"external_reference\": \"LOT-REF-1\"\n },\n {\n \"lot_code\": \"LOT-2026-02\",\n \"quantity\": 24,\n \"external_reference\": \"LOT-REF-2\"\n }\n ]\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": 55001,
"status": "REQUESTED",
"store_id": 1234,
"notes": "Pallet 2 contains fragile items",
"created_at": "2026-10-12T14:03:11.512Z",
"expected_arrived_at": "2026-11-02T15:00:00.000Z",
"sell_ahead": false,
"declared_value": null,
"warehouse_id": 7,
"replenishment_products": [
{
"product_id": 9001,
"expected_quantity": 100,
"unit_value": "12.5",
"product": {
"id": 9001,
"name": "Red T-shirt M",
"bar_code": "7501234567890",
"is_scannable": true,
"product_codes": [
{
"id": 31001,
"sku": "SKU-RED-M"
}
]
}
},
{
"product_id": 9002,
"expected_quantity": 48,
"unit_value": null,
"product": {
"id": 9002,
"name": "Blue box",
"bar_code": "7501234567891",
"is_scannable": true,
"product_codes": [
{
"id": 31002,
"sku": "SKU-BOX-BLUE"
}
]
}
}
],
"warehouse": {
"id": 7,
"name": "Mexico City",
"unique_code": "MX-CDMX-1",
"address1": "Av. Ejemplo 123",
"address2": null,
"zip_code": "01000",
"city": "Ciudad de México",
"state": "CDMX",
"country": "MX"
}
}Authorizations
Body
application/json
Response
Replenishment created
Replenishment as returned by create and update.
Lifecycle status of a replenishment.
WITHOUT_SCHEDULING: created at a warehouse that books receiving appointments natively, but no appointment has been scheduled yet.PENDING: registered but not yet requested to the warehouse (pre-arrival).REQUESTED: announced to the warehouse and awaiting arrival; the initial status at warehouses without native appointment scheduling, and the status after an appointment is booked.IN_TRANSIT: the shipment is on its way to the warehouse.RECEIVED: the shipment was recorded at the dock; counting has not started.PROCESSING: the warehouse is receiving and counting the units (stock has arrived).IN_PUTAWAY: received units are being placed in storage locations.COMPLETED: receiving and putaway finished;completed_atis set.CANCELED: the replenishment was canceled; it no longer counts for external-reference uniqueness.
Available options:
WITHOUT_SCHEDULING, PENDING, REQUESTED, IN_TRANSIT, RECEIVED, PROCESSING, IN_PUTAWAY, COMPLETED, CANCELED Example:
"REQUESTED"