> ## 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 Shipping Method

> Selects a shipping method for a specific shipment and recalculates cart totals

<Info>
  Select shipping methods at the shipment level, enabling different shipping speeds and costs for each shipment in a multi-shipment cart.
</Info>

<Note>
  **Default Selection**: When a cart is created or shipping information is set, Firmly automatically selects the cheapest available shipping method for each shipment. 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="shipping_method_id" type="string" required>
  Selected method ID from the shipment's `shipping_method_options`
</ParamField>

<ParamField body="notes" type="string">
  Special delivery instructions for this shipment
</ParamField>

<ParamField body="selected_date" type="string">
  For scheduled delivery, the selected date in YYYY-MM-DD format
</ParamField>

## Response

Returns the updated shopping cart with the selected shipping method applied.

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

  **Shipment Properties:**

  * `shipment_id` (string): Unique shipment identifier
  * `shipping_method` (object): Selected shipping method details
    * `id` (string): Method identifier
    * `description` (string): Method display name
    * `price` (object): Shipping cost for this method
    * `estimated_delivery` (string): Delivery time estimate
  * `notes` (string): Stored delivery instructions
  * `selected_date` (string): Selected delivery date (for scheduled delivery)
</ResponseField>

<ResponseField name="shipping_total" type="object">
  Updated total shipping cost across all shipments
</ResponseField>

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

## Shipping Method Types

<Warning>
  **Important**: Firmly does not standardize shipping method IDs or names. The values shown in examples are for illustration only. Each merchant defines their own shipping method IDs and descriptions, which Firmly exposes exactly as provided by the merchant's platform.
</Warning>

<Info>
  Available shipping methods are dynamic and depend on:

  * The merchant's shipping configuration
  * Shipment fulfillment type
  * Item characteristics and requirements
  * Destination address
  * Merchant-specific business rules
</Info>

### Example Method Patterns

These are common patterns you might encounter, but actual values will vary by merchant:

<Tabs>
  <Tab title="Standard Shipping Examples">
    * Ground shipping (e.g., "standard", "ground", "regular")
    * Express options (e.g., "2day", "express", "priority")
    * Overnight delivery (e.g., "overnight", "nextday", "1day")
    * Economy options (e.g., "economy", "basic", "saver")
  </Tab>

  <Tab title="Scheduled Delivery Examples">
    * Basic scheduled (merchant-defined names)
    * Premium time windows (merchant-defined)
    * White glove service (if offered)
    * Threshold delivery (if offered)
  </Tab>

  <Tab title="Store Pickup Examples">
    * In-store pickup (merchant-defined)
    * Curbside service (if available)
    * Locker pickup (if available)
  </Tab>
</Tabs>

## Examples

<CodeGroup>
  ```bash Standard Shipping theme={null}
  curl -X POST https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/shipment/methods \
    -H "x-firmly-authorization: <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "shipment_id": "shipment-12345",
      "shipping_method_id": "express-2day",
      "notes": "Please leave at front door if no answer"
    }'
  ```

  ```bash Scheduled Delivery theme={null}
  curl -X POST https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/shipment/methods \
    -H "x-firmly-authorization: <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "shipment_id": "furniture-shipment-001",
      "shipping_method_id": "white-glove-setup",
      "selected_date": "2024-03-15",
      "notes": "Please call 30 minutes before delivery"
    }'
  ```

  ```bash Curbside Pickup theme={null}
  curl -X POST https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/shipment/methods \
    -H "x-firmly-authorization: <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "shipment_id": "pickup-shipment-001",
      "shipping_method_id": "curbside",
      "notes": "Blue Honda Civic, license plate ABC123"
    }'
  ```
