acp-orders-webhooks

# ACP Orders & Webhooks

## Before writing code

**Fetch live docs**:
1. Web-search `site:github.com agentic-commerce-protocol rfcs orders` for the orders RFC
2. Fetch `https://developers.openai.com/commerce/guides/key-concepts/` for order lifecycle details
3. Web-search `site:github.com agentic-commerce-protocol examples orders` for order webhook examples
4. Web-search `site:docs.stripe.com agentic-commerce webhook` for Stripe webhook guidance

## Conceptual Architecture

### Order Lifecycle

After checkout completion, the order moves through these statuses:

```
created → confirmed → manual_review → processing → shipped → delivered
    |         |            |              |            |          |
    +─────────+────────────+──────────────+────────────+──────────+→ canceled
```

**7 statuses**:
- `created` — Order placed, payment captured
- `confirmed` — Merchant acknowledged the order
- `manual_review` — Requires human review (fraud, compliance)
- `processing` — Being prepared for fulfillment
- `shipped` — Handed to carrier (physical) or access granted (digital)
- `delivered` — Buyer received the goods
- `canceled` — Order canceled at any stage

### Webhook Events

Merchants emit two event types to the agent platform:
- **`order_created`** — Fired after successful checkout completion
- **`order_updated`** — Fired on any order status change or update

### Webhook Payload

Each webhook event contains:
- Order ID
- Checkout session ID
- Current order status
- Order permalink URL (for buyer to view)
- Fulfillment details (tracking, carrier, delivery windows)
- Line items
- Totals
- Timestamps

### HMAC Webhook Signatures

All webhook events MUST be signed:
- **Algorithm**: HMAC-SHA256
- **Header**: `Merchant-Signature` (or as specified in the latest spec)
- **Key**: Shared secret obtained during onboarding
- **Payload**: Raw request body (canonical JSON)
- **Verification**: Timing-safe comparison to prevent timing attacks

### Post-Purchase Order Adjustments

ACP supports adjustments after order creation:

| Type | Description |
|------|-------------|
| `refund` | Full refund |
| `partial_refund` | Partial amount refund |
| `store_credit` | Refund as store credit |
| `return` | Buyer returns goods |
| `exchange` | Swap for different item |
| `cancellation` | Order cancellation |
| `dispute` | Buyer disputes charge |
| `chargeback` | PSP-initiated chargeback |

Each adjustment has its own status: `pending`, `completed`, `failed`.

### Order Object

The order contains:
- `id` — Unique order identifier
- `checkout_session_id` — Links back to the checkout session
- `permalink_url` — Buyer-facing order page

### Best Practices

- Emit `order_created` immediately after payment capture
- Emit `order_updated` for every status transition
- Include all current fulfillment details in each webhook
- Use idempotent webhook delivery (include event ID for deduplication)
- Implement retry logic for failed webhook deliveries (exponential backoff)
- Sign EVERY webhook — never send unsigned events
- Use timing-safe comparison when verifying signatures on the receiving end
- Store webhook delivery status for debugging

Fetch the orders RFC and webhook examples from the GitHub repo for exact event shapes, signature format, and field definitions before implementing.