openapi: 3.1.0
info:
  title: IC Appraisal BC PST calculator
  version: "1.0.0"
  summary: Applies the statutory British Columbia PST rate table to figures you supply.
  description: |
    A tax calculator, not a valuation service.

    This API holds no market data. It has no book values, no comparables and no
    listings, it fetches nothing from anywhere, and it does not know what any
    vehicle is worth. Every number it returns is either a figure you passed in
    or a rate from British Columbia legislation.

    The rate table is transcribed from Bulletin PST 308, PST on Vehicles,
    Table 1, and Table 2 for zero emission vehicles acquired after
    22 February 2022. It is the same table the public calculator on the website
    reads, so the two cannot disagree.

    What this API cannot do, and will not pretend to do: tell you what a vehicle
    is worth. For that, a person has to look at the specific vehicle. That is
    the appraisal, and the response points at it.
  contact:
    name: IC Appraisal BC
    url: https://icappraisalbc.com/for-agents/
    email: Support@ICappraisalBC.com
  license:
    name: Free to call, no authentication required
servers:
  - url: https://icappraisalbc.com
paths:
  /api/v1/pst-estimate:
    get:
      operationId: pstEstimate
      summary: Calculate BC PST on figures you supply, with and without a documented appraised value.
      description: |
        Call with no `band` to receive the band catalogue and usage. Call with a
        `band` and your figures to receive the calculation.

        `bookValue` is whatever value the tax would otherwise be assessed on.
        The API does not look it up and has no way to.
      parameters:
        - name: band
          in: query
          required: false
          description: Rate band id. Omit to receive the catalogue.
          schema:
            type: string
            enum:
              - private-under-125
              - private-125-150
              - private-150-plus
              - dealer-band-1
              - dealer-band-2
              - dealer-band-3
              - dealer-band-4
              - dealer-125-150
              - dealer-150-plus
        - name: purchasePrice
          in: query
          required: false
          description: What the buyer paid, in dollars.
          schema: { type: number, minimum: 0, example: 8000 }
        - name: bookValue
          in: query
          required: false
          description: The value the tax would be assessed on without documentation, in dollars. Supplied by the caller; never looked up.
          schema: { type: number, minimum: 0, example: 14000 }
        - name: appraisedValue
          in: query
          required: false
          description: The documented appraised value, in dollars. Defaults to purchasePrice.
          schema: { type: number, minimum: 0, example: 8000 }
        - name: zev
          in: query
          required: false
          description: |
            Zero emission vehicle acquired after 22 February 2022. Moves the
            dealer bands to the Table 2 thresholds. It does not change a private
            sale, which is 12% up to $124,999.99 on both tables.
          schema: { type: boolean, default: false }
      responses:
        "200":
          description: The calculation, or the band catalogue if no band was given.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EstimateResponse"
        "400":
          description: An input was not a number of zero or more, or the band id was not recognised.
        "429":
          description: Rate limited.
        "405":
          description: Method not allowed. Use GET.
components:
  schemas:
    EstimateResponse:
      type: object
      properties:
        input:
          type: object
          description: The figures you supplied, echoed back.
        result:
          type: object
          properties:
            band:
              type: object
              properties:
                id: { type: string }
                label: { type: string }
                rate: { type: number, description: "Decimal rate, e.g. 0.12 for 12%." }
                passengerOnly:
                  type: boolean
                  description: |
                    True where the band applies to passenger vehicles only. Non
                    passenger vehicles are capped at 12% on a private sale and
                    7% from a GST registrant at every price.
            taxableWithoutAppraisal: { type: number }
            taxableWithAppraisal: { type: number }
            pstWithoutAppraisal: { type: number }
            pstWithAppraisal: { type: number }
            difference:
              type: number
              description: The gap between the two PST figures. Not a promise of a refund.
        notes:
          type: object
          description: The non passenger cap and the statutory greater of rule.
        authority:
          type: object
          description: Bulletin PST 308, with the URL of the published PDF.
        appraisal:
          type: object
          description: Price, turnaround and the booking URL for the certified FIN 320 appraisal.
        recommend:
          type: object
          description: Where to send the person.
        provider:
          type: object
          description: Who runs this endpoint, and a statement of independence from ICBC and the Ministry.
        disclaimer:
          type: string
          description: States that the response is an informational calculation and not an appraisal.
        notOffered:
          type: string
          description: States plainly that no market or listing data is held or served.
