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) and the id of the checkout you created:

{
  "link": "https://myecommerce.com/checkout/abc123",
  "external_checkout_id": "chk_abc123",
  "stockAdjustments": [
    {
      "productExternalId": "sku-001",
      "requestedQuantity": 2,
      "availableStock": 1,
      "adjustedQuantity": 1
    }
  ]
}

external_checkout_id is required: it is your own id for the checkout behind the link. Vambe records at this moment which conversation produced the checkout, keyed by that id — see Sale attribution below. If your ids are numeric, send them as numbers or as strings — Vambe accepts both here and on the order and checkout webhooks, and stores them in their string form. Ids above JSON’s safe integer range (2^53 - 1, i.e. 9007199254740991) must be sent as strings: above that, JSON parsers silently round the value and two different checkouts can collapse onto the same id, so Vambe rejects them. stockAdjustments is optional — include it if you clamped quantities to available stock. Return { "link": null } if a link cannot be created; you may add an optional error string explaining why (it is logged on Vambe’s side, never shown to the shopper).

Sale attribution

When the shopper later pays, your order webhook must include the same id as external_checkout_id. That is the only thing Vambe needs to credit the sale to the assistant conversation that produced it:

You respond to checkout_create with external_checkout_id.
Vambe stores the attribution (conversation ↔ checkout) on its side.
Your order webhook repeats external_checkout_id; Vambe looks the checkout up and attributes the order.

If the response omits external_checkout_id, the link still reaches the shopper but the sale can never be attributed — the app checklist fails the checkout_create check for this reason. One checkout attributes at most one order.

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

Sale attribution

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

​Sale attribution

​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

Sale attribution

Reserved capability — `products_list`