Goodeye Billing API

openapi: 3.2.0
info:
  title: Goodeye Billing API
  version: 0.1.0
servers:
- url: /v1
tags:
- name: Billing
paths:
  /billing/checkout:
    post:
      summary: Billing Checkout
      description: 'Start a Pro subscription and get a hosted checkout link.


        Returns ``{"checkout_url": ...}``. Errors: ``billing_not_enabled`` when

        self-service billing is not configured, ``already_subscribed`` when the

        caller already has an active subscription.'
      operationId: billing_checkout_billing_checkout_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Billing Checkout Billing Checkout Post
      tags:
      - Billing
  /billing/subscription/cancel:
    post:
      summary: Billing Subscription Cancel
      description: 'Cancel your Pro subscription at the end of the current billing period.


        Returns ``{"status": ..., "access_until": ...}`` where ``access_until`` is

        the ISO-8601 end of the paid period, or null. Access continues until then.

        Error: ``no_active_subscription`` when there is nothing to cancel.'
      operationId: billing_subscription_cancel_billing_subscription_cancel_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Billing Subscription Cancel Billing Subscription Cancel Post
      tags:
      - Billing
  /billing/portal:
    post:
      summary: Billing Portal
      description: 'Get a link to the billing portal to manage your subscription and payment method.


        Returns ``{"portal_url": ...}``. Error: ``billing_not_enabled`` when

        self-service billing is not configured.'
      operationId: billing_portal_billing_portal_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Billing Portal Billing Portal Post
      tags:
      - Billing
  /billing/credits/purchase:
    post:
      summary: Billing Credits Purchase
      description: 'Buy a one-time credit top-up.


        Charges the default payment method on file when one exists and returns

        ``{"status": "charged", "amount_usd": ..., "new_balance_usd": ...}``.

        Otherwise returns ``{"status": "checkout_required", "checkout_url": ...}``

        for a hosted checkout session so the purchase can complete interactively.

        Errors: ``billing_not_enabled`` when self-service billing is not

        configured, ``invalid_amount`` when the requested amount falls outside

        the allowed range.'
      operationId: billing_credits_purchase_billing_credits_purchase_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_PurchaseCreditsIn'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Billing Credits Purchase Billing Credits Purchase Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Billing
  /billing/auto-top-up:
    get:
      summary: Billing Auto Top Up Get
      description: 'Check your automatic credit top-up configuration and this month''s spend toward it.


        Returns ``{"enabled": ..., "threshold_usd": ..., "amount_usd": ...,

        "monthly_cap_usd": ..., "monthly_spent_usd": ..., "status": ...,

        "last_failure_reason": ...}``. A caller who has never configured

        automatic top-ups gets a disabled default block, not an error.'
      operationId: billing_auto_top_up_get_billing_auto_top_up_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Billing Auto Top Up Get Billing Auto Top Up Get
      tags:
      - Billing
    put:
      summary: Billing Auto Top Up Put
      description: 'Turn on automatic credit top-ups and set (or update) their terms.


        Requires a default payment method already on file: make a manual credit

        purchase first to save one. Returns the resolved config block, the same

        shape as the GET route. Errors: ``no_payment_method`` (409) when no

        default payment method is on file, ``invalid_amount`` (400) when the

        amount, threshold, or monthly cap falls outside the allowed range.

        Re-running this also clears any previously failed automatic top-up

        state, acting as a retry.'
      operationId: billing_auto_top_up_put_billing_auto_top_up_put
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_ConfigureAutoTopUpIn'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Billing Auto Top Up Put Billing Auto Top Up Put
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Billing
    delete:
      summary: Billing Auto Top Up Delete
      description: 'Turn off automatic credit top-ups.


        Returns the config block with ``enabled`` false. Clears any stored

        failure state; leaves the previously configured amount, threshold, and

        monthly cap in place for a later re-enable.'
      operationId: billing_auto_top_up_delete_billing_auto_top_up_delete
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Billing Auto Top Up Delete Billing Auto Top Up Delete
      tags:
      - Billing
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    _ConfigureAutoTopUpIn:
      properties:
        amount_usd:
          type: integer
          title: Amount Usd
          description: Amount to add, in whole US dollars, each time your balance drops below the threshold.
        threshold_usd:
          anyOf:
          - type: integer
          - type: 'null'
          title: Threshold Usd
          description: Balance, in whole US dollars, that triggers an automatic top-up. Defaults to the top-up amount when omitted.
        monthly_cap_usd:
          anyOf:
          - type: integer
          - type: 'null'
          title: Monthly Cap Usd
          description: Maximum total, in whole US dollars, automatic top-ups can spend in a calendar month. Defaults to four times the top-up amount when omitted.
      type: object
      required:
      - amount_usd
      title: _ConfigureAutoTopUpIn
      description: Request body for ``PUT /billing/auto-top-up``.
    _PurchaseCreditsIn:
      properties:
        amount_usd:
          type: integer
          title: Amount Usd
          description: Amount of credits to buy, in whole US dollars.
        idempotency_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Idempotency Key
          description: Optional caller-supplied key that makes a retried purchase request safe to resend without buying credits twice.
      type: object
      required:
      - amount_usd
      title: _PurchaseCreditsIn
      description: Request body for ``POST /billing/credits/purchase``.