curl --request POST \
  --url https://api.cubbo.com/v1/products \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "store_id": 1234,
  "name": "Widget Pro Black",
  "description": "<p>A professional-grade widget.</p>",
  "skus": [
    "SKU-RED-M"
  ],
  "upc": "7501234567890",
  "price": 99.99,
  "weight": 500,
  "weight_unit": "g",
  "length": 10,
  "width": 8,
  "height": 5,
  "dimension_unit": "cm",
  "is_fragile": false,
  "has_expiration": true,
  "freshness": 180,
  "tax_code": "3401.11.90",
  "origin": "NATIONAL"
}
'

{
  "id": 12345,
  "name": "Widget Pro Black",
  "billing_name": null,
  "description": "<p>A professional-grade widget.</p>",
  "has_imei": false,
  "is_fragile": false,
  "is_kit": false,
  "bar_code": "7501234567890",
  "is_dropshipping": false,
  "has_expiration": true,
  "freshness": 180,
  "is_scannable": true,
  "price": "99.99",
  "weight": 0.5,
  "product_codes": [
    {
      "id": 9001,
      "sku": "SKU-RED-M"
    }
  ]
}

Inventory

Create a product

Creates a product in a store, with its SKUs, barcode (UPC/EAN), logistics data (weight and dimensions) and fiscal data. Send a single product (skus + upc) or a product with variants (has_variants: true + variants[]), which creates one product per variant.

Barcode and SKU rules. Both the barcode (upc) and every SKU must be unique within the store, and a barcode may not reuse a value already registered as a SKU of another product (or the other way round). The request is rejected with 422 when any of them is already taken. SKUs are trimmed of surrounding whitespace.
Weight. weight is stored in kilograms. Send weight_unit: "g" (or "gr") to send grams; the value is converted to kg and the stored unit becomes kg. Any other unit is stored as sent, without conversion.
Dimensions. length, width and height must be between 0.01 and 999999.99; dimension_unit defaults to cm.
Dropshipping. is_dropshipping: true marks a product that Cubbo does not stock. It cannot be combined with has_variants.
Non-scannable (marketing) products. is_scannable: false requires a product_image and cannot be combined with has_variants.
Expiration. When has_expiration is true you must also send freshness (minimum shelf-life in days required at receiving), or the product fails validation.
Kits (bundles). This endpoint does not create kits: the created product always has is_kit: false. Kits are configured from the Cubbo app; their components are returned by GET /inventory as kit_childs.
Fiscal data (Brazil). tax_code is the product’s NCM code (Brazilian fiscal classification) or the id of an NCM configuration already registered in the store; an NCM that is not configured for the store is rejected. origin, extipi and fci_key feed the NF-e (Brazilian electronic invoice).
Variants. Each variant becomes an independent product named "<name> <variant name>", with its own skus and bar_code. The response is then an array of products in the full product format instead of a single product.
Concurrency. Two simultaneous requests for the same SKUs in the same store are de-duplicated: the second receives 202 Accepted while the first is still processing.
Integration accounts. For API users linked to certain marketplace integrations the endpoint behaves as an upsert by barcode: an existing barcode gets the new SKU added (or its name and weight updated when the SKU already exists), has_expiration is forced to true with a default freshness of 180 days, master_box_quantity registers the units per master box for the SKU, and a SKU that already belongs to another product can be migrated to the new product when migrate_sku is true or the store has automatic SKU migration enabled. Variants are not supported for these accounts, and weight_unit is required.

POST

products

curl --request POST \
  --url https://api.cubbo.com/v1/products \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "store_id": 1234,
  "name": "Widget Pro Black",
  "description": "<p>A professional-grade widget.</p>",
  "skus": [
    "SKU-RED-M"
  ],
  "upc": "7501234567890",
  "price": 99.99,
  "weight": 500,
  "weight_unit": "g",
  "length": 10,
  "width": 8,
  "height": 5,
  "dimension_unit": "cm",
  "is_fragile": false,
  "has_expiration": true,
  "freshness": 180,
  "tax_code": "3401.11.90",
  "origin": "NATIONAL"
}
'

{
  "id": 12345,
  "name": "Widget Pro Black",
  "billing_name": null,
  "description": "<p>A professional-grade widget.</p>",
  "has_imei": false,
  "is_fragile": false,
  "is_kit": false,
  "bar_code": "7501234567890",
  "is_dropshipping": false,
  "has_expiration": true,
  "freshness": 180,
  "is_scannable": true,
  "price": "99.99",
  "weight": 0.5,
  "product_codes": [
    {
      "id": 9001,
      "sku": "SKU-RED-M"
    }
  ]
}

Authorizations

Authorization

string

header

required

Token returned by POST /auth/token, sent as Authorization: Bearer <token>.

Body

application/json

Body of POST /products. skus and upc are required for a single product; variants is required when has_variants is true.

store_id

integer

required

Store to create the product in.

Example:

1234

name

string

required

Product name.

Example:

"Widget Pro Black"

description

string

Product description; HTML is allowed.

Example:

"<p>A professional-grade widget.</p>"

skus

string[]

SKUs of the product (single-product requests). Required unless has_variants is true. Each must be unique within the store.

Example:

["SKU-RED-M"]

upc

string

Barcode (UPC/EAN). Required unless has_variants is true. Must be unique within the store and must not match another product's SKU.

Example:

"7501234567890"

has_variants

boolean

