Aura Historia Billing API

openapi: 3.2.0
info:
  title: Aura Historia API Reference Billing API
  description: '## Overview


    The Aura Historia API powers the Aura Historia antiques platform and its partner-facing integrations. It exposes product discovery, listing source discovery, personalization, partner onboarding, and integration

    workflows on top of Aura Historia''s serverless AWS platform. This reference is designed for two audiences:

    - **Internal developers** building Aura Historia product-listings, operational tooling, and backoffice workflows

    - **External partners and integrators** synchronizing inventory, consuming platform data, or

    integrating with delegated access


    ## Core API domains


    - **ProductListings and listing-sources** — search, retrieve, and explore product-listings, related product-listings, product

    history, and listing source data

    - **Personalization** — manage watchlists, saved search filters, and user notifications

    - **Partner workflows** — submit partnership applications, maintain partnerships, ingest catalog data

    in batches, and receive WooCommerce webhooks

    - **Identity and access** — manage user accounts, Aura Historia access tokens, and OAuth 2.0

    clients and token flows

    - **Billing** — create Stripe checkout, billing-portal, and subscription-management sessions


    ## Authentication model


    The API uses more than one authentication scheme depending on the route:


    - **`BearerAuth`** — Cognito **access** JWT bearer tokens for authenticated user, admin, and

    partner-user workflows. Cognito ID tokens are not accepted as API credentials. - **`AccessTokenAuth`** — Aura Historia opaque bearer access tokens created via

    `/v1/me/access-tokens` or OAuth 2.0, primarily intended for partner automations and server-to-server

    ingestion scenarios. When a route lists multiple security schemes, any one of the listed schemes may be accepted. Some read endpoints can also be called without authentication, while a valid user token may enrich

    the response with personalized state such as watchlist, notification, or search-filter metadata. Aura Historia access

    tokens receive only the sections their read scopes permit; see `ProductListingUserStateData`. ## MCP interface


    The separate `https://mcp.aura-historia.com/v1` Streamable HTTP endpoint accepts opaque Aura access tokens only. Public calls may omit credentials; invalid supplied credentials receive HTTP 401, protected operations require their declared scopes, and insufficient grants receive HTTP 403 with the complete required scope set. Credential-free protected-resource metadata is served on the MCP host at `/.well-known/oauth-protected-resource` and `/.well-known/oauth-protected-resource/v1`. See the MCP contract for protocol and discovery details. ## Data and response conventions


    - **PATCH:** an omitted request member remains unchanged. A documented nullable PATCH member

    accepts `null` to clear its value; `null` for any other member returns `400 BAD_BODY_VALUE`. Use `[]`, not `null`, to replace a non-null collection with an empty collection. Empty HTTP

    bodies are invalid, `{}` is a valid object-PATCH no-op, and the partner-product PATCH `[]`

    remains a valid empty batch. Responses may omit absent optional values. - Product detail, watchlist, and saved-search match reads accept optional **`language`** and

    **`currency`** parameters. Currency defaults to `EUR`. Detail pricing contains the seller''s source

    amounts, converted display amounts, and FX valuation metadata. Active product-listings use the latest persisted

    snapshot; sold product-listings use their immutable sale snapshot. Product history preserves immutable source values and accepts optional `currency` for historical FX display projections. History text is not localized. - Request-wide REST errors are returned as **`application/problem+json`** using a consistent RFC 9457-style structure

    with `status`, `title`, `error`, optional `source`, and optional `detail`.'
  version: 1.0.0
  contact:
    name: Aura-Historia Team
    url: https://aura-historia.com/
  license:
    name: License
    url: https://github.com/aura-historia/backend/blob/develop/LICENSE
servers:
- url: https://api.stage.aura-historia.com
  description: Development environment
- url: https://api.aura-historia.com
  description: Production environment
tags:
- name: Billing
  description: Stripe checkout, billing-portal, and subscription-management session creation for authenticated users.
