Skip to main content

Queries

In this section

About Queries

Every GraphQL schema has a root type for both queries and mutations. The query type defines GraphQL operations that retrieve data from the server.

API Site

account

Type:AccountType

URL:https://api.octopus.energy/v1/graphql/

Get details about an account.

The possible errors that can be raised are:

  • KT-CT-4177: Unauthorized.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

Query

query Account($accountNumber: String!) {
  account(accountNumber: $accountNumber) {
    id
    number
    status
    paymentSchedules {
      ...PaymentScheduleConnectionTypeConnectionFragment
    }
    users {
      ...AccountUserTypeFragment
    }
    brand
    balance
    overdueBalance
    urn
    billingName
    billingSubName
    billingEmail
    billingAddress
    billingAddressLine1
    billingAddressLine2
    billingAddressLine3
    billingAddressLine4
    billingAddressLine5
    billingAddressPostcode
    billingCountryCode
    billingDeliveryPointIdentifier
    splitBillingAddress
    address {
      ...RichAddressTypeFragment
    }
    portfolio {
      ...PortfolioTypeFragment
    }
    ledgers {
      ...LedgerTypeFragment
    }
    metadata {
      ...MetadataFragment
    }
    canRequestRefund
    requestRefundEligibility {
      ...RequestRefundEligibilityTypeFragment
    }
    payments {
      ...AccountPaymentConnectionTypeConnectionFragment
    }
    repayments {
      ...AccountRepaymentConnectionTypeConnectionFragment
    }
    paymentPlans {
      ...PaymentPlanConnectionTypeConnectionFragment
    }
    paymentForecast {
      ...PaymentForecastTypeFragment
    }
    paginatedPaymentForecast {
      ...PaymentForecastConnectionTypeConnectionFragment
    }
    referrals {
      ...ReferralConnectionTypeConnectionFragment
    }
    referralsCreated
    rewards {
      ...RewardTypeFragment
    }
    activeReferralSchemes {
      ...ReferralSchemeTypesFragment
    }
    transactions {
      ...TransactionConnectionTypeConnectionFragment
    }
    provisionalTransactions {
      ...ProvisionalTransactionConnectionTypeConnectionFragment
    }
    annualStatements {
      ...AnnualStatementConnectionTypeConnectionFragment
    }
    bills {
      ...BillConnectionTypeConnectionFragment
    }
    billingOptions {
      ...BillingOptionsTypeFragment
    }
    bill {
      ...BillInterfaceFragment
    }
    directDebitInstructions {
      ...DirectDebitInstructionConnectionTypeConnectionFragment
    }
    paymentMethods {
      ...PaymentInstructionConnectionTypeConnectionFragment
    }
    events {
      ...AccountEventConnectionTypeConnectionFragment
    }
    applications {
      ...AccountApplicationConnectionTypeConnectionFragment
    }
    accountType
    businessType
    business {
      ...BusinessTypeFragment
    }
    commsDeliveryPreference
    communicationDeliveryPreference
    documentAccessibility
    references {
      ...AccountReferenceTypeFragment
    }
    fileAttachments {
      ...AccountFileAttachmentFragment
    }
    paginatedFileAttachments {
      ...AccountFileAttachmentConnectionTypeConnectionFragment
    }
    maximumRefund {
      ...MaximumRefundTypeFragment
    }
    campaigns {
      ...AccountCampaignTypeFragment
    }
    isInHardship
    activeHardshipAgreements {
      ...HardshipAgreementTypeFragment
    }
    notes {
      ...AccountNoteTypeFragment
    }
    contributionAgreements {
      ...ContributionAgreementTypeFragment
    }
    assistanceAgreements {
      ...AssistanceAgreementTypeFragment
    }
    debtCollectionProceedings {
      ...DebtCollectionProceedingTypeFragment
    }
    createdAt
    preferredLanguageForComms
    consents {
      ...ConsentTypeFragment
    }
    properties {
      ...PropertyTypeFragment
    }
    projectedBalance
    shouldReviewPayments
    recommendedBalanceAdjustment
    electricityAgreements {
      ...ElectricityAgreementTypeFragment
    }
    gasAgreements {
      ...GasAgreementTypeFragment
    }
    warmHomeDiscount {
      ...WarmHomeDiscountFragment
    }
    eligibilityForWarmHomeDiscount {
      ...WarmHomeDiscountEligibilityFragment
    }
    billingPostcode
    canRenewTariff
    trackerTariffDailyPricing {
      ...TrackerTariffDailyPricingFragment
    }
    paymentAdequacy {
      ...PaymentAdequacyTypeFragment
    }
    smets2Interest
    smets2RefusalReason
    greenAccomplishments {
      ...GreenAccomplishmentsTypeFragment
    }
    canChangePayments
    cotReadingWindowDays
    canBeWithdrawn
    currentEstimatedSsd
    earliestPossibleSsd
    latestPossibleSsd
    operationsTeam {
      ...OperationsTeamTypeFragment
    }
    canInputMeterReadingsViaIvr
    hasActiveDunningProcess
    hasActiveCollectionsProceedings
    isEligibleForElectricityReadingIncentive
    isEligibleForGasReadingIncentive
    isInBlockingMigration
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "account": {
      "id": "abc123",
      "number": "abc123",
      "status": "PENDING",
      "paymentSchedules": PaymentScheduleConnectionTypeConnection,
      "users": AccountUserType,
      "brand": "abc123",
      "balance": 1,
      "overdueBalance": 1,
      "urn": "abc123",
      "billingName": "abc123",
      "billingSubName": "abc123",
      "billingEmail": "abc123",
      "billingAddress": "abc123",
      "billingAddressLine1": "abc123",
      "billingAddressLine2": "abc123",
      "billingAddressLine3": "abc123",
      "billingAddressLine4": "abc123",
      "billingAddressLine5": "abc123",
      "billingAddressPostcode": "abc123",
      "billingCountryCode": "abc123",
      "billingDeliveryPointIdentifier": "abc123",
      "splitBillingAddress": ["abc123"],
      "address": RichAddressType,
      "portfolio": PortfolioType,
      "ledgers": [LedgerType],
      "metadata": [Metadata],
      "canRequestRefund": true,
      "requestRefundEligibility": RequestRefundEligibilityType,
      "payments": AccountPaymentConnectionTypeConnection,
      "repayments": AccountRepaymentConnectionTypeConnection,
      "paymentPlans": PaymentPlanConnectionTypeConnection,
      "paymentForecast": [PaymentForecastType],
      "paginatedPaymentForecast": PaymentForecastConnectionTypeConnection,
      "referrals": ReferralConnectionTypeConnection,
      "referralsCreated": 1,
      "rewards": [RewardType],
      "activeReferralSchemes": ReferralSchemeTypes,
      "transactions": TransactionConnectionTypeConnection,
      "provisionalTransactions": ProvisionalTransactionConnectionTypeConnection,
      "annualStatements": AnnualStatementConnectionTypeConnection,
      "bills": BillConnectionTypeConnection,
      "billingOptions": BillingOptionsType,
      "bill": BillInterface,
      "directDebitInstructions": DirectDebitInstructionConnectionTypeConnection,
      "paymentMethods": PaymentInstructionConnectionTypeConnection,
      "events": AccountEventConnectionTypeConnection,
      "applications": AccountApplicationConnectionTypeConnection,
      "accountType": "BUSINESS",
      "businessType": "SOLE_TRADER",
      "business": BusinessType,
      "commsDeliveryPreference": "EMAIL",
      "communicationDeliveryPreference": "abc123",
      "documentAccessibility": "LARGE_PRINT",
      "references": [AccountReferenceType],
      "fileAttachments": [AccountFileAttachment],
      "paginatedFileAttachments": AccountFileAttachmentConnectionTypeConnection,
      "maximumRefund": MaximumRefundType,
      "campaigns": [AccountCampaignType],
      "isInHardship": true,
      "activeHardshipAgreements": [HardshipAgreementType],
      "notes": [AccountNoteType],
      "contributionAgreements": [ContributionAgreementType],
      "assistanceAgreements": [AssistanceAgreementType],
      "debtCollectionProceedings": [DebtCollectionProceedingType],
      "createdAt": "2020-01-01T00:00:00.000Z",
      "preferredLanguageForComms": "abc123",
      "consents": ConsentType,
      "properties": [PropertyType],
      "projectedBalance": 1,
      "shouldReviewPayments": true,
      "recommendedBalanceAdjustment": 1,
      "electricityAgreements": [ElectricityAgreementType],
      "gasAgreements": [GasAgreementType],
      "warmHomeDiscount": WarmHomeDiscount,
      "eligibilityForWarmHomeDiscount": WarmHomeDiscountEligibility,
      "billingPostcode": "abc123",
      "canRenewTariff": true,
      "trackerTariffDailyPricing": TrackerTariffDailyPricing,
      "paymentAdequacy": PaymentAdequacyType,
      "smets2Interest": "PRIORITY",
      "smets2RefusalReason": "SMETS2_INTEREST_REASON_DO_NOT_OWN_HOME",
      "greenAccomplishments": GreenAccomplishmentsType,
      "canChangePayments": true,
      "cotReadingWindowDays": 1,
      "canBeWithdrawn": true,
      "currentEstimatedSsd": "2020-01-01",
      "earliestPossibleSsd": "2020-01-01",
      "latestPossibleSsd": "2020-01-01",
      "operationsTeam": OperationsTeamType,
      "canInputMeterReadingsViaIvr": true,
      "hasActiveDunningProcess": true,
      "hasActiveCollectionsProceedings": true,
      "isEligibleForElectricityReadingIncentive": true,
      "isEligibleForGasReadingIncentive": true,
      "isInBlockingMigration": true
    }
  }
}

accountChargeReasons

Type:[ChargeReasonType]

URL:https://api.octopus.energy/v1/graphql/

Available reasons for use in account charge mutations.

Query

query AccountChargeReasons {
  accountChargeReasons {
    code
    display
    isDeprecated
    isTaxExempt
    isHidden
    group
  }
}

Response

{
  "data": {
    "accountChargeReasons": [
      {
        "code": "abc123",
        "display": "abc123",
        "isDeprecated": true,
        "isTaxExempt": true,
        "isHidden": true,
        "group": "abc123"
      }
    ]
  }
}

accountContract

Type:Contract

URL:https://api.octopus.energy/v1/graphql/

Get details about an account contract.

The possible errors that can be raised are:

  • KT-CT-10003: Contract not found.
  • KT-CT-10005: Missing required parameter: either identifier or accountNumber must be provided.
  • KT-CT-10006: Account not found.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

identifier (String)

The identifier of the contract.

accountNumber (String)

The account number to find the contract for.

version (Int)

The version of the contract.

Query

query AccountContract(
  $identifier: String,
  $accountNumber: String,
  $version: Int
) {
  accountContract(
    identifier: $identifier,
    accountNumber: $accountNumber,
    version: $version
  ) {
    identifier
    party {
      ... on AccountType {
        ...AccountTypeFragment
      }
      ... on BusinessType {
        ...BusinessTypeFragment
      }
    }
    subject {
      ...AccountTypeFragment
    }
    validFrom
    validTo
    signedAt
    cancelledAt
    lifecycle {
      ...ContractVersionFragment
    }
    terms {
      ...TermInterfaceFragment
    }
  }
}

Variables

{
  "identifier": "abc123",
  "accountNumber": "abc123",
  "version": 1
}

Response

{
  "data": {
    "accountContract": {
      "identifier": NonEmptyString,
      "party": AccountType,
      "subject": [AccountType],
      "validFrom": "2020-01-01T00:00:00.000Z",
      "validTo": "2020-01-01T00:00:00.000Z",
      "signedAt": "2020-01-01T00:00:00.000Z",
      "cancelledAt": "2020-01-01T00:00:00.000Z",
      "lifecycle": ContractVersion,
      "terms": TermInterface
    }
  }
}

accountConversationHasHandoffEvent

Type:Boolean!

URL:https://api.octopus.energy/v1/graphql/

Whether a valid chatbot handoff event exists in the conversation belonging to an account.

The possible errors that can be raised are:

  • KT-CT-7610: No Ink conversation for account.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

The account number.

Query

query AccountConversationHasHandoffEvent($accountNumber: String!) {
  accountConversationHasHandoffEvent(accountNumber: $accountNumber)
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "accountConversationHasHandoffEvent": true
  }
}

accountCreditReasons

Type:[CreditReasonType]

URL:https://api.octopus.energy/v1/graphql/

Available reasons for use in account credit mutations.

Query

query AccountCreditReasons {
  accountCreditReasons {
    code
    display
    isDeprecated
    isTaxExempt
    isHidden
    group
  }
}

Response

{
  "data": {
    "accountCreditReasons": [
      {
        "code": "abc123",
        "display": "abc123",
        "isDeprecated": true,
        "isTaxExempt": true,
        "isHidden": true,
        "group": "abc123"
      }
    ]
  }
}

accountIoEligibility

Type:AccountIoEligibility

URL:https://api.octopus.energy/v1/graphql/

Determines whether an account is eligible to register devices with Intelligent Octopus.

Arguments

NameDescription

accountNumber (String!)

Account number.

Query

query AccountIoEligibility($accountNumber: String!) {
  accountIoEligibility(accountNumber: $accountNumber) {
    isEligibleForIo
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "accountIoEligibility": {
      "isEligibleForIo": true
    }
  }
}

accountReference

Type:[AccountReferenceType]

URL:https://api.octopus.energy/v1/graphql/

List of matching account references.

The possible errors that can be raised are:

  • KT-CT-8310: Invalid data.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

value (String)

Query

query AccountReference($value: String) {
  accountReference(value: $value) {
    namespace
    value
    createdAt
    updatedAt
    account {
      ...AccountTypeFragment
    }
  }
}

Variables

{
  "value": "abc123"
}

Response

{
  "data": {
    "accountReference": [
      {
        "namespace": "abc123",
        "value": "abc123",
        "createdAt": "2020-01-01T00:00:00.000Z",
        "updatedAt": "2020-01-01T00:00:00.000Z",
        "account": AccountType
      }
    ]
  }
}

accounts

Type:[AccountType]

URL:https://api.octopus.energy/v1/graphql/

Get details about multiple accounts.

Arguments

NameDescription

phoneNumber (String)

A phone number to find accounts associated with.

portfolioNumber (String)

A portfolio number to find accounts associated with.

Query

query Accounts(
  $phoneNumber: String,
  $portfolioNumber: String
) {
  accounts(
    phoneNumber: $phoneNumber,
    portfolioNumber: $portfolioNumber
  ) {
    id
    number
    status
    paymentSchedules {
      ...PaymentScheduleConnectionTypeConnectionFragment
    }
    users {
      ...AccountUserTypeFragment
    }
    brand
    balance
    overdueBalance
    urn
    billingName
    billingSubName
    billingEmail
    billingAddress
    billingAddressLine1
    billingAddressLine2
    billingAddressLine3
    billingAddressLine4
    billingAddressLine5
    billingAddressPostcode
    billingCountryCode
    billingDeliveryPointIdentifier
    splitBillingAddress
    address {
      ...RichAddressTypeFragment
    }
    portfolio {
      ...PortfolioTypeFragment
    }
    ledgers {
      ...LedgerTypeFragment
    }
    metadata {
      ...MetadataFragment
    }
    canRequestRefund
    requestRefundEligibility {
      ...RequestRefundEligibilityTypeFragment
    }
    payments {
      ...AccountPaymentConnectionTypeConnectionFragment
    }
    repayments {
      ...AccountRepaymentConnectionTypeConnectionFragment
    }
    paymentPlans {
      ...PaymentPlanConnectionTypeConnectionFragment
    }
    paymentForecast {
      ...PaymentForecastTypeFragment
    }
    paginatedPaymentForecast {
      ...PaymentForecastConnectionTypeConnectionFragment
    }
    referrals {
      ...ReferralConnectionTypeConnectionFragment
    }
    referralsCreated
    rewards {
      ...RewardTypeFragment
    }
    activeReferralSchemes {
      ...ReferralSchemeTypesFragment
    }
    transactions {
      ...TransactionConnectionTypeConnectionFragment
    }
    provisionalTransactions {
      ...ProvisionalTransactionConnectionTypeConnectionFragment
    }
    annualStatements {
      ...AnnualStatementConnectionTypeConnectionFragment
    }
    bills {
      ...BillConnectionTypeConnectionFragment
    }
    billingOptions {
      ...BillingOptionsTypeFragment
    }
    bill {
      ...BillInterfaceFragment
    }
    directDebitInstructions {
      ...DirectDebitInstructionConnectionTypeConnectionFragment
    }
    paymentMethods {
      ...PaymentInstructionConnectionTypeConnectionFragment
    }
    events {
      ...AccountEventConnectionTypeConnectionFragment
    }
    applications {
      ...AccountApplicationConnectionTypeConnectionFragment
    }
    accountType
    businessType
    business {
      ...BusinessTypeFragment
    }
    commsDeliveryPreference
    communicationDeliveryPreference
    documentAccessibility
    references {
      ...AccountReferenceTypeFragment
    }
    fileAttachments {
      ...AccountFileAttachmentFragment
    }
    paginatedFileAttachments {
      ...AccountFileAttachmentConnectionTypeConnectionFragment
    }
    maximumRefund {
      ...MaximumRefundTypeFragment
    }
    campaigns {
      ...AccountCampaignTypeFragment
    }
    isInHardship
    activeHardshipAgreements {
      ...HardshipAgreementTypeFragment
    }
    notes {
      ...AccountNoteTypeFragment
    }
    contributionAgreements {
      ...ContributionAgreementTypeFragment
    }
    assistanceAgreements {
      ...AssistanceAgreementTypeFragment
    }
    debtCollectionProceedings {
      ...DebtCollectionProceedingTypeFragment
    }
    createdAt
    preferredLanguageForComms
    consents {
      ...ConsentTypeFragment
    }
    properties {
      ...PropertyTypeFragment
    }
    projectedBalance
    shouldReviewPayments
    recommendedBalanceAdjustment
    electricityAgreements {
      ...ElectricityAgreementTypeFragment
    }
    gasAgreements {
      ...GasAgreementTypeFragment
    }
    warmHomeDiscount {
      ...WarmHomeDiscountFragment
    }
    eligibilityForWarmHomeDiscount {
      ...WarmHomeDiscountEligibilityFragment
    }
    billingPostcode
    canRenewTariff
    trackerTariffDailyPricing {
      ...TrackerTariffDailyPricingFragment
    }
    paymentAdequacy {
      ...PaymentAdequacyTypeFragment
    }
    smets2Interest
    smets2RefusalReason
    greenAccomplishments {
      ...GreenAccomplishmentsTypeFragment
    }
    canChangePayments
    cotReadingWindowDays
    canBeWithdrawn
    currentEstimatedSsd
    earliestPossibleSsd
    latestPossibleSsd
    operationsTeam {
      ...OperationsTeamTypeFragment
    }
    canInputMeterReadingsViaIvr
    hasActiveDunningProcess
    hasActiveCollectionsProceedings
    isEligibleForElectricityReadingIncentive
    isEligibleForGasReadingIncentive
    isInBlockingMigration
  }
}

Variables

{
  "phoneNumber": "abc123",
  "portfolioNumber": "abc123"
}

Response

{
  "data": {
    "accounts": [
      {
        "id": "abc123",
        "number": "abc123",
        "status": "PENDING",
        "paymentSchedules": PaymentScheduleConnectionTypeConnection,
        "users": AccountUserType,
        "brand": "abc123",
        "balance": 1,
        "overdueBalance": 1,
        "urn": "abc123",
        "billingName": "abc123",
        "billingSubName": "abc123",
        "billingEmail": "abc123",
        "billingAddress": "abc123",
        "billingAddressLine1": "abc123",
        "billingAddressLine2": "abc123",
        "billingAddressLine3": "abc123",
        "billingAddressLine4": "abc123",
        "billingAddressLine5": "abc123",
        "billingAddressPostcode": "abc123",
        "billingCountryCode": "abc123",
        "billingDeliveryPointIdentifier": "abc123",
        "splitBillingAddress": ["abc123"],
        "address": RichAddressType,
        "portfolio": PortfolioType,
        "ledgers": [LedgerType],
        "metadata": [Metadata],
        "canRequestRefund": true,
        "requestRefundEligibility": RequestRefundEligibilityType,
        "payments": AccountPaymentConnectionTypeConnection,
        "repayments": AccountRepaymentConnectionTypeConnection,
        "paymentPlans": PaymentPlanConnectionTypeConnection,
        "paymentForecast": [PaymentForecastType],
        "paginatedPaymentForecast": PaymentForecastConnectionTypeConnection,
        "referrals": ReferralConnectionTypeConnection,
        "referralsCreated": 1,
        "rewards": [RewardType],
        "activeReferralSchemes": ReferralSchemeTypes,
        "transactions": TransactionConnectionTypeConnection,
        "provisionalTransactions": ProvisionalTransactionConnectionTypeConnection,
        "annualStatements": AnnualStatementConnectionTypeConnection,
        "bills": BillConnectionTypeConnection,
        "billingOptions": BillingOptionsType,
        "bill": BillInterface,
        "directDebitInstructions": DirectDebitInstructionConnectionTypeConnection,
        "paymentMethods": PaymentInstructionConnectionTypeConnection,
        "events": AccountEventConnectionTypeConnection,
        "applications": AccountApplicationConnectionTypeConnection,
        "accountType": "BUSINESS",
        "businessType": "SOLE_TRADER",
        "business": BusinessType,
        "commsDeliveryPreference": "EMAIL",
        "communicationDeliveryPreference": "abc123",
        "documentAccessibility": "LARGE_PRINT",
        "references": [AccountReferenceType],
        "fileAttachments": [AccountFileAttachment],
        "paginatedFileAttachments": AccountFileAttachmentConnectionTypeConnection,
        "maximumRefund": MaximumRefundType,
        "campaigns": [AccountCampaignType],
        "isInHardship": true,
        "activeHardshipAgreements": [HardshipAgreementType],
        "notes": [AccountNoteType],
        "contributionAgreements": [ContributionAgreementType],
        "assistanceAgreements": [AssistanceAgreementType],
        "debtCollectionProceedings": [DebtCollectionProceedingType],
        "createdAt": "2020-01-01T00:00:00.000Z",
        "preferredLanguageForComms": "abc123",
        "consents": ConsentType,
        "properties": [PropertyType],
        "projectedBalance": 1,
        "shouldReviewPayments": true,
        "recommendedBalanceAdjustment": 1,
        "electricityAgreements": [ElectricityAgreementType],
        "gasAgreements": [GasAgreementType],
        "warmHomeDiscount": WarmHomeDiscount,
        "eligibilityForWarmHomeDiscount": WarmHomeDiscountEligibility,
        "billingPostcode": "abc123",
        "canRenewTariff": true,
        "trackerTariffDailyPricing": TrackerTariffDailyPricing,
        "paymentAdequacy": PaymentAdequacyType,
        "smets2Interest": "PRIORITY",
        "smets2RefusalReason": "SMETS2_INTEREST_REASON_DO_NOT_OWN_HOME",
        "greenAccomplishments": GreenAccomplishmentsType,
        "canChangePayments": true,
        "cotReadingWindowDays": 1,
        "canBeWithdrawn": true,
        "currentEstimatedSsd": "2020-01-01",
        "earliestPossibleSsd": "2020-01-01",
        "latestPossibleSsd": "2020-01-01",
        "operationsTeam": OperationsTeamType,
        "canInputMeterReadingsViaIvr": true,
        "hasActiveDunningProcess": true,
        "hasActiveCollectionsProceedings": true,
        "isEligibleForElectricityReadingIncentive": true,
        "isEligibleForGasReadingIncentive": true,
        "isInBlockingMigration": true
      }
    ]
  }
}

activeAffiliateReferralScheme

Type:ReferralSchemeType

URL:https://api.octopus.energy/v1/graphql/

Return the current active referral reward scheme of a given affiliate organisation, if any exists.

Arguments

NameDescription

subdomain (String!)

The affiliate link subdomain.

Query

query ActiveAffiliateReferralScheme($subdomain: String!) {
  activeAffiliateReferralScheme(subdomain: $subdomain) {
    referralUrl
    referralDisplayUrl
    referrerRewardAmount
    referredRewardAmount
    combinedRewardAmount
    loyaltyPointsBonus
    canBeReferred
    code
    referrerGivenName
    referrerFamilyName
    schemeType
    isUsageAtCapacity
  }
}

Variables

{
  "subdomain": "abc123"
}

Response

