Get Availability

POST

api

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>"
}
'

import requests

url = "https://api.firmly.work/api/v2/domains/{domain}/cart/shipments/get-availability"

payload = { "shipment_id": "<string>" }
headers = {
    "x-firmly-authorization": "<x-firmly-authorization>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-firmly-authorization': '<x-firmly-authorization>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({shipment_id: '<string>'})
};

fetch('https://api.firmly.work/api/v2/domains/{domain}/cart/shipments/get-availability', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.firmly.work/api/v2/domains/{domain}/cart/shipments/get-availability",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'shipment_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-firmly-authorization: <x-firmly-authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.firmly.work/api/v2/domains/{domain}/cart/shipments/get-availability"

	payload := strings.NewReader("{\n  \"shipment_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-firmly-authorization", "<x-firmly-authorization>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.firmly.work/api/v2/domains/{domain}/cart/shipments/get-availability")
  .header("x-firmly-authorization", "<x-firmly-authorization>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"shipment_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.firmly.work/api/v2/domains/{domain}/cart/shipments/get-availability")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-firmly-authorization"] = '<x-firmly-authorization>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"shipment_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "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

string

required

The merchant’s domain (e.g. staging.luma.gift)

string

required

Device authentication token for session identification

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.

string

The shipment identifier

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

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

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

Ensure shipment has SCHEDULED_DELIVERY fulfillment type set
Call this endpoint to get available delivery dates and time slots
Customer selects preferred delivery date and time slot
Use Set Shipping Method with the selected date and slot
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

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

⌘I

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>"
}
'

import requests

url = "https://api.firmly.work/api/v2/domains/{domain}/cart/shipments/get-availability"

payload = { "shipment_id": "<string>" }
headers = {
    "x-firmly-authorization": "<x-firmly-authorization>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-firmly-authorization': '<x-firmly-authorization>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({shipment_id: '<string>'})
};

fetch('https://api.firmly.work/api/v2/domains/{domain}/cart/shipments/get-availability', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.firmly.work/api/v2/domains/{domain}/cart/shipments/get-availability",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'shipment_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-firmly-authorization: <x-firmly-authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.firmly.work/api/v2/domains/{domain}/cart/shipments/get-availability"

	payload := strings.NewReader("{\n  \"shipment_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-firmly-authorization", "<x-firmly-authorization>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.firmly.work/api/v2/domains/{domain}/cart/shipments/get-availability")
  .header("x-firmly-authorization", "<x-firmly-authorization>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"shipment_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.firmly.work/api/v2/domains/{domain}/cart/shipments/get-availability")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-firmly-authorization"] = '<x-firmly-authorization>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"shipment_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "shipment_id": "<string>",
  "fulfillment_type": {},
  "available_dates": [
    {}
  ],
  "delivery_windows": [
    {}
  ]
}

Home

Core Concepts

Implementation Guides

Ask Agent SDK

API Reference

firmly Connect

Resources

Request

Response

Example Request

Example Response

Usage Pattern

Scheduled Delivery Flow

Prerequisites

Error Codes

​Request

​Response

​Example Request

​Example Response

​Usage Pattern

​Scheduled Delivery Flow

​Prerequisites

​Error Codes

Request

Response

Example Request

Example Response

Usage Pattern

Scheduled Delivery Flow

Prerequisites

Error Codes