Skip to main content
POST
/
api
/
v2
/
domains
/
{domain}
/
cart
/
shipments
/
fulfillment-type
Set Fulfillment Type
curl --request POST \
  --url https://api.firmly.work/api/v2/domains/{domain}/cart/shipments/fulfillment-type \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-firmly-authorization: <x-firmly-authorization>' \
  --data '
{
  "shipment_id": "<string>",
  "fulfillment_type": "<string>",
  "location_id": "<string>"
}
'
{
  "cart_id": "cart_01H2XVBR8C8JS5MQSFPJ8HF9SA",
  "platform_id": "shopify",
  "shop_id": "staging.luma.gift",
  "display_name": "Luma Store",
  "cart_status": "active",
  "line_items": [
    {
      "line_item_id": "item-12345",
      "platform_line_item_id": "0",
      "sku": "MH07-XS-Gray",
      "description": "Hero Hoodie",
      "base_sku": "MH07",
      "quantity": 2,
      "price": {
        "currency": "USD",
        "value": 49.99,
        "number": 4999,
        "symbol": "$"
      },
      "line_price": {
        "currency": "USD",
        "value": 99.98,
        "number": 9998,
        "symbol": "$"
      },
      "msrp": {
        "currency": "USD",
        "value": 49.99,
        "number": 4999,
        "symbol": "$"
      },
      "image": {
        "url": "https://cdn.staging.luma.gift/hero-hoodie.jpg",
        "alt": "Hero Hoodie",
        "type": "default"
      },
      "requires_shipping": true
    }
  ],
  "shipments": [
    {
      "shipment_id": "shipment-12345",
      "line_item_ids": ["item-12345"],
      "fulfillment_type": {
        "id": "SHIP_TO_ADDRESS",
        "name": "Ship to Address",
        "description": "Standard shipping to your address"
      },
      "fulfillment_type_options": [
        {
          "id": "SHIP_TO_ADDRESS",
          "name": "Ship to Address",
          "description": "Standard shipping to your address"
        },
        {
          "id": "SCHEDULED_DELIVERY",
          "name": "Scheduled Delivery",
          "description": "Choose a delivery date and time"
        }
      ],
      "shipping_method_options": [
        {
          "id": "STANDARD_GROUND",
          "description": "Standard Ground",
          "price": {
            "currency": "USD",
            "value": 9.99,
            "number": 999,
            "symbol": "$"
          },
          "estimated_delivery": "5-7 business days"
        },
        {
          "id": "EXPRESS_2DAY",
          "description": "2-Day Express",
          "price": {
            "currency": "USD",
            "value": 19.99,
            "number": 1999,
            "symbol": "$"
          },
          "estimated_delivery": "2 business days"
        }
      ],
      "shipping_method": null,
      "notes": ""
    }
  ],
  "sub_total": {
    "currency": "USD",
    "value": 99.98,
    "number": 9998,
    "symbol": "$"
  },
  "shipping_total": {
    "currency": "USD",
    "value": 0,
    "number": 0,
    "symbol": "$"
  },
  "tax_total": {
    "currency": "USD",
    "value": 8.00,
    "number": 800,
    "symbol": "$"
  },
  "total": {
    "currency": "USD",
    "value": 107.98,
    "number": 10798,
    "symbol": "$"
  },
  "addons": {
    "offers": [],
    "selections": []
  },
  "addon_total": {
    "currency": "USD",
    "value": 0,
    "number": 0,
    "symbol": "$"
  },
  "payment_method_options": [
    {
      "type": "CreditCard",
      "wallet": "user"
    },
    {
      "type": "PayPal",
      "wallet": "paypal"
    }
  ],
  "schema_version": "2.0"
}
Switch between fulfillment types at the shipment level. Each shipment exposes its available fulfillment types in the fulfillment_type_options array, and only these values can be set.
Default Selection: Firmly automatically selects a default fulfillment type when the cart is created. You only need to call this endpoint if you want to change from the default selection.

​
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
​
fulfillment_type
string
required
New fulfillment method. Must be one of the values from fulfillment_type_options in the shipment object.Common values include:
  • SHIP_TO_ADDRESS - Standard shipping to customer address
  • SCHEDULED_DELIVERY - Date/time-specific delivery
  • PICKUP_IN_STORE - Customer pickup at store location (if supported)
Important: Only fulfillment types listed in the shipment’s fulfillment_type_options array are valid. Attempting to set an unsupported fulfillment type will result in an error.
​
location_id
string
Required when fulfillment_type is PICKUP_IN_STORE. Store location identifier.

​
Response

Returns the updated shopping cart with the new fulfillment configuration.
​
shipments
array
Array of shipments with updated fulfillment typeShipment Properties:
  • shipment_id (string): Unique shipment identifier
  • fulfillment_type (object): Current fulfillment configuration
    • id (string): Fulfillment type identifier
    • name (string): Display name
    • description (string): Detailed description
  • fulfillment_type_options (array): Available fulfillment types for this shipment
  • shipping_method_options (array): Updated shipping methods based on new fulfillment type
  • selected_location (object): Store location details (for PICKUP_IN_STORE)
