Set Shipping Method - Firmly API

POST

api

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:

Standard Shipping Examples
Scheduled Delivery Examples
Store Pickup 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”)

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

Standard Shipping Response

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

Scheduled Delivery Response

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

Pickup Method Response

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

Get Available Options

Use Get Cart to retrieve shipping_method_options for each shipment

Choose Method

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

Set Method

Call this endpoint with the selected shipping_method_id

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:

For Standard Shipping: Proceed to set shipping address
For Scheduled Delivery: May need to select specific time slot
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

Get AvailabilityRetrieves available delivery dates and time slots for scheduled delivery shipments

⌘I

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

​Request

​Response

​Shipping Method Types

​Example Method Patterns

​Examples

​V2 Multi-Shipment Scenarios

​Mixed Shipping Speeds

​Cost Optimization

​Method Selection Process

​Behavior Notes

​Next Steps

​Error Codes

Request

Response

Shipping Method Types

Example Method Patterns

Examples

V2 Multi-Shipment Scenarios

Mixed Shipping Speeds

Cost Optimization

Method Selection Process

Behavior Notes

Next Steps

Error Codes