Standard checkout

Address, shipping, and consent steps for the Standard flow (/api/v1). Run these after the cart has items and before placing the order. Each call returns the updated cart.

All calls are on https://api.firmly.work with the x-firmly-authorization header. {domain} is the merchant domain, e.g. staging.luma.gift.

​​ Set the shipping address

POST /api/v1/domains/{domain}/cart/shipping-info

Sets the delivery address. Setting it lets the merchant calculate shipping rates and tax.

The body is an address:

{
  "first_name": "Ada",
  "last_name": "Lovelace",
  "email": "ada@example.com",
  "phone": "5125550100",
  "address1": "1 Infinite Loop",
  "city": "Austin",
  "state_or_province": "TX",
  "country": "US",
  "postal_code": "78701"
}

curl --request POST \
  --url https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/shipping-info \
  --header 'Content-Type: application/json' \
  --header 'x-firmly-authorization: YOUR_TOKEN' \
  --data @address.json

​​ Get shipping rates

GET /api/v1/domains/{domain}/cart/shipping-rates

Returns the available shipping methods for the cart. Set the shipping address first.

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

Response — an array of shipping methods, each with a sku, description, and price:

[
  { "sku": "freeshipping_freeshipping", "description": "Standard", "price": { "currency": "USD", "value": 0, "number": 0, "symbol": "$" } },
  { "sku": "flatrate_flatrate", "description": "Expedited", "price": { "currency": "USD", "value": 4, "number": 400, "symbol": "$" } }
]

​​ Set the shipping method

POST /api/v1/domains/{domain}/cart/shipping-method

Selects one of the methods returned by shipping rates.

• shipping_method (string, required) — the sku of the chosen method from shipping rates.

curl --request POST \
  --url https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/shipping-method \
  --header 'Content-Type: application/json' \
  --header 'x-firmly-authorization: YOUR_TOKEN' \
  --data '{ "shipping_method": "freeshipping_freeshipping" }'

​​ Set the billing address

POST /api/v1/domains/{domain}/cart/billing-info

Same address shape as shipping. Send it when billing differs from shipping (or to confirm it explicitly).

curl --request POST \
  --url https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/billing-info \
  --header 'Content-Type: application/json' \
  --header 'x-firmly-authorization: YOUR_TOKEN' \
  --data @address.json

​​ Consents

POST /api/v1/domains/{domain}/cart/consents returns the consents the merchant requires. PUT on the same path records the shopper’s choices.

• consents (array, required) — each { "id": "...", "revoke": false }.

curl --request PUT \
  --url https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/consents \
  --header 'Content-Type: application/json' \
  --header 'x-firmly-authorization: YOUR_TOKEN' \
  --data '{ "consents": [ { "id": "terms_and_conditions" } ] }'

​​ Errors

Errors return { code, error, description }; program against error. Common cases: CartNotFound (404), InvalidInputBody (400, address missing a required field), OperationNotSupported (412). See Errors & Conventions for the full catalog.

​​ Next