orcaqubits/acp-fulfillment

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.