{
  "Protocol": "AIXE",
  "Version": "1.0",
  "Endpoint": "/aixe/owner/get-recurrence",
  "DiscoveryRequest": "GET /aixe/owner/get-recurrence/?",
  "CanonicalHelpTrigger": "GET /aixe/owner/get-recurrence/?",
  "ActionRequest": "POST /aixe/owner/get-recurrence",
  "Method": "POST",
  "ContentType": "application/json",
  "Title": "Get Recurrence",
  "AuthenticationRequired": true,
  "AccessType": "Site Administrator",
  "Purpose": "Read an invoice\u0027s fixed-hour recurrence schedule and available intervals.",
  "ThingsYouCanAsk": [
    "Repeat this invoice every week.",
    "Stop future invoices for this subscription.",
    "When will my next invoice be created?"
  ],
  "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 the invoice and its current RowVersion before changing the schedule.",
    "CorrectWorkflow": [
      "Read the invoice and its current RowVersion before changing the schedule.",
      "Create or edit the draft, configure recurrence, then place or complete the order.",
      "Only SUCCESS means the action succeeded."
    ],
    "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"
    },
    "InvoiceKey": {
      "Type": "string",
      "Description": "Public UUID identifying the invoice being read or changed. Customer endpoints additionally enforce ownership.",
      "Required": true,
      "SubmittedIn": "JSON body",
      "Format": "UUID"
    }
  },
  "OptionalFields": {},
  "BusinessRules": [
    "Products with IsSubscription true require exactly one line with quantity 1 on a dedicated invoice. Ordinary invoices may contain multiple ordinary products and optionally recur. Subscription classification is snapshotted on invoice items; catalog edits do not change historical invoices. SubscriptionDays on a product accepts 1 to 36500 whole days, default 30, stored as SubscriptionHours (days times 24). Adding a subscription product automatically copies its hours to the invoice and sets the first renewal one interval after addition. Later product edits never change saved invoices. Customers cannot edit subscription schedules, including through customer/update-recurrence; administrators manage them. Ordinary RecurringHours supports 24, 168, 336, 720, 2160, 4320 or 8760 fixed hours. Subscription invoices also support custom whole-day intervals from 24 to 876000 hours. Generated copies cannot activate their own schedule. Three months means 90 days. FirstOccurrenceDate is a UTC timestamp ending in Z and means the first NEW invoice to generate, not the existing source invoice. Pending and Cancelled invoices never generate invoices. The first date cannot change after generation begins. LastRecurrenceDate records the last scheduled occurrence, not the delayed request time. Stopping recurrence preserves history. New invoices copy current source prices and items, receive new numbers and keys, start Ordered and unpaid, and have recurrence disabled. Payments, packing, provider assignments and confirmed appointments are not copied; services start Unscheduled. No card charge or automatic email occurs. The public /renewinvoices GET or POST trigger creates at most one due occurrence per source per call, reading all due sources in database pages of 100; MoreDue indicates catch-up work remains. Repeated and simultaneous calls cannot duplicate an occurrence. Calls are safe to retry; authentication is unnecessary for this trigger. Schedule edits require the normal authorized account, invoice ownership, current RowVersion."
  ],
  "ResponseFields": {
    "Schedule": {
      "Type": "object",
      "Description": "Returned by get/update: InvoiceKey, RowVersion, RecurringHours (0 means stopped), FirstOccurrenceDate, LastRecurrenceDate, NextOccurrenceDate and public invoice summary. UTC dates; no next date when inactive.",
      "Required": false,
      "SubmittedIn": "Response body"
    },
    "SourceInvoiceKey": {
      "Type": "string",
      "Description": "Returned by get-recurrence for a generated invoice when the caller can access the original invoice. Manage ongoing recurrence on that source invoice.",
      "Required": false,
      "SubmittedIn": "Response body",
      "Format": "UUID"
    },
    "Intervals": {
      "Type": "object",
      "Description": "Available fixed-hour values and friendly labels, returned by get-recurrence.",
      "Required": false,
      "SubmittedIn": "Response body"
    },
    "Schedules": {
      "Type": "array",
      "Description": "Returned by list-recurrences: invoice summaries with recurrence dates; TotalMatches, ReturnedCount, HasMore and NextCursor describe pagination. Send NextCursor with identical Search to continue.",
      "Required": false,
      "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": "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",
      "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."
  }
}