{
  "data": {
    "activeAffiliateReferralScheme": {
      "referralUrl": "abc123",
      "referralDisplayUrl": "abc123",
      "referrerRewardAmount": 1,
      "referredRewardAmount": 1,
      "combinedRewardAmount": 1,
      "loyaltyPointsBonus": 1,
      "canBeReferred": true,
      "code": "abc123",
      "referrerGivenName": "abc123",
      "referrerFamilyName": "abc123",
      "schemeType": "abc123",
      "isUsageAtCapacity": true
    }
  }
}

activeCampaignOffers

Type:[CampaignType]

URL:https://api.octopus.energy/v1/graphql/

All active campaigns with offers for the given account.

Arguments

NameDescription

accountNumber (String!)

Query

query ActiveCampaignOffers($accountNumber: String!) {
  activeCampaignOffers(accountNumber: $accountNumber) {
    name
    slug
    expiryDate
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "activeCampaignOffers": [
      {
        "name": "abc123",
        "slug": "abc123",
        "expiryDate": "2020-01-01"
      }
    ]
  }
}

activeDomesticSignupRewardScheme

Type:ReferralSchemeType

URL:https://api.octopus.energy/v1/graphql/

Return the current active signup referral reward scheme with the given code, if any exists.

Query

query ActiveDomesticSignupRewardScheme {
  activeDomesticSignupRewardScheme {
    referralUrl
    referralDisplayUrl
    referrerRewardAmount
    referredRewardAmount
    combinedRewardAmount
    loyaltyPointsBonus
    canBeReferred
    code
    referrerGivenName
    referrerFamilyName
    schemeType
    isUsageAtCapacity
  }
}

Response

{
  "data": {
    "activeDomesticSignupRewardScheme": {
      "referralUrl": "abc123",
      "referralDisplayUrl": "abc123",
      "referrerRewardAmount": 1,
      "referredRewardAmount": 1,
      "combinedRewardAmount": 1,
      "loyaltyPointsBonus": 1,
      "canBeReferred": true,
      "code": "abc123",
      "referrerGivenName": "abc123",
      "referrerFamilyName": "abc123",
      "schemeType": "abc123",
      "isUsageAtCapacity": true
    }
  }
}

addressMeterpoints

Type:AddressMeterPointsType

URL:https://api.octopus.energy/v1/graphql/

Search for all energised meterpoint's belonging to the given UPRN using ECOES & Xoserve APIs.

The possible errors that can be raised are:

  • KT-GB-6620: Invalid data.
  • KT-GB-6631: Invalid data.
  • KT-GB-6630: We can't communicate with our address database right now to look up your address. Please try again.
  • KT-GB-6632: UPRN not found.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

uprn (String!)

The UPRN of the property to search for meterpoints.

postcode (String!)

The postcode of the property to search for meterpoints.

Query

query AddressMeterpoints(
  $uprn: String!,
  $postcode: String!
) {
  addressMeterpoints(
    uprn: $uprn,
    postcode: $postcode
  ) {
    electricityMeterPoints {
      ...ElectricMeterTechnicalDetailsFragment
    }
    gasMeterPoints {
      ...GasMeterTechnicalDetailsFragment
    }
  }
}

Variables

{
  "uprn": "abc123",
  "postcode": "abc123"
}

Response

{
  "data": {
    "addressMeterpoints": {
      "electricityMeterPoints": [ElectricMeterTechnicalDetails],
      "gasMeterPoints": [GasMeterTechnicalDetails]
    }
  }
}

addressUprns

Type:AddressUPRNTypeConnection

URL:https://api.octopus.energy/v1/graphql/

Search for addresses belonging to the given postcode using ECOES & Xoserve APIs, with the results grouped by UPRN.

Arguments

NameDescription

postcode (String!)

The postcode to search for.

electricityOnly (Boolean)

If it should only return addresses from the ECOES EES data source.

before (String)

after (String)

first (Int)

last (Int)

Query

query AddressUprns(
  $postcode: String!,
  $electricityOnly: Boolean,
  $before: String,
  $after: String,
  $first: Int,
  $last: Int
) {
  addressUprns(
    postcode: $postcode,
    electricityOnly: $electricityOnly,
    before: $before,
    after: $after,
    first: $first,
    last: $last
  ) {
    pageInfo {
      ...PageInfoFragment
    }
    edges {
      ...AddressUPRNTypeEdgeFragment
    }
    totalCount
    edgeCount
  }
}

Variables

{
  "postcode": "abc123",
  "electricityOnly": true,
  "before": "abc123",
  "after": "abc123",
  "first": 1,
  "last": 1
}

Response

{
  "data": {
    "addressUprns": {
      "pageInfo": PageInfo,
      "edges": AddressUPRNTypeEdge,
      "totalCount": 1,
      "edgeCount": 1
    }
  }
}

Arguments

NameDescription

postcode (String!)

searchDomesticOnly (Boolean)

useDes (Boolean)

dataSource (DataSource)

before (String)

after (String)

first (Int)

last (Int)

Query

query Addresses(
  $postcode: String!,
  $searchDomesticOnly: Boolean,
  $useDes: Boolean,
  $dataSource: DataSource,
  $before: String,
  $after: String,
  $first: Int,
  $last: Int
) {
  addresses(
    postcode: $postcode,
    searchDomesticOnly: $searchDomesticOnly,
    useDes: $useDes,
    dataSource: $dataSource,
    before: $before,
    after: $after,
    first: $first,
    last: $last
  ) {
    pageInfo {
      ...PageInfoFragment
    }
    edges {
      ...AddressConnectionTypeEdgeFragment
    }
    totalCount
    edgeCount
  }
}

Variables

{
  "postcode": "abc123",
  "searchDomesticOnly": true,
  "useDes": true,
  "dataSource": "CACHE",
  "before": "abc123",
  "after": "abc123",
  "first": 1,
  "last": 1
}

Response

{
  "data": {
    "addresses": {
      "pageInfo": PageInfo,
      "edges": AddressConnectionTypeEdge,
      "totalCount": 1,
      "edgeCount": 1
    }
  }
}

Arguments

NameDescription

accountNumber (String!)

mpxn (String!)

startAt (DateTime!)

endAt (DateTime!)

before (String)

after (String)

first (Int)

last (Int)

Query

query ApplicableRates(
  $accountNumber: String!,
  $mpxn: String!,
  $startAt: DateTime!,
  $endAt: DateTime!,
  $before: String,
  $after: String,
  $first: Int,
  $last: Int
) {
  applicableRates(
    accountNumber: $accountNumber,
    mpxn: $mpxn,
    startAt: $startAt,
    endAt: $endAt,
    before: $before,
    after: $after,
    first: $first,
    last: $last
  ) {
    pageInfo {
      ...PageInfoFragment
    }
    edges {
      ...ApplicableRateConnectionTypeEdgeFragment
    }
    totalCount
    edgeCount
  }
}

Variables

{
  "accountNumber": "abc123",
  "mpxn": "abc123",
  "startAt": "2020-01-01T00:00:00.000Z",
  "endAt": "2020-01-01T00:00:00.000Z",
  "before": "abc123",
  "after": "abc123",
  "first": 1,
  "last": 1
}

Response

{
  "data": {
    "applicableRates": {
      "pageInfo": PageInfo,
      "edges": ApplicableRateConnectionTypeEdge,
      "totalCount": 1,
      "edgeCount": 1
    }
  }
}

areBlanketsAvailable

Type:Boolean

URL:https://api.octopus.energy/v1/graphql/

Whether there are still blankets available.

The possible errors that can be raised are:

  • KT-GB-6012: Unable to determine if blankets are available.
  • KT-CT-1113: Disabled GraphQL field requested.

Query

query AreBlanketsAvailable {
  areBlanketsAvailable
}

Response

{
  "data": {
    "areBlanketsAvailable": true
  }
}

areDiscountCodesAvailable

Type:Boolean

URL:https://api.octopus.energy/v1/graphql/

Whether or not there are remaining discount codes available at the time of querying.

Query

query AreDiscountCodesAvailable {
  areDiscountCodesAvailable
}

Response

{
  "data": {
    "areDiscountCodesAvailable": true
  }
}

autoTopupConfigs

Type:AutoTopupConfigConnectionTypeConnection

URL:https://api.octopus.energy/v1/graphql/

Get the auto top-up configs for a device. Ordered by effective from date, latest first.

Arguments

NameDescription

deviceId (String!)

Target device ID, e.g. 'A1-BC-D2-00-01-23-EF-4G'.

accountNumber (String!)

Target account number, e.g. 'A-A1B2C3D4'.

effectiveFrom (DateTime)

The datetime from which the auto top-up is effective, e.g. '2024-01-01T00:00:00+00:00'.

before (String)

after (String)

first (Int)

last (Int)

Query

query AutoTopupConfigs(
  $deviceId: String!,
  $accountNumber: String!,
  $effectiveFrom: DateTime,
  $before: String,
  $after: String,
  $first: Int,
  $last: Int
) {
  autoTopupConfigs(
    deviceId: $deviceId,
    accountNumber: $accountNumber,
    effectiveFrom: $effectiveFrom,
    before: $before,
    after: $after,
    first: $first,
    last: $last
  ) {
    pageInfo {
      ...PageInfoFragment
    }
    edges {
      ...AutoTopupConfigConnectionTypeEdgeFragment
    }
  }
}

Variables

{
  "deviceId": "abc123",
  "accountNumber": "abc123",
  "effectiveFrom": "2020-01-01T00:00:00.000Z",
  "before": "abc123",
  "after": "abc123",
  "first": 1,
  "last": 1
}

Response

{
  "data": {
    "autoTopupConfigs": {
      "pageInfo": PageInfo,
      "edges": AutoTopupConfigConnectionTypeEdge
    }
  }
}

autoTopupTriggers

Type:AutoTopupTriggerConnectionTypeConnection

URL:https://api.octopus.energy/v1/graphql/

Get auto top-up trigger events for an auto topup config. Ordered by triggered_at datetime, latest first.

Arguments

NameDescription

autoTopupConfigId (ID!)

Target auto top-up config ID, e.g. '123'.

triggersFrom (DateTime)

Filter by datetime (inclusive) from which trigger events have occurred, e.g. '2024-01-01T00:00:00+00:00'.

status (SmartDeviceAutoTopupTriggerStatus)

Filter by status of the auto top-up trigger event.

source (SmartDeviceAutoTopupTriggerSources)

Filter by source of the auto top-up trigger event.

failureReason (SmartDeviceAutoTopupTriggerFailureReasons)

Filter by failure reason of the auto top-up trigger event.

before (String)

after (String)

first (Int)

last (Int)

Query

query AutoTopupTriggers(
  $autoTopupConfigId: ID!,
  $triggersFrom: DateTime,
  $status: SmartDeviceAutoTopupTriggerStatus,
  $source: SmartDeviceAutoTopupTriggerSources,
  $failureReason: SmartDeviceAutoTopupTriggerFailureReasons,
  $before: String,
  $after: String,
  $first: Int,
  $last: Int
) {
  autoTopupTriggers(
    autoTopupConfigId: $autoTopupConfigId,
    triggersFrom: $triggersFrom,
    status: $status,
    source: $source,
    failureReason: $failureReason,
    before: $before,
    after: $after,
    first: $first,
    last: $last
  ) {
    pageInfo {
      ...PageInfoFragment
    }
    edges {
      ...AutoTopupTriggerConnectionTypeEdgeFragment
    }
  }
}

Variables

{
  "autoTopupConfigId": "abc123",
  "triggersFrom": "2020-01-01T00:00:00.000Z",
  "status": "INITIATED",
  "source": "LOW_CREDIT_BALANCE",
  "failureReason": "NO_IMPORT_METER",
  "before": "abc123",
  "after": "abc123",
  "first": 1,
  "last": 1
}

Response

{
  "data": {
    "autoTopupTriggers": {
      "pageInfo": PageInfo,
      "edges": AutoTopupTriggerConnectionTypeEdge
    }
  }
}

availableProductFromDisplayName

Type:EnergyProductType

URL:https://api.octopus.energy/v1/graphql/

Available energy product, whose display name has the given prefix.

The possible errors that can be raised are:

  • KT-GB-9514: No available product found.
  • KT-GB-9515: Multiple available products found.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

displayName (String!)

Display name of the product.

Query

query AvailableProductFromDisplayName($displayName: String!) {
  availableProductFromDisplayName(displayName: $displayName) {
    id
    fullName
    displayName
    description
    availableFrom
    availableTo
    isHidden
    code
    direction
    notes
    isVariable
    isGreen
    isBusiness
    isChargedHalfHourly
    isPrepay
    isDefault
    isOccupier
    term
    tariffs {
      ...EnergyTariffConnectionTypeConnectionFragment
    }
    isAvailable
    isUnavailable
    isFixed
    isDomestic
    includesEpgReduction
    exitFees
    exitFeesType
    tags
  }
}

Variables

{
  "displayName": "abc123"
}

Response

{
  "data": {
    "availableProductFromDisplayName": {
      "id": "abc123",
      "fullName": "abc123",
      "displayName": "abc123",
      "description": "abc123",
      "availableFrom": "2020-01-01T00:00:00.000Z",
      "availableTo": "2020-01-01T00:00:00.000Z",
      "isHidden": true,
      "code": "abc123",
      "direction": "IMPORT",
      "notes": "abc123",
      "isVariable": true,
      "isGreen": true,
      "isBusiness": true,
      "isChargedHalfHourly": true,
      "isPrepay": true,
      "isDefault": true,
      "isOccupier": true,
      "term": 1,
      "tariffs": EnergyTariffConnectionTypeConnection,
      "isAvailable": true,
      "isUnavailable": true,
      "isFixed": true,
      "isDomestic": true,
      "includesEpgReduction": true,
      "exitFees": 1,
      "exitFeesType": "abc123",
      "tags": ["abc123"]
    }
  }
}

availableProductSwitchDates

Type:[Date]

URL:https://api.octopus.energy/v1/graphql/

Get available dates for product switch.

The possible errors that can be raised are:

  • KT-CT-1501: Agreement not found.
  • KT-CT-4930: Unsupported market.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

agreementId (Int!)

Agreement ID.

Query

query AvailableProductSwitchDates($agreementId: Int!) {
  availableProductSwitchDates(agreementId: $agreementId)
}

Variables

{
  "agreementId": 1
}

Response

{
  "data": {
    "availableProductSwitchDates": ["2020-01-01"]
  }
}

availableProductsForMeterPoint

Type:[MPxNProductType]

URL:https://api.octopus.energy/v1/graphql/

A list of product codes that are the currently available products for a meter point.

Arguments

NameDescription

accountNumber (String!)

Kraken account number.

mpxns ([String]!)

A list of MPxNs.

availableAt (DateTime!)

includeRestrictedProducts (Boolean)

Include products with a restricted availability in the results.

Query