</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": "WS12-XS-Orange",
        "description": "Radiant Tee",
        "base_sku": "WS12",
        "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/radiant-tee.jpg",
          "alt": "Radiant Tee",
          "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 Shipping",
            "price": {
              "currency": "USD",
              "value": 9.99,
              "number": 999,
              "symbol": "$"
            },
            "estimated_delivery": "5-7 business days"
          },
          {
            "id": "express-2day",
            "description": "Express 2-Day Shipping",
            "price": {
              "currency": "USD",
              "value": 19.99,
              "number": 1999,
              "symbol": "$"
            },
            "estimated_delivery": "2 business days"
          }
        ],
        "shipping_method": {
          "id": "express-2day",
          "description": "Express 2-Day Shipping",
          "price": {
            "currency": "USD",
            "value": 19.99,
            "number": 1999,
            "symbol": "$"
          },
          "estimated_delivery": "2 business days"
        },
        "notes": "Please leave at front door if no answer"
      }
    ],
    "sub_total": {
      "currency": "USD",
      "value": 99.98,
      "number": 9998,
      "symbol": "$"
    },
    "shipping_total": {
      "currency": "USD",
      "value": 19.99,
      "number": 1999,
      "symbol": "$"
    },
    "tax_total": {
      "currency": "USD",
      "value": 9.60,
      "number": 960,
      "symbol": "$"
    },
    "total": {
      "currency": "USD",
      "value": 129.57,
      "number": 12957,
      "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}
  {
    "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"
        },
        "shipping_method": {
          "id": "EXPEDITED_2DAY",
          "description": "2-Day Express",
          "price": {
            "currency": "USD",
            "value": 19.99,
            "number": 1999,
            "symbol": "$"
          },
          "estimated_delivery": "2 business days"
        },
        "notes": "Please leave at front door if no answer"
      }
    ],
    "sub_total": {
      "currency": "USD",
      "value": 99.98,
      "number": 9998,
      "symbol": "$"
    },
    "shipping_total": {
      "currency": "USD",
      "value": 19.99,
      "number": 1999,
      "symbol": "$"
    },
    "total": {
      "currency": "USD",
      "value": 129.57,
      "number": 12957,
      "symbol": "$"
    }
  }
  ```
</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": {
          "id": "WHITE_GLOVE_DELIVERY",
          "description": "White Glove Delivery & Setup",
          "price": {
            "currency": "USD",
            "value": 199.99,
            "number": 19999,
            "symbol": "$"
          },
          "estimated_delivery": "Premium delivery with setup"
        },
        "selected_date": "2024-03-15",
        "selected_time_slot": null,
        "notes": "Please call 30 minutes before delivery"
      }
    ],
    "shipping_total": {
      "currency": "USD",
      "value": 199.99,
      "number": 19999,
      "symbol": "$"
    }
  }
  ```
</Accordion>

<Accordion title="Pickup Method 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"
          }
        },
        "shipping_method": {
          "id": "CURBSIDE_PICKUP",
          "description": "Curbside Pickup",
          "price": {
            "currency": "USD",
            "value": 0,
            "number": 0,
            "symbol": "$"
          },
          "estimated_delivery": "Available immediately"
        },
        "notes": "Blue Honda Civic, license plate ABC123"
      }
    ],
    "shipping_total": {
      "currency": "USD",
      "value": 0,
      "number": 0,
      "symbol": "$"
    }
  }
  ```
</Accordion>

## V2 Multi-Shipment Scenarios

<Info>
  V2's shipment-level method selection enables complex fulfillment scenarios where different items have different shipping speeds and costs.
</Info>

### Mixed Shipping Speeds

```javascript theme={null}
// Shipment 1: Rush delivery for urgent items
{
  "shipment_id": "urgent-items",
  "shipping_method_id": "overnight-express"  // Merchant's actual ID
}

// Shipment 2: Standard delivery for non-urgent items
{
  "shipment_id": "regular-items",
  "shipping_method_id": "ground-shipping"    // Merchant's actual ID
}
```

### Cost Optimization

```javascript theme={null}
// Heavy items: Special delivery option (if merchant offers)
{
  "shipment_id": "heavy-furniture",
  "shipping_method_id": "threshold-delivery"  // Merchant-specific ID
}

// Light items: Regular shipping
{
  "shipment_id": "accessories",
  "shipping_method_id": "standard"            // Merchant-specific ID
}
```

## Method Selection Process

<Steps>
  <Step title="Get Available Options">
    Use Get Cart to retrieve `shipping_method_options` for each shipment
  </Step>

  <Step title="Choose Method">
    Select an `id` from the available options based on cost/speed preference
  </Step>

  <Step title="Set Method">
    Call this endpoint with the selected `shipping_method_id`
  </Step>

  <Step title="Verify Selection">
    Check response for updated `shipping_method` and recalculated totals
  </Step>
</Steps>

## Behavior Notes

<Warning>
  * The `shipping_method_id` must exactly match an ID from the shipment's current `shipping_method_options`
  * Method IDs are case-sensitive and must match the merchant's values exactly
  * Available methods and their IDs are determined entirely by the merchant
  * Changing fulfillment type clears the selected shipping method
  * Shipping costs automatically recalculate for the entire cart
  * Date validation applies only to scheduled delivery fulfillment types
</Warning>

## Next Steps

After setting shipping methods:

1. **For Standard Shipping**: Proceed to set shipping address
2. **For Scheduled Delivery**: May need to select specific time slot
3. **For Pickup**: Confirm pickup time and proceed to checkout

## Error Codes

| Code | Description                                  |
| ---- | -------------------------------------------- |
| 400  | Invalid shipping method ID or request format |
| 401  | Invalid authentication token                 |
| 404  | Shipment not found                           |
| 422  | Invalid date or unprocessable data           |