Skip to main content
POST
/
api
/
v2
/
domains
/
{domain}
/
cart
/
shipments
/
get-availability
Get Availability
curl --request POST \
  --url https://api.firmly.work/api/v2/domains/{domain}/cart/shipments/get-availability \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-firmly-authorization: <x-firmly-authorization>' \
  --data '
{
  "shipment_id": "<string>"
}
'
{
  "shipment_id": "<string>",
  "fulfillment_type": {},
  "available_dates": [
    {}
  ],
  "delivery_windows": [
    {}
  ]
}
This endpoint is only available for shipments with SCHEDULED_DELIVERY fulfillment type. It returns available delivery dates and time slots for scheduling deliveries.

​
Request

​
domain
string
required
The merchant’s domain (e.g. staging.luma.gift)
​
x-firmly-authorization
string
required
Device authentication token for session identification
​
shipment_id
string
required
Target shipment identifier

​
Response

This endpoint only works for shipments that have been configured with SCHEDULED_DELIVERY fulfillment type. For other fulfillment types, this endpoint is not applicable.
​
shipment_id
string
The shipment identifier
​
fulfillment_type
object
Current fulfillment configuration (will always be SCHEDULED_DELIVERY)Properties:
  • id (string): Fulfillment type identifier: SCHEDULED_DELIVERY
  • name (string): Display name for the fulfillment type
  • description (string): Detailed description of the fulfillment method
​
available_dates
array
List of available delivery dates with time slotsDate Properties:
  • date (string): Date in YYYY-MM-DD format
  • description (string): Description of the delivery option
  • time_slots (array): Available time slots for this date
Time Slot Properties:
  • slot_id (string): Unique identifier for the time slot
  • start_time (string): Start time in 24-hour format (HH:MM)
  • end_time (string): End time in 24-hour format (HH:MM)
  • description (string): Human-readable description
  • available (boolean): Whether the slot is available for selection
​
delivery_windows
array
Premium delivery window options (if available)Properties:
  • window_id (string): Unique window identifier
  • name (string): Window display name
  • description (string): Detailed window description
  • price (object): Additional cost for this window
  • date_range (object): Available date range
    • start_date (string): First available date
    • end_date (string): Last available date

​
Example Request

curl -X POST https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/shipments/get-availability \
  -H "x-firmly-authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "shipment_id": "furniture-shipment-001"
  }'

​
Example Response

{
  "fulfillment_type": {
    "id": "SCHEDULED_DELIVERY",
    "name": "Scheduled Delivery",
    "description": "Choose a delivery date and time"
  },
  "available_dates": [
    {
      "date": "2024-03-15",
      "description": "Premium delivery available",
      "time_slots": [
        {
          "slot_id": "morning-premium",
          "start_time": "08:00",
          "end_time": "12:00",
          "description": "Morning premium delivery",
          "available": true
        }
      ]
    }
  ],
  "delivery_windows": [
    {
      "window_id": "premium-week",
      "name": "Premium Delivery Window",
      "description": "White glove delivery with setup",
      "price": {
        "currency": "USD",
        "value": 199.99,
        "number": 19999,
        "symbol": "$"
      },
      "date_range": {
        "start_date": "2024-03-15",
        "end_date": "2024-03-22"
      }
    }
  ]
}

​
Usage Pattern

This endpoint is specifically designed for scheduled delivery scenarios where customers need to select specific delivery dates and time slots.

​
Scheduled Delivery Flow

  1. Ensure shipment has SCHEDULED_DELIVERY fulfillment type set
  2. Call this endpoint to get available delivery dates and time slots
  3. Customer selects preferred delivery date and time slot
  4. Use Set Shipping Method with the selected date and slot
  5. Complete checkout with scheduled delivery information

​
Prerequisites

  • Shipment must already exist in the cart
  • Shipment must have SCHEDULED_DELIVERY fulfillment type configured
  • Shipping address must be set on the cart

​
Error Codes

CodeDescription
400Missing authentication header or invalid request body
401Invalid JWT token
404Shipment not found
422Unprocessable data in request
503Availability service temporarily unavailable