openapi: 3.2.0
info:
  title: Arcadia API Reference Plug API
  version: 0.3.0
  contact:
    email: platformsupport@arcadia.com
  x-logo:
    url: images/arcadia_logo.png
servers:
- url: https://api.arcadia.com
security:
- bearerAuth: []
tags:
- name: Plug
paths:
  /plug/utility_statements:
    get:
      tags:
      - Plug
      summary: List Utility Statements
      description: Returns a paginated list of UtilityStatements for all users, or filtered by `utility_account_id`. Default ordered by descending `updated_at`.
      operationId: getUtilityStatements
      parameters:
      - $ref: '#/components/parameters/deprecatedClientUserIdQueryParam'
      - $ref: '#/components/parameters/utilityAccountIdQueryParam'
      - $ref: '#/components/parameters/paginationLimitParam'
      - $ref: '#/components/parameters/paginationUpdatedAfterParam'
      - $ref: '#/components/parameters/paginationUpdatedBeforeParam'
      - $ref: '#/components/parameters/paginationOrderParam'
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      responses:
        '200':
          description: Success
          headers:
            Arcadia-Version:
              $ref: '#/components/headers/ArcVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUtilityStatements'
        '404':
          description: Not Found
          headers:
            Arcadia-Version:
              $ref: '#/components/headers/ArcVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UtilityAccountNotFoundError'
        '422':
          description: Unprocessable Entity
          headers:
            Arcadia-Version:
              $ref: '#/components/headers/ArcVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UtilityStatementsFeatureAvailabilityError'
  /plug/utility_statements/{utility_statement_id}:
    get:
      tags:
      - Plug
      summary: Get Utility Statement
      description: Returns a single UtilityStatement specified by ID.
      operationId: getUtilityStatement
      parameters:
      - $ref: '#/components/parameters/utilityStatementIdInPathParam'
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      responses:
        '200':
          description: Success
          headers:
            Arcadia-Version:
              $ref: '#/components/headers/ArcVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UtilityStatement'
