{ "Protocol": "AIXE", "Version": "1.0", "Endpoint": "/aixe/owner/list-orders", "DiscoveryRequest": "GET /aixe/owner/list-orders/?", "CanonicalHelpTrigger": "GET /aixe/owner/list-orders/?", "ActionRequest": "POST /aixe/owner/list-orders", "Method": "POST", "ContentType": "application/json", "Title": "List Orders", "AuthenticationRequired": true, "AccessType": "Site Administrator", "Purpose": "Latest ten by default for page parity; independent text and invoice-date bounds, status/payment filters, totals and continuation.", "RecurrenceRules": "Product and invoice-item responses include IsSubscription. Subscription items require one line with quantity exactly 1, with no mixed products. Invoice headers include RecurringHours (0 means stopped), FirstOccurrenceDate, LastRecurrenceDate and NextOccurrenceDate in UTC. Use owner/get-recurrence or customer/get-recurrence, then update-recurrence with a current RowVersion. SubscriptionDays on the product automatically sets new subscription invoice hours and the first renewal one interval after the item is added. Customers cannot change subscription schedules. Product changes affect new invoices only. Ordinary invoices can optionally repeat multiple products. Generation copies the source into a fresh Ordered, unpaid invoice with recurrence disabled. The public /renewinvoices trigger needs no authentication and never creates the same occurrence twice.", "ThingsYouCanAsk": [ "Help me list orders.", "Show me the information needed to list orders.", "Use this capability for my business." ], "DocumentationSource": "AIXEEndpointRegistry", "ProtocolReference": { "ProtocolHome": "http://aixeprotocol.com/", "CanonicalUsageContract": "http://aixeprotocol.com/usage/?", "Whitepaper": "http://aixeprotocol.com/whitepaper/full-spec.html", "Inventor": "Gregory Oglethorpe", "IncludeIn": [ "/aixe.ai starter discovery documents", "Every endpoint self-description returned by GET /endpoint/?" ], "AIInstruction": "Read this live endpoint contract as operational guidance, not merely as a transport schema. Use its purpose, field meanings, business rules, outcomes, and recovery guidance to reason about whether and how to perform the capability." }, "UsageGuidance": { "Role": "Read this contract and use the capability only for the human\u0027s authorized request.", "CorrectWorkflow": [ "Read this contract and use the capability only for the human\u0027s authorized request.", "Read current public keys and record versions before changing records. Send fields in the JSON body.", "Read SuccessCode and the detailed outcome; a saved business action and its email outcome are separate." ], "DoNotDo": [ "Do not send business variables, keys, filters, or action inputs in the URL or query string.", "Do not infer success from HTTP status alone." ] }, "AIUsageGuidance": { "ContractRole": "This live document teaches an AI what the capability means and how to use it; it is not merely a list of request fields.", "ReasoningInstruction": "Decide whether this capability serves the human\u0027s intent from Purpose and BusinessRules, gather values using each field\u0027s Description and constraints, then interpret the returned SuccessCode before reporting an outcome.", "FieldInstruction": "Field names are transport labels. Their Description, source, constraints, and business meaning explain what information the AI should obtain and why." }, "RequiredFields": { "PersonAuthenticationToken": { "Type": "string", "Description": "Temporary secret from account/login. Authorization uses the active account and its current roles; never echo or store it.", "Required": true, "SubmittedIn": "JSON body" } }, "OptionalFields": { "Search": { "Type": "string", "Description": "Case-insensitive search text, up to 200 characters. Order searches match invoice number, customer name, email, phone, status, payment status and fulfillment method. Product searches match every word across name, SKU and category. Customer searches include full name, email and normalized phone.", "Required": false, "SubmittedIn": "JSON body" }, "PageSize": { "Type": "integer", "Description": "Number of rows per response, from 1 to 1000. Does not truncate the matching dataset: follow NextCursor while HasMore. Default 100; unfiltered owner orders default 10 and customer orders 30.", "Required": false, "SubmittedIn": "JSON body" }, "Limit": { "Type": "integer", "Description": "Compatibility alias for PageSize. PageSize takes precedence. It limits one response, not all accessible matches.", "Required": false, "SubmittedIn": "JSON body" }, "Cursor": { "Type": "string", "Description": "Continuation value returned as NextCursor by the previous identical search. Keep filters and page size unchanged. Results are ordered deterministically; concurrent edits may change a later page.", "Required": false, "SubmittedIn": "JSON body" }, "StartDate": { "Type": "string", "Description": "Inclusive start date, YYYY-MM-DD. Optional and independent of text or EndDate. Order-list Created dates use the local invoice date shown by the website.", "Required": false, "SubmittedIn": "JSON body", "Format": "YYYY-MM-DD" }, "EndDate": { "Type": "string", "Description": "Inclusive end date, YYYY-MM-DD; may be used alone. Must not precede StartDate. The entire end day is included, including the maximum representable date.", "Required": false, "SubmittedIn": "JSON body", "Format": "YYYY-MM-DD" }, "InvoiceStatus": { "Type": "string", "Description": "Explicit target status code from StatusCatalog. Status edits can move backward or reopen an order; pickup and delivery applicability still applies. Finalize-order accepts only its matching ready status.", "Required": false, "SubmittedIn": "JSON body", "AllowedValues": [ "Pending", "Ordered", "Being Fulfilled", "Ready For Pickup", "Ready For Delivery", "Out For Delivery", "Completed", "Cancelled", "Abandoned" ] }, "PaymentStatus": { "Type": "string", "Description": "Exact payment-state filter returned by an order read.", "Required": false, "SubmittedIn": "JSON body" }, "FulfillmentType": { "Type": "string", "Description": "Pickup or Delivery. Delivery requires a complete address in an active service area.", "Required": false, "SubmittedIn": "JSON body", "AllowedValues": [ "Pickup", "Delivery" ] }, "ListAll": { "Type": "boolean", "Description": "Explicitly request unfiltered results. Customer selection otherwise remains empty until Search contains text. No preloading of customer choices.", "Required": false, "SubmittedIn": "JSON body" }, "CustomerKey": { "Type": "string", "Description": "Public UUID identifying the customer. Select it from an authorized customer search; this is not authentication.", "Required": false, "SubmittedIn": "JSON body", "Format": "UUID" }, "ProductKey": { "Type": "string", "Description": "Public UUID identifying a product from the product catalog.", "Required": false, "SubmittedIn": "JSON body", "Format": "UUID" }, "DeliveryCity": { "Type": "string", "Description": "Invoice delivery City. This is an invoice snapshot; editing it does not change the customer profile.", "Required": false, "SubmittedIn": "JSON body" }, "MinimumBalanceDue": { "Type": "number", "Description": "Nonnegative minimum invoice balance.", "Required": false, "SubmittedIn": "JSON body" }, "MinimumTotal": { "Type": "number", "Description": "Nonnegative minimum invoice total.", "Required": false, "SubmittedIn": "JSON body" }, "MaximumTotal": { "Type": "number", "Description": "Nonnegative maximum invoice total; must not be below MinimumTotal.", "Required": false, "SubmittedIn": "JSON body" } }, "BusinessRules": [ "Read-only; no business state or email is changed.", "Only active authorized accounts may use protected capabilities. Customer order queries are restricted to the authenticated customer\u0027s orders before filtering. Internal notes, staff activity and vendor details are owner-only.", "Dates and text filters can be supplied independently or together. Searches expose all matches through continuation; there is no silent first-50 or first-200 cutoff.", "Customer selection is empty without Search or explicit ListAll. The configured customer result limit is disclosed as AppliedLimit.", "Payment amounts, identity and invoice relationships are permanent. No payment deletion exists. Update-payment-details accepts only date, method, reference and note in addition to its keys and versions. Negative entries require a note and cannot exceed net collected. Overpayments are retained as credit.", "The status endpoint sets any supported status, including backward moves and reopening. Pickup/delivery compatibility applies. It sends no email and does not claim the checklist is complete. Finalize-order requires every current line packed and commits readiness before its immediate email attempt.", "Email is attempted immediately with a bounded SMTP timeout. Failed sends log a NOC and stop. No queue, delivery worker or automatic retry exists. A mail failure never reverses a saved order, payment or vendor assignment. Explicit resend-request is a new intentional send.", "Customer deletion removes access and preserves invoice history. Referenced vendors must be deactivated. Administrators cannot remove themselves or the last active administrator. Passwords and SMTP secrets are never returned.", "Editing a submitted record requires its returned RowVersion. Stale edits fail and must be reviewed before submitting a new request. Unsupported fields are rejected rather than silently accepted." ], "ResponseFields": { "SuccessCode": { "Type": "string", "Description": "SUCCESS confirms the read or committed business action. Check email acceptance separately. A failed email-only action returns EMAIL_NOT_SENT. HTTP status alone does not establish success.", "Required": true, "SubmittedIn": "Response body" }, "Orders": { "Type": "array", "Description": "The matching records for this page, with public keys. Orders include invoice number, dates, status, payment totals and balance. Fulfillment queue rows also include line count, total quantity and packed progress. Activity and concerns include safe administrator diagnostics. Report groups contain period/customer/product keys and aggregate amounts.", "Required": true, "SubmittedIn": "Response body" }, "TotalMatches": { "Type": "integer", "Description": "Count of all matching records before pagination.", "Required": true, "SubmittedIn": "Response body" }, "ReturnedCount": { "Type": "integer", "Description": "Number of records in this response.", "Required": true, "SubmittedIn": "Response body" }, "HasMore": { "Type": "boolean", "Description": "True if more matches remain.", "Required": true, "SubmittedIn": "Response body" }, "NextCursor": { "Type": "string", "Description": "Continuation for the identical filters; omitted when complete. Follow it to retrieve every match.", "Required": true, "SubmittedIn": "Response body" }, "MatchingTotals": { "Type": "object", "Description": "Whole-search InvoiceTotal, Receipts, Refunds and BalanceDue; not totals of just this page.", "Required": true, "SubmittedIn": "Response body" }, "DateType": { "Type": "string", "Description": "Date basis actually applied to the search.", "Required": true, "SubmittedIn": "Response body" }, "StatusCatalog": { "Type": "array", "Description": "Every Code and its plain-language Description.", "Required": true, "SubmittedIn": "Response body" } }, "Errors": [ { "SuccessCode": "VALIDATION_FAILED", "Meaning": "One or more required request values are missing or malformed.", "Recovery": "Use the field descriptions and constraints in this contract, correct the named fields, and retry the same capability.", "Recoverable": true }, { "SuccessCode": "UNAUTHORIZED", "Meaning": "The submitted identity or token does not authorize this capability or record scope.", "Recovery": "Use the correct active authentication token and confirm the required account role.", "Recoverable": true }, { "SuccessCode": "NOT_FOUND", "Meaning": "A submitted public key did not identify a record within this capability\u0027s declared scope.", "Recovery": "Re-check the key against a current list or creation response; do not treat this as a missing web route.", "Recoverable": true }, { "SuccessCode": "CONFLICT", "Meaning": "The capability could not complete for an execution failure.", "Recovery": "Read the returned message and error detail. Retry only when the response identifies a recoverable condition.", "Recoverable": false }, { "SuccessCode": "EMAIL_NOT_SENT", "Meaning": "The capability could not complete for an execution failure.", "Recovery": "Read the returned message and error detail. Retry only when the response identifies a recoverable condition.", "Recoverable": false }, { "SuccessCode": "FAILED", "Meaning": "The capability could not complete for an execution failure.", "Recovery": "Read the returned message and error detail. Retry only when the response identifies a recoverable condition.", "Recoverable": false } ], "ActionResponse": { "RequiredResponseFields": [ "SuccessCode" ], "SuccessCodes": [ "SUCCESS" ], "FailureCodes": [ "VALIDATION_FAILED", "UNAUTHORIZED", "NOT_FOUND", "CONFLICT", "EMAIL_NOT_SENT", "FAILED" ], "NonFinalCodes": [], "MissingOrEmptyResponse": "Treat as FAILED.", "Rule": "The endpoint response is authoritative. Only an exact SuccessCode value listed in SuccessCodes means the business action succeeded; HTTP status alone does not declare the AIXE outcome." }, "StatusCatalog": [ { "Code": "Pending", "Description": "Draft invoice that has not been submitted." }, { "Code": "Ordered", "Description": "Submitted order awaiting preparation and packing." }, { "Code": "Being Fulfilled", "Description": "Preparation and packing are underway." }, { "Code": "Ready For Pickup", "Description": "Pickup order ready for the customer to collect." }, { "Code": "Ready For Delivery", "Description": "Delivery order packaged and awaiting courier collection; not dispatched." }, { "Code": "Out For Delivery", "Description": "Delivery order dispatched and on its way to the customer." }, { "Code": "Completed", "Description": "Order collected or delivered." }, { "Code": "Cancelled", "Description": "Order cancelled. This does not refund or remove payment transactions." }, { "Code": "Abandoned", "Description": "Unpaid checkout left unfinished. Reserved stock is released and recurrence is stopped." } ] }