openapi: 3.0.3
info:
  title: Octopus Energy Public API
  version: '1.0'
  description: |
    The Octopus Energy Public API is a free JSON-over-HTTPS REST API exposing the
    UK product catalog, electricity and gas tariffs, electricity and gas meter
    points, half-hourly smart-meter consumption, and industry grid supply points.

    Authentication uses HTTP Basic auth with a per-customer API key as the
    username and an empty password. Products and tariffs endpoints are open and
    do not require authentication; meter-point and consumption endpoints require
    a key for the account that owns the meter.
  contact:
    name: Octopus Energy Developer Support
    url: https://developer.octopus.energy/docs/api/
  license:
    name: Octopus Energy API Terms
    url: https://octopus.energy/policies/
servers:
- url: https://api.octopus.energy/v1
  description: Public production API
security:
- basicAuth: []
- {}
tags:
- name: Products
  description: Octopus Energy product catalog and tariff lookups.
- name: ElectricityTariffs
  description: Electricity tariff unit rates and standing charges.
- name: GasTariffs
  description: Gas tariff unit rates and standing charges.
- name: ElectricityMeterPoints
  description: Electricity meter points (MPAN) and registered meters.
- name: GasMeterPoints
  description: Gas meter points (MPRN) and registered meters.
- name: Consumption
  description: Half-hourly smart-meter consumption readings.
- name: Industry
  description: UK industry references such as grid supply points.