paths:
  /v1/me/billing/checkout:
    post:
      summary: Create Stripe checkout session
      description: 'Creates a hosted Stripe Checkout session for the authenticated user to start a subscription.

        The request body selects the desired subscription plan and billing cycle.

        The backend first creates and persists a Stripe customer for the user, then creates a

        subscription-mode Checkout session for that customer. Stripe and PostgreSQL are separate

        systems; an association remains persisted if later session creation fails.

        This endpoint can only be used when the user does not already have a `stripe_customer_id`.

        Requires Cognito JWT or Aura Historia access-token authentication. Delegated access tokens require `users:read`.'
      operationId: postBillingCheckout
      tags:
      - Billing
      security:
      - BearerAuth: []
      requestBody:
        required: true
        description: Desired subscription plan and billing cycle for the new Stripe checkout session.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostBillingCheckoutData'
            examples:
              pro_monthly:
                summary: Create a monthly Pro checkout session
                value:
                  plan: PRO
                  cycle: MONTHLY
              ultimate_yearly:
                summary: Create a yearly Ultimate checkout session
                value:
                  plan: ULTIMATE
                  cycle: YEARLY
      responses:
        '201':
          description: Checkout session created successfully
          headers:
            Access-Control-Allow-Origin:
              description: CORS header
              schema:
                type: string
              example: '*'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingSessionUrlData'
              example:
                url: https://checkout.stripe.com/c/pay/cs_test_123
        '400':
          description: Bad request - request body is missing, empty, malformed JSON, or contains unsupported enum values
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                missing_body:
                  summary: Request body is absent or empty
                  value:
                    status: 400
                    title: Bad Request
                    error: BAD_BODY_VALUE
                    detail: Body cannot be empty
                invalid_plan:
                  summary: Unsupported billing plan
                  value:
                    status: 400
                    title: Bad Request
                    error: BAD_BODY_VALUE
                    detail: unknown variant `ENTERPRISE`, expected `PRO` or `ULTIMATE` at line 1 column 20
        '401':
          description: Unauthorized - invalid or missing JWT token
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                status: 401
                title: Unauthorized
                error: UNAUTHORIZED
        '404':
          description: User not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                status: 404
                title: Not Found
                error: USER_NOT_FOUND
        '409':
          description: Conflict - the authenticated user already has a Stripe customer record
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                status: 409
                title: Conflict
                error: STRIPE_CUSTOMER_ALREADY_EXISTS
                detail: User has already created a Stripe customer; use the customer-portal endpoint instead
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                status: 500
                title: Internal Server Error
                error: INTERNAL_SERVER_ERROR
  /v1/me/billing/portal:
    post:
      summary: Create Stripe billing portal session
      description: 'Creates a hosted Stripe customer-portal session for the authenticated user.

        This endpoint does not accept a request body.

        It can only be used when the user already has a persisted `stripe_customer_id`.

        Requires Cognito JWT or Aura Historia access-token authentication. Delegated access tokens require `users:read`.'
      operationId: postBillingPortal
      tags:
      - Billing
      security:
      - BearerAuth: []
      responses:
        '201':
          description: Billing portal session created successfully
          headers:
            Access-Control-Allow-Origin:
              description: CORS header
              schema:
                type: string
              example: '*'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingSessionUrlData'
              example:
                url: https://billing.stripe.com/p/session/test_123
        '401':
          description: Unauthorized - invalid or missing JWT token
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                status: 401
                title: Unauthorized
                error: UNAUTHORIZED
        '404':
          description: User not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                status: 404
                title: Not Found
                error: USER_NOT_FOUND
        '422':
          description: Unprocessable Content - the authenticated user has no Stripe customer record yet
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                status: 422
                title: Unprocessable Content
                error: STRIPE_CUSTOMER_DOES_NOT_EXIST
                detail: User has never had a Stripe subscription; no customer-portal session can be created
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                status: 500
                title: Internal Server Error
                error: INTERNAL_SERVER_ERROR
  /v1/me/billing/manage:
    post:
      summary: Create Stripe billing management session
      description: 'Creates a hosted Stripe billing session for the authenticated user through a single entrypoint.

        - Users with tier `FREE` receive a Stripe Checkout session for the requested `plan` and `cycle`.

        - Users with tier `PRO` or `ULTIMATE` receive a Stripe customer-portal session instead.


        The request body is required for all callers and must contain supported billing enum values.

        For free users, the backend uses the provided `plan` and `cycle` to select the configured Stripe

        price and creates a Stripe customer first when none exists yet. For paid users, the backend still

        validates that the body is present and well-formed, but returns a portal session based on the

        stored Stripe customer rather than purchasing a new plan.


        Requires Cognito JWT or Aura Historia access-token authentication. Delegated access tokens require `users:read`.'
      operationId: postBillingManage
      tags:
      - Billing
      security:
      - BearerAuth: []
      requestBody:
        required: true
        description: Desired subscription plan and billing cycle. Required for all callers.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostBillingCheckoutData'
            examples:
              pro_monthly:
                summary: Valid request body for a free user upgrading to Pro monthly
                value:
                  plan: PRO
                  cycle: MONTHLY
              ultimate_yearly:
                summary: Valid request body for a free user upgrading to Ultimate yearly
                value:
                  plan: ULTIMATE
                  cycle: YEARLY
      responses:
        '201':
          description: Billing management session created successfully
          headers:
            Access-Control-Allow-Origin:
              description: CORS header
              schema:
                type: string
              example: '*'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingSessionUrlData'
              examples:
                checkout_session:
                  summary: Free user receives a Stripe Checkout session URL
                  value:
                    url: https://checkout.stripe.com/c/pay/cs_test_manage_free
                portal_session:
                  summary: Paid user receives a Stripe customer-portal session URL
                  value:
                    url: https://billing.stripe.com/p/session/manage_paid
        '400':
          description: Bad request - request body is missing, empty, malformed JSON, or contains unsupported enum values
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                missing_body:
                  summary: Request body is absent or empty
                  value:
                    status: 400
                    title: Bad Request
                    error: BAD_BODY_VALUE
                    detail: Body cannot be empty
                invalid_plan:
                  summary: Unsupported billing plan
                  value:
                    status: 400
                    title: Bad Request
                    error: BAD_BODY_VALUE
                    detail: unknown variant `ENTERPRISE`, expected `PRO` or `ULTIMATE` at line 1 column 20
        '401':
          description: Unauthorized - invalid or missing JWT token
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                status: 401
                title: Unauthorized
                error: UNAUTHORIZED
        '404':
          description: User not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                status: 404
                title: Not Found
                error: USER_NOT_FOUND
        '422':
          description: Unprocessable Content - the authenticated paid user has no Stripe customer record yet
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                status: 422
                title: Unprocessable Content
                error: STRIPE_CUSTOMER_DOES_NOT_EXIST
                detail: User has never had a Stripe subscription; no customer-portal session can be created
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                status: 500
                title: Internal Server Error
                error: INTERNAL_SERVER_ERROR
