Skip to main content

Shipping

Shipping methods are configured per-store and presented during checkout. The API calculates available shipping options based on the delivery address and store configuration.

Get Shipping Methods​

Shipping methods are returned as part of the checkout session creation. You can also query them independently:

GET /api/storefront/shipping/methods
X-Store-Code: us-store

Response:

[
  {
    "id": "guid",
    "name": "Standard Shipping",
    "description": "Delivery in 3-5 business days",
    "cost": 5.99,
    "estimatedDays": "3-5",
    "isActive": true
  },
  {
    "id": "guid",
    "name": "Express Shipping",
    "description": "Next day delivery",
    "cost": 14.99,
    "estimatedDays": "1",
    "isActive": true
  }
]

Free Shipping Promotions​

Automatic promotions can grant free shipping when conditions are met (e.g., "Free shipping on orders over $50"). When this applies:

  • The basket response includes hasFreeShipping: true
  • During checkout, the shipping cost is set to 0 for qualifying methods
  • The promotion details appear in appliedPromotions
{
  "appliedPromotions": [
    {
      "name": "Free Shipping Over $50",
      "type": "FreeShipping",
      "hasFreeShipping": true
    }
  ]
}

Shipping in Checkout​

During the checkout flow, select a shipping method in Step 2:

PUT /api/storefront/checkout/session/{sessionId}/shipping
Content-Type: application/json

{
  "shippingMethodId": "guid"
}

The session totals are recalculated to include the shipping cost.

Store-Specific Methods

Each store can have different shipping methods and pricing. The available methods depend on the X-Store-Code header and the shipping destination.