paths:
  /products/:
    get:
      tags: [Products]
      summary: List Products
      description: List Octopus Energy products. Filter by availability, business type, variant, and brand.
      operationId: listProducts
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      - name: is_variable
        in: query
        schema: {type: boolean}
      - name: is_green
        in: query
        schema: {type: boolean}
      - name: is_tracker
        in: query
        schema: {type: boolean}
      - name: is_prepay
        in: query
        schema: {type: boolean}
      - name: is_business
        in: query
        schema: {type: boolean}
      - name: available_at
        in: query
        description: ISO 8601 timestamp filtering products available at that moment.
        schema: {type: string, format: date-time}
      - name: brand
        in: query
        schema: {type: string}
      responses:
        '200':
          description: A paginated list of products.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedProductList'
  /products/{product_code}/:
    get:
      tags: [Products]
      summary: Retrieve a Product
      description: Retrieve a single product including its electricity and gas tariffs by region.
      operationId: getProduct
      parameters:
      - $ref: '#/components/parameters/ProductCode'
      - name: tariffs_active_at
        in: query
        schema: {type: string, format: date-time}
      responses:
        '200':
          description: The requested product.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductDetail'
  /products/{product_code}/electricity-tariffs/{tariff_code}/standard-unit-rates/:
    get:
      tags: [ElectricityTariffs]
      summary: List Electricity Standard Unit Rates
      description: Half-hourly or daily standard unit rates for an electricity tariff such as Agile Octopus or Octopus Tracker.
      operationId: listElectricityStandardUnitRates
      parameters:
      - $ref: '#/components/parameters/ProductCode'
      - $ref: '#/components/parameters/TariffCode'
      - $ref: '#/components/parameters/PeriodFrom'
      - $ref: '#/components/parameters/PeriodTo'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paginated list of standard unit rates.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUnitRateList'
  /products/{product_code}/electricity-tariffs/{tariff_code}/standing-charges/:
    get:
      tags: [ElectricityTariffs]
      summary: List Electricity Standing Charges
      operationId: listElectricityStandingCharges
      parameters:
      - $ref: '#/components/parameters/ProductCode'
      - $ref: '#/components/parameters/TariffCode'
      - $ref: '#/components/parameters/PeriodFrom'
      - $ref: '#/components/parameters/PeriodTo'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paginated list of standing charges.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedStandingChargeList'
  /products/{product_code}/electricity-tariffs/{tariff_code}/day-unit-rates/:
    get:
      tags: [ElectricityTariffs]
      summary: List Electricity Day Unit Rates
      operationId: listElectricityDayUnitRates
      parameters:
      - $ref: '#/components/parameters/ProductCode'
      - $ref: '#/components/parameters/TariffCode'
      - $ref: '#/components/parameters/PeriodFrom'
      - $ref: '#/components/parameters/PeriodTo'
      responses:
        '200':
          description: A paginated list of day unit rates.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUnitRateList'
  /products/{product_code}/electricity-tariffs/{tariff_code}/night-unit-rates/:
    get:
      tags: [ElectricityTariffs]
      summary: List Electricity Night Unit Rates
      operationId: listElectricityNightUnitRates
      parameters:
      - $ref: '#/components/parameters/ProductCode'
      - $ref: '#/components/parameters/TariffCode'
      - $ref: '#/components/parameters/PeriodFrom'
      - $ref: '#/components/parameters/PeriodTo'
      responses:
        '200':
          description: A paginated list of night unit rates.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUnitRateList'
  /products/{product_code}/gas-tariffs/{tariff_code}/standard-unit-rates/:
    get:
      tags: [GasTariffs]
      summary: List Gas Standard Unit Rates
      operationId: listGasStandardUnitRates
      parameters:
      - $ref: '#/components/parameters/ProductCode'
      - $ref: '#/components/parameters/TariffCode'
      - $ref: '#/components/parameters/PeriodFrom'
      - $ref: '#/components/parameters/PeriodTo'
      responses:
        '200':
          description: A paginated list of gas standard unit rates.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUnitRateList'
  /products/{product_code}/gas-tariffs/{tariff_code}/standing-charges/:
    get:
      tags: [GasTariffs]
      summary: List Gas Standing Charges
      operationId: listGasStandingCharges
      parameters:
      - $ref: '#/components/parameters/ProductCode'
      - $ref: '#/components/parameters/TariffCode'
      - $ref: '#/components/parameters/PeriodFrom'
      - $ref: '#/components/parameters/PeriodTo'
      responses:
        '200':
          description: A paginated list of gas standing charges.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedStandingChargeList'
  /electricity-meter-points/{mpan}/:
    get:
      tags: [ElectricityMeterPoints]
      summary: Retrieve an Electricity Meter Point
      description: Retrieve information about an electricity meter point including the GSP region and registered meters.
      operationId: getElectricityMeterPoint
      security:
      - basicAuth: []
      parameters:
      - $ref: '#/components/parameters/MPAN'
      responses:
        '200':
          description: An electricity meter point.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ElectricityMeterPoint'
  /electricity-meter-points/{mpan}/meters/{serial_number}/consumption/:
    get:
      tags: [Consumption]
      summary: List Electricity Consumption
      description: List half-hourly smart-meter electricity consumption readings for the given meter.
      operationId: listElectricityConsumption
      security:
      - basicAuth: []
      parameters:
      - $ref: '#/components/parameters/MPAN'
      - $ref: '#/components/parameters/SerialNumber'
      - $ref: '#/components/parameters/PeriodFrom'
      - $ref: '#/components/parameters/PeriodTo'
      - name: order_by
        in: query
        schema: {type: string, enum: [period, -period]}
      - name: group_by
        in: query
        schema: {type: string, enum: [hour, day, week, month, quarter]}
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paginated list of consumption readings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedConsumptionList'
  /gas-meter-points/{mprn}/:
    get:
      tags: [GasMeterPoints]
      summary: Retrieve a Gas Meter Point
      operationId: getGasMeterPoint
      security:
      - basicAuth: []
      parameters:
      - $ref: '#/components/parameters/MPRN'
      responses:
        '200':
          description: A gas meter point.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GasMeterPoint'
  /gas-meter-points/{mprn}/meters/{serial_number}/consumption/:
    get:
      tags: [Consumption]
      summary: List Gas Consumption
      operationId: listGasConsumption
      security:
      - basicAuth: []
      parameters:
      - $ref: '#/components/parameters/MPRN'
      - $ref: '#/components/parameters/SerialNumber'
      - $ref: '#/components/parameters/PeriodFrom'
      - $ref: '#/components/parameters/PeriodTo'
      - name: group_by
        in: query
        schema: {type: string, enum: [hour, day, week, month, quarter]}
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paginated list of gas consumption readings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedConsumptionList'
  /industry/grid-supply-points/:
    get:
      tags: [Industry]
      summary: List Grid Supply Points
      description: List UK grid supply points and resolve the GSP for a postcode.
      operationId: listGridSupplyPoints
      parameters:
      - name: postcode
        in: query
        schema: {type: string}
      responses:
        '200':
          description: A list of grid supply points.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedGridSupplyPointList'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication with the customer API key as the username and an empty password.
  parameters:
    Page:
      name: page
      in: query
      schema: {type: integer, minimum: 1}
    PageSize:
      name: page_size
      in: query
      schema: {type: integer, minimum: 1, maximum: 1500}
    ProductCode:
      name: product_code
      in: path
      required: true
      schema: {type: string}
      description: Product code, for example AGILE-24-10-01 or VAR-22-11-01.
    TariffCode:
      name: tariff_code
      in: path
      required: true
      schema: {type: string}
      description: Tariff code, for example E-1R-AGILE-24-10-01-A.
    PeriodFrom:
      name: period_from
      in: query
      schema: {type: string, format: date-time}
      description: ISO 8601 inclusive start of the period.
    PeriodTo:
      name: period_to
      in: query
      schema: {type: string, format: date-time}
      description: ISO 8601 exclusive end of the period.
    MPAN:
      name: mpan
      in: path
      required: true
      schema: {type: string}
      description: Meter Point Administration Number for electricity (13 digits).
    MPRN:
      name: mprn
      in: path
      required: true
      schema: {type: string}
      description: Meter Point Reference Number for gas.
    SerialNumber:
      name: serial_number
      in: path
      required: true
      schema: {type: string}
  schemas:
    Paginated:
      type: object
      properties:
        count: {type: integer}
        next: {type: string, nullable: true}
        previous: {type: string, nullable: true}
    Product:
      type: object
      properties:
        code: {type: string}
        direction: {type: string, enum: [IMPORT, EXPORT]}
        full_name: {type: string}
        display_name: {type: string}
        description: {type: string}
        is_variable: {type: boolean}
        is_green: {type: boolean}
        is_tracker: {type: boolean}
        is_prepay: {type: boolean}
        is_business: {type: boolean}
        is_restricted: {type: boolean}
        term: {type: integer, nullable: true}
        available_from: {type: string, format: date-time}
        available_to: {type: string, format: date-time, nullable: true}
        brand: {type: string}
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
    ProductDetail:
      allOf:
      - $ref: '#/components/schemas/Product'
      - type: object
        properties:
          tariffs_active_at: {type: string, format: date-time}
          single_register_electricity_tariffs:
            type: object
            additionalProperties:
              $ref: '#/components/schemas/TariffByPayment'
          dual_register_electricity_tariffs:
            type: object
            additionalProperties:
              $ref: '#/components/schemas/TariffByPayment'
          single_register_gas_tariffs:
            type: object
            additionalProperties:
              $ref: '#/components/schemas/TariffByPayment'
          sample_quotes:
            type: object
          sample_consumption:
            type: object
    TariffByPayment:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/Tariff'
    Tariff:
      type: object
      properties:
        code: {type: string}
        standing_charge_exc_vat: {type: number}
        standing_charge_inc_vat: {type: number}
        online_discount_exc_vat: {type: number}
        online_discount_inc_vat: {type: number}
        dual_fuel_discount_exc_vat: {type: number}
        dual_fuel_discount_inc_vat: {type: number}
        exit_fees_exc_vat: {type: number}
        exit_fees_inc_vat: {type: number}
        standard_unit_rate_exc_vat: {type: number}
        standard_unit_rate_inc_vat: {type: number}
        day_unit_rate_exc_vat: {type: number}
        day_unit_rate_inc_vat: {type: number}
        night_unit_rate_exc_vat: {type: number}
        night_unit_rate_inc_vat: {type: number}
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
    Link:
      type: object
      properties:
        href: {type: string}
        method: {type: string}
        rel: {type: string}
    UnitRate:
      type: object
      properties:
        value_exc_vat: {type: number}
        value_inc_vat: {type: number}
        valid_from: {type: string, format: date-time}
        valid_to: {type: string, format: date-time, nullable: true}
        payment_method: {type: string, nullable: true}
    StandingCharge:
      type: object
      properties:
        value_exc_vat: {type: number}
        value_inc_vat: {type: number}
        valid_from: {type: string, format: date-time}
        valid_to: {type: string, format: date-time, nullable: true}
        payment_method: {type: string, nullable: true}
    ElectricityMeterPoint:
      type: object
      properties:
        gsp: {type: string, description: Grid Supply Point group, e.g. _A through _P.}
        mpan: {type: string}
        profile_class: {type: integer}
        meters:
          type: array
          items:
            $ref: '#/components/schemas/Meter'
    GasMeterPoint:
      type: object
      properties:
        mprn: {type: string}
        consumption_standard: {type: number}
        meters:
          type: array
          items:
            $ref: '#/components/schemas/Meter'
    Meter:
      type: object
      properties:
        serial_number: {type: string}
        registers:
          type: array
          items:
            type: object
            properties:
              identifier: {type: string}
              rate: {type: string}
              is_settlement_register: {type: boolean}
    ConsumptionReading:
      type: object
      properties:
        consumption: {type: number, description: kWh consumed in the interval.}
        interval_start: {type: string, format: date-time}
        interval_end: {type: string, format: date-time}
    GridSupplyPoint:
      type: object
      properties:
        group_id: {type: string}
    PaginatedProductList:
      allOf:
      - $ref: '#/components/schemas/Paginated'
      - type: object
        properties:
          results:
            type: array
            items:
              $ref: '#/components/schemas/Product'
    PaginatedUnitRateList:
      allOf:
      - $ref: '#/components/schemas/Paginated'
      - type: object
        properties:
          results:
            type: array
            items:
              $ref: '#/components/schemas/UnitRate'
    PaginatedStandingChargeList:
      allOf:
      - $ref: '#/components/schemas/Paginated'
      - type: object
        properties:
          results:
            type: array
            items:
              $ref: '#/components/schemas/StandingCharge'
    PaginatedConsumptionList:
      allOf:
      - $ref: '#/components/schemas/Paginated'
      - type: object
        properties:
          results:
            type: array
            items:
              $ref: '#/components/schemas/ConsumptionReading'
    PaginatedGridSupplyPointList:
      allOf:
      - $ref: '#/components/schemas/Paginated'
      - type: object
        properties:
          results:
            type: array
            items:
              $ref: '#/components/schemas/GridSupplyPoint'