Orders

Fields marked * are required. Updates keep every field they are not given. An AI app can ask vritto_describe for the same details, filtered to what its connection may use.

Order`order`

Something the user bought, with delivery and return state.

orders_getOrderFindthrough vritto_find

Get one order by ID with its notes, pickup code, and full scan timeline. Resolve the ID with orders_listOrders first.

Field	Type	Description
orderId*	string	Order ID from a prior orders_listOrders result, never invented.

orders_listOrdersFindthrough vritto_find

List orders, newest first. ALWAYS pass status for delivery-state questions, kind for a type of purchase, and from/to when the question concerns a period (a year, a month, 'recently').

Field	Type	Description
status	one of placed, shipped, arriving, completed, issue, cancelled	Only orders in this lifecycle state.
kind	one of shipment, pickup, delivery, digital, ticket, service	Only orders of this kind.
from	string	Earliest orderedOn to include (YYYY-MM-DD).
to	string	Latest orderedOn to include (YYYY-MM-DD).
detail	one of summary, full	Row shape: "summary" (default, id, title, merchant, kind, status, order/tracking number, total, dates) or "full" (adds notes, pickup code, location, and the events[] scan timeline).
limit	integer	Max orders to return (default 100 in summary mode).
includeArchived	boolean	Include removed orders (default false).

orders_queryOrderStatsFindthrough vritto_find

Count orders by lifecycle status plus the number still open. Prefer this over orders_listOrders for how-many and anything-arriving questions.

No input.

orders_querySpendFindthrough vritto_find

Spend rollup: net USD per month, this month, this year, and the top merchants by total. Prefer this over listing rows for any how-much-did-I-spend question. Orders in a currency that could not be converted are excluded from the totals and counted in unconvertedCount, say so if it is above zero rather than presenting the total as complete.

Field	Type	Description
limit	integer	Max merchant rows to return (default 20).

orders_upsertOrderCreate or Updatethrough vritto_create or vritto_update

Create or update one order. Omit record.id to create; include a real id from orders_listOrders to update. Only the fields you send change.

Field	Type	Description
record*	object	Provide at least a title or merchantName when creating.
record.id	string	Existing order ID to update. Omit to create.
record.title	string	What was bought, e.g. 'Air Zoom Pegasus 41'. Falls back to the merchant name.
record.merchantName	string	Retailer, e.g. 'Nike'. Resolves the logo.
record.merchantDomain	string	Merchant domain, e.g. 'nike.com'.
record.kind	one of shipment, pickup, delivery, digital, ticket, service	How it reaches the user; inferred when omitted.
record.source	one of manual, gmail, outlook, import, carrier, bank	Where the record came from. Set by the ingestion pipeline; leave unset.
record.status	one of placed, shipped, arriving, completed, issue, cancelled	Lifecycle state (default 'placed').
record.statusDetail	string	Latest status line, e.g. why an order is in 'issue'.
record.orderNumber	string	Merchant order number, e.g. '112-3456789'.
record.carrier	one of ups, usps, fedex, dhl, amazon, ontrac, lasership, other, unknown	Delivery carrier; kind 'shipment' only.
record.trackingNumber	string	Carrier tracking number for THIS package. A second, different number on the same order adds a package rather than replacing the first.
record.pickupCode	string	Locker or counter code; kind 'pickup'.
record.pickupLocation	string	Where to collect it.
record.pickupByOn	string	Date the pickup window closes.
record.orderedOn	string	Date the order was placed.
record.shippedOn	string	Date it shipped.
record.expectedOn	string	Expected arrival or pickup date.
record.completedOn	string	Date it arrived, was collected, or was redeemed.
record.amount	number	Order total (default 0).
record.currency	string	ISO 4217 code (default USD).
record.returnState	one of none, started, shipped, refunded	Return progress (default 'none').
record.returnByOn	string	Date the return window closes.
record.refundAmount	number	Amount refunded.
record.refundedOn	string	Date the refund landed.
record.cardId	string	Finance card id that paid for it. Never a card number or last4.
record.recipientPersonId	string	People id the order is for; omit for the account owner.
record.notes	string	Free-form notes.
record.tags	list of string	Tags.
trackingMode	one of merge, primary	How trackingNumber is meant. Default 'merge': it names one package, and a different number adds a second package (what a shipping email means). Use 'primary' ONLY when the user is correcting this order's existing tracking number, which replaces the primary package instead of adding one.

Example input

{
  "record": {
    "title": "Standing desk",
    "merchantName": "Uplift",
    "kind": "shipment",
    "status": "shipped",
    "carrier": "fedex",
    "trackingNumber": "771234567890",
    "expectedOn": "2026-10-01",
    "amount": 689,
    "currency": "USD"
  }
}

orders_setOrderStatusUpdatethrough vritto_update

Cheap update of an order's lifecycle state, expected date, or return progress without sending the whole record. Stamps shippedOn / completedOn / refundedOn automatically.

Field	Type	Description
orderId*	string	Order ID from a prior orders_listOrders result, never invented.
status	one of placed, shipped, arriving, completed, issue, cancelled	New lifecycle state.
statusDetail	string	Latest status line.
lastLocation	string	Most recent known location.
expectedOn	string	Updated expected arrival or pickup date.
completedOn	string	Date it actually arrived or was collected.
returnState	one of none, started, shipped, refunded	Return progress.
returnByOn	string	Date the return window closes.
refundAmount	number	Amount refunded.

Example input

{
  "orderId": "order_desk",
  "status": "completed",
  "completedOn": "2026-10-01"
}

orders_deleteOrderDeletethrough vritto_delete

Delete (archive) one order. Only for explicit removal requests. Resolve the ID with orders_listOrders first.

Field	Type	Description
orderId*	string	Order ID from a prior orders_listOrders result, never invented.

Kept in the Vritto app

orders_refreshTracking: Reaches outside Vritto: another service, a device, or the public web.

Orders

Orderorder

Kept in the Vritto app

Order`order`