xpoz-ai Billing API

openapi: 3.2.0
info:
  title: XPOZ Billing API
  version: 1.0.0
  description: 'Social media data API for Twitter/X, Instagram, Reddit, and TikTok.


    **Data endpoints** (`/api/data/*`) are authenticated with an API access key and are metered against the account''s credits. Most stored-data endpoints share the same query options: `fields` selects which attributes to return, `since`/`until` bound the date range, and `responseType` picks between a synchronous first page (`fast`), a full paged query run as a background operation (`paging`), and a CSV export (`csv`). `/live` endpoints fetch from the platform on demand and page with a cursor instead.


    **Account, billing, and crawl-settings endpoints** are used by the XPOZ dashboard and authenticate with the user''s session.'
servers:
- url: /
  description: This server
tags:
- name: Billing
  description: Stripe checkout, subscription changes, and add-on purchases.
paths:
  /api/extra-credits/purchase:
    post:
      tags:
      - Billing
      summary: Buy extra credits
      description: Charge the saved payment method for extra credits.
      security:
      - UserSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                dollarsAmount:
                  type: integer
                  minimum: 1
              required:
              - dollarsAmount
      responses:
        '200':
          description: Charged, or requires client-side confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseResult'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/UnauthorizedMessage'
        '402':
          description: Card declined or payment rejected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentError'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorField'
      operationId: postExtraCreditsPurchase
  /api/extra-credits/confirm:
    post:
      tags:
      - Billing
      summary: Confirm extra credits payment
      description: Finalize a purchase after the client confirmed the payment intent.
      security:
      - UserSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                paymentIntentId:
                  type: string
                  minLength: 1
              required:
              - paymentIntentId
      responses:
        '200':
          description: Charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeConfirmed'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/UnauthorizedMessage'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorField'
      operationId: postExtraCreditsConfirm
  /api/extra-csv-rows/purchase:
    post:
      tags:
      - Billing
      summary: Buy extra CSV rows
      description: Charge the saved payment method for extra CSV export rows.
      security:
      - UserSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                dollarsAmount:
                  type: integer
                  minimum: 1
              required:
              - dollarsAmount
      responses:
        '200':
          description: Charged, or requires client-side confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseResult'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/UnauthorizedMessage'
        '402':
          description: Card declined or payment rejected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentError'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorField'
      operationId: postExtraCsvRowsPurchase
  /api/extra-csv-rows/confirm:
    post:
      tags:
      - Billing
      summary: Confirm extra CSV rows payment
      description: Finalize a purchase after the client confirmed the payment intent.
      security:
      - UserSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                paymentIntentId:
                  type: string
                  minLength: 1
              required:
              - paymentIntentId
      responses:
        '200':
          description: Charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeConfirmed'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/UnauthorizedMessage'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorField'
      operationId: postExtraCsvRowsConfirm
  /api/extra-tracked-items:
    get:
      tags:
      - Billing
      summary: Get extra tracked items
      description: Number of extra tracked items on the subscription.
      security:
      - UserSession: []
      responses:
        '200':
          description: Quantity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtraTrackedItems'
        '401':
          $ref: '#/components/responses/UnauthorizedMessage'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorField'
      operationId: getExtraTrackedItems
    patch:
      tags:
      - Billing
      summary: Set extra tracked items
      description: Change the extra tracked items quantity on the subscription (prorated).
      security:
      - UserSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                quantity:
                  type: integer
                  minimum: 0
              required:
              - quantity
      responses:
        '200':
          description: Quantity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtraTrackedItems'
        '400':
          description: Validation failed, reduction below current usage, or not available on the plan.
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/SimpleError'
                - $ref: '#/components/schemas/ErrorField'
        '401':
          $ref: '#/components/responses/UnauthorizedMessage'
        '402':
          description: Card declined or payment rejected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentError'
        '404':
          description: No active subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorField'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorField'
      operationId: patchExtraTrackedItems
  /api/stripe/create-checkout-session:
    post:
      tags:
      - Billing
      summary: Create a Stripe Checkout session
      description: Create a Checkout session for a subscription or one-time payment.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                priceId:
                  type: string
                quantity:
                  type: integer
                  default: 1
                mode:
                  type: string
                  enum:
                  - subscription
                  - payment
                successUrl:
                  type: string
                  format: uri
                cancelUrl:
                  type: string
                  format: uri
                customerEmail:
                  type: string
                  format: email
                descopeUserId:
                  type: string
                metadata:
                  type: object
                  additionalProperties:
                    type: string
              required:
              - priceId
              - successUrl
              - cancelUrl
              - descopeUserId
      responses:
        '200':
          description: Session.
          content:
            application/json:
              schema:
                type: object
                properties:
                  sessionId:
                    type: string
                  url:
                    anyOf:
                    - type: string
                    - type: 'null'
                required:
                - sessionId
                - url
        '400':
          description: Missing fields, or the user already has an active subscription.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  subscriptionId:
                    type: string
                  planId:
                    type: string
                required:
                - error
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorField'
      operationId: postStripeCreateCheckoutSession
  /api/stripe/subscription:
    patch:
      tags:
      - Billing
      summary: Change subscription plan
      description: Switch the caller's active subscription to another plan and/or billing period.
      security:
      - UserSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                planName:
                  type: string
                billingPeriod:
                  type: string
                  enum:
                  - monthly
                  - annual
              required:
              - planName
      responses:
        '200':
          description: Changed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  message:
                    type: string
                  subscription:
                    type: object
                    properties:
                      planName:
                        type: string
                      billingPeriod:
                        type: string
                        enum:
                        - monthly
                        - annual
                    required:
                    - planName
                    - billingPeriod
                required:
                - success
                - message
                - subscription
        '400':
          description: Validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorField'
        '401':
          $ref: '#/components/responses/UnauthorizedMessage'
        '404':
          description: No active subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorField'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
      operationId: patchStripeSubscription
  /api/stripe/webhooks:
    post:
      tags:
      - Billing
      summary: Stripe webhook
      description: Receives Stripe events. The raw body is verified against the `stripe-signature` header.
      security: []
      parameters:
      - name: stripe-signature
        in: header
        required: true
        schema:
          type: string
        description: Stripe webhook signature.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StripeWebhookEvent'
      responses:
        '200':
          description: Received.
          content:
            application/json:
              schema:
                type: object
                properties:
                  received:
                    type: boolean
                    const: true
                required:
                - received
        '400':
          description: Missing or invalid signature.
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorField'
      operationId: postStripeWebhooks
  /api/trial/token:
    post:
      tags:
      - Billing
      summary: Create a trial token (deprecated)
      description: Trial tokens are no longer issued.
      security: []
      responses:
        '410':
          description: Gone.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
      deprecated: true
      operationId: postTrialToken
