Quickstart

This walkthrough takes you from credentials to a created order.

Prerequisites

A test store. Contact Cubbo’s support team or your account manager to create it. Run this quickstart there, never in your production account.
The client_id and client_secret of an Open API integration created in the Cubbo app. See Set up your integration.
The store_id of your test store. The app shows it under Authorized Stores when you create the integration.
At least one shipping method mapped in the integration. Its name is the shipping_line_code you send with the order.

Steps

Get a token

Exchange your credentials for a bearer token. Tokens last up to 24 hours (expires_in, in seconds). Cache the token and reuse it until it expires: do not request a new one per call.

curl -X POST https://api.cubbo.com/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "expires_in": 86400
  }'

{
  "token": "<token>",
  "expires_in": 86400,
  "type": "Bearer"
}

Create a product

Register the product you will sell. skus and the barcode (upc) must be unique in the store. Send the weight and dimensions so Cubbo can choose the right package and quote shipping. Grams are converted to kilograms.

curl -X POST https://api.cubbo.com/v1/products \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "store_id": 1234,
    "name": "Red T-shirt M",
    "skus": ["SKU-RED-M"],
    "upc": "7501234567890",
    "price": 299.00,
    "weight": 250,
    "weight_unit": "g",
    "length": 30,
    "width": 25,
    "height": 3,
    "dimension_unit": "cm"
  }'

{
  "id": 12345,
  "name": "Red T-shirt M",
  "bar_code": "7501234567890",
  "is_kit": false,
  "price": "299.0",
  "weight": 0.25,
  "product_codes": [{ "id": 9001, "sku": "SKU-RED-M" }]
}

Every field is described in Create a product.

Check the inventory

List the store’s inventory and confirm the SKU appears.

curl "https://api.cubbo.com/v1/inventory?store_id=1234&sku=SKU-RED-M" \
  -H "Authorization: Bearer <token>"

A new product has no stock until the warehouse receives it. Send it with a replenishment (POST /v1/replenishments). An order for a product without stock waits in backorder until stock arrives.

Create an order

Send the buyer’s shipping address and the products to ship. order_number is your own reference and must be unique within the store.

curl -X POST https://api.cubbo.com/v1/orders \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "store_id": 1234,
    "order_number": "ORD-0001",
    "shipping_line_code": "standard",
    "shipping": {
      "first_name": "Ana",
      "last_name": "Pérez",
      "phone": "+525512345678",
      "email": "buyer@example.com",
      "address1": "Av. Insurgentes Sur 1000",
      "number": "1000",
      "city": "Ciudad de México",
      "province": "CDMX",
      "zip_code": "03100",
      "country": "MX"
    },
    "products": [
      { "sku": "SKU-RED-M", "quantity": 2 }
    ]
  }'

The response is the created order, including its Cubbo id and its status.

Follow the order

Poll GET /v1/orders?store_id=1234&order_number=ORD-0001, or configure a webhook and let Cubbo notify you when the order is fulfilled or its shipment changes.

Next steps

Authentication

Token lifetime, store access and how unauthorized requests fail.

Create an order

Every field you can send with an order.

Errors

Status codes and the error body.

Webhooks

Events, payloads and signature verification.

Getting started

Working with the API

Events

Prerequisites

Steps

Next steps

Authentication

Create an order

Errors

Webhooks