Acp Fulfillment

---
name: acp-fulfillment
description: >
  Implement ACP fulfillment options — shipping, digital delivery, in-store
  pickup, and local delivery. Use when building fulfillment selection, rate
  calculation, delivery window management, or tracking integration.
---

# ACP Fulfillment

## Before writing code

**Fetch live docs**:
1. Fetch `https://developers.openai.com/commerce/specs/checkout/` — fulfillment options are part of the checkout spec
2. Web-search `site:github.com agentic-commerce-protocol spec json-schema FulfillmentOption` for the schema
3. Web-search `site:github.com agentic-commerce-protocol rfcs orders fulfillment` for fulfillment in orders

## Conceptual Architecture

### Four Fulfillment Types

| Type | Use Case | Key Fields |
|------|----------|------------|
| **shipping** | Physical delivery to address | Carrier, tracking number/URL, delivery windows |
| **digital** | Downloads, licenses, access | Access URL, license key, expiration date |
| **pickup** | In-store or locker collection | Location, ready-by window, pickup-by deadline |
| **local_delivery** | Same-day/local service delivery | Service area, delivery window |

### How Fulfillment Works in Checkout

1. **Create session** — Merchant returns available `fulfillment_options[]` based on items and address
2. **Agent selects** — Agent (or buyer) picks a `fulfillment_option_id`
3. **Update session** — Agent sends the chosen `fulfillment_option_id` in an update
4. **Merchant recalculates** — Totals update to include fulfillment cost
5. **Post-purchase** — Merchant emits order updates with tracking and delivery details

### FulfillmentOption Object

Each option includes:
- `id` — Unique identifier for this option
- `type` — One of the four types above
- `title` — Display name (e.g., "Standard Shipping")
- `subtitle` — Additional info (e.g., "5-7 business days")
- `carrier` — Carrier name for shipping
- Delivery window (estimated dates/times)
- Pricing — Cost of this fulfillment option

### Delivery Windows

Time-based constraints:
- **Estimated delivery** — Date range for when buyer can expect delivery
- **Ready-by** (pickup) — When the order will be ready for collection
- **Pickup-by** (pickup) — Deadline to collect before order is returned
- **Delivery window** (local delivery) — Time slot for delivery

### Fulfillment in Orders

After checkout completion, fulfillment details appear in order webhook events:
- Tracking number and tracking URL
- Carrier name
- Shipment status updates
- Delivery confirmation

### Best Practices

- Return all available fulfillment options on session create (not just the cheapest)
- Compute fulfillment costs based on actual address (not estimates)
- Include realistic delivery windows — agents present these to buyers
- Update tracking information in real-time via order webhooks
- Support multiple fulfillment groups for split shipments
- Handle address validation before computing fulfillment options

Fetch the checkout spec and JSON schema for exact FulfillmentOption field names, types, and required fields before implementing.