# Skill: unified_checkout

**Type:** http
**Method:** POST
**URL:** https://cimonamia.com/api/agent/checkout

**Recommended for AI agents.** Combines product lookup, shipping quote, and
Stripe payment intent creation into a single call. Instead of the standard
3-request flow (add-to-cart → shipping-quote → create-payment-intent),
agents can submit the whole intent at once and receive a hosted Stripe
checkout URL.

## Request body

```json
{
  "items": [
    { "product_slug": "abrigo-nomada", "quantity": 1 },
    { "product_id":   "6a077c8a2863c24f2152e87d", "quantity": 2 }
  ],
  "shipping_address": {
    "full_name":  "Ada Lovelace",
    "email":      "ada@example.com",
    "phone":      "3001234567",
    "street":     "Calle 122 #11c 51",
    "number":     "11c-51",
    "apartment":  "Apto 302",
    "city":       "Bogotá",
    "state":      "Cundinamarca",
    "postal_code":"110111",
    "country":    "CO"
  },
  "country":  "CO",
  "currency": "COP",
  "preferred_shipping_id": null,
  "notes": "Gift wrap"
}
```

Each item accepts EITHER `product_slug` (recommended for agents) OR
`product_id` (Mongo ObjectId as string). `country` defaults to the
shipping country; `currency` is inferred from country pricing.

`preferred_shipping_id` is optional — if omitted, the endpoint picks
the cheapest option from the shipping quote.

## Response (200)

```json
{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_...",
  "session_id":   "cs_test_...",
  "amount": {
    "subtotal": 496700.0,
    "shipping": 0.0,
    "total":    496700.0,
    "currency": "COP"
  },
  "shipping_method": {
    "id": "free-shipping-co",
    "name": "Envío Gratis",
    "description": "Sin costo de envío",
    "price": 0.0,
    "currency": "COP"
  },
  "items": [ ... enriched line items ... ],
  "next_steps": {
    "human_action_required": true,
    "redirect_user_to": "https://checkout.stripe.com/...",
    "poll_status":       "https://cimonamia.com/api/checkout/payment-status/{session_id}",
    "track_after_payment":"https://cimonamia.com/api/tracking/{order_id}"
  },
  "protocol": { "name": "acp", "version": "1.0",
                "discovery": "https://cimonamia.com/.well-known/acp.json" }
}
```

The agent MUST redirect the human user to `checkout_url` (per ACP guest
flow); Cimonamia never charges cards server-side without user consent.

## Errors

- `404` — product slug/id not found
- `400` — no shipping options for destination
- `422` — invalid item schema
- `502` — Stripe unavailable