> ## Documentation Index
> Fetch the complete documentation index at: https://developers.firmly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Fulfillment Type

> Changes the fulfillment method for a specific shipment to one of the available options

<Info>
  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.
</Info>

<Note>
  **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.
</Note>

## Request

<ParamField path="domain" type="string" required>
  The merchant's domain (e.g. staging.luma.gift)
</ParamField>

<ParamField header="x-firmly-authorization" type="string" required>
  Device authentication token for session identification
</ParamField>

<ParamField body="shipment_id" type="string" required>
  Target shipment identifier
</ParamField>

<ParamField body="fulfillment_type" 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.
</ParamField>

<ParamField body="location_id" type="string">
  Required when `fulfillment_type` is `PICKUP_IN_STORE`. Store location identifier.
</ParamField>

## Response

Returns the updated shopping cart with the new fulfillment configuration.

<ResponseField name="shipments" type="array">
  Array of shipments with updated fulfillment type

  **Shipment 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)
</ResponseField>

<ResponseField name="shipping_total" type="object">
  Updated shipping costs after fulfillment change
</ResponseField>

<ResponseField name="total" type="object">
  Updated cart total including new shipping costs
</ResponseField>

## Important Notes

<Warning>
  * 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
</Warning>

### State Transitions

| From → To                  | Cleared Fields                                             | New Options                |
| -------------------------- | ---------------------------------------------------------- | -------------------------- |
| Any → `SHIP_TO_ADDRESS`    | `selected_location`, `selected_date`, `selected_time_slot` | Standard shipping methods  |
| Any → `SCHEDULED_DELIVERY` | `selected_location`, `selected_date`, `selected_time_slot` | Scheduled delivery methods |
| Any → `PICKUP_IN_STORE`    | `selected_date`, `selected_time_slot`                      | Pickup-specific options    |

## Examples

### First, Check Available Options

Always check what fulfillment types are available for a shipment before attempting to set one:

```javascript theme={null}
// 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

<CodeGroup>
  ```bash Switch to Standard Shipping theme={null}
  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"
    }'
  ```

  ```bash Switch to Scheduled Delivery theme={null}
  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": "furniture-shipment-001",
      "fulfillment_type": "SCHEDULED_DELIVERY"
    }'
  ```

  ```javascript Safe Fulfillment Type Switch theme={null}
  async function setFulfillmentTypeSafely(domain, shipmentId, desiredType) {
    // Get current cart state
    const cart = await getCart(domain);
    const shipment = cart.shipments.find(s => s.shipment_id === shipmentId);
    
    if (!shipment) {
      throw new Error('Shipment not found');
    }
    
    // Check if desired type is available
    const isAvailable = shipment.fulfillment_type_options.some(
      opt => opt.id === desiredType
    );
    
    if (!isAvailable) {
      const available = shipment.fulfillment_type_options
        .map(opt => opt.id)
        .join(', ');
      throw new Error(
        `Fulfillment type '${desiredType}' not available. ` +
        `Available types: ${available}`
      );
    }
    
    // Safe to set the fulfillment type
    return await fetch(
      `https://api.firmly.work/api/v2/domains/${domain}/cart/shipments/fulfillment-type`,
      {
        method: 'POST',
        headers: {
          'x-firmly-authorization': authToken,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          shipment_id: shipmentId,
          fulfillment_type: desiredType
        })
      }
    );
  }
  ```
</CodeGroup>

<ResponseExample>
  ```json theme={null}
  {
    "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"
  }
  ```
</ResponseExample>

<Accordion title="Standard Shipping Response">
  ```json theme={null}
  {
    "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"
  }
  ```
</Accordion>

<Accordion title="Scheduled Delivery Response">
  ```json theme={null}
  {
    "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
      }
    ]
  }
  ```
</Accordion>

<Accordion title="Store Pickup Response">
  ```json theme={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": "$"
    }
  }
  ```
</Accordion>

## V2 Multi-Shipment Features

<Info>
  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
</Info>

### Common Scenarios

<Tabs>
  <Tab title="Mixed Fulfillment">
    ```javascript theme={null}
    // 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"
    }
    ```
  </Tab>

  <Tab title="Multi-Location Pickup">
    ```javascript theme={null}
    // Different items from different stores
    {
      "shipment_id": "electronics-001",
      "fulfillment_type": "PICKUP_IN_STORE",
      "location_id": "store-north"
    }

    {
      "shipment_id": "clothing-001",
      "fulfillment_type": "PICKUP_IN_STORE",
      "location_id": "store-south"
    }
    ```
  </Tab>
</Tabs>

## 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](/api-reference/shipment-configuration/set-shipping-method)
3. **`For SCHEDULED_DELIVERY`**: [Get availability](/api-reference/shipment-configuration/get-availability) then set date/time
4. **`For PICKUP_IN_STORE`**: Configure pickup location (if supported by merchant)

## Error Codes

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