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.

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
    }
    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,
      "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"
      }
    ]
  }
}

accountConversationHasHandoffEvent

Type:Boolean!

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

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

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
    }
  }
}

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
      }
    ]
  }
}

accountUrls

Type:[AccountUrl]

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

List URLs for an account.

Deprecated

The 'accountUrls' field is deprecated.

Please access the URLs through the support site.

- Marked as deprecated on 2021-10-12.
- Scheduled for removal on or after 2024-01-01.

Arguments

NameDescription

accountNumber (String!)

Query

query AccountUrls($accountNumber: String!) {
  accountUrls(accountNumber: $accountNumber) {
    urlIdentifier
    url
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "accountUrls": [
      {
        "urlIdentifier": "abc123",
        "url": "abc123"
      }
    ]
  }
}

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
    }
    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,
        "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.

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.

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.

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.

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"]
  }
}

Arguments

NameDescription

accountNumber (String!)

Kraken account number.

Query

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

Variables

{
  "accountNumber": "abc123"
}

Response

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

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.

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"
    }
  }
}

Arguments

NameDescription

id (ID!)

The business ID.

Query

query Business($id: ID!) {
  business(id: $id) {
    name
    number
    businessType
    linkedAccountNumber
  }
}

Variables

{
  "id": "abc123"
}

Response

{
  "data": {
    "business": {
      "name": "abc123",
      "number": "abc123",
      "businessType": "SOLE_TRADER",
      "linkedAccountNumber": "abc123"
    }
  }
}

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]
      }
    ]
  }
}

Arguments

NameDescription

accountNumber (String!)

Query

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

Variables

{
  "accountNumber": "abc123"
}

Response

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

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.

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
    bankCode
    accountType
    validFrom
    vendor
    cardNumber
    cardType
    maskedAccountIdentifier
  }
}

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,
      "bankCode": "abc123",
      "accountType": "abc123",
      "validFrom": "2020-01-01T00:00:00.000Z",
      "vendor": "abc123",
      "cardNumber": "abc123",
      "cardType": "abc123",
      "maskedAccountIdentifier": "abc123"
    }
  }
}

defaultRawScore

Type:Int

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

Get default raw score for a customer feedback form.

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.

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])

before (String)

after (String)

first (Int)

last (Int)

Query

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

Variables

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

Response

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

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.

before (String)

after (String)

first (Int)

last (Int)

Query

query EnergyProducts(
  $postcode: String!,
  $tags: [String],
  $brand: String,
  $brands: [String],
  $availability: EnergyProductAvailability,
  $filterBy: [EnergyProductFilters],
  $before: String,
  $after: String,
  $first: Int,
  $last: Int
) {
  energyProducts(
    postcode: $postcode,
    tags: $tags,
    brand: $brand,
    brands: $brands,
    availability: $availability,
    filterBy: $filterBy,
    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",
  "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.

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.

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"]
    }
  }
}

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])

before (String)

after (String)

first (Int)

last (Int)

Query

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

Variables

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

Response

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

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
    }
  }
}

getConstantines

Type:ConstantineSpawnData

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

Octoplus Snap constantines currently available for a given account_user.

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"
    }
  }
}

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 InkPost {
      ...InkPostFragment
    }
    ... on InkGenericMessage {
      ...InkGenericMessageFragment
    }
  }
}

Variables

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

Response

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

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]
    }
  }
}

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.

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]
    }
  }
}

getWinterGasComparison

Type:WinterGasComparisonResultType

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

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

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
    }
    marketParams
    clientParams
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "goodsPurchases": [
      {
        "code": "abc123",
        "ledgerId": "abc123",
        "ledgerNumber": "abc123",
        "goodsSaleItems": [GoodsSaleItem],
        "goodsGrants": [GoodsGrant],
        "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": 1,
        "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.

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
  }
}

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.

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.

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

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.

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.

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 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"
    }
  }
}

Arguments

NameDescription

leadId (ID)

The identifier of the lead to query.

key (String)

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

Query

query LeadValueByKey(
  $leadId: ID,
  $key: String
) {
  leadValueByKey(
    leadId: $leadId,
    key: $key
  )
}

Variables

{
  "leadId": "abc123",
  "key": "abc123"
}

Response

{
  "data": {
    "leadValueByKey": "abc123"
  }
}

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.

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"
      }
    ]
  }
}

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.

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.

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
    }
  }
}

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.

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.

Arguments

NameDescription

accountNumber (String!)

Query

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

Variables

{
  "accountNumber": "abc123"
}

Response

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

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.

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"
      }
    ]
  }
}

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.

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
    }
  }
}

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.

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
      }
    ]
  }
}

octoPoints

Type:OctoPointsType

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

Query relating to OctoPoints.

Deprecated

The 'octoPoints' field is deprecated.

Please use the loyaltyPointLedgers query instead

