Examples

Each SDK ships a runnable examples/ folder. These are the flows most integrations need.

warning

The order examples create and cancel real orders in the environment you point them at. Run them against dev.

Order lifecycle

Validate, create, check status, mark ready and cancel, handling the errors you are most likely to see.

TypeScript

import { CargoApiError, CargoClient } from "@rappi_cargo/cargo-core-api-sdk";

const client = new CargoClient({ apiKey: process.env.CARGO_API_KEY!, environment: "dev" });

try {
  await client.orderV3.validateOrder(order);

  const created = await client.orderV3.createOrder(order);
  const rappiOrderId = created.rappi_order_id;
  if (rappiOrderId === undefined) throw new Error("No rappi_order_id returned");

  const status = await client.orderV3.getOrderStatus({ rappi_order_id: rappiOrderId });
  console.log(status.state);

  await client.orderV3.markOrderReady({ rappi_order_id: rappiOrderId });
  await client.orderV3.cancelOrder({ rappi_order_id: rappiOrderId });
} catch (err) {
  if (err instanceof CargoApiError) {
    if (err.code === "ALREADY_EXTERNAL_ORDER_ID") console.error("Use a new order_id");
    else if (err.code === "COVERAGE_VALIDATION") console.error("Outside coverage");
    else console.error(err.status, err.code, err.message);
  } else {
    throw err;
  }
}

Python

import os
from cargo_core_api_sdk import CargoApiError, CargoClient

with CargoClient(api_key=os.environ["CARGO_API_KEY"], environment="dev") as client:
    try:
        client.order_v3.validate_order(order)

        created = client.order_v3.create_order(order)
        rappi_order_id = created["rappi_order_id"]

        status = client.order_v3.get_order_status({"rappi_order_id": rappi_order_id})
        print(status["state"])

        client.order_v3.mark_order_ready(rappi_order_id)
        client.order_v3.cancel_order({"rappi_order_id": rappi_order_id})
    except CargoApiError as err:
        if err.code == "ALREADY_EXTERNAL_ORDER_ID":
            print("Use a new order_id")
        elif err.code == "COVERAGE_VALIDATION":
            print("Outside coverage")
        else:
            print(err.status, err.code, err)

Duplicate an order

Repeat a delivery (same stores, client, products and options) without rebuilding the payload: fetch the body of the original order and send it back to createOrder. The fetched body has order_id removed and parent_order_id set to the original order, and you can change anything you need before sending it (products, tip, deliver_at, ...).

TypeScript

const { body } = await client.orderV3.getOrderCreationBody({ rappi_order_id: 123 });

const duplicate = await client.orderV3.createOrder({ ...body, deliver_at: "2026-10-08T15:00:00Z" });
console.log(duplicate.rappi_order_id);

Python

original = client.order_v3.get_order_creation_body(123)

duplicate = client.order_v3.create_order({**original["body"], "deliver_at": "2026-10-08T15:00:00Z"})
print(duplicate["rappi_order_id"])

A create body carries either order_id (a new order) or parent_order_id (a duplicate), never both.

Register a store and read its checkin code

TypeScript

const store = await client.pickingPoints.createPickingPoint({
  lat: 4.60971,
  lng: -74.08175,
  address: "Carrera 123 #12 - 1",
  city: "Bogota",
  phone: "31212345567",
  name: "Restaurante laureles",
  contact_name: "Julian",
  contact_email: "julian@example.com",
  preparation_time: 30,
});

const refreshed = await client.pickingPoints.refreshCheckinCode({ p: String(store.external_id) });
console.log(refreshed.checkin.code);

Python

store = client.picking_points.create_picking_point(
    {
        "lat": 4.60971,
        "lng": -74.08175,
        "address": "Carrera 123 #12 - 1",
        "city": "Bogota",
        "phone": "31212345567",
        "name": "Restaurante laureles",
        "contact_name": "Julian",
        "contact_email": "julian@example.com",
        "preparation_time": 30,
    }
)

refreshed = client.picking_points.refresh_checkin_code({"p": str(store["external_id"])})
print(refreshed["checkin"]["code"])

Create a user with a role

TypeScript

const [role] = await client.authorization.listPermissionGroups();

await client.users.createUser({
  user_enabled: true,
  email: "julian@example.com",
  password: "Passw0rd?",
  confirm_password: "Passw0rd?",
  name: "Julian",
  phone: "3011234567",
  permission_group_id: role.id,
});

Python

role = client.authorization.list_permission_groups()[0]

client.users.create_user(
    {
        "user_enabled": True,
        "email": "julian@example.com",
        "password": "Passw0rd?",
        "confirm_password": "Passw0rd?",
        "name": "Julian",
        "phone": "3011234567",
        "permission_group_id": role["id"],
    }
)

Clear the debt of a returned cash order

TypeScript

try {
  await client.rt.confirmOrderReturn({ rappi_order_id: 123 });
} catch (err) {
  if (err instanceof CargoApiError && err.code === "ORDER_WITH_WRONG_DEBT") {
    // The debt is still being settled. Retry in a few seconds.
  } else {
    throw err; // invalid token, unknown order, network failure: don't hide them
  }
}

Python

try:
    client.rt.confirm_order_return(123)
except CargoApiError as err:
    if err.code == "ORDER_WITH_WRONG_DEBT":
        ...  # The debt is still being settled. Retry in a few seconds.
    else:
        raise  # invalid token, unknown order...: don't hide them