Docs
Firmly Agentic Commerce
Docs
Set theme to dark (⇧+D)
  1. Docs
  2. Resources
  3. Schemas
  4. Shipment schema

Shipment schema

When a cart contains items that ship from different warehouses or have different fulfillment timelines, Firmly groups them into shipments. Each shipment has its own shipment_id for availability and method selection. See Shipping & Fulfillment.

​​ Shipment

Represents a group of items with the same fulfillment method.

  • shipment_id (string, required) — Unique shipment identifier (UUID). Echo it back exactly as returned when calling Set Fulfillment Type, Set Shipping Method, or Get Availability. The request side accepts any non-empty string, so treat the value as opaque rather than parsing it.

  • fulfillment_type (FulfillmentType, required) — Current fulfillment method for this shipment

  • fulfillment_type_options (array) — Available fulfillment options for these items

    properties
    • FulfillmentType (object) — See FulfillmentType schema

  • line_item_ids (array, required) — Array of line item IDs in this shipment

  • shipping_method_options (array) — Available shipping methods (for SHIP_TO_ADDRESS)

    properties
    • ShippingMethod (object) — See ShippingMethod schema

  • shipping_method (ShippingMethod) — Selected shipping method

  • selected_location (PickupLocation) — Selected store for pickup (PICKUP_IN_STORE)

  • selected_date (string) — Selected delivery/pickup date (YYYY-MM-DD)

  • selected_time_slot (TimeSlot) — Selected time window for delivery/pickup

  • notes (string) — Delivery instructions or special requests


{
  "shipment_id": "f05a8032-9bc5-8e50-d672-9bfa7253485e",
  "fulfillment_type": {
    "id": "SHIP_TO_ADDRESS",
    "name": "Standard Delivery",
    "description": "Ship to customer address"
  },
  "line_item_ids": ["cfc9f563-f860-237d-9a0c-d8970ee710f6", "bb00bef1-df27-b9a2-fed9-3bac13b1893f"],
  "shipping_method_options": [
    {
      "id": "standard",
      "description": "Standard Shipping (5-7 days)",
      "price": {
        "value": 5.99,
        "currency": "USD"
      }
    }
  ],
  "shipping_method": {
    "id": "standard",
    "description": "Standard Shipping (5-7 days)",
    "price": {
      "value": 5.99,
      "currency": "USD"
    }
  }

}
    ```

{
  "shipment_id": "ee74829d-e8b1-a875-38be-5e70b1b5a9f1",
  "fulfillment_type": {
    "id": "SCHEDULED_DELIVERY",
    "name": "Scheduled Delivery",
    "description": "Choose delivery date and time"
  },
  "line_item_ids": ["5fa6a3db-b4a7-c9da-fa93-562f13c27e6e"],
  "selected_date": "2024-02-15",
  "selected_time_slot": {
    "slot_id": "morning",
    "start_time": {
      "utc": "2024-02-15T17:00:00Z",
      "local": "2024-02-15T09:00:00",
      "local_timezone": "America/Los_Angeles"
    },
    "end_time": {
      "utc": "2024-02-15T20:00:00Z",
      "local": "2024-02-15T12:00:00",
      "local_timezone": "America/Los_Angeles"
    },
    "description": "9:00 AM - 12:00 PM"
  }

}
    ```