AdvisorPPC Stripe API

openapi: 3.2.0
info:
  title: AdvisorPPC Stripe API
  version: 0.1.0
tags:
- name: Stripe
paths:
  /api/stripe/checkout/{tier}:
    post:
      tags:
      - Stripe
      summary: Create Checkout
      description: '``ga`` / ``ga_s`` are the browser''s ``_ga`` / ``_ga_`` cookie

        values and ``ad_consent`` its advertising choice, for the server-side GA4

        purchase (services/ga4_measurement.py). They never reach Stripe.'
      operationId: create_checkout_api_stripe_checkout__tier__post
      security:
      - HTTPBearer: []
      parameters:
      - name: tier
        in: path
        required: true
        schema:
          type: string
          title: Tier
      - name: cycle
        in: query
        required: false
        schema:
          type: string
          default: monthly
          title: Cycle
      - name: switch
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Switch
      - name: ga
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Ga
      - name: ga_s
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Ga S
      - name: ad_consent
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Ad Consent
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: X-Tenant-Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/stripe/addons/{kind}:
    post:
      tags:
      - Stripe
      summary: Add Addon
      description: 'Add extra accounts or seats to the tenant''s live subscription.


        Confirm-then-charge: the connectors UI has already shown the price from

        the priced 409 and the owner clicked. Stripe invoices the proration now;

        the webhook makes the quantity durable. The row is updated here too so the

        owner''s retry succeeds before the webhook lands.'
      operationId: add_addon_api_stripe_addons__kind__post
      security:
      - HTTPBearer: []
      parameters:
      - name: kind
        in: path
        required: true
        schema:
          type: string
          title: Kind
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: X-Tenant-Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/AddonIn'
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddonOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/stripe/portal:
    post:
      tags:
      - Stripe
      summary: Open Portal
      description: Open the Stripe billing portal for the tenant's linked customer.
      operationId: open_portal_api_stripe_portal_post
      security:
      - HTTPBearer: []
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: X-Tenant-Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/stripe/webhook:
    post:
      tags:
      - Stripe
      summary: Webhook
      description: 'Receive a Stripe event and apply it to per-tenant subscription state.


        No user auth — authenticity is the Stripe signature (verified in

        ``parse_event`` when a webhook secret is configured).'
      operationId: webhook_api_stripe_webhook_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookOut'
components:
  schemas:
    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
    PortalOut:
      properties:
        url:
          type: string
          title: Url
      type: object
      required:
      - url
      title: PortalOut
    CheckoutOut:
      properties:
        url:
          type: string
          title: Url
      type: object
      required:
      - url
      title: CheckoutOut
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AddonOut:
      properties:
        ok:
          type: boolean
          title: Ok
        kind:
          type: string
          title: Kind
        extra_accounts:
          type: integer
          title: Extra Accounts
        extra_seats:
          type: integer
          title: Extra Seats
        monthly_usd_each:
          type: integer
          title: Monthly Usd Each
      type: object
      required:
      - ok
      - kind
      - extra_accounts
      - extra_seats
      - monthly_usd_each
      title: AddonOut
    WebhookOut:
      properties:
        ok:
          type: boolean
          title: Ok
        handled:
          type: string
          title: Handled
      type: object
      required:
      - ok
      - handled
      title: WebhookOut
    AddonIn:
      properties:
        quantity:
          type: integer
          title: Quantity
          default: 1
      type: object
      title: AddonIn
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer