Skip to main content

​
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:
HeaderValue
AuthorizationBearer {access_token} — the merchant’s OAuth token from connection.
X-Vambe-Store-IdThe store’s external_id (from account_info_url), when available.
Content-Typeapplication/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 }
    ]
  }
]
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.