Carts & Checkout
Shipping methods
List the store's active shipping methods with the effective price for a specific cart.
View as MarkdownShipping methods are configured by the merchant. Each has a fixed amount and an optional free_over_amount threshold: when the cart's goods gross total reaches the threshold, shipping is free for that cart. This endpoint returns each method with its effective_amount already resolved against the given cart, so the storefront can render the shipping picker without re-implementing the free-shipping rule.
Shipping only applies to carts that contain shippable lines. Product types simple, variable, and configurable are shippable; digital, license, and subscription are not. See the Checkout page for when shipping_method_id is required.
Shipping methods are configured by the merchant. Each has a fixed amount and an optional free_over_amount threshold: when the cart's goods gross total reaches the threshold, shipping is free for that cart. This endpoint returns each method with its effective_amount already resolved against the given cart, so the storefront can render the shipping picker without re-implementing the free-shipping rule.
Shipping only applies to carts that contain shippable lines. Product types simple, variable, and configurable are shippable; digital, license, and subscription are not. See the Checkout page for when shipping_method_id is required.
GET /v1/api/commerce/carts/{id}/shipping-methods
Lists the store's active shipping methods, ordered by name, with the effective price for this cart. Requires commerce:read. Cart ownership is enforced (see the Carts page). The list is not paginated.
Parameters
Path
| Name | Type | Required | Description |
|---|---|---|---|
id | string (UUID) | yes | Cart id. Any status is accepted for lookup, but the price context only makes sense for an active cart. |
Headers
| Name | Type | Required | Description |
|---|---|---|---|
X-Customer-Token | string | no | Required if the cart is bound to a non-guest customer. |
Response fields
The envelope is {"data": [...]}. Unlike cart and order money values, the amounts here are bare integers in minor units, not money objects; the currency is the cart's currency (EUR).
| Name | Type | Required | Description |
|---|---|---|---|
id | string (UUID) | always | Shipping method id. Pass it as shipping_method_id at checkout. |
name | string | always | Display name. |
amount | integer | always | Base price in minor units. |
free_over_amount | integer or null | always | Goods gross total (minor units) at which shipping becomes free, or null when the method is never free. |
effective_amount | integer | always | The price this cart would pay right now: 0 when the cart's goods gross total reaches free_over_amount, otherwise amount. |
effective_amount is a snapshot for the cart as it is now: changing cart contents can change it, so re-fetch after cart mutations if the shipping picker is visible.
Errors
| Status | Body | When |
|---|---|---|
| 404 | {"message": "..."} | Unknown cart id or a cart of another store. |
| 403 | {"message": "This cart belongs to a customer."} | Ownership check failed. |
| 403 | scope, module, or suspension body | See the Carts page. |
| 429 | {"message": "Too Many Attempts."} | Rate limit exceeded. |
curl https://api.borkol.com/v1/api/commerce/carts/9d3f2a10-6b7c-4e6d-9f21-8a54c1d2e3f4/shipping-methods \
-H "Authorization: Bearer {api_key}"const res = await fetch(
`https://api.borkol.com/v1/api/commerce/carts/${cartId}/shipping-methods`,
{ headers: { Authorization: `Bearer ${apiKey}` } }
);
const { data: methods } = await res.json();{
"data": [
{
"id": "3c4d5e6f-7a8b-4c9d-0e1f-2a3b4c5d6e7f",
"name": "Express",
"amount": 995,
"free_over_amount": null,
"effective_amount": 995
},
{
"id": "4d5e6f7a-8b9c-4d0e-1f2a-3b4c5d6e7f8a",
"name": "Standard",
"amount": 495,
"free_over_amount": 5000,
"effective_amount": 0
}
]
}GET /v1/api/commerce/carts/{id}/shipping-methods
Lists the store's active shipping methods, ordered by name, with the effective price for this cart. Requires commerce:read. Cart ownership is enforced (see the Carts page). The list is not paginated.
Parameters
Path
| Name | Type | Required | Description |
|---|---|---|---|
id | string (UUID) | yes | Cart id. Any status is accepted for lookup, but the price context only makes sense for an active cart. |
Headers
| Name | Type | Required | Description |
|---|---|---|---|
X-Customer-Token | string | no | Required if the cart is bound to a non-guest customer. |
Response fields
The envelope is {"data": [...]}. Unlike cart and order money values, the amounts here are bare integers in minor units, not money objects; the currency is the cart's currency (EUR).
| Name | Type | Required | Description |
|---|---|---|---|
id | string (UUID) | always | Shipping method id. Pass it as shipping_method_id at checkout. |
name | string | always | Display name. |
amount | integer | always | Base price in minor units. |
free_over_amount | integer or null | always | Goods gross total (minor units) at which shipping becomes free, or null when the method is never free. |
effective_amount | integer | always | The price this cart would pay right now: 0 when the cart's goods gross total reaches free_over_amount, otherwise amount. |
curl https://api.borkol.com/v1/api/commerce/carts/9d3f2a10-6b7c-4e6d-9f21-8a54c1d2e3f4/shipping-methods \
-H "Authorization: Bearer {api_key}"const res = await fetch(
`https://api.borkol.com/v1/api/commerce/carts/${cartId}/shipping-methods`,
{ headers: { Authorization: `Bearer ${apiKey}` } }
);
const { data: methods } = await res.json();{
"data": [
{
"id": "3c4d5e6f-7a8b-4c9d-0e1f-2a3b4c5d6e7f",
"name": "Express",
"amount": 995,
"free_over_amount": null,
"effective_amount": 995
},
{
"id": "4d5e6f7a-8b9c-4d0e-1f2a-3b4c5d6e7f8a",
"name": "Standard",
"amount": 495,
"free_over_amount": 5000,
"effective_amount": 0
}
]
}effective_amount is a snapshot for the cart as it is now: changing cart contents can change it, so re-fetch after cart mutations if the shipping picker is visible.
Errors
| Status | Body | When |
|---|---|---|
| 404 | {"message": "..."} | Unknown cart id or a cart of another store. |
| 403 | {"message": "This cart belongs to a customer."} | Ownership check failed. |
| 403 | scope, module, or suspension body | See the Carts page. |
| 429 | {"message": "Too Many Attempts."} | Rate limit exceeded. |