default:false

Create one product per entry in variants instead of a single product.

Example:

false

options

object[]

Option axes of a variant product. Only with has_variants.

Show child attributes

variants

object[]

Variants to create. Required and non-empty when has_variants is true.

Show child attributes

is_fragile

boolean

default:false

Requires fragile handling.

Example:

false

is_dropshipping

boolean

default:false

Product fulfilled by dropshipping (Cubbo holds no stock). Not allowed with has_variants.

Example:

false

has_expiration

boolean

default:false

Stock is tracked by lot with expiration dates. Requires freshness.

Example:

true

freshness

integer | null

Minimum shelf life in days a lot must have when received. Required when has_expiration is true.

Example:

180

tax_code

string | null

Brazil only. NCM code of the product (for example 3401.11.90) or the id of an NCM configuration of the store. Must already be configured for the store.

Example:

"3401.11.90"

is_packageless

boolean

default:false

Ships without additional packaging.

Example:

false

has_imei

boolean

default:false

Each unit is identified by an IMEI.

Example:

false

requires_unit_code

boolean

default:false

Each unit is identified by a unique code (serial) that is scanned at receiving and picking.

Example:

false

product_image_url

string

Public URL of the product image to download and attach (PNG or JPEG).

Example:

"https://cdn.example.com/images/widget.png"

product_image

object

An image sent inline as base64. PNG or JPEG, at most 5 MB decoded; the base64 payload may not exceed 10485760 bytes.

Show child attributes

is_scannable

boolean

default:true

Units can be scanned at picking. Set to false for marketing inserts; then product_image is required and has_variants is not allowed.

Example:

true

price

number

default:0

Unit price. Up to 8 significant digits. A non-numeric value is stored as 0.

Example:

99.99

billing_name

string | null

Name printed on invoices, when different from name.

Example:

"Widget Pro - Black Edition"

origin

enum<string>

default:NATIONAL

Brazil only. Fiscal origin of the goods for the NF-e.

Available options:

NATIONAL,

FOREIGN_IMPORTED,

FOREIGN_ACQUIRED_INTERNALLY,

NATIONAL_40_70_IMPORTED,

NATIONAL_MANUFACTURED,

NATIONAL_0_40_IMPORTED,

FOREIGN_DIRECT_IMPORT,

FOREIGN_ACQUIRED_INTERNALLY_WITHOUT_NATIONAL_SIMILAR,

NATIONAL_70_IMPORTED

Example:

"NATIONAL"

extipi

string | null

Brazil only. IPI exception code (EX TIPI), 2 or 3 digits.

Example:

"001"

fci_key

string | null

Brazil only. FCI (import content form) key for the NF-e.

Example:

"00000000-0000-0000-0000-000000000000"

weight

number

Unit weight, in weight_unit. Stored in kilograms.

Example:

500

weight_unit

string

Unit of weight. g or gr is converted to kilograms; any other value (for example kg) is stored as sent. Required for certain marketplace integration accounts.

Example:

"g"

length

number

Package length in dimension_unit, between 0.01 and 999999.99.

Required range: 0.01 <= x <= 999999.99

Example:

10

width

number

Package width in dimension_unit, between 0.01 and 999999.99.

Required range: 0.01 <= x <= 999999.99

Example:

8

height

number

Package height in dimension_unit, between 0.01 and 999999.99.

Required range: 0.01 <= x <= 999999.99

Example:

5

dimension_unit

enum<string>

default:cm

Unit of the dimensions.

Available options:

cm,

mm,

in,

m

Example:

"cm"

master_box_quantity

integer | null

Certain marketplace integration accounts only. Units per master box for the SKU; registers or updates the master box configuration.

Required range: x >= 1

Example:

12

migrate_sku

boolean

default:false

Certain marketplace integration accounts only. When the SKU already belongs to another product of the store, move the SKU (with its lots, stock, open order lines and open replenishments) to the new product instead of failing.

Example:

false

Response

Product created. A single product returns one object; a has_variants request returns an array with one full product per variant.

object
object[]

The product returned by POST /products for a single (non-variant) request.

integer

required

Cubbo product id. Use it for PATCH /products/{id}.

Example:

12345

name

string

required

Product name.

Example:

"Widget Pro Black"

is_kit

boolean

required

Always false for products created through the API.

Example:

false

product_codes

object[]

required

SKUs registered for the product.

Show child attributes

billing_name

string | null

Name printed on invoices.

Example:

null

description

string | null

Product description.

Example:

"<p>A professional-grade widget.</p>"

has_imei

boolean

Each unit is identified by an IMEI.

Example:

false

is_fragile

boolean

Requires fragile handling.

Example:

false

bar_code

string | null

Barcode (UPC/EAN).

Example:

"7501234567890"

is_dropshipping

boolean

Fulfilled by dropshipping.

Example:

false

has_expiration

boolean | null

Stock is tracked by lot with expiration dates.

Example:

true

freshness

integer | null

Minimum shelf life in days at receiving.

Example:

180

is_scannable

boolean

Units can be scanned at picking.

Example:

true

price

string | null

Unit price, as a decimal string.

Example:

"99.99"

weight

number | null

Unit weight in kilograms (after conversion).

Example:

0.5

Authentication

Orders

Click and collect

Inventory

Lots

Shipping labels

Replenishments

Reports

Returns

Shipping methods

Stores

Webhooks

Create a product

Authorizations

Body

Response