Skip to main content
POST
https://api.firmly.work
/
api
/
v2
/
domains
/
{domain}
/
cart
/
shipment
/
methods
Set Shipping Method
curl --request POST \
  --url https://api.firmly.work/api/v2/domains/{domain}/cart/shipment/methods \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-firmly-authorization: <x-firmly-authorization>' \
  --data '
{
  "shipment_id": "<string>",
  "shipping_method_id": "<string>",
  "notes": "<string>",
  "selected_date": "<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": "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"
}
Select shipping methods at the shipment level, enabling different shipping speeds and costs for each shipment in a multi-shipment cart.
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.

​
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
​
shipping_method_id
string
required
Selected method ID from the shipment’s shipping_method_options
​
notes
string
Special delivery instructions for this shipment
​
selected_date
string
For scheduled delivery, the selected date in YYYY-MM-DD format

​
Response

Returns the updated shopping cart with the selected shipping method applied.
​
shipments
array
Array of shipments with updated shipping methodShipment 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)
​
shipping_total
object
Updated total shipping cost across all shipments
​
total
object
Updated cart total including new shipping costs

​
Shipping Method Types

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

​
Example Method Patterns

These are common patterns you might encounter, but actual values will vary by merchant:
  • 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”)

​
Examples

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

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

{
  "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": "$"
  }
}

{
  "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": "$"
  }
}

{
  "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": "$"
  }
}

​
V2 Multi-Shipment Scenarios

V2’s shipment-level method selection enables complex fulfillment scenarios where different items have different shipping speeds and costs.

​
Mixed Shipping Speeds

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

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

1

Get Available Options

Use Get Cart to retrieve shipping_method_options for each shipment
2

Choose Method

Select an id from the available options based on cost/speed preference
3

Set Method

Call this endpoint with the selected shipping_method_id
4

Verify Selection

Check response for updated shipping_method and recalculated totals

​
Behavior Notes

  • 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

​
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

CodeDescription
400Invalid shipping method ID or request format
401Invalid authentication token
404Shipment not found
422Invalid date or unprocessable data