query AvailableProductsForMeterPoint(
  $accountNumber: String!,
  $mpxns: [String]!,
  $availableAt: DateTime!,
  $includeRestrictedProducts: Boolean
) {
  availableProductsForMeterPoint(
    accountNumber: $accountNumber,
    mpxns: $mpxns,
    availableAt: $availableAt,
    includeRestrictedProducts: $includeRestrictedProducts
  ) {
    mpxn
    products {
      ...EnergyProductTypeFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123",
  "mpxns": "abc123",
  "availableAt": "2020-01-01T00:00:00.000Z",
  "includeRestrictedProducts": true
}

Response

{
  "data": {
    "availableProductsForMeterPoint": [
      {
        "mpxn": "abc123",
        "products": [EnergyProductType]
      }
    ]
  }
}

Arguments

NameDescription

screenId (ID!)

The ID of the screen to return.

params ([BackendScreenParamInputType])

List of key-value pairs (strings) to pass as parameters to the screen.

maxVersionSupported (Int)

The maximum version of backend screens supported by the client.

Query

query BackendScreen(
  $screenId: ID!,
  $params: [BackendScreenParamInputType],
  $maxVersionSupported: Int
) {
  backendScreen(
    screenId: $screenId,
    params: $params,
    maxVersionSupported: $maxVersionSupported
  ) {
    ... on ComponentListType {
      ...ComponentListTypeFragment
    }
    ... on GenericBackendScreen {
      ...GenericBackendScreenFragment
    }
    ... on Dashboard {
      ...DashboardFragment
    }
  }
}

Variables

{
  "screenId": "abc123",
  "params": BackendScreenParamInputType,
  "maxVersionSupported": 1
}

Response

{
  "data": {
    "backendScreen": ComponentListType
  }
}

backendScreenEventIds

Type:[String]

URL:https://api.octopus.energy/v1/graphql/

Get all registered backend screen event IDs.

Query

query BackendScreenEventIds {
  backendScreenEventIds
}

Response

{
  "data": {
    "backendScreenEventIds": ["abc123"]
  }
}

backendScreenIds

Type:[String]

URL:https://api.octopus.energy/v1/graphql/

Get all registered backend screen IDs.

Query

query BackendScreenIds {
  backendScreenIds
}

Response

{
  "data": {
    "backendScreenIds": ["abc123"]
  }
}

balanceForecast

Type:BalanceForecastType

URL:https://api.octopus.energy/v1/graphql/

The balance forecast for an account.

The possible errors that can be raised are:

  • KT-CT-4123: Unauthorized.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

Kraken account number.

Query

query BalanceForecast($accountNumber: String!) {
  balanceForecast(accountNumber: $accountNumber) {
    isAvailable
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "balanceForecast": {
      "isAvailable": true
    }
  }
}

batteryDevice

Type:BatteryDeviceType

URL:https://api.octopus.energy/v1/graphql/

The currently active battery device.

The possible errors that can be raised are:

  • KT-CT-1111: Unauthorized.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

propertyId (Int!)

Query

query BatteryDevice(
  $accountNumber: String!,
  $propertyId: Int!
) {
  batteryDevice(
    accountNumber: $accountNumber,
    propertyId: $propertyId
  ) {
    krakenflexDeviceId
    deviceType
    provider
    params {
      ...BatteryParamsTypeFragment
    }
    deviceStatus {
      ...DeviceStatusTypeFragment
    }
    chargingPreferences {
      ...BatteryChargingPreferencesTypeFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123",
  "propertyId": 1
}

Response

{
  "data": {
    "batteryDevice": {
      "krakenflexDeviceId": "abc123",
      "deviceType": "BATTERIES",
      "provider": "DAIKIN",
      "params": BatteryParamsType,
      "deviceStatus": DeviceStatusType,
      "chargingPreferences": BatteryChargingPreferencesType
    }
  }
}

batteryVariants

Type:[BatteryVariantsType]

URL:https://api.octopus.energy/v1/graphql/

All supported batteries and their details.

Arguments

NameDescription

make (String)

Only return batteries of a specific make.

Query

query BatteryVariants($make: String) {
  batteryVariants(make: $make) {
    make
    models {
      ...BatteryVariantModelsTypeFragment
    }
  }
}

Variables

{
  "make": "abc123"
}

Response

{
  "data": {
    "batteryVariants": [
      {
        "make": "abc123",
        "models": [BatteryVariantModelsType]
      }
    ]
  }
}

bookSmartMeterInstallationUrl

Type:AccountUrl

URL:https://api.octopus.energy/v1/graphql/

URL to book a smart meter installation for the given account and property.

The possible errors that can be raised are:

  • KT-CT-4123: Unauthorized.
  • KT-CT-1113: Disabled GraphQL field requested.

Deprecated

The 'bookSmartMeterInstallationUrl' field is deprecated.

A GraphQL query is not required to find out the URL for booking a smart meter installation.

- Marked as deprecated on 2025-04-03.
- Scheduled for removal on or after 2025-05-03.

Arguments

NameDescription

accountNumber (String!)

The account number of the URLs' account.

propertyId (Int!)

The ID of the property needing a smart meter installation.

Query

query BookSmartMeterInstallationUrl(
  $accountNumber: String!,
  $propertyId: Int!
) {
  bookSmartMeterInstallationUrl(
    accountNumber: $accountNumber,
    propertyId: $propertyId
  ) {
    urlIdentifier
    url
  }
}

Variables

{
  "accountNumber": "abc123",
  "propertyId": 1
}

Response

{
  "data": {
    "bookSmartMeterInstallationUrl": {
      "urlIdentifier": "abc123",
      "url": "abc123"
    }
  }
}

business

Type:BusinessType

URL:https://api.octopus.energy/v1/graphql/

Get details about a business.

The possible errors that can be raised are:

  • KT-CT-11101: The viewer is not authorized to execute the query/mutation. Check the ownership/permissions of provided data.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

id (ID!)

The business ID.

Query

query Business($id: ID!) {
  business(id: $id) {
    name
    number
    businessType
    details {
      ...BusinessDetailTypeFragment
    }
    linkedAccountNumber
    linkedAccountNumbers
    segmentName
    paymentMethods {
      ...PaymentInstructionConnectionTypeConnectionFragment
    }
  }
}

Variables

{
  "id": "abc123"
}

Response

{
  "data": {
    "business": {
      "name": "abc123",
      "number": "abc123",
      "businessType": "SOLE_TRADER",
      "details": [BusinessDetailType],
      "linkedAccountNumber": "abc123",
      "linkedAccountNumbers": "abc123",
      "segmentName": "abc123",
      "paymentMethods": PaymentInstructionConnectionTypeConnection
    }
  }
}

businessContract

Type:Contract

URL:https://api.octopus.energy/v1/graphql/

Get details about an account contract.

The possible errors that can be raised are:

  • KT-CT-10003: Contract not found.
  • KT-CT-10005: Missing required parameter: either identifier or accountNumber must be provided.
  • KT-CT-10006: Account not found.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

identifier (String)

The identifier of the contract.

accountNumber (String)

The account number to find the business contract for.

version (Int)

The version of the contract.

Query

query BusinessContract(
  $identifier: String,
  $accountNumber: String,
  $version: Int
) {
  businessContract(
    identifier: $identifier,
    accountNumber: $accountNumber,
    version: $version
  ) {
    identifier
    party {
      ... on AccountType {
        ...AccountTypeFragment
      }
      ... on BusinessType {
        ...BusinessTypeFragment
      }
    }
    subject {
      ...AccountTypeFragment
    }
    validFrom
    validTo
    signedAt
    cancelledAt
    lifecycle {
      ...ContractVersionFragment
    }
    terms {
      ...TermInterfaceFragment
    }
  }
}

Variables

{
  "identifier": "abc123",
  "accountNumber": "abc123",
  "version": 1
}

Response

{
  "data": {
    "businessContract": {
      "identifier": NonEmptyString,
      "party": AccountType,
      "subject": [AccountType],
      "validFrom": "2020-01-01T00:00:00.000Z",
      "validTo": "2020-01-01T00:00:00.000Z",
      "signedAt": "2020-01-01T00:00:00.000Z",
      "cancelledAt": "2020-01-01T00:00:00.000Z",
      "lifecycle": ContractVersion,
      "terms": TermInterface
    }
  }
}

call

Type:CallInterface!

URL:https://api.octopus.energy/v1/graphql/

Get a call for a given ID.

The possible errors that can be raised are:

  • KT-CT-11802: Call not found.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

id (ID!)

The call ID.

Query

query Call($id: ID!) {
  call(id: $id) {
    id
    account {
      ...AccountTypeFragment
    }
    metadata {
      ...CallMetadataItemTypeFragment
    }
  }
}

Variables

{
  "id": "abc123"
}

Response

{
  "data": {
    "call": {
      "id": "abc123",
      "account": AccountType,
      "metadata": CallMetadataItemType
    }
  }
}

Arguments

NameDescription

accountNumber (String!)

The account number.

before (String)

after (String)

first (Int)

last (Int)

Query

query Campaigns(
  $accountNumber: String!,
  $before: String,
  $after: String,
  $first: Int,
  $last: Int
) {
  campaigns(
    accountNumber: $accountNumber,
    before: $before,
    after: $after,
    first: $first,
    last: $last
  ) {
    pageInfo {
      ...PageInfoFragment
    }
    edges {
      ...AccountCampaignConnectionTypeEdgeFragment
    }
    totalCount
    edgeCount
  }
}

Variables

{
  "accountNumber": "abc123",
  "before": "abc123",
  "after": "abc123",
  "first": 1,
  "last": 1
}

Response

{
  "data": {
    "campaigns": {
      "pageInfo": PageInfo,
      "edges": AccountCampaignConnectionTypeEdge,
      "totalCount": 1,
      "edgeCount": 1
    }
  }
}

cancelEnrolmentData

Type:CancelEnrolmentDataType

URL:https://api.octopus.energy/v1/graphql/

Data required for the cancel enrollment journey.

The possible errors that can be raised are:

  • KT-CT-4177: Unauthorized.
  • KT-GB-1503: The account's enrollment has already been cancelled.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

Kraken account number.

Query

query CancelEnrolmentData($accountNumber: String!) {
  cancelEnrolmentData(accountNumber: $accountNumber) {
    canBeDelayed
    canBeWithdrawn
    currentEstimatedSsd
    earliestPossibleSsd
    latestPossibleSsd
    canSkipSsdPayment
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "cancelEnrolmentData": {
      "canBeDelayed": true,
      "canBeWithdrawn": true,
      "currentEstimatedSsd": "2020-01-01",
      "earliestPossibleSsd": "2020-01-01",
      "latestPossibleSsd": "2020-01-01",
      "canSkipSsdPayment": true
    }
  }
}

caredForAccounts

Type:[String!]!

URL:https://api.octopus.energy/v1/graphql/

The account numbers of the accounts that the user is caring for.

Query

query CaredForAccounts {
  caredForAccounts
}

Response

{
  "data": {
    "caredForAccounts": "abc123"
  }
}

chargePointDevices

Type:[ChargePointDevicesType]

URL:https://api.octopus.energy/v1/graphql/

All charge point devices.

Deprecated

The 'chargePointDevices' field is deprecated.

Please use chargePointVariants instead of this query.

- Marked as deprecated on 2023-05-10.
- Scheduled for removal on or after 2024-01-01.

Query

query ChargePointDevices {
  chargePointDevices {
    make
    models {
      ...ChargePointModelsTypeFragment
    }
  }
}

Response

{
  "data": {
    "chargePointDevices": [
      {
        "make": "abc123",
        "models": [ChargePointModelsType]
      }
    ]
  }
}

Query

query ChargePointVariants {
  chargePointVariants {
    make
    models {
      ...ChargePointVariantModelTypeFragment
    }
  }
}

Response

{
  "data": {
    "chargePointVariants": [
      {
        "make": "abc123",
        "models": [ChargePointVariantModelType]
      }
    ]
  }
}

charityDonationHistory

Type:CharityDonationHistoryType

URL:https://api.octopus.energy/v1/graphql/

Data concerning accounts charity donations.

The possible errors that can be raised are:

  • KT-CT-4123: Unauthorized.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

Query

query CharityDonationHistory($accountNumber: String!) {
  charityDonationHistory(accountNumber: $accountNumber) {
    totalDonatedAmount
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "charityDonationHistory": {
      "totalDonatedAmount": 1
    }
  }
}

charityDonationSettings

Type:CharityDonationSettings

URL:https://api.octopus.energy/v1/graphql/

Show the account's charity donation settings.

The possible errors that can be raised are:

  • KT-CT-4123: Unauthorized.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

Account number.

Query

query CharityDonationSettings($accountNumber: String!) {
  charityDonationSettings(accountNumber: $accountNumber) {
    monthlyAmount
    isOptedIn
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "charityDonationSettings": {
      "monthlyAmount": "ONE",
      "isOptedIn": true
    }
  }
}

chatbotRealtimeToken

Type:String!

URL:https://api.octopus.energy/v1/graphql/

A token used to subscribe to realtime chatbot updates.

The possible errors that can be raised are:

  • KT-CT-1111: Unauthorized.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

The account number.

Query

query ChatbotRealtimeToken($accountNumber: String!) {
  chatbotRealtimeToken(accountNumber: $accountNumber)
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "chatbotRealtimeToken": "abc123"
  }
}

completedDispatches

Type:[UpsideDispatchType]

URL:https://api.octopus.energy/v1/graphql/

All completed device dispatches 12 hours behind, in reverse time order.

Arguments

NameDescription

accountNumber (String!)

Query

query CompletedDispatches($accountNumber: String!) {
  completedDispatches(accountNumber: $accountNumber) {
    start
    end
    startDt
    endDt
    deltaKwh
    delta
    meta {
      ...UpsideDispatchMetaTypeFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "completedDispatches": [
      {
        "start": "2020-01-01T00:00:00.000Z",
        "end": "2020-01-01T00:00:00.000Z",
        "startDt": "abc123",
        "endDt": "abc123",
        "deltaKwh": 1,
        "delta": 1.0,
        "meta": UpsideDispatchMetaType
      }
    ]
  }
}

consumptionEstimates

Type:ConsumptionEstimates

URL:https://api.octopus.energy/v1/graphql/

Consumption estimates based on ofgem statistics.

Query

query ConsumptionEstimates {
  consumptionEstimates {
    low {
      ...ConsumptionEstimateFragment
    }
    medium {
      ...ConsumptionEstimateFragment
    }
    high {
      ...ConsumptionEstimateFragment
    }
  }
}

Response

{
  "data": {
    "consumptionEstimates": {
      "low": ConsumptionEstimate,
      "medium": ConsumptionEstimate,
      "high": ConsumptionEstimate
    }
  }
}

Query

query ContributionSchemes {
  contributionSchemes {
    id
    code
    displayName
    taxable
    acceptingContributions
  }
}

Response

{
  "data": {
    "contributionSchemes": [
      {
        "id": "abc123",
        "code": "abc123",
        "displayName": "abc123",
        "taxable": true,
        "acceptingContributions": true
      }
    ]
  }
}

controllerEuids

Type:[String]

URL:https://api.octopus.energy/v1/graphql/

Heat pump controller EUIDs associated with an account.

Arguments

NameDescription

accountNumber (String)

Query

query ControllerEuids($accountNumber: String) {
  controllerEuids(accountNumber: $accountNumber)
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "controllerEuids": ["abc123"]
  }
}

costOfCharge

Type:[CostOfChargeType]

URL:https://api.octopus.energy/v1/graphql/

Aggregated cost of charge for an EV device.

Arguments

NameDescription

accountNumber (String!)

frequency (DataFrequency!)

Frequency by day, week, month or year.

reportDate (Date)

The date up to which data should be relative to.

startDate (Date)

The start date of the results required. Overrides report date (end date) if provided.

Query

query CostOfCharge(
  $accountNumber: String!,
  $frequency: DataFrequency!,
  $reportDate: Date,
  $startDate: Date
) {
  costOfCharge(
    accountNumber: $accountNumber,
    frequency: $frequency,
    reportDate: $reportDate,
    startDate: $startDate
  ) {
    costOfChargeId
    krakenflexDeviceId
    reportDate
    isSmartCharge
    totalConsumption
    totalCostExclTax
    totalCostInclTax
  }
}

Variables

{
  "accountNumber": "abc123",
  "frequency": "DAILY",
  "reportDate": "2020-01-01",
  "startDate": "2020-01-01"
}

Response

{
  "data": {
    "costOfCharge": [
      {
        "costOfChargeId": "abc123",
        "krakenflexDeviceId": "abc123",
        "reportDate": "2020-01-01",
        "isSmartCharge": true,
        "totalConsumption": 1.0,
        "totalCostExclTax": 1.0,
        "totalCostInclTax": 1.0
      }
    ]
  }
}

costOfUsage

Type:CostOfUsageType

URL:https://api.octopus.energy/v1/graphql/

Cost of usage recorded by the meter.

The possible errors that can be raised are:

  • KT-GB-4011: No SMETS consumption found.
  • KT-GB-6312: Unable to query unit rates.
  • KT-GB-3810: Unable to get cost of usage.
  • KT-CT-1113: Disabled GraphQL field requested.

Deprecated

The 'cost_of_usage' field is deprecated.

Please measurements statistics node instead.

- Marked as deprecated on 2024-09-02.
- Scheduled for removal on or after 2024-12-01.

Arguments

NameDescription

accountNumber (String)

Account number.

meterId (String)

The electricity or gas meter ID.

fuelType (FuelType)

The energy type, i.e. ELECTRICITY or GAS.

startAt (DateTime)

Datetime the data should be queried from.

grouping (ConsumptionGroupings!)

Aggregate cost according to this grouping.

timezone (String)

Timezone to use for grouping.

Query

query CostOfUsage(
  $accountNumber: String,
  $meterId: String,
  $fuelType: FuelType,
  $startAt: DateTime,
  $grouping: ConsumptionGroupings!,
  $timezone: String
) {
  costOfUsage(
    accountNumber: $accountNumber,
    meterId: $meterId,
    fuelType: $fuelType,
    startAt: $startAt,
    grouping: $grouping,
    timezone: $timezone
  ) {
    costEnabled
    direction
    details {
      ...CostOfUsageConnectionTypeConnectionFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123",
  "meterId": "abc123",
  "fuelType": "ELECTRICITY",
  "startAt": "2020-01-01T00:00:00.000Z",
  "grouping": "QUARTER_HOUR",
  "timezone": "abc123"
}

Response

{
  "data": {
    "costOfUsage": {
      "costEnabled": true,
      "direction": "abc123",
      "details": CostOfUsageConnectionTypeConnection
    }
  }
}

dashboardScreen

Type:Dashboard

URL:https://api.octopus.energy/v1/graphql/

Get a dashboard screen to render in the form of a json list of sections containing cards or grouped cards each with an order attribute.

Arguments

NameDescription

dashboardId (ID!)

The ID of the dashboard type screen to return.

accountNumber (String!)

The account number of the user.

maxVersionSupported (Int!)

The maximum version of dahshboard type screens supported by the client.

ledgerId (String)

The ledger id associated to the account.

ledgerNumber (String)

The ledger number associated to the account.

propertyId (String)

The property id associated to the account.

params ([BackendScreenParamInputType])

List of key-value pairs (strings) to pass as parameters to the screen.

Query

query DashboardScreen(
  $dashboardId: ID!,
  $accountNumber: String!,
  $maxVersionSupported: Int!,
  $ledgerId: String,
  $ledgerNumber: String,
  $propertyId: String,
  $params: [BackendScreenParamInputType]
) {
  dashboardScreen(
    dashboardId: $dashboardId,
    accountNumber: $accountNumber,
    maxVersionSupported: $maxVersionSupported,
    ledgerId: $ledgerId,
    ledgerNumber: $ledgerNumber,
    propertyId: $propertyId,
    params: $params
  ) {
    id
    typename
    dashboardItems {
      ...SectionTypeFragment
    }
    serialisedDashboardItems
  }
}

Variables

{
  "dashboardId": "abc123",
  "accountNumber": "abc123",
  "maxVersionSupported": 1,
  "ledgerId": "abc123",
  "ledgerNumber": "abc123",
  "propertyId": "abc123",
  "params": BackendScreenParamInputType
}

Response

{
  "data": {
    "dashboardScreen": {
      "id": "abc123",
      "typename": "abc123",
      "dashboardItems": SectionType,
      "serialisedDashboardItems": "abc123"
    }
  }
}

defaultPaymentInstruction

Type:PaymentInstructionType

URL:https://api.octopus.energy/v1/graphql/

Get the default payment instruction for the account's main ledger.

Arguments

NameDescription

accountNumber (String!)

The account number.

instructionType (PaymentType)

Provide an option to get either a CARD or DIRECT_DEBIT instruction.

Query

query DefaultPaymentInstruction(
  $accountNumber: String!,
  $instructionType: PaymentType
) {
  defaultPaymentInstruction(
    accountNumber: $accountNumber,
    instructionType: $instructionType
  ) {
    id
    status
    sortCode
    iban
    accountHolder
    instructionType
    cardPaymentNetwork
    cardExpiryMonth
    cardExpiryYear
    supplementaryLedger {
      ...SupplementaryLedgerTypeFragment
    }
    bankCode
    accountType
    validFrom
    vendor
    cardNumber
    cardType
    maskedAccountIdentifier
    owners {
      ...PaymentInstructionOwnerTypeFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123",
  "instructionType": "BPAY"
}

Response

{
  "data": {
    "defaultPaymentInstruction": {
      "id": "abc123",
      "status": "abc123",
      "sortCode": "abc123",
      "iban": "abc123",
      "accountHolder": "abc123",
      "instructionType": "abc123",
      "cardPaymentNetwork": "abc123",
      "cardExpiryMonth": 1,
      "cardExpiryYear": 1,
      "supplementaryLedger": SupplementaryLedgerType,
      "bankCode": "abc123",
      "accountType": "abc123",
      "validFrom": "2020-01-01T00:00:00.000Z",
      "vendor": "abc123",
      "cardNumber": "abc123",
      "cardType": "abc123",
      "maskedAccountIdentifier": "abc123",
      "owners": [PaymentInstructionOwnerType]
    }
  }
}

defaultRawScore

Type:Int

URL:https://api.octopus.energy/v1/graphql/

Get default raw score for a customer feedback form.

The possible errors that can be raised are:

  • KT-CT-5513: Invalid data.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

formId (Int!)

Query

query DefaultRawScore($formId: Int!) {
  defaultRawScore(formId: $formId)
}

Variables

{
  "formId": 1
}

Response

{
  "data": {
    "defaultRawScore": 1
  }
}

devices

Type:[SmartFlexDeviceInterface!]

URL:https://api.octopus.energy/v1/graphql/

A list of devices registered to an account.

Arguments

NameDescription

accountNumber (String!)

The account number, e.g. A-12345678.

propertyId (ID)

Only list devices registered to this property.

deviceId (String)

Only list the device with this ID.

integrationDeviceId (String)

Only list the device with this integration device ID.

Query

query Devices(
  $accountNumber: String!,
  $propertyId: ID,
  $deviceId: String,
  $integrationDeviceId: String
) {
  devices(
    accountNumber: $accountNumber,
    propertyId: $propertyId,
    deviceId: $deviceId,
    integrationDeviceId: $integrationDeviceId
  ) {
    id
    name
    deviceType
    provider
    integrationDeviceId
    status {
      ...SmartFlexDeviceStatusInterfaceFragment
    }
    alerts {
      ...SmartFlexDeviceAlertInterfaceFragment
    }
    onboardingWizard {
      ...SmartFlexOnboardingWizardFragment
    }
    preferences {
      ...SmartFlexDevicePreferencesInterfaceFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123",
  "propertyId": "abc123",
  "deviceId": "abc123",
  "integrationDeviceId": "abc123"
}

Response

{
  "data": {
    "devices": [
      {
        "id": "abc123",
        "name": "abc123",
        "deviceType": "BATTERIES",
        "provider": "DAIKIN",
        "integrationDeviceId": "abc123",
        "status": SmartFlexDeviceStatusInterface,
        "alerts": SmartFlexDeviceAlertInterface,
        "onboardingWizard": SmartFlexOnboardingWizard,
        "preferences": SmartFlexDevicePreferencesInterface
      }
    ]
  }
}

discountCode

Type:String

URL:https://api.octopus.energy/v1/graphql/

The discount code for this account, if one exists.

Arguments

NameDescription

accountNumber (String!)

Kraken account number.

Query

query DiscountCode($accountNumber: String!) {
  discountCode(accountNumber: $accountNumber)
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "discountCode": "abc123"
  }
}

doesAccountMeetVulnerabilityCriteria

Type:Boolean

URL:https://api.octopus.energy/v1/graphql/

Whether the account is meets the vulnerability criteria to receive a blanket.

Arguments

NameDescription

accountNumber (String!)

The account number to check.

Query

query DoesAccountMeetVulnerabilityCriteria($accountNumber: String!) {
  doesAccountMeetVulnerabilityCriteria(accountNumber: $accountNumber)
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "doesAccountMeetVulnerabilityCriteria": true
  }
}

domesticAccountReferralRewardScheme

Type:ReferralSchemeType

URL:https://api.octopus.energy/v1/graphql/

Return a referral reward scheme for the given account referral code.

Arguments

NameDescription

code (String!)

Friend referral code.

Query

query DomesticAccountReferralRewardScheme($code: String!) {
  domesticAccountReferralRewardScheme(code: $code) {
    referralUrl
    referralDisplayUrl
    referrerRewardAmount
    referredRewardAmount
    combinedRewardAmount
    loyaltyPointsBonus
    canBeReferred
    code
    referrerGivenName
    referrerFamilyName
    schemeType
    isUsageAtCapacity
  }
}

Variables

{
  "code": "abc123"
}

Response

{
  "data": {
    "domesticAccountReferralRewardScheme": {
      "referralUrl": "abc123",
      "referralDisplayUrl": "abc123",
      "referrerRewardAmount": 1,
      "referredRewardAmount": 1,
      "combinedRewardAmount": 1,
      "loyaltyPointsBonus": 1,
      "canBeReferred": true,
      "code": "abc123",
      "referrerGivenName": "abc123",
      "referrerFamilyName": "abc123",
      "schemeType": "abc123",
      "isUsageAtCapacity": true
    }
  }
}

domesticJoiningRewardScheme

Type:ReferralSchemeType

URL:https://api.octopus.energy/v1/graphql/

Return a joining reward scheme with the given code, if it's active. A joining reward can be a signup reward or a promotional reward.

Arguments

NameDescription

code (String!)

Reward code for the scheme.

Query

query DomesticJoiningRewardScheme($code: String!) {
  domesticJoiningRewardScheme(code: $code) {
    referralUrl
    referralDisplayUrl
    referrerRewardAmount
    referredRewardAmount
    combinedRewardAmount
    loyaltyPointsBonus
    canBeReferred
    code
    referrerGivenName
    referrerFamilyName
    schemeType
    isUsageAtCapacity
  }
}

Variables

{
  "code": "abc123"
}

Response

{
  "data": {
    "domesticJoiningRewardScheme": {
      "referralUrl": "abc123",
      "referralDisplayUrl": "abc123",
      "referrerRewardAmount": 1,
      "referredRewardAmount": 1,
      "combinedRewardAmount": 1,
      "loyaltyPointsBonus": 1,
      "canBeReferred": true,
      "code": "abc123",
      "referrerGivenName": "abc123",
      "referrerFamilyName": "abc123",
      "schemeType": "abc123",
      "isUsageAtCapacity": true
    }
  }
}

domesticSignupRewardScheme

Type:ReferralSchemeType

URL:https://api.octopus.energy/v1/graphql/

Return a signup referral reward scheme with the given code, if it's active.

Arguments

NameDescription

code (String!)

Reward code for the scheme.

Query

query DomesticSignupRewardScheme($code: String!) {
  domesticSignupRewardScheme(code: $code) {
    referralUrl
    referralDisplayUrl
    referrerRewardAmount
    referredRewardAmount
    combinedRewardAmount
    loyaltyPointsBonus
    canBeReferred
    code
    referrerGivenName
    referrerFamilyName
    schemeType
    isUsageAtCapacity
  }
}

Variables

{
  "code": "abc123"
}

Response

{
  "data": {
    "domesticSignupRewardScheme": {
      "referralUrl": "abc123",
      "referralDisplayUrl": "abc123",
      "referrerRewardAmount": 1,
      "referredRewardAmount": 1,
      "combinedRewardAmount": 1,
      "loyaltyPointsBonus": 1,
      "canBeReferred": true,
      "code": "abc123",
      "referrerGivenName": "abc123",
      "referrerFamilyName": "abc123",
      "schemeType": "abc123",
      "isUsageAtCapacity": true
    }
  }
}

earliestPossibleDirectDebitPaymentDate

Type:EarliestPossibleDirectDebitPaymentDate

URL:https://api.octopus.energy/v1/graphql/

Earliest possible payment date from today for which the first direct debit payment can be made.

The possible errors that can be raised are:

  • KT-GB-3914: Unable to get earliest ssd payment date.
  • KT-CT-1113: Disabled GraphQL field requested.

Query

query EarliestPossibleDirectDebitPaymentDate {
  earliestPossibleDirectDebitPaymentDate {
    earliestPossibleDirectDebitPaymentDate
  }
}

Response

{
  "data": {
    "earliestPossibleDirectDebitPaymentDate": {
      "earliestPossibleDirectDebitPaymentDate": "2020-01-01"
    }
  }
}

electricVehicles

Type:[ElectricVehicleType]

URL:https://api.octopus.energy/v1/graphql/

All electric vehicle types and their details.

Arguments

NameDescription

make (String)

Only return vehicle types for the specified make.

supportedProvider (ProviderChoices)

Only return vehicle types supported by the specified provider, e.g. Tesla.

isIntegrationLive (Boolean)

Only return vehicles that are currently integrated.

Query

query ElectricVehicles(
  $make: String,
  $supportedProvider: ProviderChoices,
  $isIntegrationLive: Boolean
) {
  electricVehicles(
    make: $make,
    supportedProvider: $supportedProvider,
    isIntegrationLive: $isIntegrationLive
  ) {
    make
    models {
      ...ElectricVehicleModelTypeFragment
    }
  }
}

Variables

{
  "make": "abc123",
  "supportedProvider": "DAIKIN",
  "isIntegrationLive": true
}

Response

{
  "data": {
    "electricVehicles": [
      {
        "make": "abc123",
        "models": [ElectricVehicleModelType]
      }
    ]
  }
}

electricityAgreement

Type:AgreementInterface

URL:https://api.octopus.energy/v1/graphql/

Get an electricity agreement.

This field requires the Authorization header to be set.

Arguments

NameDescription

id (ID!)

Query

query ElectricityAgreement($id: ID!) {
  electricityAgreement(id: $id) {
    id
    validFrom
    validTo
    agreedFrom
    agreedTo
    isRevoked
  }
}

Variables

{
  "id": "abc123"
}

Response

{
  "data": {
    "electricityAgreement": {
      "id": 1,
      "validFrom": "2020-01-01T00:00:00.000Z",
      "validTo": "2020-01-01T00:00:00.000Z",
      "agreedFrom": "2020-01-01T00:00:00.000Z",
      "agreedTo": "2020-01-01T00:00:00.000Z",
      "isRevoked": true
    }
  }
}

electricityMeterReadings

Type:ElectricityMeterReadingConnectionTypeConnection

URL:https://api.octopus.energy/v1/graphql/

Fetch electricity meter readings for a given account and meter

This field is a connection type. Connections are used to implement cursor based pagination.

This field requires the Authorization header to be set.

Arguments

NameDescription

accountNumber (String!)

meterId (String!)

eventTypes ([MeterReadingEventType])

readFrom (DateTime)

Only fetch meter readings made since this date

readTo (DateTime)

Only fetch meter readings made until this date

before (String)

after (String)

first (Int)

last (Int)

Query

query ElectricityMeterReadings(
  $accountNumber: String!,
  $meterId: String!,
  $eventTypes: [MeterReadingEventType],
  $readFrom: DateTime,
  $readTo: DateTime,
  $before: String,
  $after: String,
  $first: Int,
  $last: Int
) {
  electricityMeterReadings(
    accountNumber: $accountNumber,
    meterId: $meterId,
    eventTypes: $eventTypes,
    readFrom: $readFrom,
    readTo: $readTo,
    before: $before,
    after: $after,
    first: $first,
    last: $last
  ) {
    pageInfo {
      ...PageInfoFragment
    }
    edges {
      ...ElectricityMeterReadingConnectionTypeEdgeFragment
    }
    totalCount
    edgeCount
  }
}

Variables

{
  "accountNumber": "abc123",
  "meterId": "abc123",
  "eventTypes": "CUSTOMER",
  "readFrom": "2020-01-01T00:00:00.000Z",
  "readTo": "2020-01-01T00:00:00.000Z",
  "before": "abc123",
  "after": "abc123",
  "first": 1,
  "last": 1
}

Response

{
  "data": {
    "electricityMeterReadings": {
      "pageInfo": PageInfo,
      "edges": ElectricityMeterReadingConnectionTypeEdge,
      "totalCount": 1,
      "edgeCount": 1
    }
  }
}

electricityMeterpoint

Type:ElectricMeterTechnicalDetails

URL:https://api.octopus.energy/v1/graphql/

Search for the meterpoint with given MPAN using ECOES switching API.

The possible errors that can be raised are:

  • KT-GB-6634: The provided MPAN is not valid.
  • KT-GB-6630: We can't communicate with our address database right now to look up your address. Please try again.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

mpan (String!)

The MPAN of the meterpoint.

Query

query ElectricityMeterpoint($mpan: String!) {
  electricityMeterpoint(mpan: $mpan) {
    mpan
    distributorMpid
    tradingStatus
    tradingStatusEfd
    gspGroupId
    gspGroupEfd
    lineLossFactor
    lineLossFactorEfd
    dccServiceFlag
    dccServiceFlagEfd
    greenDealInEffect
    supplierMpid
    supplierEfd
    energisationStatus
    energisationStatusEfd
    profileClass
    profileClassEfd
    standardSettlementConfiguration
    standardSettlementConfigurationEfd
    meterTimeswitchClass
    meterTimeswitchClassEfd
    measurementClass
    measurementClassEfd
    dataAggregatorMpid
    dataAggregatorEfd
    dataCollectorMpid
    dataCollectorEfd
    meterOperatorMpid
    meterOperatorEfd
    smsoMpid
    smsoEfd
    ihdStatus
    ihdStatusEfd
    smetsVersion
    meteredIndicator
    meteredIndicatorEfd
    meteredIndicatorEtd
    consumerType
    domesticConsumerIndicator
    relationshipStatusIndicator
    rmpState
    rmpStateEfd
    cssSupplierMpid
    cssSupplyStartDate
    energyDirection
    energyDirectionEfd
    energyDirectionEtd
    connectionType
    connectionTypeEfd
    connectionTypeEtd
    meters {
      ...ElectricMeterTechnicalSubDetailsFragment
    }
  }
}

Variables

{
  "mpan": "abc123"
}

Response

{
  "data": {
    "electricityMeterpoint": {
      "mpan": "abc123",
      "distributorMpid": "abc123",
      "tradingStatus": "abc123",
      "tradingStatusEfd": "2020-01-01",
      "gspGroupId": "abc123",
      "gspGroupEfd": "2020-01-01",
      "lineLossFactor": "abc123",
      "lineLossFactorEfd": "2020-01-01",
      "dccServiceFlag": "abc123",
      "dccServiceFlagEfd": "2020-01-01",
      "greenDealInEffect": "abc123",
      "supplierMpid": "abc123",
      "supplierEfd": "2020-01-01",
      "energisationStatus": "abc123",
      "energisationStatusEfd": "2020-01-01",
      "profileClass": 1,
      "profileClassEfd": "2020-01-01",
      "standardSettlementConfiguration": "abc123",
      "standardSettlementConfigurationEfd": "2020-01-01",
      "meterTimeswitchClass": 1,
      "meterTimeswitchClassEfd": "2020-01-01",
      "measurementClass": "abc123",
      "measurementClassEfd": "2020-01-01",
      "dataAggregatorMpid": "abc123",
      "dataAggregatorEfd": "2020-01-01",
      "dataCollectorMpid": "abc123",
      "dataCollectorEfd": "2020-01-01",
      "meterOperatorMpid": "abc123",
      "meterOperatorEfd": "2020-01-01",
      "smsoMpid": "abc123",
      "smsoEfd": "2020-01-01",
      "ihdStatus": "abc123",
      "ihdStatusEfd": "2020-01-01",
      "smetsVersion": "abc123",
      "meteredIndicator": true,
      "meteredIndicatorEfd": "2020-01-01",
      "meteredIndicatorEtd": "2020-01-01",
      "consumerType": "abc123",
      "domesticConsumerIndicator": true,
      "relationshipStatusIndicator": "abc123",
      "rmpState": "abc123",
      "rmpStateEfd": "2020-01-01",
      "cssSupplierMpid": "abc123",
      "cssSupplyStartDate": "2020-01-01",
      "energyDirection": "abc123",
      "energyDirectionEfd": "2020-01-01",
      "energyDirectionEtd": "2020-01-01",
      "connectionType": "abc123",
      "connectionTypeEfd": "2020-01-01",
      "connectionTypeEtd": "2020-01-01",
      "meters": [ElectricMeterTechnicalSubDetails]
    }
  }
}

electricityPrepayLedgers

Type:PrepayLedgersType

URL:https://api.octopus.energy/v1/graphql/

Override Field to add additional attributes and extend description with possible_errors

The possible errors that can be raised are:

  • KT-GB-6211: Account does not exist.
  • KT-GB-6212: Meter does not exist.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

mpan (String!)

serialNumber (String!)

Query

query ElectricityPrepayLedgers(
  $accountNumber: String!,
  $mpan: String!,
  $serialNumber: String!
) {
  electricityPrepayLedgers(
    accountNumber: $accountNumber,
    mpan: $mpan,
    serialNumber: $serialNumber
  ) {
    creditLedger {
      ...SupplementaryLedgerTypeFragment
    }
    debtLedger {
      ...SupplementaryLedgerTypeFragment
    }
    paymentLedger {
      ...PrepayPaymentLedgerTypeFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123",
  "mpan": "abc123",
  "serialNumber": "abc123"
}

Response

{
  "data": {
    "electricityPrepayLedgers": {
      "creditLedger": SupplementaryLedgerType,
      "debtLedger": SupplementaryLedgerType,
      "paymentLedger": PrepayPaymentLedgerType
    }
  }
}

eligibleDeviceTypes

Type:[KrakenFlexDeviceTypes]

URL:https://api.octopus.energy/v1/graphql/

A list of device types that are eligible for registration.

Arguments

NameDescription

accountNumber (String!)

The account number, e.g. A-12345678.

Query

query EligibleDeviceTypes($accountNumber: String!) {
  eligibleDeviceTypes(accountNumber: $accountNumber)
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "eligibleDeviceTypes": "BATTERIES"
  }
}

Arguments

NameDescription

id (ID!)

Query

query EmbeddedNetwork($id: ID!) {
  embeddedNetwork(id: $id) {
    id
    name
    embeddedProperties {
      ...EmbeddedPropertyTypeFragment
    }
  }
}

Variables

{
  "id": "abc123"
}

Response

{
  "data": {
    "embeddedNetwork": {
      "id": "abc123",
      "name": "abc123",
      "embeddedProperties": [EmbeddedPropertyType]
    }
  }
}

Query

query EnergyMixData {
  energyMixData {
    carbonIntensityIndex
  }
}

Response

{
  "data": {
    "energyMixData": {
      "carbonIntensityIndex": "abc123"
    }
  }
}

energyProduct

Type:EnergyProductType

URL:https://api.octopus.energy/v1/graphql/

Get an energy product that matches the given code.

Arguments

NameDescription

code (String!)

Code for the energy product.

Query

query EnergyProduct($code: String!) {
  energyProduct(code: $code) {
    id
    fullName
    displayName
    description
    availableFrom
    availableTo
    isHidden
    code
    direction
    notes
    isVariable
    isGreen
    isBusiness
    isChargedHalfHourly
    isPrepay
    isDefault
    isOccupier
    term
    tariffs {
      ...EnergyTariffConnectionTypeConnectionFragment
    }
    isAvailable
    isUnavailable
    isFixed
    isDomestic
    includesEpgReduction
    exitFees
    exitFeesType
    tags
  }
}

Variables

{
  "code": "abc123"
}

Response

{
  "data": {
    "energyProduct": {
      "id": "abc123",
      "fullName": "abc123",
      "displayName": "abc123",
      "description": "abc123",
      "availableFrom": "2020-01-01T00:00:00.000Z",
      "availableTo": "2020-01-01T00:00:00.000Z",
      "isHidden": true,
      "code": "abc123",
      "direction": "IMPORT",
      "notes": "abc123",
      "isVariable": true,
      "isGreen": true,
      "isBusiness": true,
      "isChargedHalfHourly": true,
      "isPrepay": true,
      "isDefault": true,
      "isOccupier": true,
      "term": 1,
      "tariffs": EnergyTariffConnectionTypeConnection,
      "isAvailable": true,
      "isUnavailable": true,
      "isFixed": true,
      "isDomestic": true,
      "includesEpgReduction": true,
      "exitFees": 1,
      "exitFeesType": "abc123",
      "tags": ["abc123"]
    }
  }
}

energyProducts

Type:EnergyProductConnectionTypeConnection

URL:https://api.octopus.energy/v1/graphql/

Get all products for a given brand and postcode. The supplied postcode will ensure that there are tariffs available on the product for the GSP.

Arguments

NameDescription

postcode (String!)

Postcode to search energy products for.

tags ([String])

Filter by specific tags which are attached to the product.

brand (String)

Filter by a specific energy brand.

brands ([String])

Filter by these brands.

availability (EnergyProductAvailability)

Filter for available or unavailable products only.

filterBy ([EnergyProductFilters])

Filter by the type of energy product.

direction (EnergyProductDirection)

Energy product direction to filter products by.

before (String)

after (String)

first (Int)

last (Int)

Query

query EnergyProducts(
  $postcode: String!,
  $tags: [String],
  $brand: String,
  $brands: [String],
  $availability: EnergyProductAvailability,
  $filterBy: [EnergyProductFilters],
  $direction: EnergyProductDirection,
  $before: String,
  $after: String,
  $first: Int,
  $last: Int
) {
  energyProducts(
    postcode: $postcode,
    tags: $tags,
    brand: $brand,
    brands: $brands,
    availability: $availability,
    filterBy: $filterBy,
    direction: $direction,
    before: $before,
    after: $after,
    first: $first,
    last: $last
  ) {
    pageInfo {
      ...PageInfoFragment
    }
    edges {
      ...EnergyProductConnectionTypeEdgeFragment
    }
    totalCount
    edgeCount
  }
}

Variables

{
  "postcode": "abc123",
  "tags": ["abc123"],
  "brand": "abc123",
  "brands": ["abc123"],
  "availability": "AVAILABLE",
  "filterBy": "PREPAY",
  "direction": "IMPORT",
  "before": "abc123",
  "after": "abc123",
  "first": 1,
  "last": 1
}

Response

{
  "data": {
    "energyProducts": {
      "pageInfo": PageInfo,
      "edges": EnergyProductConnectionTypeEdge,
      "totalCount": 1,
      "edgeCount": 1
    }
  }
}

enodeLinkSession

Type:EnodeLinkSessionType

URL:https://api.octopus.energy/v1/graphql/

The user specific Enode link session details.

The possible errors that can be raised are:

  • KT-CT-4328: Invalid data.
  • KT-CT-1111: Unauthorized.
  • KT-CT-4319: Unable to get Enode link session.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String)

vendor (EnodeVendors)

Query

query EnodeLinkSession(
  $accountNumber: String,
  $vendor: EnodeVendors
) {
  enodeLinkSession(
    accountNumber: $accountNumber,
    vendor: $vendor
  ) {
    linkState
    linkUrl
  }
}

Variables

{
  "accountNumber": "abc123",
  "vendor": "AUDI"
}

Response

{
  "data": {
    "enodeLinkSession": {
      "linkState": "abc123",
      "linkUrl": "abc123"
    }
  }
}

fanClubStatus

Type:[FanClubStatus]

URL:https://api.octopus.energy/v1/graphql/

Get current status, historic discounts and future projections for a Fan Club source.

Arguments

NameDescription

accountNumber (String)

The account number.

propertyId (Int)

The ID of the property.

Query

query FanClubStatus(
  $accountNumber: String,
  $propertyId: Int
) {
  fanClubStatus(
    accountNumber: $accountNumber,
    propertyId: $propertyId
  ) {
    discountSource
    name
    location
    windFarm
    accountNumbers
    propertyIds
    catchments
    thresholds {
      ...ThresholdFragment
    }
    current {
      ...DiscountDataFragment
    }
    historic {
      ...DiscountDataFragment
    }
    forecast {
      ...DiscountForecastFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123",
  "propertyId": 1
}

Response

{
  "data": {
    "fanClubStatus": [
      {
        "discountSource": "abc123",
        "name": "abc123",
        "location": "abc123",
        "windFarm": "abc123",
        "accountNumbers": "abc123",
        "propertyIds": 1,
        "catchments": "abc123",
        "thresholds": Threshold,
        "current": DiscountData,
        "historic": DiscountData,
        "forecast": DiscountForecast
      }
    ]
  }
}

fitInstallations

Type:[InstallationType]

URL:https://api.octopus.energy/v1/graphql/

Get details about FIT installations attached to an account, including any meters and previous readings.

Arguments

NameDescription

accountNumber (String!)

Account to query for FIT installations.

Query

query FitInstallations($accountNumber: String!) {
  fitInstallations(accountNumber: $accountNumber) {
    fitId
    inspectionAt
    meters {
      ...FitMeterTypeFragment
    }
    propertyAddress {
      ...PropertyAddressTypeFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "fitInstallations": [
      {
        "fitId": "abc123",
        "inspectionAt": "2020-01-01T00:00:00.000Z",
        "meters": [FitMeterType],
        "propertyAddress": PropertyAddressType
      }
    ]
  }
}

fitSchedule

Type:FitScheduleType

URL:https://api.octopus.energy/v1/graphql/

Get details about a FIT schedule attached to an account.

The possible errors that can be raised are:

  • KT-CT-4177: Unauthorized.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

The number of the account responsible for this FIT schedule.

scheduleId (String!)

Unique identifier for the schedule.

Query

query FitSchedule(
  $accountNumber: String!,
  $scheduleId: String!
) {
  fitSchedule(
    accountNumber: $accountNumber,
    scheduleId: $scheduleId
  ) {
    scheduleId
    sentAt
    acceptedAt
    temporaryDownloadUrls
  }
}

Variables

{
  "accountNumber": "abc123",
  "scheduleId": "abc123"
}

Response

{
  "data": {
    "fitSchedule": {
      "scheduleId": "500c164d-38c7-4f74-9ac6-be210197e9e4",
      "sentAt": "2020-01-01T00:00:00.000Z",
      "acceptedAt": "2020-01-01T00:00:00.000Z",
      "temporaryDownloadUrls": ["abc123"]
    }
  }
}

followOnProduct

Type:FollowOnProductType

URL:https://api.octopus.energy/v1/graphql/

Follow on product.

The possible errors that can be raised are:

  • KT-GB-9510: At least one agreement ID is required.
  • KT-GB-9511: Please, provide either electricityagreementid or gasagreementid. Both are not accepted.
  • KT-GB-9512: No agreement found.
  • KT-GB-9513: No follow on product found.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

Kraken account number.

electricityAgreementId (ID)

Electricity agreement Kraken ID.

gasAgreementId (ID)

Gas agreement Kraken ID.

validAt (DateTime!)

Query

query FollowOnProduct(
  $accountNumber: String!,
  $electricityAgreementId: ID,
  $gasAgreementId: ID,
  $validAt: DateTime!
) {
  followOnProduct(
    accountNumber: $accountNumber,
    electricityAgreementId: $electricityAgreementId,
    gasAgreementId: $gasAgreementId,
    validAt: $validAt
  ) {
    activeFrom
    activeTo
    accountType
    paymentMethod
    renewalProducts {
      ...RenewalProductTypeFragment
    }
    createdAt
  }
}

Variables

{
  "accountNumber": "abc123",
  "electricityAgreementId": "abc123",
  "gasAgreementId": "abc123",
  "validAt": "2020-01-01T00:00:00.000Z"
}

Response

{
  "data": {
    "followOnProduct": {
      "activeFrom": "2020-01-01T00:00:00.000Z",
      "activeTo": "2020-01-01T00:00:00.000Z",
      "accountType": "BUSINESS",
      "paymentMethod": "DIRECT_DEBIT",
      "renewalProducts": [RenewalProductType],
      "createdAt": "2020-01-01T00:00:00.000Z"
    }
  }
}

gasAgreement

Type:AgreementInterface

URL:https://api.octopus.energy/v1/graphql/

Get an gas agreement.

This field requires the Authorization header to be set.

Arguments

NameDescription

id (ID!)

Query

query GasAgreement($id: ID!) {
  gasAgreement(id: $id) {
    id
    validFrom
    validTo
    agreedFrom
    agreedTo
    isRevoked
  }
}

Variables

{
  "id": "abc123"
}

Response

{
  "data": {
    "gasAgreement": {
      "id": 1,
      "validFrom": "2020-01-01T00:00:00.000Z",
      "validTo": "2020-01-01T00:00:00.000Z",
      "agreedFrom": "2020-01-01T00:00:00.000Z",
      "agreedTo": "2020-01-01T00:00:00.000Z",
      "isRevoked": true
    }
  }
}

gasMeterReadings

Type:GasMeterReadingConnectionTypeConnection

URL:https://api.octopus.energy/v1/graphql/

Fetch gas meter readings for a given account and meter

This field is a connection type. Connections are used to implement cursor based pagination.

This field requires the Authorization header to be set.

Arguments

NameDescription

accountNumber (String!)

meterId (String!)

eventTypes ([MeterReadingEventType])

readFrom (DateTime)

Only fetch meter readings made since this date

readTo (DateTime)

Only fetch meter readings made until this date

before (String)

after (String)

first (Int)

last (Int)

Query

query GasMeterReadings(
  $accountNumber: String!,
  $meterId: String!,
  $eventTypes: [MeterReadingEventType],
  $readFrom: DateTime,
  $readTo: DateTime,
  $before: String,
  $after: String,
  $first: Int,
  $last: Int
) {
  gasMeterReadings(
    accountNumber: $accountNumber,
    meterId: $meterId,
    eventTypes: $eventTypes,
    readFrom: $readFrom,
    readTo: $readTo,
    before: $before,
    after: $after,
    first: $first,
    last: $last
  ) {
    pageInfo {
      ...PageInfoFragment
    }
    edges {
      ...GasMeterReadingConnectionTypeEdgeFragment
    }
    totalCount
    edgeCount
  }
}

Variables

{
  "accountNumber": "abc123",
  "meterId": "abc123",
  "eventTypes": "CUSTOMER",
  "readFrom": "2020-01-01T00:00:00.000Z",
  "readTo": "2020-01-01T00:00:00.000Z",
  "before": "abc123",
  "after": "abc123",
  "first": 1,
  "last": 1
}

Response

{
  "data": {
    "gasMeterReadings": {
      "pageInfo": PageInfo,
      "edges": GasMeterReadingConnectionTypeEdge,
      "totalCount": 1,
      "edgeCount": 1
    }
  }
}

gasMeterpoint

Type:GasMeterTechnicalDetails

URL:https://api.octopus.energy/v1/graphql/

Search for the meterpoint with given MPRN using Xoserve switching API.

The possible errors that can be raised are:

  • KT-GB-6635: The provided MPRN is not valid.
  • KT-GB-6630: We can't communicate with our address database right now to look up your address. Please try again.
  • KT-GB-6636: The provided MPRN is linked to an extinct meterpoint.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

mprn (String!)

The MPRN of the meterpoint.

Query

query GasMeterpoint($mprn: String!) {
  gasMeterpoint(mprn: $mprn) {
    mprn
    currentSupplierId
    currentSupplierRegEffectiveDate
    pendingSupplierRegEffectiveDate
    dmq
    gasTransportId
    ldzId
    meterCapacity
    meterMechanismCode
    meterNumberOfDials
    meterSerialNumber
    mpaq
    marketSectorCode
    ndmq
    smartEquipmentTechnicalCode
  }
}

Variables

{
  "mprn": "abc123"
}

Response

{
  "data": {
    "gasMeterpoint": {
      "mprn": "abc123",
      "currentSupplierId": "abc123",
      "currentSupplierRegEffectiveDate": "abc123",
      "pendingSupplierRegEffectiveDate": "abc123",
      "dmq": 1.0,
      "gasTransportId": "abc123",
      "ldzId": "abc123",
      "meterCapacity": "abc123",
      "meterMechanismCode": "abc123",
      "meterNumberOfDials": "abc123",
      "meterSerialNumber": "abc123",
      "mpaq": 1.0,
      "marketSectorCode": "abc123",
      "ndmq": 1.0,
      "smartEquipmentTechnicalCode": "abc123"
    }
  }
}

gasPrepayLedgers

Type:PrepayLedgersType

URL:https://api.octopus.energy/v1/graphql/

Override Field to add additional attributes and extend description with possible_errors

The possible errors that can be raised are:

  • KT-GB-6211: Account does not exist.
  • KT-GB-6212: Meter does not exist.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

mprn (String!)

serialNumber (String!)

Query

query GasPrepayLedgers(
  $accountNumber: String!,
  $mprn: String!,
  $serialNumber: String!
) {
  gasPrepayLedgers(
    accountNumber: $accountNumber,
    mprn: $mprn,
    serialNumber: $serialNumber
  ) {
    creditLedger {
      ...SupplementaryLedgerTypeFragment
    }
    debtLedger {
      ...SupplementaryLedgerTypeFragment
    }
    paymentLedger {
      ...PrepayPaymentLedgerTypeFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123",
  "mprn": "abc123",
  "serialNumber": "abc123"
}

Response

{
  "data": {
    "gasPrepayLedgers": {
      "creditLedger": SupplementaryLedgerType,
      "debtLedger": SupplementaryLedgerType,
      "paymentLedger": PrepayPaymentLedgerType
    }
  }
}

getActiveCosLossProcessesForAccount

Type:[ActiveCosLossProcess]

URL:https://api.octopus.energy/v1/graphql/

Fetch all the active COS loss processes for the account.

Arguments

NameDescription

accountNumber (String!)

The account number of the account of which to query active COS loss processes.

Query

query GetActiveCosLossProcessesForAccount($accountNumber: String!) {
  getActiveCosLossProcessesForAccount(accountNumber: $accountNumber) {
    cosLossProcessId
    cosLossProcessFuelType
    addressLine1
    addressLine2
    addressLine3
    postcode
    supplyEndDate
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "getActiveCosLossProcessesForAccount": [
      {
        "cosLossProcessId": 1,
        "cosLossProcessFuelType": "ELECTRICITY",
        "addressLine1": "abc123",
        "addressLine2": "abc123",
        "addressLine3": "abc123",
        "postcode": "abc123",
        "supplyEndDate": "2020-01-01"
      }
    ]
  }
}

getConstantines

Type:ConstantineSpawnData

URL:https://api.octopus.energy/v1/graphql/

Octoplus Snap constantines currently available for a given account_user.

The possible errors that can be raised are:

  • KT-CT-1111: Unauthorized.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

Account number for the Octoplus-enrolled account.

Query

query GetConstantines($accountNumber: String!) {
  getConstantines(accountNumber: $accountNumber) {
    constantines {
      ...ConstantineSpawnFragment
    }
    cacheExpiry
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "getConstantines": {
      "constantines": [ConstantineSpawn],
      "cacheExpiry": "2020-01-01T00:00:00.000Z"
    }
  }
}

getEnergyIqData

Type:EnergyIqDataType

URL:https://api.octopus.energy/v1/graphql/

Get energy IQ data for a specific account. It can either be the current record for energy IQ score or a score estimation including ev/heatpump/solar.

The possible errors that can be raised are:

  • KT-CT-4123: Unauthorized.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

The number of the account to get energy IQ data for.

isCurrentRecord (Boolean)

Is the query for the current energy IQ record? If true no 'include' parameters may be provided.

includeHeatpump (Boolean)

Should the energy IQ estimation data include heatpump.

includeSolar (Boolean)

Should the energy IQ estimation data include solar.

includeEv (Boolean)

Should the energy IQ estimation data include EV.

Query

query GetEnergyIqData(
  $accountNumber: String!,
  $isCurrentRecord: Boolean,
  $includeHeatpump: Boolean,
  $includeSolar: Boolean,
  $includeEv: Boolean
) {
  getEnergyIqData(
    accountNumber: $accountNumber,
    isCurrentRecord: $isCurrentRecord,
    includeHeatpump: $includeHeatpump,
    includeSolar: $includeSolar,
    includeEv: $includeEv
  ) {
    enqScore
    currentBill
    newBill
    hasEv
    hasSolar
    hasHeatpump
    elecCarRate
    isCurrentRecord
    canAddSolar
    canAddHeatpump
  }
}

Variables

{
  "accountNumber": "abc123",
  "isCurrentRecord": true,
  "includeHeatpump": true,
  "includeSolar": true,
  "includeEv": true
}

Response

{
  "data": {
    "getEnergyIqData": {
      "enqScore": 1,
      "currentBill": 1.0,
      "newBill": 1.0,
      "hasEv": true,
      "hasSolar": true,
      "hasHeatpump": true,
      "elecCarRate": 1.0,
      "isCurrentRecord": true,
      "canAddSolar": true,
      "canAddHeatpump": true
    }
  }
}

Arguments

NameDescription

latestMessageRelayId (String)

A message's relay id, to filter out older messages.

accountNumber (String!)

The account number.

Query

query GetInkChatbotMessages(
  $latestMessageRelayId: String,
  $accountNumber: String!
) {
  getInkChatbotMessages(
    latestMessageRelayId: $latestMessageRelayId,
    accountNumber: $accountNumber
  ) {
    ... on InkEmail {
      ...InkEmailFragment
    }
    ... on InkSMS {
      ...InkSMSFragment
    }
    ... on InkLine {
      ...InkLineFragment
    }
    ... on InkWhatsApp {
      ...InkWhatsAppFragment
    }
    ... on InkTwilioWhatsApp {
      ...InkTwilioWhatsAppFragment
    }
    ... on InkPost {
      ...InkPostFragment
    }
    ... on InkGenericMessage {
      ...InkGenericMessageFragment
    }
  }
}

Variables

{
  "latestMessageRelayId": "abc123",
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "getInkChatbotMessages": InkEmail
  }
}

getProjectedRegionalCarbonIntensity

Type:ProjectedRegionalCarbonIntensityType

URL:https://api.octopus.energy/v1/graphql/

Get regional carbon intensity forecast.

The possible errors that can be raised are:

  • KT-GB-1301: The provided postcode is not a UK postcode.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

postcode (String!)

The postcode for which to fetch regional carbon intensity forecast.

Query

query GetProjectedRegionalCarbonIntensity($postcode: String!) {
  getProjectedRegionalCarbonIntensity(postcode: $postcode) {
    projectedRegionalCarbonIntensity {
      ...ProjectedRegionalCarbonIntensitiesTypeFragment
    }
  }
}

Variables

{
  "postcode": "abc123"
}

Response

{
  "data": {
    "getProjectedRegionalCarbonIntensity": {
      "projectedRegionalCarbonIntensity": [ProjectedRegionalCarbonIntensitiesType]
    }
  }
}

getSnaps

Type:GetSnapsResponseType

URL:https://api.octopus.energy/v1/graphql/

Get snap for given account user.

The possible errors that can be raised are:

  • KT-CT-1111: Unauthorized.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

Account number for the Octoplus-enrolled account.

Query

query GetSnaps($accountNumber: String!) {
  getSnaps(accountNumber: $accountNumber) {
    sets {
      ...SnapSetTypeFragment
    }
    totalPrizeEntries
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "getSnaps": {
      "sets": [SnapSetType],
      "totalPrizeEntries": 1
    }
  }
}

getSolarGenerationEstimate

Type:SolarGenerationEstimatesType

URL:https://api.octopus.energy/v1/graphql/

Get an estimate of the number of kWh an average domestic solar installation would produce for a given postcode.

The possible errors that can be raised are:

  • KT-GB-1301: The provided postcode is not a UK postcode.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

postcode (String!)

The postcode area to fetch estimate for.

fromDate (Date!)

The start date from which to pull a weeks worth of data.

Query

query GetSolarGenerationEstimate(
  $postcode: String!,
  $fromDate: Date!
) {
  getSolarGenerationEstimate(
    postcode: $postcode,
    fromDate: $fromDate
  ) {
    solarGenerationEstimates {
      ...SolarGenerationEstimateTypeFragment
    }
  }
}

Variables

{
  "postcode": "abc123",
  "fromDate": "2020-01-01"
}

Response

{
  "data": {
    "getSolarGenerationEstimate": {
      "solarGenerationEstimates": [SolarGenerationEstimateType]
    }
  }
}

getSpringElectricityComparison

Type:SpringElectricityComparisonType

URL:https://api.octopus.energy/v1/graphql/

Get spring clock change electricity consumption comparison data for a specific account and property.

The possible errors that can be raised are:

  • KT-CT-4123: Unauthorized.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

The account number to get comparison data for.

propertyId (Int!)

The ID for the specific property to get comparison data for.

Query

query GetSpringElectricityComparison(
  $accountNumber: String!,
  $propertyId: Int!
) {
  getSpringElectricityComparison(
    accountNumber: $accountNumber,
    propertyId: $propertyId
  ) {
    priorPeakPercentage
    postPeakPercentage
    absoluteReductionPercentage
    relativeReductionPercentage
    isReduction
  }
}

Variables

{
  "accountNumber": "abc123",
  "propertyId": 1
}

Response

{
  "data": {
    "getSpringElectricityComparison": {
      "priorPeakPercentage": 1.0,
      "postPeakPercentage": 1.0,
      "absoluteReductionPercentage": 1.0,
      "relativeReductionPercentage": 1.0,
      "isReduction": true
    }
  }
}

getWinterGasComparison

Type:WinterGasComparisonResultType

URL:https://api.octopus.energy/v1/graphql/

Get gas consumption comparison data for a specific account and property.

The possible errors that can be raised are:

  • KT-CT-4123: Unauthorized.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

The account number to get comparison data for.

propertyId (Int!)

The ID for the specific property to get comparison data for.

Query

query GetWinterGasComparison(
  $accountNumber: String!,
  $propertyId: Int!
) {
  getWinterGasComparison(
    accountNumber: $accountNumber,
    propertyId: $propertyId
  ) {
    winterGasComparison {
      ...WinterGasComparisonTypeFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123",
  "propertyId": 1
}

Response

{
  "data": {
    "getWinterGasComparison": {
      "winterGasComparison": [WinterGasComparisonType]
    }
  }
}

Arguments

NameDescription

marketName (String!)

Market name of the products to list.

productType ([String])

Types of the products to filter by.

code ([String])

Code of the products to filter by.

before (String)

after (String)

first (Int)

last (Int)

Query

query GoodsProducts(
  $marketName: String!,
  $productType: [String],
  $code: [String],
  $before: String,
  $after: String,
  $first: Int,
  $last: Int
) {
  goodsProducts(
    marketName: $marketName,
    productType: $productType,
    code: $code,
    before: $before,
    after: $after,
    first: $first,
    last: $last
  ) {
    pageInfo {
      ...PageInfoFragment
    }
    edges {
      ...GoodsProductConnectionTypeEdgeFragment
    }
    totalCount
    edgeCount
  }
}

Variables

{
  "marketName": "abc123",
  "productType": ["abc123"],
  "code": ["abc123"],
  "before": "abc123",
  "after": "abc123",
  "first": 1,
  "last": 1
}

Response

{
  "data": {
    "goodsProducts": {
      "pageInfo": PageInfo,
      "edges": GoodsProductConnectionTypeEdge,
      "totalCount": 1,
      "edgeCount": 1
    }
  }
}

Arguments

NameDescription

accountNumber (String!)

The account number.

Query

query GoodsPurchases($accountNumber: String!) {
  goodsPurchases(accountNumber: $accountNumber) {
    code
    ledgerId
    ledgerNumber
    goodsSaleItems {
      ...GoodsSaleItemFragment
    }
    goodsGrants {
      ...GoodsGrantFragment
    }
    marketName
    marketParams
    clientParams
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "goodsPurchases": [
      {
        "code": "abc123",
        "ledgerId": "abc123",
        "ledgerNumber": "abc123",
        "goodsSaleItems": [GoodsSaleItem],
        "goodsGrants": [GoodsGrant],
        "marketName": "abc123",
        "marketParams": {"key": "value"},
        "clientParams": {"key": "value"}
      }
    ]
  }
}

goodsQuotes

Type:[GoodsQuote]

URL:https://api.octopus.energy/v1/graphql/

List quotes given an account number or retrieve a Goods quote given a quote code.

Arguments

NameDescription

accountNumber (String)

The account number.

quoteCode (String)

The quote code.

Query

query GoodsQuotes(
  $accountNumber: String,
  $quoteCode: String
) {
  goodsQuotes(
    accountNumber: $accountNumber,
    quoteCode: $quoteCode
  ) {
    id
    code
    totalNetAmount
    quotedAt
    goodsQuotedProducts {
      ...GoodsQuotedProductFragment
    }
    hasQuoteExpired
  }
}

Variables

{
  "accountNumber": "abc123",
  "quoteCode": "abc123"
}

Response

{
  "data": {
    "goodsQuotes": [
      {
        "id": "abc123",
        "code": "abc123",
        "totalNetAmount": 1,
        "quotedAt": "2020-01-01T00:00:00.000Z",
        "goodsQuotedProducts": [GoodsQuotedProduct],
        "hasQuoteExpired": true
      }
    ]
  }
}

greennessForecast

Type:[GreennessForecastPeriod]

URL:https://api.octopus.energy/v1/graphql/

A forecast of how green the electricity generation is predicted to be (do not assume a fixed length, that the periods are contiguous or in time order).

Query

query GreennessForecast {
  greennessForecast {
    validFrom
    validTo
    greennessScore
    greennessIndex
    highlightFlag
  }
}

Response

{
  "data": {
    "greennessForecast": [
      {
        "validFrom": "2020-01-01T00:00:00.000Z",
        "validTo": "2020-01-01T00:00:00.000Z",
        "greennessScore": 1,
        "greennessIndex": "LOW",
        "highlightFlag": true
      }
    ]
  }
}

hasAlreadyReceivedBlanket

Type:Boolean

URL:https://api.octopus.energy/v1/graphql/

Whether the account has already received a blanket.

The possible errors that can be raised are:

  • KT-GB-6011: Unable to determine if blanket has already been sent.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

The account number to check.

Query

query HasAlreadyReceivedBlanket($accountNumber: String!) {
  hasAlreadyReceivedBlanket(accountNumber: $accountNumber)
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "hasAlreadyReceivedBlanket": true
  }
}

hasReceivedADiscountCode

Type:Boolean

URL:https://api.octopus.energy/v1/graphql/

Whether the account has already received a discount code.

Arguments

NameDescription

accountNumber (String!)

Kraken account number.

Query

query HasReceivedADiscountCode($accountNumber: String!) {
  hasReceivedADiscountCode(accountNumber: $accountNumber)
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "hasReceivedADiscountCode": true
  }
}

heatPumpControllerConfiguration

Type:ControllerAndZoneConfiguration

URL:https://api.octopus.energy/v1/graphql/

Heat pump controller, zones and sensor configuration.

The possible errors that can be raised are:

  • KT-CT-4305: Unable to fetch heating controller configuration.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

euid (ID!)

Query

query HeatPumpControllerConfiguration(
  $accountNumber: String!,
  $euid: ID!
) {
  heatPumpControllerConfiguration(
    accountNumber: $accountNumber,
    euid: $euid
  ) {
    controller {
      ...ControllerConfigurationFragment
    }
    zones {
      ...ZoneInformationFragment
    }
    heatPump {
      ...HeatPumpConfigurationFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123",
  "euid": "abc123"
}

Response

{
  "data": {
    "heatPumpControllerConfiguration": {
      "controller": ControllerConfiguration,
      "zones": [ZoneInformation],
      "heatPump": HeatPumpConfiguration
    }
  }
}

heatPumpControllerStatus

Type:ControllerStatus

URL:https://api.octopus.energy/v1/graphql/

Retrieve the heat pump controller device status.

The possible errors that can be raised are:

  • KT-CT-4303: Unable to fetch device status.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

euid (ID!)

Query

query HeatPumpControllerStatus(
  $accountNumber: String!,
  $euid: ID!
) {
  heatPumpControllerStatus(
    accountNumber: $accountNumber,
    euid: $euid
  ) {
    sensors {
      ...SensorStatusFragment
    }
    zones {
      ...ZoneStatusFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123",
  "euid": "abc123"
}

Response

{
  "data": {
    "heatPumpControllerStatus": {
      "sensors": [SensorStatus],
      "zones": [ZoneStatus]
    }
  }
}

heatPumpDevice

Type:HeatPumpDeviceType

URL:https://api.octopus.energy/v1/graphql/

The currently active heat pump device.

The possible errors that can be raised are:

  • KT-CT-1111: Unauthorized.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

propertyId (Int!)

Query

query HeatPumpDevice(
  $accountNumber: String!,
  $propertyId: Int!
) {
  heatPumpDevice(
    accountNumber: $accountNumber,
    propertyId: $propertyId
  ) {
    krakenflexDeviceId
    deviceType
    provider
    params {
      ...HeatPumpParamsTypeFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123",
  "propertyId": 1
}

Response

{
  "data": {
    "heatPumpDevice": {
      "krakenflexDeviceId": "abc123",
      "deviceType": "BATTERIES",
      "provider": "DAIKIN",
      "params": HeatPumpParamsType
    }
  }
}

Arguments

NameDescription

code (String!)

Quote code.

Query

query HeatPumpGoodsQuote($code: String!) {
  heatPumpGoodsQuote(code: $code) {
    accountNumber
    code
    quoteId
    quotedProduct {
      ...GoodsQuotedProductFragment
    }
    contactDetails {
      ...ContactDetailsFragment
    }
    addressDetails {
      ...AddressDetailsFragment
    }
  }
}

Variables

{
  "code": "abc123"
}

Response

{
  "data": {
    "heatPumpGoodsQuote": {
      "accountNumber": "abc123",
      "code": "abc123",
      "quoteId": 1,
      "quotedProduct": GoodsQuotedProduct,
      "contactDetails": ContactDetails,
      "addressDetails": AddressDetails
    }
  }
}

heatPumpStatus

Type:HeatPumpStatusType

URL:https://api.octopus.energy/v1/graphql/

A heat pump registered with KrakenFlex for a given account

The possible errors that can be raised are:

  • KT-CT-1111: Unauthorized.
  • KT-CT-4360: Device status could not be fetched.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

Query

query HeatPumpStatus($accountNumber: String!) {
  heatPumpStatus(accountNumber: $accountNumber) {
    isConnected
    climateControlStatus {
      ...ClimateControlDetailsTypeFragment
    }
    waterTemperatureStatus {
      ...WaterTemperatureDetailsTypeFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "heatPumpStatus": {
      "isConnected": true,
      "climateControlStatus": ClimateControlDetailsType,
      "waterTemperatureStatus": WaterTemperatureDetailsType
    }
  }
}

Arguments

NameDescription

make (String)

Only return heat pumps of a specific make.

isDeprecated (Boolean)

Only return (non-) deprecated heat pumps.

Query

query HeatPumpVariants(
  $make: String,
  $isDeprecated: Boolean
) {
  heatPumpVariants(
    make: $make,
    isDeprecated: $isDeprecated
  ) {
    make
    models {
      ...HeatPumpVariantModelsTypeFragment
    }
  }
}

Variables

{
  "make": "abc123",
  "isDeprecated": true
}

Response

{
  "data": {
    "heatPumpVariants": [
      {
        "make": "abc123",
        "models": [HeatPumpVariantModelsType]
      }
    ]
  }
}

inkConversation

Type:InkConversation!

URL:https://api.octopus.energy/v1/graphql/

Get the Ink conversation for a given account.

The possible errors that can be raised are:

  • KT-CT-7612: The Ink conversation was not found.
  • KT-CT-4177: Unauthorized.
  • KT-CT-7610: No Ink conversation for account.
  • KT-CT-7617: Must supply account number or relay id to get a conversation.
  • KT-CT-7638: Invalid conversation ID.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String)

The account number.

conversationRelayId (String)

The conversation's relay id.

Query

query InkConversation(
  $accountNumber: String,
  $conversationRelayId: String
) {
  inkConversation(
    accountNumber: $accountNumber,
    conversationRelayId: $conversationRelayId
  ) {
    id
    status
    contactChannelIdentities {
      ...InkContactChannelIdentitiesFragment
    }
    accountUsers {
      ...AccountUserTypeFragment
    }
    events {
      ...InkConversationEventsConnectionFragment
    }
    buckets {
      ...InkBucketFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123",
  "conversationRelayId": "abc123"
}

Response

{
  "data": {
    "inkConversation": {
      "id": "abc123",
      "status": "OPEN",
      "contactChannelIdentities": InkContactChannelIdentities,
      "accountUsers": [AccountUserType],
      "events": InkConversationEventsConnection,
      "buckets": [InkBucket]
    }
  }
}

inkMessage

Type:InkMessage!

URL:https://api.octopus.energy/v1/graphql/

Get the content for a given message.

The possible errors that can be raised are:

  • KT-CT-7611: The message was not found.
  • KT-CT-7638: Invalid conversation ID.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

messageRelayId (String!)

The message's relay id.

Query

query InkMessage($messageRelayId: String!) {
  inkMessage(messageRelayId: $messageRelayId) {
    ... on InkEmail {
      ...InkEmailFragment
    }
    ... on InkSMS {
      ...InkSMSFragment
    }
    ... on InkLine {
      ...InkLineFragment
    }
    ... on InkWhatsApp {
      ...InkWhatsAppFragment
    }
    ... on InkTwilioWhatsApp {
      ...InkTwilioWhatsAppFragment
    }
    ... on InkPost {
      ...InkPostFragment
    }
    ... on InkGenericMessage {
      ...InkGenericMessageFragment
    }
  }
}

Variables

{
  "messageRelayId": "abc123"
}

Response

{
  "data": {
    "inkMessage": InkEmail
  }
}

isPasswordResetTokenValid

Type:Boolean

URL:https://api.octopus.energy/v1/graphql/

Check validity of a password reset token.

Arguments

NameDescription

userId (String!)

Base64 encoded user id.

token (String!)

Password reset token to check.

Query

query IsPasswordResetTokenValid(
  $userId: String!,
  $token: String!
) {
  isPasswordResetTokenValid(
    userId: $userId,
    token: $token
  )
}

Variables

{
  "userId": "abc123",
  "token": "abc123"
}

Response

{
  "data": {
    "isPasswordResetTokenValid": true
  }
}

Query

query KrakenVersion {
  krakenVersion {
    number
    SHA
  }
}

Response

{
  "data": {
    "krakenVersion": {
      "number": "abc123",
      "SHA": "abc123"
    }
  }
}

leaveSupplierProcess

Type:LeaveSupplierProcessType

URL:https://api.octopus.energy/v1/graphql/

Details associated with a LeaveSupplier process.

The possible errors that can be raised are:

  • KT-CT-10302: Invalid data.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

leaveSupplierProcessId (ID!)

The leave supplier process ID.

Query

query LeaveSupplierProcess($leaveSupplierProcessId: ID!) {
  leaveSupplierProcess(leaveSupplierProcessId: $leaveSupplierProcessId) {
    id
    status
    supplyPoints {
      ...SupplyPointConnectionTypeConnectionFragment
    }
  }
}

Variables

{
  "leaveSupplierProcessId": "abc123"
}

Response

{
  "data": {
    "leaveSupplierProcess": {
      "id": "abc123",
      "status": "COMPLETED",
      "supplyPoints": SupplyPointConnectionTypeConnection
    }
  }
}

lifecycleProcesses

Type:LifecycleProcessesType

URL:https://api.octopus.energy/v1/graphql/

Get all lifecycle processes associated with an account.

The possible errors that can be raised are:

  • KT-CT-4123: Unauthorized.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

onlyActive (Boolean)

A flag to filter out only active/current processes.

sortOrder (LifecycleProcessesSortOrder)

The chronological order in which the lifecycle processes are sorted.

accountNumber (String!)

The account number, e.g. A-12345678.

Query

query LifecycleProcesses(
  $onlyActive: Boolean,
  $sortOrder: LifecycleProcessesSortOrder,
  $accountNumber: String!
) {
  lifecycleProcesses(
    onlyActive: $onlyActive,
    sortOrder: $sortOrder,
    accountNumber: $accountNumber
  ) {
    leaveSupplierProcesses {
      ...LeaveSupplierProcessConnectionTypeConnectionFragment
    }
    joinSupplierProcesses {
      ...JoinSupplierProcessConnectionTypeConnectionFragment
    }
    occupyPropertyProcesses {
      ...OccupyPropertyProcessConnectionTypeConnectionFragment
    }
    leavePropertyProcesses {
      ...LeavePropertyProcessConnectionTypeConnectionFragment
    }
  }
}

Variables

{
  "onlyActive": true,
  "sortOrder": "ASC",
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "lifecycleProcesses": {
      "leaveSupplierProcesses": LeaveSupplierProcessConnectionTypeConnection,
      "joinSupplierProcesses": JoinSupplierProcessConnectionTypeConnection,
      "occupyPropertyProcesses": OccupyPropertyProcessConnectionTypeConnection,
      "leavePropertyProcesses": LeavePropertyProcessConnectionTypeConnection
    }
  }
}

livePaymentAdequacy

Type:LivePaymentAdequacyQuery

URL:https://api.octopus.energy/v1/graphql/

Get up to date payment adequacy data.

The possible errors that can be raised are:

  • KT-CT-3923: Unauthorized.
  • KT-GB-3916: No statement in last 60 days.
  • KT-GB-3915: Could not calculate current PA data.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

Kraken account number.

Query

query LivePaymentAdequacy($accountNumber: String!) {
  livePaymentAdequacy(accountNumber: $accountNumber) {
    recommendedPayment {
      ...PaymentBreakdownFragment
    }
    currentBalance
    targetBalance
    estimatedConsumption {
      ...ConsumptionBreakdownFragment
    }
    reviewedOn
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "livePaymentAdequacy": {
      "recommendedPayment": PaymentBreakdown,
      "currentBalance": 1,
      "targetBalance": 1,
      "estimatedConsumption": [ConsumptionBreakdown],
      "reviewedOn": "2020-01-01"
    }
  }
}

livePaymentAdequacyCalculation

Type:LivePaymentAdequacyCalculation

URL:https://api.octopus.energy/v1/graphql/

Get payment adequacy data with an up to date calculation.

The possible errors that can be raised are:

  • KT-CT-3963: Could not calculate live PA data.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

ledgerNumber (String!)

Kraken ledger number.

Query

query LivePaymentAdequacyCalculation($ledgerNumber: String!) {
  livePaymentAdequacyCalculation(ledgerNumber: $ledgerNumber) {
    suggestedNewMonthlyAmount
    consumption {
      ...ConsumptionBreakdownConnectionTypeConnectionFragment
    }
    averageMonthlyCharge
    existingMonthlyAmount
    balanceAdjustment
    currentBalance
    targetBalance
    reviewedOn
  }
}

Variables

{
  "ledgerNumber": "abc123"
}

Response

{
  "data": {
    "livePaymentAdequacyCalculation": {
      "suggestedNewMonthlyAmount": 1,
      "consumption": ConsumptionBreakdownConnectionTypeConnection,
      "averageMonthlyCharge": 1,
      "existingMonthlyAmount": 1,
      "balanceAdjustment": 1,
      "currentBalance": 1,
      "targetBalance": 1,
      "reviewedOn": "2020-01-01"
    }
  }
}

loyaltyPointLedgers

Type:[LoyaltyPointLedgerEntryType]

URL:https://api.octopus.energy/v1/graphql/

Get the Loyalty Point ledger entries for the passed user.

Query

query LoyaltyPointLedgers {
  loyaltyPointLedgers {
    id
    ledgerType
    value
    balanceBroughtForward
    balanceCarriedForward
    reasonCode
    postedAt
    accountNumber
  }
}

Response

{
  "data": {
    "loyaltyPointLedgers": [
      {
        "id": "abc123",
        "ledgerType": "abc123",
        "value": "abc123",
        "balanceBroughtForward": "abc123",
        "balanceCarriedForward": "abc123",
        "reasonCode": "abc123",
        "postedAt": "2020-01-01T00:00:00.000Z",
        "accountNumber": "abc123"
      }
    ]
  }
}

loyaltyPointsBalance

Type:AccountLoyaltyPointsType

URL:https://api.octopus.energy/v1/graphql/

Get the loyalty points balance for an account.

The possible errors that can be raised are:

  • KT-CT-9218: Unauthorized.
  • KT-CT-9217: Unauthorized.
  • KT-CT-9215: Loyalty points balance query disabled.
  • KT-CT-9216: Unauthorized.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

The account number.

Query

query LoyaltyPointsBalance($accountNumber: String!) {
  loyaltyPointsBalance(accountNumber: $accountNumber) {
    loyaltyPoints
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "loyaltyPointsBalance": {
      "loyaltyPoints": 1
    }
  }
}

metadata

Type:[Metadata]

URL:https://api.octopus.energy/v1/graphql/

Metadata for a linked object.

Arguments

NameDescription

linkedObjectType (LinkedObjectType)

identifier (String!)

Query

query Metadata(
  $linkedObjectType: LinkedObjectType,
  $identifier: String!
) {
  metadata(
    linkedObjectType: $linkedObjectType,
    identifier: $identifier
  ) {
    key
    value
  }
}

Variables

{
  "linkedObjectType": "ACCOUNT",
  "identifier": "abc123"
}

Response

{
  "data": {
    "metadata": [
      {
        "key": "abc123",
        "value": {"key": "value"}
      }
    ]
  }
}

metadataForKey

Type:Metadata

URL:https://api.octopus.energy/v1/graphql/

Metadata for a linked object with key.

The possible errors that can be raised are:

  • KT-CT-4123: Unauthorized.
  • KT-CT-4124: Unauthorized.
  • KT-CT-8411: Invalid data.
  • KT-CT-4179: No metadata found with given key.
  • KT-CT-4155: Invalid data.
  • KT-CT-4177: Unauthorized.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

linkedObjectType (LinkedObjectType)

identifier (String!)

key (String!)

Query

query MetadataForKey(
  $linkedObjectType: LinkedObjectType,
  $identifier: String!,
  $key: String!
) {
  metadataForKey(
    linkedObjectType: $linkedObjectType,
    identifier: $identifier,
    key: $key
  ) {
    key
    value
  }
}

Variables

{
  "linkedObjectType": "ACCOUNT",
  "identifier": "abc123",
  "key": "abc123"
}

Response

{
  "data": {
    "metadataForKey": {
      "key": "abc123",
      "value": {"key": "value"}
    }
  }
}

meterPoints

Type:MeterPointInterface

URL:https://api.octopus.energy/v1/graphql/

Get a meter point via it's associated mpan or mprn.

The possible errors that can be raised are:

  • KT-GB-5601: One of either MPAN or MPRN must be provided.
  • KT-CT-4011: No meter points found with the given ID.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

mpan (ID)

The MPAN for the electricity meterpoint to return.

mprn (ID)

The MPRN for the gas meterpoint to return.

Query

query MeterPoints(
  $mpan: ID,
  $mprn: ID
) {
  meterPoints(
    mpan: $mpan,
    mprn: $mprn
  ) {
    status
    meters {
      ...MeterFragment
    }
    enrolment {
      ...EnrolmentTypeFragment
    }
  }
}

Variables

{
  "mpan": "abc123",
  "mprn": "abc123"
}

Response

{
  "data": {
    "meterPoints": {
      "status": "abc123",
      "meters": Meter,
      "enrolment": EnrolmentType
    }
  }
}

multipleElectricityMeterPointsForAddress

Type:ElectricityMeterPointForAddressType

URL:https://api.octopus.energy/v1/graphql/

Override Field to add additional attributes and extend description with possible_errors

The possible errors that can be raised are:

  • KT-GB-6612: We couldn't find a match for this address. Please verify it and try again.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

address (AddressSearchType)

searchDomesticOnly (Boolean)

useDes (Boolean)

Query

query MultipleElectricityMeterPointsForAddress(
  $address: AddressSearchType,
  $searchDomesticOnly: Boolean,
  $useDes: Boolean
) {
  multipleElectricityMeterPointsForAddress(
    address: $address,
    searchDomesticOnly: $searchDomesticOnly,
    useDes: $useDes
  ) {
    addressHasMoreThanOneElectricityMeterPoint
    electricityMeterPoints
    addressLine1
    addressLine2
    postcode
  }
}

Variables

{
  "address": AddressSearchType,
  "searchDomesticOnly": true,
  "useDes": true
}

Response

{
  "data": {
    "multipleElectricityMeterPointsForAddress": {
      "addressHasMoreThanOneElectricityMeterPoint": true,
      "electricityMeterPoints": ["abc123"],
      "addressLine1": "abc123",
      "addressLine2": "abc123",
      "postcode": "abc123"
    }
  }
}

Arguments

NameDescription

id (ID!)

The ID of the object

Query

query Node($id: ID!) {
  node(id: $id) {
    id
  }
}

Variables

{
  "id": "abc123"
}

Response

{
  "data": {
    "node": {
      "id": "abc123"
    }
  }
}

occupierAccount

Type:OccupierAccount

URL:https://api.octopus.energy/v1/graphql/

Looks up an occupier account based on postcode and last 4 digits of the account number

Arguments

NameDescription

postcode (String!)

shortcode (String!)

Query

query OccupierAccount(
  $postcode: String!,
  $shortcode: String!
) {
  occupierAccount(
    postcode: $postcode,
    shortcode: $shortcode
  ) {
    account
    address
    date
    propertyId
    occupyToken
  }
}

Variables

{
  "postcode": "abc123",
  "shortcode": "abc123"
}

Response

{
  "data": {
    "occupierAccount": {
      "account": "abc123",
      "address": "abc123",
      "date": "abc123",
      "propertyId": 1,
      "occupyToken": "abc123"
    }
  }
}

ocppConnection

Type:OCPPConnectionType

URL:https://api.octopus.energy/v1/graphql/

To confirm whether a device is connected to OCPP.

The possible errors that can be raised are:

  • KT-CT-1111: Unauthorized.
  • KT-CT-4311: Unable to confirm OCPP connection.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

Query

query OcppConnection($accountNumber: String!) {
  ocppConnection(accountNumber: $accountNumber) {
    isConnected
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "ocppConnection": {
      "isConnected": true
    }
  }
}

ocppDetails

Type:OCPPDetailsType

URL:https://api.octopus.energy/v1/graphql/

The user specific generated OCPP details.

The possible errors that can be raised are:

  • KT-CT-1111: Unauthorized.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

Query

query OcppDetails($accountNumber: String!) {
  ocppDetails(accountNumber: $accountNumber) {
    url
    username
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "ocppDetails": {
      "url": "abc123",
      "username": "abc123"
    }
  }
}

octoHeatPumpControllerConfiguration

Type:ControllerAndZoneConfiguration

URL:https://api.octopus.energy/v1/graphql/

Heat pump controller, zones and sensor configuration.

The possible errors that can be raised are:

  • KT-CT-4305: Unable to fetch heating controller configuration.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

euid (ID!)

Query

query OctoHeatPumpControllerConfiguration(
  $accountNumber: String!,
  $euid: ID!
) {
  octoHeatPumpControllerConfiguration(
    accountNumber: $accountNumber,
    euid: $euid
  ) {
    controller {
      ...ControllerConfigurationFragment
    }
    zones {
      ...ZoneInformationFragment
    }
    heatPump {
      ...HeatPumpConfigurationFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123",
  "euid": "abc123"
}

Response

{
  "data": {
    "octoHeatPumpControllerConfiguration": {
      "controller": ControllerConfiguration,
      "zones": [ZoneInformation],
      "heatPump": HeatPumpConfiguration
    }
  }
}

octoHeatPumpControllerEuids

Type:[String]

URL:https://api.octopus.energy/v1/graphql/

Heat pump controller EUIDs associated with an account.

Arguments

NameDescription

accountNumber (String)

Query

query OctoHeatPumpControllerEuids($accountNumber: String) {
  octoHeatPumpControllerEuids(accountNumber: $accountNumber)
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "octoHeatPumpControllerEuids": ["abc123"]
  }
}

octoHeatPumpControllerStatus

Type:ControllerStatus

URL:https://api.octopus.energy/v1/graphql/

Retrieve the heat pump controller device status.

The possible errors that can be raised are:

  • KT-CT-4303: Unable to fetch device status.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

euid (ID!)

Query

query OctoHeatPumpControllerStatus(
  $accountNumber: String!,
  $euid: ID!
) {
  octoHeatPumpControllerStatus(
    accountNumber: $accountNumber,
    euid: $euid
  ) {
    sensors {
      ...SensorStatusFragment
    }
    zones {
      ...ZoneStatusFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123",
  "euid": "abc123"
}

Response

{
  "data": {
    "octoHeatPumpControllerStatus": {
      "sensors": [SensorStatus],
      "zones": [ZoneStatus]
    }
  }
}

octoHeatPumpControllersAtLocation

Type:[ControllerAtLocation]

URL:https://api.octopus.energy/v1/graphql/

Heat pump controllers attached to an account at a given location.

Arguments

NameDescription

accountNumber (String!)

propertyId (ID!)

Query

query OctoHeatPumpControllersAtLocation(
  $accountNumber: String!,
  $propertyId: ID!
) {
  octoHeatPumpControllersAtLocation(
    accountNumber: $accountNumber,
    propertyId: $propertyId
  ) {
    controller {
      ...ControllerFragment
    }
    heatPumpModel
    location {
      ...LocationFragment
    }
    provisionedAt
  }
}

Variables

{
  "accountNumber": "abc123",
  "propertyId": "abc123"
}

Response

{
  "data": {
    "octoHeatPumpControllersAtLocation": [
      {
        "controller": Controller,
        "heatPumpModel": "abc123",
        "location": Location,
        "provisionedAt": "2020-01-01T00:00:00.000Z"
      }
    ]
  }
}

octoHeatPumpLifetimePerformance

Type:LifetimeTelemetry

URL:https://api.octopus.energy/v1/graphql/

Latest telemetry values from the heat pump.

The possible errors that can be raised are:

  • KT-CT-4365: Device telemetry data could not be fetched.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

euid (ID!)

Query

query OctoHeatPumpLifetimePerformance($euid: ID!) {
  octoHeatPumpLifetimePerformance(euid: $euid) {
    readAt
    seasonalCoefficientOfPerformance
    energyInput {
      ...EnergyFragment
    }
    heatOutput {
      ...EnergyFragment
    }
  }
}

Variables

{
  "euid": "abc123"
}

Response

{
  "data": {
    "octoHeatPumpLifetimePerformance": {
      "readAt": "2020-01-01T00:00:00.000Z",
      "seasonalCoefficientOfPerformance": 1.0,
      "energyInput": Energy,
      "heatOutput": Energy
    }
  }
}

octoHeatPumpLivePerformance

Type:LiveTelemetry

URL:https://api.octopus.energy/v1/graphql/

Latest telemetry values from the heat pump.

The possible errors that can be raised are:

  • KT-CT-4365: Device telemetry data could not be fetched.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

euid (ID!)

Query

query OctoHeatPumpLivePerformance($euid: ID!) {
  octoHeatPumpLivePerformance(euid: $euid) {
    readAt
    coefficientOfPerformance
    powerInput {
      ...PowerFragment
    }
    heatOutput {
      ...PowerFragment
    }
    outdoorTemperature {
      ...TemperatureFragment
    }
  }
}

Variables

{
  "euid": "abc123"
}

Response

{
  "data": {
    "octoHeatPumpLivePerformance": {
      "readAt": "2020-01-01T00:00:00.000Z",
      "coefficientOfPerformance": 1.0,
      "powerInput": Power,
      "heatOutput": Power,
      "outdoorTemperature": Temperature
    }
  }
}

octoHeatPumpTimeRangedPerformance

Type:HeatPumpTimeRangedPerformance

URL:https://api.octopus.energy/v1/graphql/

Heat pump performance data between two specific dates.

The possible errors that can be raised are:

  • KT-CT-4365: Device telemetry data could not be fetched.
  • KT-CT-4370: Device telemetry data unavailable.
  • KT-CT-4381: Invalid time range provided.
  • KT-CT-4305: Unable to fetch heating controller configuration.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

euid (ID!)

startAt (DateTime!)

endAt (DateTime!)

Query

query OctoHeatPumpTimeRangedPerformance(
  $euid: ID!,
  $startAt: DateTime!,
  $endAt: DateTime!
) {
  octoHeatPumpTimeRangedPerformance(
    euid: $euid,
    startAt: $startAt,
    endAt: $endAt
  ) {
    coefficientOfPerformance
    energyInput {
      ...EnergyFragment
    }
    energyOutput {
      ...EnergyFragment
    }
  }
}

Variables

{
  "euid": "abc123",
  "startAt": "2020-01-01T00:00:00.000Z",
  "endAt": "2020-01-01T00:00:00.000Z"
}

Response

{
  "data": {
    "octoHeatPumpTimeRangedPerformance": {
      "coefficientOfPerformance": 1.0,
      "energyInput": Energy,
      "energyOutput": Energy
    }
  }
}

octoHeatPumpTimeSeriesPerformance

Type:[HeatPumpPerformanceGroupingNode]

URL:https://api.octopus.energy/v1/graphql/

Heat pump performance data over a specified period in time buckets.

The possible errors that can be raised are:

  • KT-CT-4368: Telemetry API did not return valid data.
  • KT-CT-4365: Device telemetry data could not be fetched.
  • KT-CT-4381: Invalid time range provided.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

euid (ID!)

startAt (DateTime!)

endAt (DateTime!)

performanceGrouping (PerformanceGrouping!)

Query

query OctoHeatPumpTimeSeriesPerformance(
  $euid: ID!,
  $startAt: DateTime!,
  $endAt: DateTime!,
  $performanceGrouping: PerformanceGrouping!
) {
  octoHeatPumpTimeSeriesPerformance(
    euid: $euid,
    startAt: $startAt,
    endAt: $endAt,
    performanceGrouping: $performanceGrouping
  ) {
    startAt
    endAt
    energyInput {
      ...EnergyFragment
    }
    energyOutput {
      ...EnergyFragment
    }
    outdoorTemperature {
      ...TemperatureFragment
    }
  }
}

Variables

{
  "euid": "abc123",
  "startAt": "2020-01-01T00:00:00.000Z",
  "endAt": "2020-01-01T00:00:00.000Z",
  "performanceGrouping": "LIVE"
}

Response

{
  "data": {
    "octoHeatPumpTimeSeriesPerformance": [
      {
        "startAt": "2020-01-01T00:00:00.000Z",
        "endAt": "2020-01-01T00:00:00.000Z",
        "energyInput": Energy,
        "energyOutput": Energy,
        "outdoorTemperature": Temperature
      }
    ]
  }
}

octocareOnboardingInfo

Type:OctocareOnboardingInfo

URL:https://api.octopus.energy/v1/graphql/

Returns the info required to start the onboarding process for a Mini in the cared-for account's property, by the cared.

The possible errors that can be raised are:

  • KT-GB-10502: Account is not yet enrolled.
  • KT-GB-10503: Incorrect number of communication hubs.
  • KT-GB-10501: Account is not currently supported.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

Cared-for account number.

Query

query OctocareOnboardingInfo($accountNumber: String!) {
  octocareOnboardingInfo(accountNumber: $accountNumber) {
    chfDeviceId
    propertyAddressLine1
    propertyId
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "octocareOnboardingInfo": {
      "chfDeviceId": "abc123",
      "propertyAddressLine1": "abc123",
      "propertyId": "abc123"
    }
  }
}

octocareUsageInfo

Type:OctocareUsageInfo

URL:https://api.octopus.energy/v1/graphql/

Returns the info required to request and display live usage information for the cared-for account meter: the meter device ID and 1st address line of the property.

The possible errors that can be raised are:

  • KT-GB-10502: Account is not yet enrolled.
  • KT-GB-10503: Incorrect number of communication hubs.
  • KT-GB-10501: Account is not currently supported.
  • KT-GB-10504: Property is not currently supported.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

Cared-for account number.

Query

query OctocareUsageInfo($accountNumber: String!) {
  octocareUsageInfo(accountNumber: $accountNumber) {
    meterDeviceId
    propertyAddressLine1
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "octocareUsageInfo": {
      "meterDeviceId": "abc123",
      "propertyAddressLine1": "abc123"
    }
  }
}

Arguments

NameDescription

accountNumber (String!)

Kraken account number.

Query

query OctoplusAccountInfo($accountNumber: String!) {
  octoplusAccountInfo(accountNumber: $accountNumber) {
    isOctoplusEnrolled
    enrollmentStatus
    isLoyaltyPointsUser
    octoplusEligibility {
      ...OctoplusEligibilityTypeFragment
    }
    octoplusSnapWebUrl {
      ...OctoplusSnapWebUrlTypeFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "octoplusAccountInfo": {
      "isOctoplusEnrolled": true,
      "enrollmentStatus": "ENROLLED",
      "isLoyaltyPointsUser": true,
      "octoplusEligibility": OctoplusEligibilityType,
      "octoplusSnapWebUrl": OctoplusSnapWebUrlType
    }
  }
}

Query

query OctoplusFeatureFlags {
  octoplusFeatureFlags {
    shouldClientDisplayOctopointsV2
    shouldClientDisplayOctoplus
    shouldClientDisplayOctoplusRewards
    shouldClientDisplayOctoplusPartnerOffers
    shouldClientDisplayOctoplusShoptopusOffers
    shouldClientDisplayOctoplusPartnerOfferList
  }
}

Response

{
  "data": {
    "octoplusFeatureFlags": {
      "shouldClientDisplayOctopointsV2": true,
      "shouldClientDisplayOctoplus": true,
      "shouldClientDisplayOctoplusRewards": true,
      "shouldClientDisplayOctoplusPartnerOffers": true,
      "shouldClientDisplayOctoplusShoptopusOffers": true,
      "shouldClientDisplayOctoplusPartnerOfferList": true
    }
  }
}

octoplusOfferGroups

Type:OctoplusOfferGroupConnectionTypeConnection

URL:https://api.octopus.energy/v1/graphql/

Octoplus Offer Groups available for a given account_user and account combination.

Arguments

NameDescription

accountNumber (String!)

Account number for the Octoplus-enrolled account.

id (Int)

ID of the Offer Group being queried.

before (String)

after (String)

first (Int)

last (Int)

Query

query OctoplusOfferGroups(
  $accountNumber: String!,
  $id: Int,
  $before: String,
  $after: String,
  $first: Int,
  $last: Int
) {
  octoplusOfferGroups(
    accountNumber: $accountNumber,
    id: $id,
    before: $before,
    after: $after,
    first: $first,
    last: $last
  ) {
    pageInfo {
      ...PageInfoFragment
    }
    edges {
      ...OctoplusOfferGroupConnectionTypeEdgeFragment
    }
    totalCount
    edgeCount
  }
}

Variables

{
  "accountNumber": "abc123",
  "id": 1,
  "before": "abc123",
  "after": "abc123",
  "first": 1,
  "last": 1
}

Response

{
  "data": {
    "octoplusOfferGroups": {
      "pageInfo": PageInfo,
      "edges": OctoplusOfferGroupConnectionTypeEdge,
      "totalCount": 1,
      "edgeCount": 1
    }
  }
}

octoplusOffers

Type:[OctoplusOfferType]

URL:https://api.octopus.energy/v1/graphql/

Octoplus Offers available for a given account_user and account combination.

Arguments

NameDescription

accountNumber (String!)

Account number for the Octoplus-enrolled account.

slug (String)

Slug of the offer being queried.

Query

query OctoplusOffers(
  $accountNumber: String!,
  $slug: String
) {
  octoplusOffers(
    accountNumber: $accountNumber,
    slug: $slug
  ) {
    slug
    name
    description
    longDescription
    partnerName
    priceTag
    pointsCost
    availableSitesUrl
    partnerSiteUrl
    imageUrls {
      ...OctoplusOfferImageUrlsTypeFragment
    }
    termsAndConditions
    faqs {
      ...OctoplusOfferFAQsTypeFragment
    }
    usageInstructions
    category
    claimAbility {
      ...OctoplusRewardClaimAbilityTypeFragment
    }
    claimBy
  }
}

Variables

{
  "accountNumber": "abc123",
  "slug": "abc123"
}

Response

{
  "data": {
    "octoplusOffers": [
      {
        "slug": "abc123",
        "name": "abc123",
        "description": "abc123",
        "longDescription": "abc123",
        "partnerName": "abc123",
        "priceTag": "abc123",
        "pointsCost": 1,
        "availableSitesUrl": "abc123",
        "partnerSiteUrl": "abc123",
        "imageUrls": OctoplusOfferImageUrlsType,
        "termsAndConditions": "abc123",
        "faqs": [OctoplusOfferFAQsType],
        "usageInstructions": "abc123",
        "category": "abc123",
        "claimAbility": OctoplusRewardClaimAbilityType,
        "claimBy": "2020-01-01T00:00:00.000Z"
      }
    ]
  }
}

octoplusRewards

Type:[OctoplusRewardType]

URL:https://api.octopus.energy/v1/graphql/

Octoplus Rewards for a given account user.

Arguments

NameDescription

rewardId (Int)

Id for the reward being queried.

accountNumber (String)

Account number for the Octoplus-enrolled account.

offerSlug (String)

Slug of the offer being queried.

Query

query OctoplusRewards(
  $rewardId: Int,
  $accountNumber: String,
  $offerSlug: String
) {
  octoplusRewards(
    rewardId: $rewardId,
    accountNumber: $accountNumber,
    offerSlug: $offerSlug
  ) {
    id
    accountNumber
    offer {
      ...OctoplusOfferTypeFragment
    }
    offerSlug
    offerName
    priceTag
    partnerName
    usageInstructions
    vouchers {
      ... on OctoplusVoucherType {
        ...OctoplusVoucherTypeFragment
      }
      ... on ShoptopusVoucherType {
        ...ShoptopusVoucherTypeFragment
      }
    }
    claimedAt
    status
  }
}

Variables

{
  "rewardId": 1,
  "accountNumber": "abc123",
  "offerSlug": "abc123"
}

Response

{
  "data": {
    "octoplusRewards": [
      {
        "id": 1,
        "accountNumber": "abc123",
        "offer": OctoplusOfferType,
        "offerSlug": "abc123",
        "offerName": "abc123",
        "priceTag": "abc123",
        "partnerName": "abc123",
        "usageInstructions": "abc123",
        "vouchers": OctoplusVoucherType,
        "claimedAt": "2020-01-01T00:00:00.000Z",
        "status": "PENDING"
      }
    ]
  }
}

opportunityValueByKey

Type:String

URL:https://api.octopus.energy/v1/graphql/

Override Field to add additional attributes and extend description with possible_errors

The possible errors that can be raised are:

  • KT-CT-8903: Unable to update opportunity.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

opportunityId (ID)

The identifier of the opportunity to query.

key (String)

The key the a funnel-specific value you wish to obtain.

Query

query OpportunityValueByKey(
  $opportunityId: ID,
  $key: String
) {
  opportunityValueByKey(
    opportunityId: $opportunityId,
    key: $key
  )
}

Variables

{
  "opportunityId": "abc123",
  "key": "abc123"
}

Response

{
  "data": {
    "opportunityValueByKey": "abc123"
  }
}

passwordValidatorHelpTexts

Type:[String]

URL:https://api.octopus.energy/v1/graphql/

The help text of all configured password validators as plain-text or html. Defaults to plain-text.

Arguments

NameDescription

asHtml (Boolean)

Return the results as html instead of plain-text. Defaults to False.

Query

query PasswordValidatorHelpTexts($asHtml: Boolean) {
  passwordValidatorHelpTexts(asHtml: $asHtml)
}

Variables

{
  "asHtml": true
}

Response

{
  "data": {
    "passwordValidatorHelpTexts": ["abc123"]
  }
}

paymentRequests

Type:PaymentRequestsType

URL:https://api.octopus.energy/v1/graphql/

Get all payment requests for the given ledger.

Arguments

NameDescription

ledgerNumber (String!)

Kraken ledger number.

Query

query PaymentRequests($ledgerNumber: String!) {
  paymentRequests(ledgerNumber: $ledgerNumber) {
    paymentRequest {
      ...PaymentRequestConnectionTypeConnectionFragment
    }
  }
}

Variables

{
  "ledgerNumber": "abc123"
}

Response

{
  "data": {
    "paymentRequests": {
      "paymentRequest": PaymentRequestConnectionTypeConnection
    }
  }
}

plannedDispatches

Type:[UpsideDispatchType]

URL:https://api.octopus.energy/v1/graphql/

All planned device dispatches 24 hours ahead, (usually) in time order.

Arguments

NameDescription

accountNumber (String!)

Query

query PlannedDispatches($accountNumber: String!) {
  plannedDispatches(accountNumber: $accountNumber) {
    start
    end
    startDt
    endDt
    deltaKwh
    delta
    meta {
      ...UpsideDispatchMetaTypeFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "plannedDispatches": [
      {
        "start": "2020-01-01T00:00:00.000Z",
        "end": "2020-01-01T00:00:00.000Z",
        "startDt": "abc123",
        "endDt": "abc123",
        "deltaKwh": 1,
        "delta": 1.0,
        "meta": UpsideDispatchMetaType
      }
    ]
  }
}

portfolio

Type:PortfolioType

URL:https://api.octopus.energy/v1/graphql/

Get details about a portfolio.

The possible errors that can be raised are:

  • KT-CT-9403: Received an invalid portfolioId.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

portfolioNumber (String!)

Portfolio number to be retrieved.

Query

query Portfolio($portfolioNumber: String!) {
  portfolio(portfolioNumber: $portfolioNumber) {
    id
    number
    createdAt
    updatedAt
    billingName
    collectiveBilling
    operationsTeam {
      ...OperationsTeamTypeFragment
    }
    leadAccountNumber
    brand
    name
    depth
    parent {
      ...PortfolioTypeFragment
    }
    ancestors {
      ...PortfolioConnectionTypeConnectionFragment
    }
    descendants {
      ...PortfolioConnectionTypeConnectionFragment
    }
    accounts {
      ...AccountConnectionTypeConnectionFragment
    }
  }
}

Variables

{
  "portfolioNumber": "abc123"
}

Response

{
  "data": {
    "portfolio": {
      "id": "abc123",
      "number": "abc123",
      "createdAt": "2020-01-01T00:00:00.000Z",
      "updatedAt": "2020-01-01T00:00:00.000Z",
      "billingName": "abc123",
      "collectiveBilling": true,
      "operationsTeam": OperationsTeamType,
      "leadAccountNumber": "abc123",
      "brand": "abc123",
      "name": "abc123",
      "depth": 1,
      "parent": PortfolioType,
      "ancestors": PortfolioConnectionTypeConnection,
      "descendants": PortfolioConnectionTypeConnection,
      "accounts": AccountConnectionTypeConnection
    }
  }
}

possibleErrors

Type:PossibleErrorsOutputType

URL:https://api.octopus.energy/v1/graphql/

Possible errors of the requested query/mutation.

The possible errors that can be raised are:

  • KT-CT-1606: Query/Mutation not found.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

input (PossibleErrorsInputType!)

Query or Mutation for which to get the possible errors list.

Query

query PossibleErrors($input: PossibleErrorsInputType!) {
  possibleErrors(input: $input) {
    name
    type
    authErrors
    possibleErrors {
      ...PossibleErrorTypeFragment
    }
  }
}

Variables

Response

{
  "data": {
    "possibleErrors": {
      "name": "abc123",
      "type": "query",
      "authErrors": true,
      "possibleErrors": [PossibleErrorType]
    }
  }
}

prepayBalanceSnapshot

Type:PrepayBalanceSnapshotType

URL:https://api.octopus.energy/v1/graphql/

Retrieve a snapshot of a prepay device balance at a moment in time.

The possible errors that can be raised are:

  • KT-GB-4048: Device not in prepayment mode.
  • KT-GB-4049: Balance snapshot not found.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

deviceId (String!)

The ESME or GSME's EUI64 ID, e.g. '12-34-5A-FF-FF-6B-C7-89'.

Query

query PrepayBalanceSnapshot($deviceId: String!) {
  prepayBalanceSnapshot(deviceId: $deviceId) {
    creditInPence
    debtInPence
    emergencyCreditInPence
    asAt
  }
}

Variables

{
  "deviceId": "abc123"
}

Response

{
  "data": {
    "prepayBalanceSnapshot": {
      "creditInPence": 1,
      "debtInPence": 1,
      "emergencyCreditInPence": 1,
      "asAt": "2020-01-01T00:00:00.000Z"
    }
  }
}

prepayPayments

Type:PrepayPaymentConnectionTypeConnection

URL:https://api.octopus.energy/v1/graphql/

Payments made to add credit to the account's smart prepay meters.

Arguments

NameDescription

accountNumber (String!)

before (String)

after (String)

first (Int)

last (Int)

Query

query PrepayPayments(
  $accountNumber: String!,
  $before: String,
  $after: String,
  $first: Int,
  $last: Int
) {
  prepayPayments(
    accountNumber: $accountNumber,
    before: $before,
    after: $after,
    first: $first,
    last: $last
  ) {
    pageInfo {
      ...PageInfoFragment
    }
    edges {
      ...PrepayPaymentConnectionTypeEdgeFragment
    }
    totalCount
    edgeCount
  }
}

Variables

{
  "accountNumber": "abc123",
  "before": "abc123",
  "after": "abc123",
  "first": 1,
  "last": 1
}

Response

{
  "data": {
    "prepayPayments": {
      "pageInfo": PageInfo,
      "edges": PrepayPaymentConnectionTypeEdge,
      "totalCount": 1,
      "edgeCount": 1
    }
  }
}

productEligibility

Type:ProductEligibilityType

URL:https://api.octopus.energy/v1/graphql/

Define product eligibility.

The possible errors that can be raised are:

  • KT-GB-4135: Unauthorized.
  • KT-CT-4910: No product exists with the given input.
  • KT-CT-4623: Unauthorized.
  • KT-CT-4190: Error while defining product eligibility for product enrolment candidate.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

The account to which meter point belongs.

mpxn (String!)

Meter point reference/administration number.

productCode (String!)

Product code for which verify eligibility to.

params (JSONString)

Extra parameters for eligibility verification.

Query

query ProductEligibility(
  $accountNumber: String!,
  $mpxn: String!,
  $productCode: String!,
  $params: JSONString
) {
  productEligibility(
    accountNumber: $accountNumber,
    mpxn: $mpxn,
    productCode: $productCode,
    params: $params
  ) {
    isEligible
    ineligibilityReasons {
      ...ProductIneligibilityReasonDetailsFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123",
  "mpxn": "abc123",
  "productCode": "abc123",
  "params": {"key": "value"}
}

Response

{
  "data": {
    "productEligibility": {
      "isEligible": true,
      "ineligibilityReasons": [ProductIneligibilityReasonDetails]
    }
  }
}

productEnrolment

Type:ProductEnrolmentType

URL:https://api.octopus.energy/v1/graphql/

Get the details of a product enrolment.

The possible errors that can be raised are:

  • KT-CT-4177: Unauthorized.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

The account to which the enrolment belongs.

enrolmentId (ID!)

The ID for the enrolment.

Query

query ProductEnrolment(
  $accountNumber: String!,
  $enrolmentId: ID!
) {
  productEnrolment(
    accountNumber: $accountNumber,
    enrolmentId: $enrolmentId
  ) {
    id
    account {
      ...AccountTypeFragment
    }
    status
    product {
      ...EnergyProductTypeFragment
    }
    electricityMeterPoint {
      ...ElectricityMeterPointTypeFragment
    }
    gasMeterPoint {
      ...GasMeterPointTypeFragment
    }
    stages {
      ...ProductEnrolmentStageTypeFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123",
  "enrolmentId": "abc123"
}

Response

{
  "data": {
    "productEnrolment": {
      "id": "abc123",
      "account": AccountType,
      "status": "NOT_STARTED",
      "product": EnergyProductType,
      "electricityMeterPoint": ElectricityMeterPointType,
      "gasMeterPoint": GasMeterPointType,
      "stages": [ProductEnrolmentStageType]
    }
  }
}

Arguments

NameDescription

accountNumber (String!)

The account to find all the enrolments for.

Query

query ProductEnrolments($accountNumber: String!) {
  productEnrolments(accountNumber: $accountNumber) {
    id
    account {
      ...AccountTypeFragment
    }
    status
    product {
      ...EnergyProductTypeFragment
    }
    electricityMeterPoint {
      ...ElectricityMeterPointTypeFragment
    }
    gasMeterPoint {
      ...GasMeterPointTypeFragment
    }
    stages {
      ...ProductEnrolmentStageTypeFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "productEnrolments": [
      {
        "id": "abc123",
        "account": AccountType,
        "status": "NOT_STARTED",
        "product": EnergyProductType,
        "electricityMeterPoint": ElectricityMeterPointType,
        "gasMeterPoint": GasMeterPointType,
        "stages": [ProductEnrolmentStageType]
      }
    ]
  }
}

properties

Type:[PropertyType]

URL:https://api.octopus.energy/v1/graphql/

The properties attached to the given account.

This field requires the Authorization header to be set.

Arguments

NameDescription

accountNumber (String!)

active (Boolean)

Query

query Properties(
  $accountNumber: String!,
  $active: Boolean
) {
  properties(
    accountNumber: $accountNumber,
    active: $active
  ) {
    id
    postcode
    address
    richAddress {
      ...PropertyRichAddressTypeFragment
    }
    splitAddress
    label
    occupancyPeriods {
      ...OccupancyPeriodTypeFragment
    }
    coordinates {
      ...CoordinatesTypeFragment
    }
    embeddedNetwork {
      ...EmbeddedNetworkTypeFragment
    }
    measurements {
      ...MeasurementConnectionFragment
    }
    smartDeviceNetworks {
      ...SmartMeterDeviceNetworkTypeFragment
    }
    isChangeOfTenancyOngoing
    isSmets2InstallationAllowed
    electricityMeterPoints {
      ...ElectricityMeterPointTypeFragment
    }
    gasMeterPoints {
      ...GasMeterPointTypeFragment
    }
    wanCoverage
    availableSmets2InstallationTimeslots {
      ...Smets2InstallationTimeslotTypeFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123",
  "active": true
}

Response

{
  "data": {
    "properties": [
      {
        "id": "abc123",
        "postcode": "abc123",
        "address": "abc123",
        "richAddress": PropertyRichAddressType,
        "splitAddress": ["abc123"],
        "label": "abc123",
        "occupancyPeriods": [OccupancyPeriodType],
        "coordinates": CoordinatesType,
        "embeddedNetwork": EmbeddedNetworkType,
        "measurements": MeasurementConnection,
        "smartDeviceNetworks": [SmartMeterDeviceNetworkType],
        "isChangeOfTenancyOngoing": true,
        "isSmets2InstallationAllowed": true,
        "electricityMeterPoints": [ElectricityMeterPointType],
        "gasMeterPoints": [GasMeterPointType],
        "wanCoverage": "HIGH",
        "availableSmets2InstallationTimeslots": [Smets2InstallationTimeslotType]
      }
    ]
  }
}

propertiesSearch

Type:[PropertySearchResult!]!

URL:https://api.octopus.energy/v1/graphql/

Search for properties that are already in Kraken and match the search term.

Arguments

NameDescription

searchTerm (String!)

The search term. It can be an address or a meter point identifier.

Query

query PropertiesSearch($searchTerm: String!) {
  propertiesSearch(searchTerm: $searchTerm) {
    score
    property {
      ...PropertyTypeFragment
    }
  }
}

Variables

{
  "searchTerm": "abc123"
}

Response

{
  "data": {
    "propertiesSearch": {
      "score": 1.0,
      "property": PropertyType
    }
  }
}

property

Type:PropertyType

URL:https://api.octopus.energy/v1/graphql/

A property with the given ID. Usually associated with supply points.

This field requires the Authorization header to be set.

Arguments

NameDescription

id (ID!)

Query

query Property($id: ID!) {
  property(id: $id) {
    id
    postcode
    address
    richAddress {
      ...PropertyRichAddressTypeFragment
    }
    splitAddress
    label
    occupancyPeriods {
      ...OccupancyPeriodTypeFragment
    }
    coordinates {
      ...CoordinatesTypeFragment
    }
    embeddedNetwork {
      ...EmbeddedNetworkTypeFragment
    }
    measurements {
      ...MeasurementConnectionFragment
    }
    smartDeviceNetworks {
      ...SmartMeterDeviceNetworkTypeFragment
    }
    isChangeOfTenancyOngoing
    isSmets2InstallationAllowed
    electricityMeterPoints {
      ...ElectricityMeterPointTypeFragment
    }
    gasMeterPoints {
      ...GasMeterPointTypeFragment
    }
    wanCoverage
    availableSmets2InstallationTimeslots {
      ...Smets2InstallationTimeslotTypeFragment
    }
  }
}

Variables

{
  "id": "abc123"
}

Response

{
  "data": {
    "property": {
      "id": "abc123",
      "postcode": "abc123",
      "address": "abc123",
      "richAddress": PropertyRichAddressType,
      "splitAddress": ["abc123"],
      "label": "abc123",
      "occupancyPeriods": [OccupancyPeriodType],
      "coordinates": CoordinatesType,
      "embeddedNetwork": EmbeddedNetworkType,
      "measurements": MeasurementConnection,
      "smartDeviceNetworks": [SmartMeterDeviceNetworkType],
      "isChangeOfTenancyOngoing": true,
      "isSmets2InstallationAllowed": true,
      "electricityMeterPoints": [ElectricityMeterPointType],
      "gasMeterPoints": [GasMeterPointType],
      "wanCoverage": "HIGH",
      "availableSmets2InstallationTimeslots": [Smets2InstallationTimeslotType]
    }
  }
}

propertySearch

Type:[PropertyType]

URL:https://api.octopus.energy/v1/graphql/

Search for properties that are already in Kraken and match the search term.

Deprecated

The 'propertySearch' field is deprecated.

This query is being deprecated in favour of `propertiesSearch`. The latter returns not only the matched properties but the level of confidence in the results through the `score` field.

- Marked as deprecated on 2023-05-23.
- Scheduled for removal on or after 2024-01-01.

Arguments

NameDescription

searchTerm (String!)

The search term. It can be an address or a meter point identifier.

Query

query PropertySearch($searchTerm: String!) {
  propertySearch(searchTerm: $searchTerm) {
    id
    postcode
    address
    richAddress {
      ...PropertyRichAddressTypeFragment
    }
    splitAddress
    label
    occupancyPeriods {
      ...OccupancyPeriodTypeFragment
    }
    coordinates {
      ...CoordinatesTypeFragment
    }
    embeddedNetwork {
      ...EmbeddedNetworkTypeFragment
    }
    measurements {
      ...MeasurementConnectionFragment
    }
    smartDeviceNetworks {
      ...SmartMeterDeviceNetworkTypeFragment
    }
    isChangeOfTenancyOngoing
    isSmets2InstallationAllowed
    electricityMeterPoints {
      ...ElectricityMeterPointTypeFragment
    }
    gasMeterPoints {
      ...GasMeterPointTypeFragment
    }
    wanCoverage
    availableSmets2InstallationTimeslots {
      ...Smets2InstallationTimeslotTypeFragment
    }
  }
}

Variables

{
  "searchTerm": "abc123"
}

Response

{
  "data": {
    "propertySearch": [
      {
        "id": "abc123",
        "postcode": "abc123",
        "address": "abc123",
        "richAddress": PropertyRichAddressType,
        "splitAddress": ["abc123"],
        "label": "abc123",
        "occupancyPeriods": [OccupancyPeriodType],
        "coordinates": CoordinatesType,
        "embeddedNetwork": EmbeddedNetworkType,
        "measurements": MeasurementConnection,
        "smartDeviceNetworks": [SmartMeterDeviceNetworkType],
        "isChangeOfTenancyOngoing": true,
        "isSmets2InstallationAllowed": true,
        "electricityMeterPoints": [ElectricityMeterPointType],
        "gasMeterPoints": [GasMeterPointType],
        "wanCoverage": "HIGH",
        "availableSmets2InstallationTimeslots": [Smets2InstallationTimeslotType]
      }
    ]
  }
}

providerAuthDetails

Type:ProviderAuthDetailsType

URL:https://api.octopus.energy/v1/graphql/

Auth details (e.g. OAuth 2.0 URI) for the provider (if available).

Arguments

NameDescription

provider (ProviderChoices!)

The provider to get the auth details for.

deviceType (KrakenFlexDeviceTypes!)

The device type to get the auth details for (as providers may support multiple).

clientType (ClientType)

The client type the request originated from. Used when oauth_uri is different between web and app.

accountNumber (String)

The account number that will be associated with the device. Required for some providers.

propertyId (Int)

The ID of the property the device belongs to.

Query

query ProviderAuthDetails(
  $provider: ProviderChoices!,
  $deviceType: KrakenFlexDeviceTypes!,
  $clientType: ClientType,
  $accountNumber: String,
  $propertyId: Int
) {
  providerAuthDetails(
    provider: $provider,
    deviceType: $deviceType,
    clientType: $clientType,
    accountNumber: $accountNumber,
    propertyId: $propertyId
  ) {
    oauthUri
  }
}

Variables

{
  "provider": "DAIKIN",
  "deviceType": "BATTERIES",
  "clientType": "APP",
  "accountNumber": "abc123",
  "propertyId": 1
}

Response

{
  "data": {
    "providerAuthDetails": {
      "oauthUri": "abc123"
    }
  }
}

providerVirtualKeyDetails

Type:ProviderVirtualKeyDetailsType

URL:https://api.octopus.energy/v1/graphql/

Virtual key details (e.g. certificate public key) for the provider (if available).

Arguments

NameDescription

provider (ProviderChoices!)

The provider to get the virtual key details for.

deviceType (KrakenFlexDeviceTypes!)

The device type to get the virtual key details for (as providers may support multiple).

Query

query ProviderVirtualKeyDetails(
  $provider: ProviderChoices!,
  $deviceType: KrakenFlexDeviceTypes!
) {
  providerVirtualKeyDetails(
    provider: $provider,
    deviceType: $deviceType
  ) {
    virtualKeyName
    virtualKeyUri
  }
}

Variables

{
  "provider": "DAIKIN",
  "deviceType": "BATTERIES"
}

Response

{
  "data": {
    "providerVirtualKeyDetails": {
      "virtualKeyName": "abc123",
      "virtualKeyUri": "abc123"
    }
  }
}

question

Type:String

URL:https://api.octopus.energy/v1/graphql/

Get the customer feedback survey question.

The possible errors that can be raised are:

  • KT-CT-5513: Invalid data.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

formId (Int!)

Query

query Question($formId: Int!) {
  question(formId: $formId)
}

Variables

{
  "formId": 1
}

Response

{
  "data": {
    "question": "abc123"
  }
}

quote

Type:QuoteType

URL:https://api.octopus.energy/v1/graphql/

This returns the quote with the given code.

Deprecated usage: If the code is not provided, the query returns an empty quote. This was previously used to access OFGEM consumption profiles but is now deprecated, as the dedicated consumptionEstimates query serves that purpose.

Arguments

NameDescription

code (String)

Unique identifying code of the quote to retrieve. This argument is optional, but leaving it empty is now deprecated.

Query

query Quote($code: String) {
  quote(code: $code) {
    code
    postcode
    gspGroupId
    includesElectricity
    includesGas
    isBusiness
    meterType
    mpan
    paymentMethod
    elecAnnualConsumptionStandard
    elecAnnualConsumptionDay
    elecAnnualConsumptionNight
    elecEstimate
    gasAnnualConsumption
    gasEstimate
    partnerProductId
    latitude
    longitude
    address {
      ...QuoteAddressTypeFragment
    }
    consumptionEstimates {
      ...ConsumptionEstimatesFragment
    }
    quotedProducts {
      ...QuotedProductTypeFragment
    }
    termsAndConditions {
      ...TermsAndConditionsTypeFragment
    }
    mprn
  }
}

Variables

{
  "code": "abc123"
}

Response

{
  "data": {
    "quote": {
      "code": "abc123",
      "postcode": "abc123",
      "gspGroupId": "abc123",
      "includesElectricity": true,
      "includesGas": true,
      "isBusiness": true,
      "meterType": "NO_METER",
      "mpan": "abc123",
      "paymentMethod": "DIRECTDEBIT",
      "elecAnnualConsumptionStandard": 1,
      "elecAnnualConsumptionDay": 1,
      "elecAnnualConsumptionNight": 1,
      "elecEstimate": true,
      "gasAnnualConsumption": 1,
      "gasEstimate": true,
      "partnerProductId": 1,
      "latitude": 1.0,
      "longitude": 1.0,
      "address": QuoteAddressType,
      "consumptionEstimates": ConsumptionEstimates,
      "quotedProducts": [QuotedProductType],
      "termsAndConditions": TermsAndConditionsType,
      "mprn": "abc123"
    }
  }
}

quoteRequest

Type:QuoteRequest

URL:https://api.octopus.energy/v1/graphql/

This is a work in progress and not in use yet.

The possible errors that can be raised are:

  • KT-GB-4618: Quote request not found.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

quoteCode (String!)

Code of the quote request.

Query

query QuoteRequest($quoteCode: String!) {
  quoteRequest(quoteCode: $quoteCode) {
    electricitySupplyPoints {
      ...ElectricitySupplyPointFragment
    }
    gasSupplyPoints {
      ...GasSupplyPointFragment
    }
    createdAt
    termsAndConditions {
      ...TermsAndConditionsFragment
    }
    code
  }
}

Variables

{
  "quoteCode": "abc123"
}

Response

{
  "data": {
    "quoteRequest": {
      "electricitySupplyPoints": [ElectricitySupplyPoint],
      "gasSupplyPoints": [GasSupplyPoint],
      "createdAt": "2020-01-01T00:00:00.000Z",
      "termsAndConditions": [TermsAndConditions],
      "code": "abc123"
    }
  }
}

rateLimitInfo

Type:CombinedRateLimitInformation

URL:https://api.octopus.energy/v1/graphql/

Combined information about points-allowance rate limiting and request-specific rate limiting.

Query

query RateLimitInfo {
  rateLimitInfo {
    pointsAllowanceRateLimit {
      ...PointsAllowanceRateLimitInformationFragment
    }
    fieldSpecificRateLimits {
      ...FieldSpecificRateLimitInformationConnectionTypeConnectionFragment
    }
  }
}

Response

{
  "data": {
    "rateLimitInfo": {
      "pointsAllowanceRateLimit": PointsAllowanceRateLimitInformation,
      "fieldSpecificRateLimits": FieldSpecificRateLimitInformationConnectionTypeConnection
    }
  }
}

registeredKrakenflexDevice

Type:KrakenFlexDeviceType

URL:https://api.octopus.energy/v1/graphql/

A device registered with KrakenFlex for a given account.

The possible errors that can be raised are:

  • KT-CT-1111: Unauthorized.
  • KT-CT-1113: Disabled GraphQL field requested.

Deprecated

The 'registeredKrakenflexDevice' field is deprecated.

Please use 'devices' instead.

- Marked as deprecated on 2024-04-23.
- Scheduled for removal on or after 2024-11-01.

Arguments

NameDescription

accountNumber (String!)

Query

query RegisteredKrakenflexDevice($accountNumber: String!) {
  registeredKrakenflexDevice(accountNumber: $accountNumber) {
    krakenflexDeviceId
    provider
    vehicleMake
    vehicleModel
    vehicleBatterySizeInKwh
    chargePointMake
    chargePointModel
    chargePointPowerInKw
    status
    suspended
    hasToken
    createdAt
    stateOfChargeLimit {
      ...StateOfChargeLimitFragment
    }
    testDispatchFailureReason
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "registeredKrakenflexDevice": {
      "krakenflexDeviceId": "abc123",
      "provider": "DAIKIN",
      "vehicleMake": "abc123",
      "vehicleModel": "abc123",
      "vehicleBatterySizeInKwh": 1.0,
      "chargePointMake": "abc123",
      "chargePointModel": "abc123",
      "chargePointPowerInKw": 1.0,
      "status": "abc123",
      "suspended": true,
      "hasToken": true,
      "createdAt": "2020-01-01T00:00:00.000Z",
      "stateOfChargeLimit": StateOfChargeLimit,
      "testDispatchFailureReason": "NONE"
    }
  }
}

savingSessions

Type:SavingSessionsType

URL:https://api.octopus.energy/v1/graphql/

Saving sessions queries for an account.

Arguments

NameDescription

accountNumber (String)

Kraken account number.

Query

query SavingSessions($accountNumber: String) {
  savingSessions(accountNumber: $accountNumber) {
    account {
      ...SavingSessionsAccountTypeFragment
    }
    events {
      ...SavingSessionsEventTypeFragment
    }
    eventCount
    nationalAggregatedStats {
      ...SavingSessionsNationalAggregatedStatsTypeFragment
    }
    prizeDrawInformation {
      ...SavingSessionsPrizeDrawInformationTypeFragment
    }
    regionalResults {
      ...SavingSessionsRegionalResultTypeFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "savingSessions": {
      "account": SavingSessionsAccountType,
      "events": [SavingSessionsEventType],
      "eventCount": 1,
      "nationalAggregatedStats": SavingSessionsNationalAggregatedStatsType,
      "prizeDrawInformation": SavingSessionsPrizeDrawInformationType,
      "regionalResults": [SavingSessionsRegionalResultType]
    }
  }
}

segInstallation

Type:SEGInstallationType!

URL:https://api.octopus.energy/v1/graphql/

The validity of a SEG installation via the MCS installation database.

Arguments

NameDescription

mcsCertificateNumber (String!)

The MCS certificate number.

Query

query SegInstallation($mcsCertificateNumber: String!) {
  segInstallation(mcsCertificateNumber: $mcsCertificateNumber) {
    isValid
  }
}

Variables

{
  "mcsCertificateNumber": "abc123"
}

Response

{
  "data": {
    "segInstallation": {
      "isValid": true
    }
  }
}

shoptopusVoucherAvailability

Type:[ShoptopusVoucherAvailabilityType]

URL:https://api.octopus.energy/v1/graphql/

Describes availability of Shoptopus Vouchers for given Octopoint amounts.

Arguments

NameDescription

voucherValues ([Int]!)

The values (in Octopoints) for which to return voucher availability (maximum 5 values).

Query

query ShoptopusVoucherAvailability($voucherValues: [Int]!) {
  shoptopusVoucherAvailability(voucherValues: $voucherValues) {
    value
    availability
  }
}

Variables

{
  "voucherValues": 1
}

Response

{
  "data": {
    "shoptopusVoucherAvailability": [
      {
        "value": 1,
        "availability": true
      }
    ]
  }
}

siteworksGetRtsPrimarySecondaryMpans

Type:[RTSPrimarySecondaryMPANs]!

URL:https://api.octopus.energy/v1/graphql/

Calculate the primary and secondary MPANs for an RTS property.

Deprecated

The 'siteworksGetRtsPrimarySecondayMpans' field is deprecated.

Only for use during the RTS transition.

- Marked as deprecated on 2025-08-01 00:00:00.
- Scheduled for removal on or after 2025-09-01 00:00:00.

Arguments

NameDescription

propertyId (Int!)

The id of the property.

Query

query SiteworksGetRtsPrimarySecondaryMpans($propertyId: Int!) {
  siteworksGetRtsPrimarySecondaryMpans(propertyId: $propertyId) {
    mpan
    type
  }
}

Variables

{
  "propertyId": 1
}

Response

{
  "data": {
    "siteworksGetRtsPrimarySecondaryMpans": {
      "mpan": "abc123",
      "type": "abc123"
    }
  }
}

siteworksKrakenFieldAppointmentPollDelay

Type:Int

URL:https://api.octopus.energy/v1/graphql/

Setting to determine delay in first poll when fetching async timeslots (in ms).

Query

query SiteworksKrakenFieldAppointmentPollDelay {
  siteworksKrakenFieldAppointmentPollDelay
}

Response

{
  "data": {
    "siteworksKrakenFieldAppointmentPollDelay": 1
  }
}

siteworksKrakenFieldAppointmentPollInterval

Type:Int

URL:https://api.octopus.energy/v1/graphql/

Setting to determine interval when fetching async timeslots (in ms).

Query

query SiteworksKrakenFieldAppointmentPollInterval {
  siteworksKrakenFieldAppointmentPollInterval
}

Response

{
  "data": {
    "siteworksKrakenFieldAppointmentPollInterval": 1
  }
}

siteworksKrakenFieldAppointmentPollMaxCount

Type:Int

URL:https://api.octopus.energy/v1/graphql/

Setting to determine how many times at most to fetch async timeslots.

Query

query SiteworksKrakenFieldAppointmentPollMaxCount {
  siteworksKrakenFieldAppointmentPollMaxCount
}

Response

{
  "data": {
    "siteworksKrakenFieldAppointmentPollMaxCount": 1
  }
}

smartDeviceNetwork

Type:SmartMeterDeviceNetworkType

URL:https://api.octopus.energy/v1/graphql/

Retrieve smartmeter devices connected to the same Home Area Network.

Arguments

NameDescription

deviceId (String!)

The deviceId of one of the devices on the Home Area Network.

Query

query SmartDeviceNetwork($deviceId: String!) {
  smartDeviceNetwork(deviceId: $deviceId) {
    id
    smartDevices {
      ...SmartMeterDeviceTypeFragment
    }
  }
}

Variables

{
  "deviceId": "abc123"
}

Response

{
  "data": {
    "smartDeviceNetwork": {
      "id": "abc123",
      "smartDevices": [SmartMeterDeviceType]
    }
  }
}

smartFlexOnboardingWizards

Type:[SmartFlexOnboardingWizard!]

URL:https://api.octopus.energy/v1/graphql/

A list of wizards for onboarding devices for an account and property.

Arguments

NameDescription

accountNumber (String!)

The account number, e.g. A-12345678.

propertyId (Int)

Only list wizards for this property.

wizardId (ID)

To get a specific wizard by ID, if it exists.

includeCancelled (Boolean)

Include cancelled wizards.

includeCompleted (Boolean)

Include completed wizards.

Query

query SmartFlexOnboardingWizards(
  $accountNumber: String!,
  $propertyId: Int,
  $wizardId: ID,
  $includeCancelled: Boolean,
  $includeCompleted: Boolean
) {
  smartFlexOnboardingWizards(
    accountNumber: $accountNumber,
    propertyId: $propertyId,
    wizardId: $wizardId,
    includeCancelled: $includeCancelled,
    includeCompleted: $includeCompleted
  ) {
    id
    backendScreen {
      ... on ComponentListType {
        ...ComponentListTypeFragment
      }
      ... on GenericBackendScreen {
        ...GenericBackendScreenFragment
      }
      ... on Dashboard {
        ...DashboardFragment
      }
    }
    currentStep {
      ...SmartFlexOnboardingStepInterfaceFragment
    }
    completedSteps {
      ...SmartFlexOnboardingStepInterfaceFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123",
  "propertyId": 1,
  "wizardId": "abc123",
  "includeCancelled": true,
  "includeCompleted": true
}

Response

{
  "data": {
    "smartFlexOnboardingWizards": [
      {
        "id": "abc123",
        "backendScreen": ComponentListType,
        "currentStep": SmartFlexOnboardingStepInterface,
        "completedSteps": SmartFlexOnboardingStepInterface
      }
    ]
  }
}

smartMeterDataPreferences

Type:SmartMeterDataPreferencesType

URL:https://api.octopus.energy/v1/graphql/

Override Field to add additional attributes and extend description with possible_errors

The possible errors that can be raised are:

  • KT-CT-4023: Unauthorized.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

Query

query SmartMeterDataPreferences($accountNumber: String!) {
  smartMeterDataPreferences(accountNumber: $accountNumber) {
    readingFrequency
    readingsAnalysisConsentProvided
    readingsAnalysisConsentUpdatedDatetime
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "smartMeterDataPreferences": {
      "readingFrequency": "DAILY",
      "readingsAnalysisConsentProvided": true,
      "readingsAnalysisConsentUpdatedDatetime": "2020-01-01T00:00:00.000Z"
    }
  }
}

smartMeterTelemetry

Type:[SmartMeterTelemetryType]

URL:https://api.octopus.energy/v1/graphql/

Query telemetry data collected by the CAD associated with the provided ESME or GSME device ID.

If only the smart meter device ID is provided, the latest data available will be returned.

Additionally including the range options (start, end, and grouping) will return the data for that time period, at the desired granularity.

The possible errors that can be raised are:

  • KT-GB-4039: Unable to query smart meter telemetry data.
  • KT-GB-4050: Smart meter not found.
  • KT-GB-4040: 'start', 'end', and 'grouping' must all be provided.
  • KT-GB-4041: 'end' should be later than 'start'.
  • KT-GB-4051: The start of the range is too far in the past.
  • KT-GB-4042: Too many requests. Please wait before trying again.
  • KT-GB-4043: A network error occurred. Please try again.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

deviceId (String!)

The ESME or GSME's EUI64 ID, e.g. '12-34-5A-FF-FF-6B-C7-89'

start (DateTime)

The start time of the range of readings (inclusive), e.g. '2022-01-28T16:33:22+00:00'. If no UTC timezone offset is included, UTC (+00:00) will be assumed.

end (DateTime)

The end time of the range of readings (exclusive), e.g. '2022-01-28T16:34:42+00:00'. If no UTC timezone offset is included, UTC (+00:00) will be assumed.

grouping (TelemetryGrouping)

The granularity of the returned data. The representative data item (e.g. consumption) for each group (e.g. every 5 minutes) will be the mean value over that period.

Query

query SmartMeterTelemetry(
  $deviceId: String!,
  $start: DateTime,
  $end: DateTime,
  $grouping: TelemetryGrouping
) {
  smartMeterTelemetry(
    deviceId: $deviceId,
    start: $start,
    end: $end,
    grouping: $grouping
  ) {
    readAt
    consumption
    export
    demand
    consumptionDelta
    costDelta
    costDeltaWithTax
  }
}

Variables

{
  "deviceId": "abc123",
  "start": "2020-01-01T00:00:00.000Z",
  "end": "2020-01-01T00:00:00.000Z",
  "grouping": "TEN_SECONDS"
}

Response

{
  "data": {
    "smartMeterTelemetry": [
      {
        "readAt": "2020-01-01T00:00:00.000Z",
        "consumption": 1.0,
        "export": 1.0,
        "demand": 1.0,
        "consumptionDelta": 1.0,
        "costDelta": 1.0,
        "costDeltaWithTax": 1.0
      }
    ]
  }
}

smartTariffComparison

Type:SmartTariffComparisonType

URL:https://api.octopus.energy/v1/graphql/

Compare consumption costs for different smart tariffs.

The possible errors that can be raised are:

  • KT-GB-10101: Electricity agreement not found.
  • KT-GB-10103: Not enough consumption data.
  • KT-GB-10102: Error while calculating consumption costs.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

mpan (String)

MPAN of the import meter point linked to the meter.

Query

query SmartTariffComparison($mpan: String) {
  smartTariffComparison(mpan: $mpan) {
    currentCost
    currentCostWithTax
    costComparisons {
      ...TariffComparisonTypeFragment
    }
    consumptionReadingsStartAt
    consumptionReadingsEndAt
  }
}

Variables

{
  "mpan": "abc123"
}

Response

{
  "data": {
    "smartTariffComparison": {
      "currentCost": 1.0,
      "currentCostWithTax": 1.0,
      "costComparisons": [TariffComparisonType],
      "consumptionReadingsStartAt": "2020-01-01T00:00:00.000Z",
      "consumptionReadingsEndAt": "2020-01-01T00:00:00.000Z"
    }
  }
}

Arguments

NameDescription

accountNumber (String)

Filter meter points by account.

portfolioNumber (String)

Filter meter points by portfolio.

before (String)

after (String)

first (Int)

last (Int)

Query

query SupplyPoints(
  $accountNumber: String,
  $portfolioNumber: String,
  $before: String,
  $after: String,
  $first: Int,
  $last: Int
) {
  supplyPoints(
    accountNumber: $accountNumber,
    portfolioNumber: $portfolioNumber,
    before: $before,
    after: $after,
    first: $first,
    last: $last
  ) {
    pageInfo {
      ...PageInfoFragment
    }
    edges {
      ...SupplyPointConnectionTypeEdgeFragment
    }
    totalCount
    edgeCount
  }
}

Variables

{
  "accountNumber": "abc123",
  "portfolioNumber": "abc123",
  "before": "abc123",
  "after": "abc123",
  "first": 1,
  "last": 1
}

Response

{
  "data": {
    "supplyPoints": {
      "pageInfo": PageInfo,
      "edges": SupplyPointConnectionTypeEdge,
      "totalCount": 1,
      "edgeCount": 1
    }
  }
}

taskResult

Type:TaskResult

URL:https://api.octopus.energy/v1/graphql/

Get the status of a background task.

The possible errors that can be raised are:

  • KT-CT-10401: Task not found.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

taskId (String!)

accountNumber (String!)

Query

query TaskResult(
  $taskId: String!,
  $accountNumber: String!
) {
  taskResult(
    taskId: $taskId,
    accountNumber: $accountNumber
  ) {
    status
    result
    error
  }
}

Variables

{
  "taskId": "abc123",
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "taskResult": {
      "status": "STARTED",
      "result": {"key": "value"},
      "error": "abc123"
    }
  }
}

termsAndConditionsForProduct

Type:GbrTermsAndConditionsType

URL:https://api.octopus.energy/v1/graphql/

Get the active terms and conditions for a product.

The possible errors that can be raised are:

  • KT-CT-8501: No active terms and conditions found for product.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

productCode (String!)

Query

query TermsAndConditionsForProduct($productCode: String!) {
  termsAndConditionsForProduct(productCode: $productCode) {
    name
    pdfUrl
    brandCode
    markdown
    html
    version
    effectiveFrom
  }
}

Variables

{
  "productCode": "abc123"
}

Response

{
  "data": {
    "termsAndConditionsForProduct": {
      "name": "abc123",
      "pdfUrl": "abc123",
      "brandCode": "abc123",
      "markdown": "abc123",
      "html": "abc123",
      "version": "abc123",
      "effectiveFrom": "2020-01-01T00:00:00.000Z"
    }
  }
}

urls

Type:Urls

URL:https://api.octopus.energy/v1/graphql/

URLs for an account.

The possible errors that can be raised are:

  • KT-CT-4123: Unauthorized.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

The account number of the URLs' account.

Query

query Urls($accountNumber: String!) {
  urls(accountNumber: $accountNumber) {
    wheelOfFortuneElec
    wheelOfFortuneGas
    meterReadingSubmission
    tariffRenewal
    bookSmartMeterInstallation
    updateSensitiveCustomerData
    savingSessionsJoinCampaign
    savingSessionsDashboard
    savingSessionsJoinNextEvent
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "urls": {
      "wheelOfFortuneElec": "abc123",
      "wheelOfFortuneGas": "abc123",
      "meterReadingSubmission": "abc123",
      "tariffRenewal": "abc123",
      "bookSmartMeterInstallation": "abc123",
      "updateSensitiveCustomerData": "abc123",
      "savingSessionsJoinCampaign": "abc123",
      "savingSessionsDashboard": "abc123",
      "savingSessionsJoinNextEvent": "abc123"
    }
  }
}

userVehicles

Type:[UserVehiclesType]

URL:https://api.octopus.energy/v1/graphql/

A list of vehicles available to the user.

Note: If the API returns an empty list, there might be a delay between the vehicle being registered in the provider's system, and data being fetched from the vehicle's manufacturer. In such cases, the query should be retried after a few seconds.

Arguments

NameDescription

accountNumber (String)

supportedProvider (ProviderChoices)

The provider used to authenticate the device (default Enode).

authentication (AuthenticationInput)

The authentication details required given the chosen provider.

Query

query UserVehicles(
  $accountNumber: String,
  $supportedProvider: ProviderChoices,
  $authentication: AuthenticationInput
) {
  userVehicles(
    accountNumber: $accountNumber,
    supportedProvider: $supportedProvider,
    authentication: $authentication
  ) {
    vehicleId
    information {
      ...VehicleInformationTypeFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123",
  "supportedProvider": "DAIKIN",
  "authentication": AuthenticationInput
}

Response

{
  "data": {
    "userVehicles": [
      {
        "vehicleId": "abc123",
        "information": VehicleInformationType
      }
    ]
  }
}

validateReferralClaimCode

Type:ReferralClaimCodeType

URL:https://api.octopus.energy/v1/graphql/

Validate referral claim code.

The possible errors that can be raised are:

  • KT-CT-6724: Referral claim code not found.
  • KT-CT-6726: Referral claim code has already been redeemed.
  • KT-CT-6727: Referral claim code is not available.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

value (String!)

Referral claim code value.

Query

query ValidateReferralClaimCode($value: String!) {
  validateReferralClaimCode(value: $value) {
    id
    value
    referralScheme {
      ...ReferralSchemeTypeFragment
    }
    accountReferral {
      ...ReferralTypeFragment
    }
    createdAt
  }
}

Variables

{
  "value": "abc123"
}

Response

{
  "data": {
    "validateReferralClaimCode": {
      "id": 1,
      "value": "abc123",
      "referralScheme": ReferralSchemeType,
      "accountReferral": ReferralType,
      "createdAt": "2020-01-01T00:00:00.000Z"
    }
  }
}

vehicleChargingPreferences

Type:VehicleChargingPreferencesType

URL:https://api.octopus.energy/v1/graphql/

Vehicle charging preference details.

The possible errors that can be raised are:

  • KT-CT-1111: Unauthorized.
  • KT-CT-4339: Your device charging preferences could not be fetched.
  • KT-CT-1113: Disabled GraphQL field requested.

Deprecated

The 'vehicleChargingPreferences' field is deprecated.

Please use 'devices.preferences' instead.

- Marked as deprecated on 2024-04-23.
- Scheduled for removal on or after 2024-11-01.

Arguments

NameDescription

accountNumber (String!)

Query

query VehicleChargingPreferences($accountNumber: String!) {
  vehicleChargingPreferences(accountNumber: $accountNumber) {
    weekdayTargetTime
    weekdayTargetSoc
    weekendTargetTime
    weekendTargetSoc
    minimumSocPercentage
    maximumSocPercentage
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "vehicleChargingPreferences": {
      "weekdayTargetTime": "abc123",
      "weekdayTargetSoc": 1,
      "weekendTargetTime": "abc123",
      "weekendTargetSoc": 1,
      "minimumSocPercentage": 1,
      "maximumSocPercentage": 1
    }
  }
}

viewer

Type:AccountUserType

URL:https://api.octopus.energy/v1/graphql/

The currently authenticated user.

This field requires the Authorization header to be set.

Query

query Viewer {
  viewer {
    id
    accounts {
      ...AccountInterfaceFragment
    }
    givenName
    familyName
    email
    mobile
    landline
    title
    pronouns
    isDeceased
    liveSecretKey
    portfolios {
      ...PortfolioConnectionTypeConnectionFragment
    }
    dateOfBirth
    details {
      ...AccountUserDetailTypeFragment
    }
    displayName
    firstName
    lastName
    fullName
    preferredName
    portfolioId
    portfolioIds
    specialCircumstances {
      ...SpecialCircumstancesTypeFragment
    }
    preferences {
      ...AccountUserCommsPreferencesFragment
    }
    landlinePhoneNumber
    alternativePhoneNumbers
    hasFamilyIssues
    isInHardship
    accountUserRoles {
      ...AccountUserRoleTypeFragment
    }
    portfolioUserRoles {
      ...PortfolioUserRoleTypeFragment
    }
    consents {
      ...ConsentTypeFragment
    }
    paymentMethods {
      ...PaymentInstructionConnectionTypeConnectionFragment
    }
    holdMusicChoices {
      ...TrackOptionTypeFragment
    }
    isOptedInToWof
  }
}

Response

{
  "data": {
    "viewer": {
      "id": "abc123",
      "accounts": AccountInterface,
      "givenName": "abc123",
      "familyName": "abc123",
      "email": "abc123",
      "mobile": "abc123",
      "landline": "abc123",
      "title": "abc123",
      "pronouns": "abc123",
      "isDeceased": true,
      "liveSecretKey": "abc123",
      "portfolios": PortfolioConnectionTypeConnection,
      "dateOfBirth": "2020-01-01",
      "details": [AccountUserDetailType],
      "displayName": "abc123",
      "firstName": "abc123",
      "lastName": "abc123",
      "fullName": "abc123",
      "preferredName": "abc123",
      "portfolioId": "abc123",
      "portfolioIds": ["abc123"],
      "specialCircumstances": SpecialCircumstancesType,
      "preferences": AccountUserCommsPreferences,
      "landlinePhoneNumber": "abc123",
      "alternativePhoneNumbers": ["abc123"],
      "hasFamilyIssues": true,
      "isInHardship": true,
      "accountUserRoles": [AccountUserRoleType],
      "portfolioUserRoles": [PortfolioUserRoleType],
      "consents": ConsentType,
      "paymentMethods": PaymentInstructionConnectionTypeConnection,
      "holdMusicChoices": [TrackOptionType],
      "isOptedInToWof": true
    }
  }
}

wanCoverage

Type:WANCoverageStrengths

URL:https://api.octopus.energy/v1/graphql/

Likelihood that a smart meter at the given postcode and optional address identifier will get a stable network connection.

Arguments

NameDescription

postcode (String!)

addressIdentifier (String)

The address identifier to search for.

propertyId (ID)

The property ID to search for.

Query

query WanCoverage(
  $postcode: String!,
  $addressIdentifier: String,
  $propertyId: ID
) {
  wanCoverage(
    postcode: $postcode,
    addressIdentifier: $addressIdentifier,
    propertyId: $propertyId
  )
}

Variables

{
  "postcode": "abc123",
  "addressIdentifier": "abc123",
  "propertyId": "abc123"
}

Response

{
  "data": {
    "wanCoverage": "HIGH"
  }
}

wanCoverageDetail

Type:[WanCoverageDetail]

URL:https://api.octopus.energy/v1/graphql/

Detailed WAN coverage report for a given post code and optional address identifier

Arguments

NameDescription

postcode (String!)

addressIdentifier (String)

propertyId (ID)

The property ID to search for.

Query

query WanCoverageDetail(
  $postcode: String!,
  $addressIdentifier: String,
  $propertyId: ID
) {
  wanCoverageDetail(
    postcode: $postcode,
    addressIdentifier: $addressIdentifier,
    propertyId: $propertyId
  ) {
    postcode
    addressIdentifier
    isCoverageAvailable
    anticipatedCoverageAt
    wanTechnology
    auxiliaryEquipment
    connectivityLikelihood
    additionalInformation
  }
}

Variables

{
  "postcode": "abc123",
  "addressIdentifier": "abc123",
  "propertyId": "abc123"
}

Response

{
  "data": {
    "wanCoverageDetail": [
      {
        "postcode": "abc123",
        "addressIdentifier": "abc123",
        "isCoverageAvailable": true,
        "anticipatedCoverageAt": "abc123",
        "wanTechnology": "abc123",
        "auxiliaryEquipment": "abc123",
        "connectivityLikelihood": "abc123",
        "additionalInformation": "abc123"
      }
    ]
  }
}

weeklyUsageInsights

Type:WeeklyUsageInsightsType

URL:https://api.octopus.energy/v1/graphql/

Get account status information given its number.

The possible errors that can be raised are:

  • KT-CT-1111: Unauthorized.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

The account number to search for.

Query

query WeeklyUsageInsights($accountNumber: String!) {
  weeklyUsageInsights(accountNumber: $accountNumber) {
    accountId
    meterPointId
    weekStart
    accountNumber
    propertyId
    mpan
    gspGroupId
    apiGspGroupName
    consumptionKwh
    carbonGrams
    achievedCarbonRate
    achievedCarbonIndex
    periodStart
    periodEnd
    numberPeriods
    hasFullReadings
    isLatestWeek
    achievedCarbonRank
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "weeklyUsageInsights": {
      "accountId": 1,
      "meterPointId": 1,
      "weekStart": "2020-01-01T00:00:00.000Z",
      "accountNumber": "abc123",
      "propertyId": 1,
      "mpan": "abc123",
      "gspGroupId": "abc123",
      "apiGspGroupName": "abc123",
      "consumptionKwh": "abc123",
      "carbonGrams": 1.0,
      "achievedCarbonRate": 1.0,
      "achievedCarbonIndex": "VERY_LOW",
      "periodStart": "2020-01-01T00:00:00.000Z",
      "periodEnd": "2020-01-01T00:00:00.000Z",
      "numberPeriods": "abc123",
      "hasFullReadings": "abc123",
      "isLatestWeek": "abc123",
      "achievedCarbonRank": "abc123"
    }
  }
}

wheelOfFortuneSegments

Type:WheelSegmentsType!

URL:https://api.octopus.energy/v1/graphql/

Retrieve the segments to be displayed on the Wheel of Fortune.

This field requires the Authorization header to be set.

Query

query WheelOfFortuneSegments {
  wheelOfFortuneSegments {
    segments
  }
}

Response

{
  "data": {
    "wheelOfFortuneSegments": {
      "segments": [1]
    }
  }
}

wheelOfFortuneSpins

Type:AvailableSpinsType!

URL:https://api.octopus.energy/v1/graphql/

Retrieve the number of available Wheel of Fortune spins, per energy type, of an account by the account number.

This field requires the Authorization header to be set.

The possible errors that can be raised are:

  • KT-CT-7023: Unauthorized.
  • KT-CT-1113: Disabled GraphQL field requested.

Arguments

NameDescription

accountNumber (String!)

The account number for which the available spins are gathered.

Query

query WheelOfFortuneSpins($accountNumber: String!) {
  wheelOfFortuneSpins(accountNumber: $accountNumber) {
    electricity {
      ...SupplyTypeSpecificSpinsTypeFragment
    }
    gas {
      ...SupplyTypeSpecificSpinsTypeFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "wheelOfFortuneSpins": {
      "electricity": SupplyTypeSpecificSpinsType,
      "gas": SupplyTypeSpecificSpinsType
    }
  }
}

Authentication Server

authorizedApplications

Type:[AuthorizedApplication]

URL:https://auth.octopus.energy/graphql/

Get all the confidential-client applications the current user has authorized.

Query

query AuthorizedApplications {
  authorizedApplications {
    name
    clientId
  }
}

Response

{
  "data": {
    "authorizedApplications": [
      {
        "name": "abc123",
        "clientId": "abc123"
      }
    ]
  }
}

Query

query KrakenVersion {
  krakenVersion {
    number
    SHA
  }
}

Response

{
  "data": {
    "krakenVersion": {
      "number": "abc123",
      "SHA": "abc123"
    }
  }
}

mfaDevices

Type:[MfaDevice]

URL:https://auth.octopus.energy/graphql/

Get all MFA devices for the current user.

Query

query MfaDevices {
  mfaDevices {
    deviceType
    isConfirmed
  }
}

Response

{
  "data": {
    "mfaDevices": [
      {
        "deviceType": "abc123",
        "isConfirmed": true
      }
    ]
  }
}