components:
  schemas:
    BillingSessionUrlData:
      type: object
      description: Hosted Stripe session URL returned by the billing endpoints
      required:
      - url
      properties:
        url:
          type: string
          format: uri
          description: Hosted Stripe URL that the frontend should redirect the authenticated user to
          example: https://checkout.stripe.com/c/pay/cs_test_123
    PostBillingCheckoutData:
      type: object
      description: Request body for creating a Stripe checkout session for a subscription purchase
      required:
      - plan
      - cycle
      properties:
        plan:
          $ref: '#/components/schemas/BillingPlanData'
        cycle:
          $ref: '#/components/schemas/BillingCycleData'
    ApiError:
      type: object
      description: Standard error response format (RFC 9457)
      required:
      - status
      - title
      - error
      properties:
        status:
          type: integer
          description: HTTP status code
          example: 400
        title:
          type: string
          description: HTTP status code in human-readable form
          example: Bad Request
        error:
          type: string
          description: Error code identifier
          example: BAD_PARAMETER
        source:
          $ref: '#/components/schemas/ApiErrorSource'
        detail:
          type: string
          description: Human-readable error message
          example: 'Expected any of: ''true'' or ''false''. Got: ''invalid'''
    ApiErrorSource:
      type: object
      description: Information about the source of the error
      required:
      - field
      - type
      properties:
        field:
          type: string
          description: Name of the field that caused the error
          example: listingSourceId
        type:
          type: string
          enum:
          - QUERY
          - PATH
          - HEADER
          - BODY
          description: Type of parameter that caused the error
          example: PATH
    BillingCycleData:
      type: string
      description: Billing interval that should be used for the subscription purchase
      enum:
      - MONTHLY
      - YEARLY
      example: MONTHLY
    BillingPlanData:
      type: string
      description: Subscription plan that should be purchased through Stripe Checkout
      enum:
      - PRO
      - ULTIMATE
      example: PRO
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Cognito access JWT bearer token. Signature, issuer, client, token use and expiry

        are validated locally. Signed integer `auth_time` and `iat` claims are required;

        sessions authenticated at or before the persisted local revocation cutoff are rejected.

        This check shares the existing identity lookup and makes no live Cognito status request.

        Revocation requested only in Cognito is not observed immediately; already-issued JWTs

        can remain accepted until expiry. Use the administrator session-revocation endpoint

        for immediate local enforcement. Database authentication failures return

        `503 AUTH_TEMPORARILY_UNAVAILABLE`.

        This scheme is used for authenticated user routes and for partner routes that accept Cognito user tokens.

        '
    AccessTokenAuth:
      type: http
      scheme: bearer
      bearerFormat: opaque
      description: 'Aura Historia bearer access token created through `/v1/me/access-tokens`.

        Tokens are sent as standard bearer authorization headers.

        Selected partner routes accept this scheme instead of the removed partner API-key flow.

        '
x-tagGroups:
- name: Operations
  tags:
  - Operations
- name: Discovery
  tags:
  - ProductListings
  - ListingSources
  - Auctions
- name: User Experience
  tags:
  - Search Filters
  - Watchlist
  - Notifications
  - User Account
  - Billing
  - Newsletter
- name: Partner & Platform Integrations
  tags:
  - Partnerships
  - PartnershipApplications
  - OAuth