- Marked as deprecated on 2024-02-06.
- Scheduled for removal on or after 2024-05-06.

Arguments

NameDescription

accountNumber (String)

Kraken account number.

Query

query OctoPoints($accountNumber: String) {
  octoPoints(accountNumber: $accountNumber) {
    account {
      ...OctoPointsAccountTypeFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "octoPoints": {
      "account": OctoPointsAccountType
    }
  }
}

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.

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.

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
    isLoyaltyPointsUser
    octoplusEligibility {
      ...OctoplusEligibilityTypeFragment
    }
    octoplusSnapWebUrl {
      ...OctoplusSnapWebUrlTypeFragment
    }
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "octoplusAccountInfo": {
      "isOctoplusEnrolled": true,
      "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"
      }
    ]
  }
}

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
      }
    ]
  }
}

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.

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
    possibleErrorsList {
      ...PossibleErrorTypeFragment
    }
  }
}

Variables

Response

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

prepayBalanceSnapshot

Type:PrepayBalanceSnapshotType

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

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

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
    }
  }
}

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]
    }
  }
}

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
    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"],
        "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
    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"],
      "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
    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"],
        "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.

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/

If a quote code and product id are supplied, this returns that quote. Otherwise it returns an empty quote. This is a convenient way to expose both existing quotes, as well as the OFGEM consumption profiles are creating a quote.

Arguments

NameDescription

code (String)

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.

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"
    }
  }
}

rateLimit

Type:RateLimitInformation

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

Information about rate limit for viewer.

Deprecated

The 'rateLimit' field is deprecated.

`rateLimit` has been replaced by 'rateLimitInfo', which contains more detailed info about rate limit than the former one

- Marked as deprecated on 2024-07-17.
- Scheduled for removal on or after 2025-01-01.

Query

query RateLimit {
  rateLimit {
    limit
    remainingPoints
    usedPoints
  }
}

Response

{
  "data": {
    "rateLimit": {
      "limit": 1,
      "remainingPoints": 1,
      "usedPoints": 1
    }
  }
}

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.

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
    }
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

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

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
      }
    ]
  }
}

siteworksCoconutAppointmentPollDelay

Type:Int

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

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

Deprecated

The 'siteworksCoconutAppointmentPollDelay' field is deprecated.

Please use the 'siteworksKrakenFieldAppointmentPollDelay' field instead.

- Marked as deprecated on 2024-09-03.
- Scheduled for removal on or after 2026-01-01.

Query

query SiteworksCoconutAppointmentPollDelay {
  siteworksCoconutAppointmentPollDelay
}

Response

{
  "data": {
    "siteworksCoconutAppointmentPollDelay": 1
  }
}

siteworksCoconutAppointmentPollInterval

Type:Int

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

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

Deprecated

The 'siteworksCoconutAppointmentPollInterval' field is deprecated.

Please use the 'siteworksKrakenFieldAppointmentPollInterval' field instead.

- Marked as deprecated on 2024-09-03.
- Scheduled for removal on or after 2026-01-01.

Query

query SiteworksCoconutAppointmentPollInterval {
  siteworksCoconutAppointmentPollInterval
}

Response

{
  "data": {
    "siteworksCoconutAppointmentPollInterval": 1
  }
}

siteworksCoconutAppointmentPollMaxCount

Type:Int

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

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

Deprecated

The 'siteworksCoconutAppointmentPollMaxCount' field is deprecated.

Please use the 'siteworksKrakenFieldAppointmentPollMaxCount' field instead.

- Marked as deprecated on 2024-09-03.
- Scheduled for removal on or after 2026-01-01.

Query

query SiteworksCoconutAppointmentPollMaxCount {
  siteworksCoconutAppointmentPollMaxCount
}

Response

{
  "data": {
    "siteworksCoconutAppointmentPollMaxCount": 1
  }
}

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
      }
    ]
  }
}

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.

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.

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"
    }
  }
}

taskResult

Type:TaskResult

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

Get the status of a background task.

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:TermsAndConditionsType

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

Get the active terms and conditions for a product.

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"
    }
  }
}

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
      }
    ]
  }
}

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.

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
    }
    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,
      "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.

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.

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
    }
  }
}

wofUrls

Type:[AccountUrl]

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

List Wheel of Fortune URLs for an account.

Deprecated

The 'wofUrls' field is deprecated.

Please use `urls` query instead.

- Marked as deprecated on 2021-10-12.
- Scheduled for removal on or after 2024-01-01.

Arguments

NameDescription

accountNumber (String!)

Query

query WofUrls($accountNumber: String!) {
  wofUrls(accountNumber: $accountNumber) {
    urlIdentifier
    url
  }
}

Variables

{
  "accountNumber": "abc123"
}

Response

{
  "data": {
    "wofUrls": [
      {
        "urlIdentifier": "abc123",
        "url": "abc123"
      }
    ]
  }
}

Authentication Server

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
      }
    ]
  }
}