> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vambe.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Outbound Capabilities

> Expose URLs that Vambe calls on demand so the AI assistant can fetch live order status, stock, and create checkout links.

## Overview

Some assistant tools need **live** data that does not arrive via webhooks — "where is my
order?", "is this in stock?", "send me a checkout link". For those, Vambe calls URLs you
declare in `capabilities.outbound`. You expose an endpoint per capability; Vambe calls it
on demand.

If you don't declare a capability, Vambe simply won't offer that tool for your app.

## How Vambe calls you

Every outbound request is an HTTP `POST` with a JSON body and these headers:

| Header             | Value                                                                 |
| ------------------ | --------------------------------------------------------------------- |
| `Authorization`    | `Bearer {access_token}` — the merchant's OAuth token from connection. |
| `X-Vambe-Store-Id` | The store's `external_id` (from `account_info_url`), when available.  |
| `Content-Type`     | `application/json`                                                    |

Use the bearer token (and store id) to scope the response to the right merchant.

<Warning>
  **Security requirements.** Capability URLs must be **HTTPS** and must resolve to a public IP —
  Vambe blocks requests to private, loopback, and link-local addresses. Respond within **\~15
  seconds**; on timeout or error Vambe degrades gracefully (the tool returns no data).
</Warning>

## `order_get` — live order status

Vambe calls this when the assistant is asked about an order's status.

**Request**

```json theme={null}
{ "order_id": "vambe-internal-uuid", "order_external_id": "1001" }
```

**Response** — the canonical order status shape:

```json theme={null}
{
  "fulfillmentStatus": "fulfilled",
  "statusPageUrl": "https://myecommerce.com/orders/1001/status",
  "financialStatus": "paid",
  "tags": [],
  "shippingLine": { "title": "Standard", "deliveryCategory": "shipping" },
  "createdAt": "2026-06-10T12:00:00Z",
  "cancelledAt": null,
  "closedAt": null,
  "cancelReason": null,
  "fulfillments": [
    {
      "status": "delivered",
      "deliveredAt": "2026-06-12T09:30:00Z",
      "fulfillmentAt": "2026-06-10T18:00:00Z",
      "estimatedDeliveryAt": "2026-06-12T00:00:00Z",
      "trackingInfo": [
        { "company": "Correos", "number": "TRACK123", "url": "https://track/TRACK123" }
      ],
      "items": [{ "quantity": 2, "variantName": "Premium Coffee Beans" }]
    }
  ]
}
```

All fields except `fulfillmentStatus`, `tags`, and `fulfillments` are optional.

## `stock_get` — stock by location

Vambe calls this when the assistant needs live inventory.

**Request**

```json theme={null}
{ "product_external_ids": ["sku-001", "sku-002"] }
```

**Response** — an array, one entry per product:

```json theme={null}
[
  {
    "externalId": "sku-001",
    "locations": [
      { "locationName": "Main Warehouse", "locationAddress": "Santiago, CL", "stockQuantity": 12 },
      { "locationName": "Store #2", "locationAddress": "Valparaíso, CL", "stockQuantity": 0 }
    ]
  }
]
```

## `checkout_create` — create a checkout link

Vambe calls this when the assistant builds a cart and needs a payable link to send the
customer.

**Request**

```json theme={null}
{
  "items": [
    { "external_product_id": "sku-001", "quantity": 2 }
  ],
  "customer": {
    "checkoutEmail": "jane@example.com",
    "name": "Jane",
    "lastName": "Doe",
    "address": "Av. Siempre Viva 742",
    "city": "Santiago"
  },
  "ai_contact_id": "contact-uuid",
  "assistant_id": "assistant-uuid",
  "marketplace_source": "whatsapp"
}
```

**Response** — the checkout link (full URL; Vambe shortens it before sending):

```json theme={null}
{
  "link": "https://myecommerce.com/checkout/abc123",
  "stockAdjustments": [
    {
      "productExternalId": "sku-001",
      "requestedQuantity": 2,
      "availableStock": 1,
      "adjustedQuantity": 1
    }
  ]
}
```

`stockAdjustments` is optional — include it if you clamped quantities to available stock.
Return `{ "link": null }` if a link cannot be created.

## Reserved capability — `products_list`

If you prefer Vambe to **pull** your full catalog instead of pushing product webhooks, the
`products_list` capability key is reserved for that model. Coordinate with the Vambe team
before relying on it.