Outbound Capabilities

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.

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).

`order_get` — live order status

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

{ "order_id": "vambe-internal-uuid", "order_external_id": "1001" }

Response — the canonical order status shape:

{
  "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

{ "product_external_ids": ["sku-001", "sku-002"] }

Response — an array, one entry per product:

[
  {
    "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

{
  "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):

{
  "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.

Get started

Integration contract

App management API

Webhook API

Overview

How Vambe calls you

`order_get` — live order status

`stock_get` — stock by location

`checkout_create` — create a checkout link

Reserved capability — `products_list`

​Overview

​How Vambe calls you

​order_get — live order status

​stock_get — stock by location

​checkout_create — create a checkout link

​Reserved capability — products_list

Overview

How Vambe calls you

`order_get` — live order status

`stock_get` — stock by location

`checkout_create` — create a checkout link

Reserved capability — `products_list`