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_findFindthrough vritto_find

Read Orders: one order by id (with notes and its scan timeline), orders filtered by status, kind, dates or text (view 'open' for everything still on its way), view 'spend' for spend totals, or no filter for counts by status. ALWAYS pass status, kind or from/to when the question names one.

Note: No filter returns counts by status; view 'open' lists what is still on its way; view 'spend' totals spend.

Field	Type	Description
id	string	Return just this order, in full.
view	one of open, spend, stats	'open' orders still on their way (placed, shipped, arriving or with an issue); 'spend' net spend per month, this month, this year and top merchants (USD figures plus accountFx to state them in the account's currency); 'stats' counts by status (the default with no filter).
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.
to	string	Latest orderedOn to include. ALWAYS pass from/to when the question concerns a period.
query	string	Text to match: merchant, item, order or tracking number.
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); with view 'spend', merchant rows (default 20).
includeArchived	boolean	Include removed orders (default false).
orderId	string	Older name for id.

Example input

{
  "view": "open"
}

orders_addCreate or Updatethrough vritto_create or vritto_update

Add one order (a title or merchantName, plus what the person said). A record.id from orders_find merges into that order instead; 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; leave out for the account's currency.
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.
record.showing	object	Cinema tickets only: the booking. Omit for every other order.
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_changeUpdatethrough vritto_update

Change one order by record.id; sent fields merge. 'It arrived' is status 'completed', 'it shipped' status 'shipped', a return is returnState: these stamp their dates. Resolve the id with orders_find first.

Note: Only lifecycle fields (status, returnState, refundAmount and their dates) take the cheap path that stamps shippedOn, completedOn and refundedOn.

Field	Type	Description
record	object	The order's id plus the fields to change.
record.id*	string	Order ID from a prior orders_find result, never invented.
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; leave out for the account's currency.
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.
record.showing	object	Cinema tickets only: the booking. Omit for every other order.
record.lastLocation	string	Most recent known location.
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.
orderId	string	Older form of a status change: the order, with the fields below.
status	one of placed, shipped, arriving, completed, issue, cancelled	Older form, with orderId.
statusDetail	string	Older form, with orderId.
lastLocation	string	Older form, with orderId.
expectedOn	string	Older form, with orderId.
completedOn	string	Older form, with orderId.
returnState	one of none, started, shipped, refunded	Older form, with orderId.
returnByOn	string	Older form, with orderId.
refundAmount	number	Older form, with orderId.

Example input

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

orders_removeDeletethrough vritto_delete

Remove (archive) one order. Only for explicit removal requests; a cancelled order is an orders_change with status 'cancelled'. Resolve the id with orders_find first.

Note: A cancelled order is an orders_change with status 'cancelled' instead.

Field	Type	Description
id	string	The order to remove.
orderId	string	Older name for id.

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`