Container Booking & Fulfillment Guide

This guide walks through quoting a container, booking it, and following it from the loading dock to orbit.

Real-time Webhook Updates

When a booking changes status from pending to confirmed and in-transit, Cosmo Cargo emits a booking.status_updated webhook event to your registered endpoint.

Fulfillment Steps

1. Request a Quote
Before booking, price the container for your route and delivery speed with POST /containers/quote. Quotes include the shield rating and handling surcharges for refrigerated, pressurized and hazmat cargo.

2. Book the Container

Send a POST /containers/book request with the container, the route, the delivery speed, who to notify, and how to pay:

cURL
JavaScript

curl -X POST https://api.cosmocargo.space/v2/containers/book \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "container": {
      "type": "standard",
      "stackable": true,
      "dimensions": { "length": 12000, "width": 2400, "height": 2600 },
      "maxWeight": 28000
    },
    "route": { "origin": "EARTH-LEO-1", "destination": "MARS-OLYMPUS" },
    "deliverySpeed": { "type": "standard-orbit", "estimatedDays": 21 },
    "customer": {
      "name": "Ares Mining Co.",
      "contactInfo": { "notifications": [{ "type": "email", "email": "ops@ares.example" }] }
    },
    "payment": {
      "type": "galactic-credits",
      "accountNumber": "GC-000123456789",
      "amount": 48250,
      "currencyCode": "GCR"
    }
  }'

const response = await fetch("https://api.cosmocargo.space/v2/containers/book", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    container: {
      type: "standard",
      stackable: true,
      dimensions: { length: 12000, width: 2400, height: 2600 },
      maxWeight: 28000
    },
    route: { origin: "EARTH-LEO-1", destination: "MARS-OLYMPUS" },
    deliverySpeed: { type: "standard-orbit", estimatedDays: 21 },
    customer: {
      name: "Ares Mining Co.",
      contactInfo: { notifications: [{ type: "email", email: "ops@ares.example" }] }
    },
    payment: {
      type: "galactic-credits",
      accountNumber: "GC-000123456789",
      amount: 48250,
      currencyCode: "GCR"
    }
  })
});
const booking = await response.json();
console.log("Booked container:", booking.bookingId);

3. Loading and Launch
The dock crew seals the container and assigns it a cargo bay. At launch the booking moves to in-transit, and GET /containers/{containerId} returns its live position.

Interactive Endpoint Preview

Test this endpoint live in the interactive console below:

Bay Holds

Bookings in pending status hold a cargo bay for up to 10 minutes. If payment is not confirmed within that window, the booking expires and the bay is released.