​
shipping_total
object
Updated shipping costs after fulfillment change
​
total
object
Updated cart total including new shipping costs

​
Important Notes

  • You can only set fulfillment types that are listed in the shipment’s fulfillment_type_options array
  • Changing fulfillment type clears previous selections including dates, time slots, and shipping methods
  • The cart automatically recalculates pricing based on the new fulfillment method
  • Not all merchants support all fulfillment types - check fulfillment_type_options first

​
State Transitions

From → ToCleared FieldsNew Options
Any → SHIP_TO_ADDRESSselected_location, selected_date, selected_time_slotStandard shipping methods
Any → SCHEDULED_DELIVERYselected_location, selected_date, selected_time_slotScheduled delivery methods
Any → PICKUP_IN_STOREselected_date, selected_time_slotPickup-specific options

​
Examples

​
First, Check Available Options

Always check what fulfillment types are available for a shipment before attempting to set one: 
// Get the cart and find available options
const cart = await getCart(domain);
const shipment = cart.shipments[0];

console.log('Current fulfillment type:', shipment.fulfillment_type.id);
console.log('Available options:');
shipment.fulfillment_type_options.forEach(option => {
  console.log(`- ${option.id}: ${option.name}`);
});

// Example output:
// Current fulfillment type: SHIP_TO_ADDRESS
// Available options:
// - SHIP_TO_ADDRESS: Ship to Address
// - SCHEDULED_DELIVERY: Scheduled Delivery

​
Setting Fulfillment Type

curl -X POST https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/shipments/fulfillment-type \
  -H "x-firmly-authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "shipment_id": "shipment-12345",
    "fulfillment_type": "SHIP_TO_ADDRESS"
  }'

{
  "cart_id": "cart_01H2XVBR8C8JS5MQSFPJ8HF9SA",
  "platform_id": "shopify",
  "shop_id": "staging.luma.gift",
  "display_name": "Luma Store",
  "cart_status": "active",
  "line_items": [
    {
      "line_item_id": "item-12345",
      "platform_line_item_id": "0",
      "sku": "MH07-XS-Gray",
      "description": "Hero Hoodie",
      "base_sku": "MH07",
      "quantity": 2,
      "price": {
        "currency": "USD",
        "value": 49.99,
        "number": 4999,
        "symbol": "$"
      },
      "line_price": {
        "currency": "USD",
        "value": 99.98,
        "number": 9998,
        "symbol": "$"
      },
      "msrp": {
        "currency": "USD",
        "value": 49.99,
        "number": 4999,
        "symbol": "$"
      },
      "image": {
        "url": "https://cdn.staging.luma.gift/hero-hoodie.jpg",
        "alt": "Hero Hoodie",
        "type": "default"
      },
      "requires_shipping": true
    }
  ],
  "shipments": [
    {
      "shipment_id": "shipment-12345",
      "line_item_ids": ["item-12345"],
      "fulfillment_type": {
        "id": "SHIP_TO_ADDRESS",
        "name": "Ship to Address",
        "description": "Standard shipping to your address"
      },
      "fulfillment_type_options": [
        {
          "id": "SHIP_TO_ADDRESS",
          "name": "Ship to Address",
          "description": "Standard shipping to your address"
        },
        {
          "id": "SCHEDULED_DELIVERY",
          "name": "Scheduled Delivery",
          "description": "Choose a delivery date and time"
        }
      ],
      "shipping_method_options": [
        {
          "id": "STANDARD_GROUND",
          "description": "Standard Ground",
          "price": {
            "currency": "USD",
            "value": 9.99,
            "number": 999,
            "symbol": "$"
          },
          "estimated_delivery": "5-7 business days"
        },
        {
          "id": "EXPRESS_2DAY",
          "description": "2-Day Express",
          "price": {
            "currency": "USD",
            "value": 19.99,
            "number": 1999,
            "symbol": "$"
          },
          "estimated_delivery": "2 business days"
        }
      ],
      "shipping_method": null,
      "notes": ""
    }
  ],
  "sub_total": {
    "currency": "USD",
    "value": 99.98,
    "number": 9998,
    "symbol": "$"
  },
  "shipping_total": {
    "currency": "USD",
    "value": 0,
    "number": 0,
    "symbol": "$"
  },
  "tax_total": {
    "currency": "USD",
    "value": 8.00,
    "number": 800,
    "symbol": "$"
  },
  "total": {
    "currency": "USD",
    "value": 107.98,
    "number": 10798,
    "symbol": "$"
  },
  "addons": {
    "offers": [],
    "selections": []
  },
  "addon_total": {
    "currency": "USD",
    "value": 0,
    "number": 0,
    "symbol": "$"
  },
  "payment_method_options": [
    {
      "type": "CreditCard",
      "wallet": "user"
    },
    {
      "type": "PayPal",
      "wallet": "paypal"
    }
  ],
  "schema_version": "2.0"
}

