{
  "Protocol": "AIXE",
  "Version": "1.0",
  "Endpoint": "/aixe/customer/create-order-request",
  "DiscoveryRequest": "GET /aixe/customer/create-order-request/?",
  "CanonicalHelpTrigger": "GET /aixe/customer/create-order-request/?",
  "ActionRequest": "POST /aixe/customer/create-order-request",
  "Method": "POST",
  "ContentType": "application/json; charset=utf-8",
  "Title": "Create An Order Request",
  "AuthenticationRequired": true,
  "AccessType": "Customer",
  "Purpose": "Creates a Pending order request for the authenticated customer, saves its item quantities, and calculates the invoice totals without collecting payment.",
  "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.",
  "InventoryRules": "Drafts do not reserve stock. Completing an administrator order or placing a customer order rechecks every physical product and deducts available stock atomically with submission. Scheduled service lines do not consume physical stock. If a product has become unavailable or insufficient, the whole submission fails: no stock or order status changes are committed. VALIDATION_FAILED explains which product needs replacing or reducing. Customers can use customer/replace-invoice-items on their own Pending invoice with the complete desired Items selection, current RowVersion, then place it again. Administrator item editors remain available for administrator orders. Repeating completion does not deduct again. Completing a quantity edit applies only the difference, and a removed line returns its previously deducted units when the edited order is completed. Concurrent orders cannot consume the same last units. CONFLICT means reload the order before retrying. Stock is not automatically returned by cancellation or refund; those actions do not establish that physical goods were returned. Existing historical invoices are not batch-deducted. Recurring generation also deducts physical stock in its invoice transaction; a shortage rolls back that occurrence and leaves it due for a later retry.",
  "ThingsYouCanAsk": [
    "Start an order for two dozen chocolate donuts.",
    "Prepare a delivery order for Friday morning.",
    "Create a pickup request, but don\u0027t place it yet."
  ],
  "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": "List current products first, then confirm every product, quantity, fulfillment choice, requested timing, and note with the human.",
    "CorrectWorkflow": [
      "List current products first, then confirm every product, quantity, fulfillment choice, requested timing, and note with the human.",
      "Obtain the human\u0027s approval immediately before creating the request and explain that the business must still confirm it."
    ],
    "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": "The temporary Customer token returned by the AIXE login capability.",
      "Required": true,
      "SubmittedIn": "JSON body"
    },
    "FulfillmentType": {
      "Type": "string",
      "Description": "The requested fulfillment method.",
      "Required": true,
      "SubmittedIn": "JSON body",
      "AllowedValues": [
        "Pickup",
        "Delivery"
      ]
    },
    "Items": {
      "Type": "array",
      "Description": "One or more requested product lines. Each line identifies the current ProductKey and a whole-number Quantity.",
      "Required": true,
      "SubmittedIn": "JSON body",
      "ItemFields": {
        "ProductKey": {
          "Type": "string",
          "Description": "The public product key returned by List Available Treats.",
          "Required": true,
          "SubmittedIn": "JSON body"
        },
        "Quantity": {
          "Type": "integer",
          "Description": "The whole-number quantity requested for this product. Scheduled units become independent quantity-one occurrences; use separate quantity-one lines to supply different service addresses.",
          "Required": true,
          "SubmittedIn": "JSON body",
          "MinValue": 1
        },
        "ServiceAddressLine1": {
          "Type": "string",
          "Description": "Street address for this service occurrence.",
          "Required": false,
          "SubmittedIn": "JSON body",
          "MaxLength": 200
        },
        "ServiceAddressLine2": {
          "Type": "string",
          "Description": "Second address line.",
          "Required": false,
          "SubmittedIn": "JSON body",
          "MaxLength": 200
        },
        "ServiceCity": {
          "Type": "string",
          "Description": "City for this service occurrence.",
          "Required": false,
          "SubmittedIn": "JSON body",
          "MaxLength": 100
        },
        "ServiceState": {
          "Type": "string",
          "Description": "State for this service occurrence.",
          "Required": false,
          "SubmittedIn": "JSON body",
          "MaxLength": 50
        },
        "ServicePostalCode": {
          "Type": "string",
          "Description": "Postal code for this service occurrence.",
          "Required": false,
          "SubmittedIn": "JSON body",
          "MaxLength": 20
        },
        "ServiceInstructions": {
          "Type": "string",
          "Description": "Instructions for this service occurrence.",
          "Required": false,
          "SubmittedIn": "JSON body",
          "MaxLength": 1000
        }
      }
    }
  },
  "OptionalFields": {
    "RequestedDate": {
      "Type": "string (date)",
      "Description": "The preferred fulfillment date.",
      "Required": false,
      "SubmittedIn": "JSON body",
      "Format": "YYYY-MM-DD"
    },
    "RequestedTime": {
      "Type": "string (time)",
      "Description": "The preferred local fulfillment time.",
      "Required": false,
      "SubmittedIn": "JSON body",
      "Format": "HH:MM[:SS]"
    },
    "Notes": {
      "Type": "string",
      "Description": "Customer-approved instructions for the whole order.",
      "Required": false,
      "SubmittedIn": "JSON body",
      "MaxLength": 2000
    }
  },
  "BusinessRules": [
    "The caller must be authenticated with the Customer role.",
    "This capability creates a Pending invoice and does not collect payment.",
    "Every ProductKey must identify an active, available product with sufficient quantity on hand.",
    "Delivery uses the customer\u0027s saved address and requires a currently served city.",
    "Internal numeric identifiers are never returned."
  ],
  "ResponseFields": {
    "SuccessCode": {
      "Type": "string",
      "Description": "The authoritative action outcome. SUCCESS means the Pending order request was saved.",
      "Required": true,
      "SubmittedIn": "Response body"
    },
    "OrderCreated": {
      "Type": "boolean",
      "Description": "True when the invoice, invoice items, and customer relationship were saved.",
      "Required": true,
      "SubmittedIn": "Response body"
    },
    "Order": {
      "Type": "object",
      "Description": "The complete new Pending order, including header, customer snapshot, delivery details, notes, items, totals, payment status, and activity history.",
      "Required": true,
      "SubmittedIn": "Response body"
    },
    "NextStep": {
      "Type": "string",
      "Description": "Plain-language guidance about placement and business confirmation.",
      "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": "NOT_AVAILABLE",
      "Meaning": "A requested product, quantity, or fulfillment option is not currently available.",
      "Recovery": "Refresh current catalog and business information, revise the request with the human, and retry only after approval.",
      "Recoverable": true
    },
    {
      "SuccessCode": "BUSINESS_RULE_FAILED",
      "Meaning": "The request was understood but a declared business or workflow rule was not satisfied.",
      "Recovery": "Explain the governing rule to the human and retry only after the required condition or decision changes.",
      "Recoverable": true
    },
    {
      "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",
      "NOT_AVAILABLE",
      "BUSINESS_RULE_FAILED",
      "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."
  }
}