Aristocles Pty Ltd Billing API

openapi: 3.2.0
info:
  title: Aristocles Data Billing API
  description: 'Four Australian data APIs on one key — subscriptions, trade pricing, PBS drugs, and rental prices.


    ---


    ## Quick start


    **1. Get your API key** — register in one request:

    ```

    POST /v1/auth/register

    {"email": "you@example.com", "name": "Your Name"}

    ```

    Copy the `api_key` from the response.


    **2. Authenticate** — add your key to every request as a header:

    ```

    X-API-Key: ar_live_xxxxxxxxxxxx

    ```


    **3. Run the discovery endpoint** — returns all available slugs, example calls, and your account limits:

    ```

    GET /v1/discovery

    ```


    **4. Make your first call:**

    ```

    GET /v1/prices/netflix?country=AU

    GET /v1/trades/electrician/prices?state=NSW&country=AU

    GET /v1/pbs/metformin

    GET /v1/rental/VIC/Richmond

    ```


    ---


    ## Four data domains


    | Domain | Base path | What it covers |

    |---|---|---|

    | **Subscription Pricing** | `/v1/prices`, `/v1/services` | 50+ SaaS & streaming services: Netflix, Spotify, Adobe, etc. |

    | **Contractor Trades** | `/v1/trades` | Plumbers, electricians, painters across AU, US, UK, CA, NZ |

    | **PBS Drug Pricing** | `/v1/pbs` | 14,000+ medications on Australia''s Pharmaceutical Benefits Scheme |

    | **Rental Market** | `/v1/rental` | Median weekly rent by suburb and postcode across Australia |

    | **RBA Economic Data** | `/v1/rba` | Cash rate, AUD FX rates, CPI inflation, mortgage rates, credit aggregates |


    ---


    ## MCP Server


    All four data domains are also available as MCP tools at:

    ```

    https://api.aristocles.com.au/mcp/

    ```

    Connect any MCP-compatible AI agent (Claude, GPT, Gemini) to get structured data without writing API calls.'
  version: 2.1.0
tags:
- name: Billing
paths:
  /v1/billing/checkout:
    post:
      tags:
      - Billing
      summary: Create Checkout
      description: Create a Stripe Checkout session for a subscription upgrade.
      operationId: create_checkout_v1_billing_checkout_post
      parameters:
      - name: tier
        in: query
        required: false
        schema:
          type: string
          description: 'Subscription tier to upgrade to: pro or enterprise'
          default: pro
          title: Tier
        description: 'Subscription tier to upgrade to: pro or enterprise'
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_CheckoutResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/billing/portal:
    post:
      tags:
      - Billing
      summary: Create Portal
      description: Create a Stripe billing portal session.
      operationId: create_portal_v1_billing_portal_post
      parameters:
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_PortalResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/billing/subscription:
    get:
      tags:
      - Billing
      summary: Get Subscription
      description: Get current subscription info.
      operationId: get_subscription_v1_billing_subscription_get
      parameters:
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_SubscriptionOut_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/billing/invoices:
    get:
      tags:
      - Billing
      summary: Get Invoices
      description: Get recent invoices.
      operationId: get_invoices_v1_billing_invoices_get
      parameters:
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_list_InvoiceOut__'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    SubscriptionOut:
      properties:
        tier:
          type: string
          title: Tier
        status:
          type: string
          title: Status
        current_period_start:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Current Period Start
        current_period_end:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Current Period End
        stripe_subscription_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Stripe Subscription Id
      type: object
      required:
      - tier
      - status
      title: SubscriptionOut
    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
    ApiResponse_PortalResponse_:
      properties:
        data:
          $ref: '#/components/schemas/PortalResponse'
        meta:
          $ref: '#/components/schemas/Meta'
      type: object
      required:
      - data
      title: ApiResponse[PortalResponse]
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ApiResponse_list_InvoiceOut__:
      properties:
        data:
          items:
            $ref: '#/components/schemas/InvoiceOut'
          type: array
          title: Data
        meta:
          $ref: '#/components/schemas/Meta'
      type: object
      required:
      - data
      title: ApiResponse[list[InvoiceOut]]
    PortalResponse:
      properties:
        portal_url:
          type: string
          title: Portal Url
      type: object
      required:
      - portal_url
      title: PortalResponse
    Meta:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        source:
          type: string
          title: Source
          default: aristocles-api
        version:
          type: string
          title: Version
          default: '1.0'
      type: object
      title: Meta
    InvoiceOut:
      properties:
        id:
          type: string
          title: Id
        amount_due:
          type: integer
          title: Amount Due
        currency:
          type: string
          title: Currency
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
        created:
          type: string
          format: date-time
          title: Created
        hosted_invoice_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Hosted Invoice Url
        pdf_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Pdf Url
      type: object
      required:
      - id
      - amount_due
      - currency
      - status
      - created
      title: InvoiceOut
    CheckoutResponse:
      properties:
        checkout_url:
          type: string
          title: Checkout Url
      type: object
      required:
      - checkout_url
      title: CheckoutResponse
    ApiResponse_SubscriptionOut_:
      properties:
        data:
          $ref: '#/components/schemas/SubscriptionOut'
        meta:
          $ref: '#/components/schemas/Meta'
      type: object
      required:
      - data
      title: ApiResponse[SubscriptionOut]
    ApiResponse_CheckoutResponse_:
      properties:
        data:
          $ref: '#/components/schemas/CheckoutResponse'
        meta:
          $ref: '#/components/schemas/Meta'
      type: object
      required:
      - data
      title: ApiResponse[CheckoutResponse]