Fulfillment

Overview

The Fulfillment extension adds delivery and pickup options to the checkout flow. Businesses can offer multiple fulfillment methods with different costs and delivery timeframes.

Fulfillment Types

Get Fulfillment Options

GET /checkout/sessions/{session_id}/fulfillment
Authorization: Bearer {access_token}

Response

{
  "fulfillment_options": [
    {
      "id": "ff_standard",
      "type": "shipping",
      "name": "Standard Shipping",
      "carrier": "USPS",
      "price": 5.99,
      "estimated_delivery": {
        "min_days": 5,
        "max_days": 7
      }
    },
    {
      "id": "ff_express",
      "type": "express",
      "name": "Express Shipping",
      "carrier": "FedEx",
      "price": 14.99,
      "estimated_delivery": {
        "min_days": 1,
        "max_days": 2
      }
    },
    {
      "id": "ff_pickup",
      "type": "pickup",
      "name": "Store Pickup",
      "price": 0,
      "location": {
        "name": "Downtown Store",
        "address": "456 Market St, San Francisco, CA"
      },
      "available_from": "2025-01-16T10:00:00Z"
    }
  ]
}

Select Fulfillment Method

PUT /checkout/sessions/{session_id}/fulfillment
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "fulfillment_id": "ff_express",
  "shipping_address": {
    "line1": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "US"
  }
}

Response

{
  "session_id": "sess_abc123",
  "fulfillment": {
    "id": "ff_express",
    "type": "express",
    "name": "Express Shipping",
    "carrier": "FedEx",
    "price": 14.99,
    "estimated_delivery": {
      "min_days": 1,
      "max_days": 2,
      "estimated_date": "2025-01-17"
    }
  },
  "cart": {
    "subtotal": 149.99,
    "shipping": 14.99,
    "tax": 14.85,
    "total": 179.83
  }
}

Address Validation

Optionally validate shipping addresses before checkout completion:

POST /fulfillment/validate-address
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "address": {
    "line1": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "US"
  }
}

Validation Response

{
  "valid": true,
  "normalized": {
    "line1": "123 MAIN ST",
    "city": "SAN FRANCISCO",
    "state": "CA",
    "postal_code": "94102-1234",
    "country": "US"
  },
  "deliverable": true,
  "residential": true
}

Pickup Locations

GET /fulfillment/pickup-locations
  ?postal_code=94102
  &radius=10
Authorization: Bearer {access_token}

Response

{
  "locations": [
    {
      "id": "loc_downtown",
      "name": "Downtown Store",
      "address": {
        "line1": "456 Market St",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94103"
      },
      "hours": {
        "monday": "9:00-21:00",
        "tuesday": "9:00-21:00",
        "wednesday": "9:00-21:00",
        "thursday": "9:00-21:00",
        "friday": "9:00-21:00",
        "saturday": "10:00-18:00",
        "sunday": "11:00-17:00"
      },
      "distance_miles": 0.8
    }
  ]
}

Error Handling

• INVALID_ADDRESS - Address could not be validated
• UNDELIVERABLE_ADDRESS - Cannot deliver to this address
• FULFILLMENT_UNAVAILABLE - Selected method not available
• PICKUP_LOCATION_CLOSED - Pickup location is not available

Next Steps

• Learn about Discount Extension for promotional codes
• See Order Capability for tracking shipments
• Explore Business Integration for implementation