generated: '2026-08-29'
method: derived
source: >-
  openapi/aarons-hpp-openapi.json + live probes of api.aarons.com, login.aarons.com and the
  Salesforce OCAPI surface on www.aarons.com + Aaron's own published application bundle at
  https://myaccount.aarons.com/assets/index-CNr2NkAf.js
provider: Aaron's
providerId: aarons
summary: >-
  Aaron's has no published API conventions. This document is derived from the one contract it does
  publish and from what its own hosts and shipped JavaScript demonstrably do. The headline is that
  the estate has no cross-cutting convention at all: four error shapes, two authentication models,
  two versioning strategies, and no idempotency, pagination, tracing, or rate-limit signalling on
  any surface.
auth_style:
  hpp: Bearer token in the Authorization header (securityDefinitions.Bearer, apiKey-in-header).
  customer: OpenID Connect / OAuth 2.0 via Okta on login.aarons.com, PKCE S256.
  storefront: OCAPI client_id, required on every call, not publicly issued.
  see: authentication/aarons-authentication.yml
idempotency:
  supported: false
  header: null
  scope: null
  retention: null
  evidence: >-
    No Idempotency-Key header, no idempotency parameter, and no replay semantics on any of the 15
    published paths — including /AuthorizeSession, /CreateToken and /SaveToken, all of which are
    money-adjacent. A retried payment authorisation has no declared safety property.
  note: >-
    NO Idempotency pointer is emitted in apis.yml. The Conventions artifact exists; the idempotency
    support it would attest to does not.
pagination:
  supported: na
  evidence: The published contract exposes no collection or list operations.
field_expansion:
  supported: false
sparse_fieldsets:
  supported: false
metadata:
  supported: partial
  detail: >-
    ResponseStatus.Meta and ResponseError.Meta are free-form string dictionaries. CustomFields
    appears on the Repay postback payloads. Neither is documented.
request_id_tracing:
  supported: false
  detail: >-
    No request-id or correlation-id header is declared in the contract or observed on any probed
    response. Okta responses carry errorId, but that is Okta's, and only on Okta's own host.
  session_correlation: >-
    The HPP flow correlates by SessionGuid and TokenGuid, passed as query parameters. That is a
    business correlator, not a request trace.
versioning:
  see: lifecycle/aarons-lifecycle.yml
  summary: HPP is unversioned (basePath "/"); the storefront is path-pinned to OCAPI v21_3.
error_envelope:
  see: errors/aarons-problem-types.yml
  summary: Four incompatible shapes across four hosts. None is RFC 9457.
rate_limit_signaling:
  supported: false
  headers_observed: []
  see: rate-limits/aarons-rate-limits.yml
content_negotiation:
  consumes: [application/json]
  produces: [application/json]
  source: openapi/aarons-hpp-openapi.json
naming:
  paths: PascalCase resource segments (/CreateSession/2, /AuthorizeSession, /MemoryBearerToken).
  properties: PascalCase (SessionGuid, TokenGuid, ErrorCode, Last4).
  operation_ids: '<Tag>_<Verb> — machine-generated by ServiceStack, e.g. AuthorizeSession_Post.'
  note: >-
    Path names are RPC-style verbs, not resources. Every path additionally declares GET, PUT, POST
    and DELETE regardless of what the operation means, which is a ServiceStack "any-verb" routing
    artefact rather than a designed HTTP method contract. A caller cannot tell from the document
    which verb is real.
reversibility:
  grade: undocumented
  credit: 0.0
  applies: true
  summary: >-
    The published contract has real write surfaces — it authorises payments, tokenises cards and
    stores customer payment instruments — and it documents no reversal operation and no window for
    any of them. Nothing is asserted below that Aaron's does not itself publish.
  write_surfaces:
    - operation: AuthorizeSession_Post
      path: /AuthorizeSession
      consequence: Authorises a payment against a session.
      reversal_operation: null
      window: null
      evidence: >-
        The document declares AuthorizeSession_Delete on the same path, but ServiceStack emits all
        four verbs for every route; there is no description, no response schema difference and no
        documentation establishing DELETE as a void/reversal. Treating it as one would be a guess
        with money attached, so it is not recorded as a reversal.
    - operation: CreateToken_Post / SaveToken_Post
      path: /CreateToken, /SaveToken
      consequence: Tokenises and stores a card against the customer profile.
      reversal_operation: null
      window: null
    - operation: AutoPayCustomerRetry_Post
      path: /AutoPayCustomerRetry
      consequence: Retries a failed automatic payment.
      reversal_operation: null
      window: null
  observed_but_unpublished:
    - detail: >-
        Aaron's own customer application bundle calls reversal-shaped endpoints that appear in NO
        published contract — api.aarons.com/account/Profile/DeleteOnlineAccount,
        api.aarons.com/home/Club/Cancel, and a promise-to-pay flow at
        api.aarons.com/home/payment/promisetopay. They are recorded as observed, with no window and
        no semantics claimed, because Aaron's publishes neither.
      source: https://myaccount.aarons.com/assets/index-CNr2NkAf.js
dry_run_mode:
  supported: false
observed_undocumented_surface:
  note: >-
    NOT A CONTRACT. Aaron's ships an unminified-enough React bundle that names its own API base URLs
    and route templates. Recorded here as evidence of the shape of the estate, explicitly NOT
    converted into an OpenAPI — a reverse-engineered spec would score as though Aaron's published
    one, and Aaron's has published nothing here.
  source: https://myaccount.aarons.com/assets/index-CNr2NkAf.js
  gateway: https://api.aarons.com
  gateway_platform: Azure API Management (JSON fault envelope on every path)
  bases:
    - https://api.aarons.com/account
    - https://api.aarons.com/home
    - https://api.aarons.com/ezpay
    - https://api.aarons.com/onboarding
    - https://api.aarons.com/support
    - https://api.aarons.com/Acadia
  example_routes:
    - '{accountUrl}/Club/Enroll'
    - '{accountUrl}/Club/Claim/Create'
    - '{accountUrl}/Payment/GetRecentPaymentRequest'
    - '{accountUrl}/Profile/DeleteOnlineAccount'
    - '{ezPayUrl}/cardTokenizationSession'
    - '{ezPayUrl}/ezpay/customerschedules'
    - '{ezPayUrl}/ezpay/onetimepaymentandezpayschedules'
    - '{ezPayUrl}/ezpay/processretrypayment'
    - '{homeUrl}/payment/promisetopay'
    - '{onboardingUrl}/onboarding/getUserOnboardingInfo'
  probe_result: >-
    Every base path answers 404 with the Azure APIM envelope when called anonymously at its root —
    the gateway is live, the routes are real, and nothing about them is documented.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com