{
  "line_items": [
    {
      "line_item_id": "item-12345",
      "sku": "MH07-XS-Gray",
      "description": "Hero Hoodie",
      "quantity": 2,
      "price": {
        "currency": "USD",
        "value": 49.99,
        "number": 4999,
        "symbol": "$"
      }
    }
  ],
  "shipments": [
    {
      "shipment_id": "shipment-12345",
      "line_item_ids": ["item-12345"],
      "fulfillment_type": {
        "id": "SHIP_TO_ADDRESS",
        "name": "Ship to Address",
        "description": "Standard shipping to your address"
      },
      "fulfillment_type_options": [
        {
          "id": "SHIP_TO_ADDRESS",
          "name": "Ship to Address",
          "description": "Standard shipping to your address"
        },
        {
          "id": "SCHEDULED_DELIVERY",
          "name": "Scheduled Delivery",
          "description": "Choose a delivery date and time"
        }
      ],
      "shipping_method_options": [
        {
          "id": "STANDARD_GROUND",
          "description": "Standard Ground",
          "price": {
            "currency": "USD",
            "value": 9.99,
            "number": 999,
            "symbol": "$"
          },
          "estimated_delivery": "5-7 business days"
        },
        {
          "id": "EXPEDITED_2DAY",
          "description": "2-Day Express",
          "price": {
            "currency": "USD",
            "value": 19.99,
            "number": 1999,
            "symbol": "$"
          },
          "estimated_delivery": "2 business days"
        }
      ],
      "shipping_method": null,
      "notes": ""
    }
  ],
  "sub_total": {
    "currency": "USD",
    "value": 99.98,
    "number": 9998,
    "symbol": "$"
  },
  "shipping_total": {
    "currency": "USD",
    "value": 0,
    "number": 0,
    "symbol": "$"
  },
  "total": {
    "currency": "USD",
    "value": 99.98,
    "number": 9998,
    "symbol": "$"
  },
  "schema_version": "2.0"
}

{
  "shipments": [
    {
      "shipment_id": "furniture-shipment-001",
      "line_item_ids": ["furniture-item-1"],
      "fulfillment_type": {
        "id": "SCHEDULED_DELIVERY",
        "name": "Scheduled Delivery",
        "description": "Choose a delivery date and time"
      },
      "shipping_method_options": [
        {
          "id": "PREMIUM_SCHEDULED",
          "description": "Premium Delivery",
          "price": {
            "currency": "USD",
            "value": 150,
            "number": 15000,
            "symbol": "$"
          },
          "estimated_delivery": "Premium scheduled delivery"
        },
        {
          "id": "STANDARD_SCHEDULED",
          "description": "Standard Scheduled Delivery",
          "price": {
            "currency": "USD",
            "value": 75,
            "number": 7500,
            "symbol": "$"
          },
          "estimated_delivery": "Standard scheduled delivery"
        }
      ],
      "shipping_method": null,
      "selected_date": null,
      "selected_time_slot": null
    }
  ]
}

{
  "shipments": [
    {
      "shipment_id": "pickup-shipment-001",
      "line_item_ids": ["small-item-1"],
      "fulfillment_type": {
        "id": "PICKUP_IN_STORE",
        "name": "Store Pickup",
        "description": "Pick up your items at a nearby store"
      },
      "selected_location": {
        "location_id": "store-downtown-001",
        "name": "Downtown Store",
        "address": {
          "address1": "123 Main Street",
          "city": "Anytown",
          "state_or_province": "CA",
          "postal_code": "12345",
          "country": "US"
        },
        "phone": "555-123-4567",
        "operating_hours": [
          {
            "day": "monday",
            "hours": "9:00 AM - 9:00 PM"
          }
        ]
      },
      "shipping_method": null
    }
  ],
  "shipping_total": {
    "currency": "USD",
    "value": 0,
    "number": 0,
    "symbol": "$"
  }
}

​
V2 Multi-Shipment Features

Unlike V1 where fulfillment was cart-level, V2 enables each shipment to have its own fulfillment method. This supports scenarios like:
  • Heavy items with scheduled delivery while small items ship standard
  • Some items for pickup, others for delivery
  • Different delivery dates for different shipments

​
Common Scenarios

// Shipment 1: Furniture with scheduled delivery
{
  "shipment_id": "furniture-001",
  "fulfillment_type": "SCHEDULED_DELIVERY"
}

// Shipment 2: Accessories for store pickup
{
  "shipment_id": "accessories-001",
  "fulfillment_type": "PICKUP_IN_STORE",
  "location_id": "store-123"
}

​
Next Steps

After setting the fulfillment type:
  1. Check available options: Review fulfillment_type_options in the shipment to see what’s supported
  2. For SHIP_TO_ADDRESS: Set shipping method
  3. For SCHEDULED_DELIVERY: Get availability then set date/time
  4. For PICKUP_IN_STORE: Configure pickup location (if supported by merchant)

​
Error Codes

CodeDescription
400Invalid fulfillment type or missing required fields
401Invalid authentication token
404Shipment or location not found
422Unprocessable entity data