components:
  responses:
    ValidationError:
      description: Query or body validation failed. `message` joins all validation issues with `, `.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimpleError'
    UnauthorizedMessage:
      description: Missing or invalid credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MessageError'
  schemas:
    SimpleError:
      type: object
      properties:
        success:
          type: boolean
          const: false
        message:
          type: string
      required:
      - success
      - message
    ChargeConfirmed:
      type: object
      properties:
        charged:
          type: boolean
          const: true
        newBalance:
          type: number
      required:
      - charged
      - newBalance
    ExtraTrackedItems:
      type: object
      properties:
        extraTrackedItems:
          type: integer
      required:
      - extraTrackedItems
    PurchaseResult:
      anyOf:
      - type: object
        properties:
          charged:
            type: boolean
            const: true
          newBalance:
            type: number
        required:
        - charged
        - newBalance
      - type: object
        properties:
          charged:
            type: boolean
            const: false
          requiresAction:
            type: boolean
            const: true
          paymentIntentClientSecret:
            type: string
        required:
        - charged
        - requiresAction
        - paymentIntentClientSecret
      description: Either the charge succeeded, or the card requires additional action (3DS) and the client must confirm the payment intent, then call the matching `/confirm` endpoint.
    ErrorField:
      type: object
      properties:
        error:
          type: string
      required:
      - error
    PaymentError:
      type: object
      properties:
        error:
          type: string
          enum:
          - card_declined
          - payment_rejected
        declineCode:
          type: string
        message:
          type: string
      required:
      - error
      - message
    MessageError:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    StripeWebhookEvent:
      type: object
      additionalProperties: true
      description: 'Raw Stripe event payload. Handled types: `customer.subscription.created`, `customer.subscription.updated`, `customer.subscription.deleted`, `checkout.session.completed`, `payment_intent.succeeded`, `payment_intent.payment_failed`.'
  securitySchemes:
    AccessKey:
      type: http
      scheme: bearer
      description: 'XPOZ API access key, created from the dashboard or `POST /api/tokens`. Send as `Authorization: Bearer <access key>`.'
    UserSession:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Descope session JWT of a logged-in dashboard user. Send as `Authorization: Bearer <session JWT>`.'