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

Fulfillment schemas

These three schemas describe how a cart is fulfilled: shipping to an address, BOPIS (buy online, pick up in store), or scheduled delivery. The FulfillmentType schema captures the high-level choice; ShippingMethod and PickupLocation describe the specific selection.

​​ FulfillmentType

Defines how items will be delivered to the customer.

  • id (string, required) — Fulfillment type identifier. Enum values:

    • SHIP_TO_ADDRESS — Standard shipping to address
    • SCHEDULED_DELIVERY — Delivery with date/time selection
    • PICKUP_IN_STORE — Customer pickup at store location

  • name (string, required) — Human-readable name for display.

  • description (string, required) — Detailed description of the fulfillment method.


{
  "id": "SHIP_TO_ADDRESS",
  "name": "Standard Delivery",
  "description": "Items will be shipped to your address"

}


{
  "id": "SCHEDULED_DELIVERY",
  "name": "White Glove Delivery",
  "description": "Schedule delivery date and time window"}


{"id": "PICKUP_IN_STORE",
  "name": "Store Pickup",
  "description": "Pick up at selected store location"

}

​​ ShippingMethod

A shipping option returned on the cart (in shipping_method_options[] and, once selected, shipping_method). See ShoppingCartV2.

  • id (string, required) — Unique shipping method identifier.

  • description (string, required) — Display name for the shipping option.

  • price (Amount) — Shipping cost. Required unless hide_price is true.

  • hide_price (boolean) — When true, the price is not shown to the buyer (and price may be omitted).

  • message (string) — Optional message shown alongside the option (for example, a free-shipping threshold note).

  • estimated_delivery (string) — Estimated delivery timeframe.


{
  "id": "express",
  "description": "Express Shipping",
  "price": {
    "value": 19.99,
    "currency": "USD"
  },
  "estimated_delivery": "1-2 business days"

}

​​ PickupLocation

Store location for in-store pickup.

  • location_id (string, required) — Unique location identifier.

  • name (string, required) — Store name.

  • address (AddressInfo, required) — Store address. See Common types → Address.

  • pickup_options (array, required) — Available pickup dates and their time slots.

    properties
    • date (string, required) — Pickup date.
    • time_slots (array, required) — Time slots available on the date. Each is a TimeSlot.

  • phone (string) — Store contact phone number.

  • operating_hours (array) — Store operating hours, one entry per day.

    properties
    • day (string, required) — Day of the week.
    • open_time (string, required) — Opening time.
    • close_time (string, required) — Closing time.
    • is_closed (boolean) — Whether the store is closed on this day.

  • distance (object) — Distance from the buyer to the store.

    properties
    • value (number, required) — Distance value.
    • unit (string, required) — Distance unit. One of miles, kilometers.
    • formatted (string, required) — Display-ready distance string.


{
  "location_id": "store_123",
  "name": "Downtown Store",
  "address": {
    "address1": "123 Main St",
    "city": "San Francisco",
    "state_or_province": "CA",
    "postal_code": "94105",
    "country": "US"
  },
  "phone": "(415) 555-0123",
  "operating_hours": [
    {
      "day": "Monday",
      "open_time": "09:00",
      "close_time": "18:00"
    },
    {
      "day": "Sunday",
      "open_time": "",
      "close_time": "",
      "is_closed": true
    }
  ],
  "distance": {
    "value": 2.4,
    "unit": "miles",
    "formatted": "2.4 mi"
  },
  "pickup_options": [
    {
      "date": "2024-02-15",
      "time_slots": [
        {
          "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"
        }
      ]
    }
  ]

}