components:
  parameters:
    paginationUpdatedBeforeParam:
      in: query
      name: updated_before
      required: false
      description: ISO8601 datetime, used to traverse paginated responses. Use of this parameter is mutually exclusive with `updated_after`.
      schema:
        type: string
        format: date-time
    utilityAccountIdQueryParam:
      in: query
      name: utility_account_id
      required: false
      description: A utility account id to filter the list of returned items by.
      schema:
        type: integer
    paginationOrderParam:
      in: query
      name: order
      required: false
      description: Used to specify the order in which records should be returned. Currently ordered by `updated_at` timestamp.
      schema:
        type: string
        enum:
        - asc
        - desc
        default: desc
    paginationUpdatedAfterParam:
      in: query
      name: updated_after
      required: false
      description: ISO8601 datetime, used to traverse paginated responses. Use of this parameter is mutually exclusive with `updated_before`.
      schema:
        type: string
        format: date-time
    utilityStatementIdInPathParam:
      name: utility_statement_id
      in: path
      required: true
      schema:
        type: integer
    deprecatedClientUserIdQueryParam:
      in: query
      name: client_user_id
      required: false
      deprecated: true
      description: A client_user_id to filter the list of returned items by. This field is deprecated, prefer to use `utility_account_id` instead.
      schema:
        type: string
    arcVersionInHeaderParam:
      name: Arcadia-Version
      in: header
      example: '2022-10-13'
      description: The Arcadia-Version for the request
      required: true
      schema:
        type: string
        default: '2022-10-13'
    paginationLimitParam:
      in: query
      name: limit
      required: false
      schema:
        type: integer
        minimum: 1
        default: 10
  schemas:
    PaginatedUtilityStatements:
      required:
      - data
      - total_count
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/UtilityStatement'
        total_count:
          type: integer
          example: 1
      additionalProperties: false
    UtilityStatementsFeatureAvailabilityError:
      required:
      - error
      properties:
        error:
          type: object
          required:
          - description
          - type
          - details
          properties:
            description:
              type: string
              enum:
              - The utility_statements feature is not available for this UtilityAccount.
              - The utility_statements feature is not ready yet. Please refer to UtilityAccount#FeatureAvailability for updates.
            type:
              type: string
              enum:
              - BAD_REQUEST
            details:
              type:
              - object
              - 'null'
      additionalProperties: false
    Tariff:
      description: Information about a tariff.
      required:
      - main_tariff_id
      - tariff_code
      - tariff_name
      - utility_name
      properties:
        main_tariff_id:
          type: string
          description: The Genability 'masterTariffId' unique identifier for this tariff. See [Genability documentation](https://developer.genability.com/api-reference/tariff-api/tariff/) for details.
          example: gen_mtid_3331108
        property_inputs:
          description: Properties applied to this tariff which may affect the calculated cost of electricity.
          type: array
          items:
            type: object
            required:
            - id
            - value
            properties:
              id:
                type: string
                example: territoryId
              value:
                type:
                - boolean
                - number
                - string
                example: 3
        supplier_name:
          description: The name of the retail electricity supplier or the community choice aggregator. If there is no retail electricity supplier or community choice aggregator, this field is null.
          example: East Bay Community Energy
          type:
          - string
          - 'null'
        tariff_code:
          type: string
          description: Abbreviation code of the tariff used for this calculation.
          example: EV-2A-TOU
        tariff_name:
          type: string
          description: Full name of the tariff used for this calculation.
          example: Residential - Time of Use - Plug-In Electric Vehicle 2
        utility_name:
          type: string
          description: Name of the utility associated with this tariff
          example: Pacific Gas & Electric
    UtilityStatement:
      required:
      - client_user_id
      - created_at
      - due_date
      - final_bill
      - gas_charge
      - id
      - kwh
      - past_due
      - pdf_url
      - sandboxed
      - service_end_date
      - service_start_date
      - statement_date
      - supplier_charge
      - tariff
      - updated_at
      - utility_account_id
      - utility_charge
      - utility_name
      - utility_long_name
      - service_window_inclusive_of_end_date
      - commercial_line_items_detail
      - billing_flags
      - virtual_net_metering
      - most_recent_payment_detail
      properties:
        id:
          type: integer
          example: 123
        client_user_id:
          type: string
          example: fff57dc7-3a2b-4395-8a62-e3486d46dabe
        tariff:
          anyOf:
          - type: 'null'
          - $ref: '#/components/schemas/Tariff'
        utility_name:
          type: string
          example: AEP SWEPCO
          description: The list of supported Arcadia utilities can be found [here](https://arc.arcadia.com/coverage?first=25&page=1).
        utility_long_name:
          type: string
          example: AEP SWEPCO AR
          description: Provides greater detail than `utility_name`. The list of supported Arcadia utilities can be found [here](https://arc.arcadia.com/coverage?first=25&page=1).
        utility_account_id:
          type: integer
          example: 2243
        statement_date:
          type: string
          format: date
          example: '2019-08-24'
        due_date:
          type:
          - string
          - 'null'
          format: date
          example: '2019-09-24'
        service_start_date:
          type: string
          format: date
          example: '2019-08-24'
        service_end_date:
          type: string
          format: date
          example: '2019-09-24'
        kwh:
          type: integer
          example: 100
        utility_charge:
          type: number
          example: 90.33
          description: Total dollar amount billed by the utility on this statement.
        supplier_charge:
          example: 41.54
          description: 'Total dollar amount billed by the energy supplier.


            **Note**: Not available for all utilities.

            '
          type:
          - number
          - 'null'
        gas_charge:
          example: 23.32
          description: 'Total dollar amount billed by the utility for natural gas.


            **Note**: Not available for all utilities that provide gas service.

            '
          type:
          - number
          - 'null'
        past_due:
          type:
          - boolean
          - 'null'
          example: false
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        sandboxed:
          type: boolean
          example: false
        pdf_url:
          format: uri
          description: A url to the utility created PDF bill for this statement. Note that this url will only be valid for 600 seconds.
          type:
          - string
          - 'null'
        final_bill:
          description: Indicates if this is the final bill that this account will receive before closing.
          example: false
          type:
          - boolean
          - 'null'
        service_window_inclusive_of_end_date:
          type: boolean
          example: true
          description: Indicates that the service window for this UtilityStatement includes the service_end_date.
        net_metering:
          anyOf:
          - type: 'null'
          - type: object
            description: Details on the customer's net metering credit data. Currently only supported for Versant.
            required:
            - current_cycle_generated_kwh
            properties:
              current_cycle_generated_kwh:
                description: The kwh generated during the current cycle
                example: 40.57
                type:
                - number
                - 'null'
        virtual_net_metering:
          anyOf:
          - type: 'null'
          - type: object
            description: Details on the customer's virtual net metering credit data. Currently only supported for National Grid New York and Central Maine Power.
            required:
            - current_cycle_generated_credits
            - current_cycle_applied_credits
            - last_cycle_carry_over_credits
            - next_cycle_carry_over_credits
            - current_cycle_generated_kwh
            - current_cycle_applied_kwh
            - last_cycle_carry_over_kwh
            - next_cycle_carry_over_kwh
            - current_cycle_expiring_kwh
            - current_cycle_allocation_percentage
            - cdg_net_credit
            properties:
              current_cycle_generated_credits:
                description: The amount of credits generated during the current cycle, in dollars
                example: 100.15
                type:
                - number
                - 'null'
              current_cycle_applied_credits:
                description: The amount of credits applied during the current cycle, in dollars
                example: 90.33
                type:
                - number
                - 'null'
              last_cycle_carry_over_credits:
                description: The amount of credits carried over from the last cycle, in dollars
                example: 3.83
                type:
                - number
                - 'null'
              next_cycle_carry_over_credits:
                description: The amount of credits carried over to the next cycle, in dollars
                example: 5.99
                type:
                - number
                - 'null'
              current_cycle_generated_kwh:
                description: The kwh generated during the current cycle
                example: 40
                type:
                - number
                - 'null'
              current_cycle_applied_kwh:
                description: The kwh applied during the current cycle
                example: 30
                type:
                - number
                - 'null'
              last_cycle_carry_over_kwh:
                description: The kwh carried over to the next cycle
                example: 5
                type:
                - number
                - 'null'
              next_cycle_carry_over_kwh:
                description: The kwh carried over to the next cycle
                example: 10
                type:
                - number
                - 'null'
              current_cycle_expiring_kwh:
                description: the kwh that are expiring during the current cycle
                example: 5
                type:
                - number
                - 'null'
              current_cycle_allocation_percentage:
                description: the fixed allocation percentage during the current cycle
                example: '0.05'
                type:
                - string
                - 'null'
              cdg_net_credit:
                description: The net credit from the community solar project, in dollars
                example: 10
                type:
                - number
                - 'null'
        most_recent_payment_detail:
          anyOf:
          - type: 'null'
          - type: object
            description: Detail on the most recent payment. Currently only supported for National Grid Massachusetts and NYSEG.
            required:
            - most_recent_payment_received_amount
            - most_recent_payment_received_date
            properties:
              most_recent_payment_received_amount:
                example: 50.5
                description: Total dollar amount received on the most recent payment.
                type:
                - number
                - 'null'
              most_recent_payment_received_date:
                type:
                - string
                - 'null'
                format: date
                description: The date of the most recent payment.
                example: '2023-08-24'
        commercial_line_items_detail:
          anyOf:
          - type: 'null'
          - type: object
            description: This field is in *beta*. Click [here](release-phases) for a description on Arcadia's release phases. -- Details on line items specific to commercial accounts. Currently only supported for the ConEd utility.
            required:
            - supply_energy_kwh
            - supply_energy_cost
            - supply_demand_kw
            - supply_demand_cost
            - supply_customer_charge
            - supply_merchant_function_charge
            - supply_taxes
            - supply_total_charge
            - delivery_energy_kwh
            - delivery_energy_cost
            - delivery_demand_kw
            - delivery_demand_cost
            - delivery_customer_charge
            - delivery_system_benefit_cost
            - delivery_processing_charge
            - delivery_taxes
            - delivery_total_charge
            - sales_tax
            - electric_charge
            properties:
              supply_energy_kwh:
                type:
                - number
                - 'null'
              supply_energy_cost:
                description: The energy supply cost, in dollars.
                type:
                - number
                - 'null'
              supply_demand_kw:
                type:
                - number
                - 'null'
              supply_demand_cost:
                description: The demand supply cost, in dollars.
                type:
                - number
                - 'null'
              supply_customer_charge:
                description: The customer charge for energy supply, in dollars.
                type:
                - number
                - 'null'
              supply_merchant_function_charge:
                description: The charge for merchant function in energy supply, in dollars.
                type:
                - number
                - 'null'
              supply_taxes:
                description: Any other charges for taxes on energy supply, in dollars.
                type:
                - number
                - 'null'
              supply_total_charge:
                description: The total cost of energy supply, in dollars.
                type:
                - number
                - 'null'
              delivery_energy_kwh:
                type:
                - number
                - 'null'
              delivery_energy_cost:
                description: The energy delivery cost, in dollars.
                type:
                - number
                - 'null'
              delivery_demand_kw:
                type:
                - number
                - 'null'
              delivery_demand_cost:
                description: The demand delivery cost, in dollars.
                type:
                - number
                - 'null'
              delivery_customer_charge:
                description: The customer charge for energy delivery, in dollars.
                type:
                - number
                - 'null'
              delivery_system_benefit_cost:
                description: The delivery system benefit cost, in dollars.
                type:
                - number
                - 'null'
              delivery_processing_charge:
                description: The delivery processing charge, in dollars.
                type:
                - number
                - 'null'
              delivery_taxes:
                description: Any other charges for taxes on energy delivery, in dollars.
                type:
                - number
                - 'null'
              delivery_total_charge:
                description: The total cost of energy delivery, in dollars.
                type:
                - number
                - 'null'
              sales_tax:
                description: Sales taxes applied to the total bill, in dollars.
                type:
                - number
                - 'null'
              electric_charge:
                description: The total combined charge for this bill - supply, delivery, and taxes - in dollars.
                type:
                - number
                - 'null'
        billing_flags:
          type: array
          description: These flags may be of interest if the corresponding Utility Account is enrolled in Bundle.
          items:
            type: object
            properties:
              type:
                type: string
                description: The 'possible_rebill' flag indicates that this Utility Statement may be a duplicate or variation of a previous Utility Statement
                enum:
                - possible_rebill
              details:
                type: object
                properties:
                  conflicting_utility_statment_id:
                    type: integer
      additionalProperties: false
    UtilityAccountNotFoundError:
      required:
      - error
      properties:
        error:
          type: string
          enum:
          - Couldn't find UtilityAccount
      additionalProperties: false
  headers:
    ArcVersion:
      description: The Arcadia-Version for the response
      schema:
        type: string
      example: '2022-10-13'
      required: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
x-readme:
  proxy-enabled: false
  headers:
  - key: from-readme
    value: true
x-tagGroups:
- name: General
  tags:
  - Auth
  - Webhooks
  - Webhook Events
- name: Connections
  tags:
  - Utility Credentials
  - Utility Accounts
  - Utility Meters (Beta)
  - Users
- name: Products
  tags:
  - Plug
  - Spark
x-provenance:
  method: harvested
  publisher: Arcadiapower2
  source: https://api.arcadia.com/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)