Docs
Firmly Agentic Commerce
Docs
Set theme to dark (⇧+D)
  1. Docs
  2. API Reference
  3. Shipment Configuration
  4. Get Shipping Methods

Get Shipping Methods

GET https://api.firmly.work/api/v1/domains/{domain}/cart/shipping-rates

Returns the list of shipping methods available for the cart, with their prices and estimated delivery timeframes. This is the v1 way to read shipping methods as a standalone call.

​​ Authentication

  • x-firmly-authorization (string, required) — Device access token from Browser Session

​​ Path Parameters

  • domain (string, required) — The merchant’s domain (e.g. staging.luma.gift).

​​ Response

Returns a JSON array of shipping-method objects.

  • sku (string, required) — Shipping-method identifier. Use this value to select the method. (This is the method’s sku; on the v2 surface the equivalent identifier is shipping_method.id.)

  • description (string, required) — Human-readable name of the shipping method (e.g. “Standard Shipping (5–7 days)”).

  • price (object, required) — Cost of the shipping method. Amount object.

    Amount properties
    • currency (string) — Currency code (e.g. USD).
    • value (number) — Price as a decimal.
    • number (number) — Price in the smallest currency unit.
    • symbol (string) — Currency symbol.

  • estimated_delivery (string) — Optional delivery timeframe (e.g. “3–5 business days”).

​​ Example Request 


curl --request GET \
  --url https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/shipping-rates \
  --header 'x-firmly-authorization: YOUR_TOKEN'

​​ Response Example 


[
  {
    "sku": "standard",
    "description": "Standard Shipping (5-7 days)",
    "price": { "currency": "USD", "value": 5.99, "number": 599, "symbol": "$" },
    "estimated_delivery": "5-7 business days"
  },
  {
    "sku": "express",
    "description": "Express Shipping (2-3 days)",
    "price": { "currency": "USD", "value": 14.99, "number": 1499, "symbol": "$" },
    "estimated_delivery": "2-3 business days"
  }

]

​​ Error Responses

Errors return a JSON body with code, error, and description. Program against the error value — descriptions are human-readable and may change.

400 — MissingAuthHeader

The x-firmly-authorization header is missing or empty.


{ "code": 400, "error": "MissingAuthHeader", "description": "x-firmly-authorization header is missing or invalid." }
400 — InvalidToken

The authorization token is not a valid JWT structure.


{ "code": 400, "error": "InvalidToken", "description": "Jwt token is invalid." }
401 — InvalidJWTToken

The device JWT signature does not verify, or required claims are missing.


{ "code": 401, "error": "InvalidJWTToken", "description": "Jwt token is invalid." }
404 — DomainNotFound

The {domain} path parameter does not match any merchant configured with Firmly, or the merchant has been disabled.


{ "code": 404, "error": "DomainNotFound", "description": "This domain was not found in firmly servers." }
404 — CartNotFound

No cart exists for this device on this domain.


{ "code": 404, "error": "CartNotFound", "description": "Cart was not found." }
412 — MissingShippingInfo

Shipping rates were requested before a shipping address was set on the cart. Call Set Shipping Info first.


{ "code": 412, "error": "MissingShippingInfo", "description": "Shipping info is missing." }
503 — StoreUnavailable

The merchant’s API returned an unexpected response and rates could not be fetched. Retry with backoff.


{ "code": 503, "error": "StoreUnavailable", "description": "Store is unavailable." }