openapi: 3.2.0 info: title: Kraken Post Account Import API version: v1 description: APIs for importing additional data after an account has been imported. servers: - url: https://api.origin-kraken.energy/v1 description: Base URL declared by the provider in apis.yml (roadmap#122). tags: - name: post_account_import x-title: Post Account Import description: APIs for importing additional data after an account has been imported. x-documentation-order: 6 paths: /v1/data-import/historical-statements/create/: post: operationId: V1 Create Historical Statements description: Use this endpoint to import historical PDF statements onto an account. summary: Use this endpoint to import historical PDF statements onto an account. tags: - post_account_import requestBody: content: application/json: schema: $ref: '#/components/schemas/HistoricalStatements' examples: ExamplePayload: value: import_supplier: TENTACLE_ENERGY external_account_number: EXTERNAL-1234 statements: - bill_period_from_date: '2022-01-01' bill_period_to_date: '2022-01-31' statement_id: '1' issued_date: '2022-02-02' number: '1' gross_amount: 100 statement_path: path/to/statement-1.pdf summary: Example payload required: true security: - DataImportViewerAPIKeyAuthentication: [] - DRFKrakenTokenAuthentication: [] responses: '400': content: application/json: schema: $ref: '#/components/schemas/NonFieldErrors' examples: AccountNumberOrExternalAccountNumberMustBeProvided: value: non_field_errors: - Either account_number or external_account_number must be provided. summary: account_number or external_account_number must be provided description: Validation error. '404': description: The account import process or account have not been found. To resolve the error, check that the account has been imported (not just staged) and that the `import_supplier code` and `external_account_number` are correct. '201': content: application/json: schema: $ref: '#/components/schemas/HistoricalStatements' description: If the payload is valid, the validated data will be returned in the body of the response. x-doc-alerts: [] /v1/data-import/notes/create/: post: operationId: V1 Create Account Notes description: 'Some points to note: - A note must contain at least one of the fields `body` or `document_paths`. - A `created_at` datetime may optionally be provided. Otherwise, it will default to the current local time. - The `document_paths` refer to the locations in S3 where attached documents are stored. - An optional `is_pinned` boolean can be passed in the payload to control whether this note will be pinned to the top of the Kraken account support site page.' summary: Use this endpoint to add notes to an account. tags: - post_account_import requestBody: content: application/json: schema: $ref: '#/components/schemas/AccountNote' examples: ExamplePayload: value: import_supplier: TENTACLE_ENERGY external_account_number: EXTERNAL-1234 notes: - body: Some important pinned note. is_pinned: true unpin_at: '2020-06-01T12:00:00Z' - created_at: '2020-02-01T12:00:00Z' body: Some important note with an attachment. document_paths: - document_path: some/path/to/a/document.pdf summary: Example payload required: true security: - DataImportViewerAPIKeyAuthentication: [] - DRFKrakenTokenAuthentication: [] responses: '400': content: application/json: schema: $ref: '#/components/schemas/NonFieldErrors' examples: AccountNumberOrExternalAccountNumberMustBeProvided: value: non_field_errors: - Either account_number or external_account_number must be provided. summary: account_number or external_account_number must be provided description: Validation error. '404': description: The account import process or account have not been found. To resolve the error, check that the account has been imported (not just staged) and that the `import_supplier code` and `external_account_number` are correct. '201': content: application/json: schema: $ref: '#/components/schemas/CreateAccountNotesResponse' examples: CreateNoteSuccessExample: value: - created_at: '2020-01-01T12:00:00Z' body: Something very important to import. status: NOTE_CREATION_SUCCESS - created_at: '2020-02-01T12:00:00Z' body: Something else very important to import. status: NOTE_ALREADY_EXISTS summary: Create note success example description: If the payload is valid, a list of the posted notes and their creation status will be returned in the response. A new note will only be created if a note on the account with the same body (and `created_at`, if provided) does not already exist. x-doc-alerts: [] /v1/data-import/payment-instruction/create/: post: operationId: V1 Create Payment Instruction description: Create a payment instruction. summary: Create a payment instruction. tags: - post_account_import requestBody: content: application/json: schema: $ref: '#/components/schemas/LegacyPaymentInstruction' examples: ExamplePayload: value: import_supplier: TENTACLE_ENERGY external_account_number: EXTERNAL-1234 vendor: STRIPE reference: THIS-IS-A-FAKE-REFERENCE type: CARD summary: Example payload required: true security: - DataImportViewerAPIKeyAuthentication: [] - DRFKrakenTokenAuthentication: [] responses: '201': content: application/json: schema: $ref: '#/components/schemas/CreatePaymentInstructionResponse' examples: CreatedPaymentInstruction.: value: kraken_account_number: A-C90DC431 reference: THIS-IS-A-FAKE-REFERENCE summary: Created payment instruction. description: If the payload is valid, the Kraken account number and the reference will be returned. '400': content: application/json: schema: $ref: '#/components/schemas/CreatePaymentInstructionError' examples: AccountAlreadyHasAnActiveInstructionError.: value: error_detail: Account already has an active instruction external_account_number: '7654321' import_supplier: SOME_IMPORT_SUPPLIER reference: THIS-IS-A-FAKE-REFERENCE summary: Account already has an active instruction error. description: ' If there are validation errors, the errors will be detailed in the body of the response. To resolve the error, refer to the field definitions and validation rules. This error can be returned if we have persistent issues communicating with the upstream payment vendor (we call their API to verify the instruction exists, and retrieve the details to store in Kraken). In this case, **the request should not be retried in its current form**. ' '500': content: application/json: schema: $ref: '#/components/schemas/CreatePaymentInstructionError' description: ' This error can be returned if we have intermittent issues communicating with the upstream payment vendor (we call their API to verify the instruction exists, and retrieve the details to store in Kraken). In this case, **the request should be retried as-is**. ' x-doc-alerts: [] /v1/data-import/transactions/create/: post: operationId: V1 Create Transactions description: Use this endpoint to import financial transactions to an account. summary: Use this endpoint to import financial transactions to an account. parameters: - in: query name: check_previously_added schema: type: boolean default: true description: Boolean flag indicating whether to check if a transaction has already been added. - in: query name: force_add_to_current_statement schema: type: boolean default: true description: boolean flag. If set to true and the payload contains a transaction that is outside the currently-open statement period, this will modify the transaction date so that it is within the currently-open statement period. This then allows the transaction to be added to the statement instead of throwing an error. A description is added to the transaction to explain this, and a note is pinned to the account. tags: - post_account_import requestBody: content: application/json: schema: $ref: '#/components/schemas/Transactions' examples: ExamplePayload: value: import_supplier: TENTACLE_ENERGY external_account_number: EXTERNAL-1234 transactions: - transaction_id: '1' transaction_date: '2019-10-01' amount: 10.0 type: CHARGE reason: IMPORTED_CHARGE display_note: Some customer facing note about the charge. note: Some internal note about the charge. - transaction_id: '2' transaction_date: '2019-10-01' amount: 10.0 type: CREDIT reason: IMPORTED_CREDIT display_note: Some customer facing note about the credit. note: Some internal note about the credit. - transaction_id: '3' transaction_date: '2019-10-01' amount: 10.0 type: PAYMENT reason: ACCOUNT_CHARGE_PAYMENT reference: payment-reference-1 payment_type: DD_REGULAR_COLLECTION note: Some internal note about the payment. - transaction_id: '4' transaction_date: '2019-10-01' amount: 10.0 type: REPAYMENT reason: FULL_CREDIT_REFUND reference: repayment-reference-1 payment_type: DIRECT_CREDIT note: Some internal note about the repayment. - transaction_id: '5' transaction_date: '2019-10-01' amount: 53.24 type: SUPPLY_CHARGE display_note: Some customer facing note about the supply charge. product_code: SOME-PRODUCT-CODE-4321 line_items: - rate_band: CONSUMPTION_STANDARD start_date: '2019-10-01' end_date: '2019-11-01' number_of_units: 4.0 net_amount: 44.0 price_per_unit: 11.0 units: - 4.0 - 8.0 tax_items: - amount: 9.24 tax_type: VAT value_taxed: 44.0 rate: 0.21 unit_type: PROPORTION summary: Example payload required: true security: - DataImportViewerAPIKeyAuthentication: [] - DRFKrakenTokenAuthentication: [] responses: '400': content: application/json: schema: $ref: '#/components/schemas/BadCreateTransactionsRequest' examples: BadTransactionPayload: value: transactions: '0': reason: - Not a valid string. summary: Bad transaction payload ErrorCreatingTheTransaction: value: status: TRANSACTION_IMPORT_ERROR error_detail: 'UnableToCreateTransaction - 2019-09-28 of Payment #1 of 7100 on 2019-09-28 (ThirdParty) is not within the statement A-00000001 2019-10-01 - 2019-10-15 (OPEN) period' transaction_data: transaction_id: '1' transaction_date: '2019-09-28' amount: '71.00' type: PAYMENT reason: GENERAL_CREDIT reference: reference 1 payment_type: DEBIT_CARD summary: Error creating the transaction description: Could not create transactions '404': description: The account import process or account have not been found. To resolve the error, check that the account has been imported (not just staged) and that the `import_supplier code` and `external_account_number` are correct. '201': content: application/json: schema: $ref: '#/components/schemas/TransactionsCreated' examples: TransactionCreationResponseExample: value: results: - status: TRANSACTION_ALREADY_EXISTS transaction_data: transaction_id: '1' transaction_date: '2019-10-01' amount: '71.00' type: PAYMENT reason: GENERAL_CREDIT reference: reference 1 payment_type: DEBIT_CARD status: TRANSACTION_IMPORT_SUCCESS - status: TRANSACTION_ADDED_TO_ACCOUNT transaction_data: transaction_id: '2' transaction_date: '2019-10-04' amount: '180.00' type: PAYMENT reason: GENERAL_CREDIT reference: reference 2 payment_type: DEBIT_CARD summary: Transaction creation response example description: If the payload is valid, and there were no errors while importing the transactions, an object will be returned with a list of transactions that were passed in along with their creation statuses. x-doc-alerts: [] components: schemas: AusStatement: type: object properties: average_daily_usage: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,10})?$ description:

The average daily usage of the statement.

bill_period_from_date: type: string format: date description:

The statement start date (inclusive).

bill_period_to_date: type: string format: date description:

The statement end date (inclusive).

gross_amount: type: - integer - 'null' description:

The gross amount of the statement, in the lowest denomination for the currency.

is_reversed: type: boolean description:

Whether or not is reversed.

issued_date: type: - string - 'null' format: date description:

The date the statement was issued.

net_emissions: type: - array - 'null' items: $ref: '#/components/schemas/AusNetEmissions' description:

List of net emissions.

number: type: string description:

The external customer-facing statement number.

statement_id: type: string description:

The ID of the statement.

statement_path: type: string description:

The relative path in S3 of the statement PDF file.

x-validators: - name: Validate path exists in file store description: Validate that the given path corresponds to a file that has previously been uploaded to the migration file store. Note that this validation is disabled by default and can be enabled using the relevant feature flag. possible_errors: - path_does_not_exist_in_file_store total_consumption: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,10})?$ description:

The total consumption of the statement.

total_consumption_cost: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,10})?$ description:

The total consunption cost of the statement.

total_feed_in_cost: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,10})?$ description:

The total feed in cost of the statement.

total_feed_in_energy: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,10})?$ description:

The total feed in energy of the statement.

total_supply_cost: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,10})?$ description:

The total supply cost of the statement.

required: - bill_period_from_date - bill_period_to_date - statement_id x-validators: - name: null description: null possible_errors: - missing_statement_path_or_pdf_context - received_statement_path_and_pdf_context BadCreateTransactionsRequest: oneOf: - $ref: '#/components/schemas/NonFieldErrors' - $ref: '#/components/schemas/ErrorCreatingTransactions' CreatePaymentInstructionResponse: type: object properties: account_number: type: string description:

The account number in the source system. This, along with the import_supplier, will be used to find the account in Kraken.

maxLength: 128 kraken_account_number: type: string description:

The account number in the source system. This, along with the import_supplier, will be used to find the account in Kraken.

maxLength: 128 reference: type: string description:

The reference of the mandate as known by the vendor.

maxLength: 128 required: - account_number - kraken_account_number - reference Repayment: type: object properties: type: enum: - CHARGE - PAYMENT - REPAYMENT - CREDIT - SUPPLY_CHARGE type: string x-spec-enum-id: 06d6aba5cee32f9a description:

The type of the transaction.

x-enum-descriptions: CHARGE: Charge PAYMENT: Payment REPAYMENT: Repayment CREDIT: Credit SUPPLY_CHARGE: Supply Charge amount: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,10})?$ description:

The amount of the transaction. e.g. if the customer has a consumption charge worth 23.43, this equates to a transaction of type CHARGE of 23.43. Payments and repayments must be positive numbers. Generally charges and credits are also positive, but may be negative to represent reversed charges or credits, or if an incorrect estimated reading has resulted in a negative consumption charge. Provide this amount in the currency's major unit rather than its minor unit (for example euros rather than cents, or pounds rather than pence). These examples are illustrative only; the same applies to any currency that has a major and minor unit. For currencies without a minor unit, such as the Japanese yen, pass the value as-is.

billing_document_identifier: type: string description:

The identifier from the source system that groups a set of transactions together. This will be used in Kraken during the migration of historical statement transactions to create an archived billing document. For now this field is only required if HISTORICAL_STATEMENT_REQUIRE_SINGLE_BILLING_DOCUMENT_IDENTIFIER settings is ON and is meant for only historical_statements_transactions. Passing this to other transactions like current_statement_transactions or transactions_in_open_settlement_period will raise validation error.

display_note: type: string description:

The customer-facing note that can be displayed in a statement or email to the customer.

deprecated: true note: type: string description:

Any additional notes about the transaction.

payment_type: enum: - DIRECT_CREDIT - CARD_REFUND - BACS - CHEQUE - BPAY - '' type: string x-spec-enum-id: d2c4d6e823ed27aa description:

The payment type for the transaction.

x-enum-descriptions: DIRECT_CREDIT: DIRECT_CREDIT CARD_REFUND: CARD_REFUND BACS: BACS CHEQUE: CHEQUE BPAY: BPAY ? '' : '' reason: type: string description:

The reason for the transaction.

reference: type: string description:

The reference for the transaction. This could be an external id to help identify this transaction.

transaction_date: type: string format: date description:

The date of the transaction.

x-validators: - name: Validate transaction date description: Validates that the transaction date provided in the payload is not in the future. possible_errors: - transaction_in_future transaction_id: type: string description:

The unique internal identifier for the transaction.

required: - amount - transaction_date - transaction_id - type HistoricalStatements: type: object properties: external_account_number: type: string description:

The account number in the source system. This, along with the import_supplier, will be used to find the account in Kraken.

import_supplier: enum: - ORIGIN_SOLARFLEX_INACTIVE - ORIGIN - WIN_CONNECT_PARENT - ORIGIN_CNI - ORIGIN_BUSINESS - WIN_CONNECT - ORIGIN_SOLARFLEX - ORIGIN_BUSINESS_NO_CONTRACT type: string x-spec-enum-id: 9572ea198e3a9787 description:

The import supplier code that the account was imported on to. This, along with the external_account_number, will be used to find the account in Kraken.

x-enum-descriptions: ORIGIN_SOLARFLEX_INACTIVE: Origin SolarFlex Inactive ORIGIN: Origin WIN_CONNECT_PARENT: Win Connect Parent ORIGIN_CNI: Origin CNI ORIGIN_BUSINESS: Origin Zero Business Import Supplier WIN_CONNECT: WinConnect ORIGIN_SOLARFLEX: Origin SolarFlex ORIGIN_BUSINESS_NO_CONTRACT: Origin Business - No Contracts e.g. trustee statements: type: array items: $ref: '#/components/schemas/AusStatement' description:

List of historical statements for the account.

required: - external_account_number - import_supplier - statements x-validators: - name: Validate that account data is staged and account created description: Validate that an account exists for the external_account_number and import_supplier code. This means that the import data must already have been staged and processed into an account. possible_errors: - account_not_found - import_process_does_not_exist - name: Validate that migration is ongoing description: Validate whether or not an import supplier is open for further data migration. possible_errors: - import_supplier_migration_not_ongoing - name: Validate that the account doesn't have historical statements description: Validate the the historical statements that are being imported do not already exist on the account. To check this the statement_id's in the payload are checked against any historical statement IDs already associated with the account. possible_errors: - account_not_found - historical_statement_already_exists LegacyPaymentInstruction: type: object properties: external_account_number: type: string description:

The account number in the source system. This, along with the import_supplier, will be used to find the account in Kraken.

import_supplier: enum: - ORIGIN_SOLARFLEX_INACTIVE - ORIGIN - WIN_CONNECT_PARENT - ORIGIN_CNI - ORIGIN_BUSINESS - WIN_CONNECT - ORIGIN_SOLARFLEX - ORIGIN_BUSINESS_NO_CONTRACT type: string x-spec-enum-id: 9572ea198e3a9787 description:

The import supplier code that the account was imported on to. This, along with the external_account_number, will be used to find the account in Kraken.

x-enum-descriptions: ORIGIN_SOLARFLEX_INACTIVE: Origin SolarFlex Inactive ORIGIN: Origin WIN_CONNECT_PARENT: Win Connect Parent ORIGIN_CNI: Origin CNI ORIGIN_BUSINESS: Origin Zero Business Import Supplier WIN_CONNECT: WinConnect ORIGIN_SOLARFLEX: Origin SolarFlex ORIGIN_BUSINESS_NO_CONTRACT: Origin Business - No Contracts e.g. trustee instruction_reference: type: string description:

The reference of the mandate as known by the vendor.

deprecated: true x-use-instead: reference maxLength: 128 ledger_code: type: string description:

The code of the relevant Kraken ledger type for the payment instruction. This code must exist in Kraken.

x-validators: - name: Validate ledger code description: Validates that the ledger code provided in the payload matches an available ledger type in Kraken. possible_errors: - ledger_code_does_not_exist reference: type: string description:

The reference of the mandate as known by the vendor.

maxLength: 512 type: enum: - BPAY - CARD - CUSTOM - DIRECT_DEBIT - GMO_REFUND - PAYMENT_SLIP type: string x-spec-enum-id: 601d0b035869d4dd description:

The payment type of the payment instruction.

x-enum-descriptions: BPAY: BPAY CARD: Card CUSTOM: Custom DIRECT_DEBIT: Direct Debit GMO_REFUND: GMO Refund PAYMENT_SLIP: Payment slip use_for_scheduled_payments: type: - boolean - 'null' description:

Whether this payment instruction should be used for scheduled payments on a given ledger. If true, this instruction will be set as the payment method for the account's payment schedule.

valid_from: type: - string - 'null' format: date description:

The date from which the payment instruction is valid.

vendor: enum: - WESTPAC type: string x-spec-enum-id: 19baa89b6ef9d00c description:

The vendor for the payment instruction.

x-enum-descriptions: WESTPAC: Westpac required: - external_account_number - import_supplier - type - vendor x-validators: - name: Validate that account data is staged and account created description: Validate that an account exists for the external_account_number and import_supplier code. This means that the import data must already have been staged and processed into an account. possible_errors: - account_not_found - import_process_does_not_exist - name: Validate that migration is ongoing description: Validate whether or not an import supplier is open for further data migration. possible_errors: - import_supplier_migration_not_ongoing - name: Validate that either ⁨instruction_reference⁩ or ⁨reference⁩ are provided description: Validate that exactly one of ⁨instruction_reference⁩ or ⁨reference⁩ is provided. possible_errors: - mutually_exclusive_field_required NonFieldErrors: type: object properties: non_field_errors: type: array items: type: string description: Description of the error. description: Validation error messages. required: - non_field_errors NoteDocument: type: object properties: document_path: type: string description:

The S3 relative path to the document to be attached to the note.

x-validators: - name: Validate path exists in file store description: Validate that the given path corresponds to a file that has previously been uploaded to the migration file store. Note that this validation is disabled by default and can be enabled using the relevant feature flag. possible_errors: - path_does_not_exist_in_file_store required: - document_path TransactionData: oneOf: - $ref: '#/components/schemas/Credit' - $ref: '#/components/schemas/AusCharge' - $ref: '#/components/schemas/Payment' - $ref: '#/components/schemas/Repayment' - $ref: '#/components/schemas/OriginSupplyCharge' discriminator: propertyName: type mapping: CREDIT: '#/components/schemas/Credit' CHARGE: '#/components/schemas/AusCharge' PAYMENT: '#/components/schemas/Payment' REPAYMENT: '#/components/schemas/Repayment' SUPPLY_CHARGE: '#/components/schemas/OriginSupplyCharge' Transactions: type: object properties: account_number: type: string description:

The account number in the source system. This, along with the import_supplier, will be used to find the account in Kraken.

deprecated: true x-use-instead: external_account_number dry_run: type: boolean default: false description:

Whether to run the transactions creation process in dry-run mode. Running in dry-run mode will not create any transactions.

external_account_number: type: string description:

The account number in the source system. This, along with the import_supplier, will be used to find the account in Kraken.

import_supplier: enum: - ORIGIN_SOLARFLEX_INACTIVE - ORIGIN - WIN_CONNECT_PARENT - ORIGIN_CNI - ORIGIN_BUSINESS - WIN_CONNECT - ORIGIN_SOLARFLEX - ORIGIN_BUSINESS_NO_CONTRACT type: string x-spec-enum-id: 9572ea198e3a9787 description:

The import supplier code that the account was imported on to. This, along with the external_account_number, will be used to find the account in Kraken.

x-enum-descriptions: ORIGIN_SOLARFLEX_INACTIVE: Origin SolarFlex Inactive ORIGIN: Origin WIN_CONNECT_PARENT: Win Connect Parent ORIGIN_CNI: Origin CNI ORIGIN_BUSINESS: Origin Zero Business Import Supplier WIN_CONNECT: WinConnect ORIGIN_SOLARFLEX: Origin SolarFlex ORIGIN_BUSINESS_NO_CONTRACT: Origin Business - No Contracts e.g. trustee transactions: type: array items: $ref: '#/components/schemas/OriginTransaction' description:

A list of financial transactions to be imported onto the account.

required: - import_supplier x-validators: - name: Validate that account data is staged and account created description: Validate that an account exists for the external_account_number and import_supplier code. This means that the import data must already have been staged and processed into an account. possible_errors: - account_not_found - import_process_does_not_exist - name: Validate that migration is ongoing description: Validate whether or not an import supplier is open for further data migration. possible_errors: - import_supplier_migration_not_ongoing - name: Validate unique transaction IDs description: Validate that all transaction IDs provided are unique. possible_errors: - duplicate_transaction_ids - missing_transaction_id AusNetEmissions: type: object properties: from_time: type: string format: date-time description:

Net emission from time.

kg_co2_net_emissions: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,10})?$ description:

CO2 net emission in kg.

to_time: type: string format: date-time description:

Net emission to time.

required: - from_time - kg_co2_net_emissions - to_time x-validators: - name: Validate from time not after to time description: Validate that from time is not after to time. possible_errors: - from_time_not_after_to_time AccountNote: type: object properties: account_number: type: string description:

The account number in the source system. This, along with the import_supplier, will be used to find the account in Kraken.

deprecated: true x-use-instead: external_account_number external_account_number: type: string description:

The account number in the source system. This, along with the import_supplier, will be used to find the account in Kraken.

import_supplier: enum: - ORIGIN_SOLARFLEX_INACTIVE - ORIGIN - WIN_CONNECT_PARENT - ORIGIN_CNI - ORIGIN_BUSINESS - WIN_CONNECT - ORIGIN_SOLARFLEX - ORIGIN_BUSINESS_NO_CONTRACT type: string x-spec-enum-id: 9572ea198e3a9787 description:

The import supplier code that the account was imported on to. This, along with the external_account_number, will be used to find the account in Kraken.

x-enum-descriptions: ORIGIN_SOLARFLEX_INACTIVE: Origin SolarFlex Inactive ORIGIN: Origin WIN_CONNECT_PARENT: Win Connect Parent ORIGIN_CNI: Origin CNI ORIGIN_BUSINESS: Origin Zero Business Import Supplier WIN_CONNECT: WinConnect ORIGIN_SOLARFLEX: Origin SolarFlex ORIGIN_BUSINESS_NO_CONTRACT: Origin Business - No Contracts e.g. trustee notes: type: array items: $ref: '#/components/schemas/Note' description:

List of notes linked to the account. A note body or document_paths must be provided.

required: - import_supplier - notes x-validators: - name: Validate that account data is staged and account created description: Validate that an account exists for the external_account_number and import_supplier code. This means that the import data must already have been staged and processed into an account. possible_errors: - account_not_found - import_process_does_not_exist - name: Validate that migration is ongoing description: Validate whether or not an import supplier is open for further data migration. possible_errors: - import_supplier_migration_not_ongoing OriginLineItem: type: object properties: end_date: type: string format: date description:

The end date for the billing period, inclusive.

external_rate_identifier: type: string description:

The external identifier of the rate used to generate the charge for this line item. Only required if Kraken is configured to use placeholder rates when creating supply charge line items.

net_amount: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,10})?$ description:

Charge amount for the line item. Provide this amount in the currency's major unit rather than its minor unit (for example euros rather than cents, or pounds rather than pence). These examples are illustrative only; the same applies to any currency that has a major and minor unit. For currencies without a minor unit, such as the Japanese yen, pass the value as-is.

network_tariff_distributor_code: type: - string - 'null' description:

The distributor code identifying the network tariff library entry. Required when importing a supply charge line item backed by an NTL rate.

network_tariff_rate_code: type: - string - 'null' description:

The rate code identifying the specific rate within the network tariff. Must match a READY_TO_BILL rate whose effective period covers the line item period.

network_tariff_tariff_code: type: - string - 'null' description:

The tariff code identifying the network tariff library entry. Required when importing a supply charge line item backed by an NTL rate.

number_of_units: type: string format: decimal pattern: ^-?\d{0,12}(?:\.\d{0,4})?$ description:

E.g. cubic meters consumed for the period, days on supply for fixed charges or RV proportion for period for unmetered RV charges.

params: type: object description: "

Additional parameters for the line item.

\n

Specify the following keys to control line item charge targets:

\n

\n

\n

" x-validators: - name: Validate supply charge target description: Validate that the supply charge target are supplied correctly in params. possible_errors: - invalid_charge_target_type price_per_unit: type: string format: decimal pattern: ^-?\d{0,8}(?:\.\d{0,7})?$ description:

Price per unit for the line item. If this is not provided, then the price per unit from the relevant product rate will be used instead. Provide this amount in the currency's major unit rather than its minor unit (for example euros rather than cents, or pounds rather than pence). These examples are illustrative only; the same applies to any currency that has a major and minor unit. For currencies without a minor unit, such as the Japanese yen, pass the value as-is.

rate_band: type: string description:

Rate of the product this charge is for. Must match an existing rate of a product product_code. Rate must be active from start_date to end_date.

rate_specification_code: type: string description:

Rate specification code of the product this charge is for. This code must refer to an existing rate specification within the product.

start_date: type: string format: date description:

The start date for the billing period, inclusive.

time_series_specification_code: type: string description:

Time series specification code.

units: type: array items: type: string format: decimal pattern: ^-?\d{0,12}(?:\.\d{0,4})?$ description:

For metered accounts only. List of decimal numbers representing the meter readings for the billing period.

x-validators: - name: Validate line item units description: Validates that the line item units provided in the payload is a list of two items only. possible_errors: - line_item_units_must_be_two_values required: - end_date - net_amount - number_of_units - params - start_date x-validators: - name: Validate ⁨end_date⁩ not before ⁨start_date⁩ description: Validates that ⁨end_date⁩, if given, is on or later than ⁨start_date⁩. possible_errors: - start_date_later_than_end_date - name: Validate the line item net amount description: Validate that the line item net amount is equal to the price per unit multiplied by the number of units. possible_errors: - incorrect_line_item_net_amount - name: Ensure that the band or rate specification or time series specification for a line item is specified. description: Validate line items include exactly one of rate_band, rate_specification_code, or time_series_specification_code. possible_errors: - conflicting_rate_band_specification CreateAccountNotesResponse: type: object properties: body: type: string description:

The body of the note. Should include who/what created the note if this is required.

created_at: type: string format: date-time description:

The date and time the note was created.

document_paths: type: array items: $ref: '#/components/schemas/NoteDocument' description:

A list of relative paths in S3 for documents to be attached to the note.

More details on document path parameters can be found here.

external_id: type: string description:

Unique identifier for this note to avoid duplicate entries.

is_archived: type: boolean description:

If set to true, this will archive the note in the Kraken account support site page.

is_pinned: type: boolean description:

If set to true, this will pin the note to the top of the Kraken account support site page.

status: enum: - NOTE_CREATION_SUCCESS - NOTE_ALREADY_EXISTS type: string x-spec-enum-id: 31aeae5ed4ff8531 description:

The creation status for each note attempted to be imported.

x-enum-descriptions: NOTE_CREATION_SUCCESS: The note has been successfully created. NOTE_ALREADY_EXISTS: A similar note has been found preventing the creation of a new note. unpin_at: type: string format: date-time description:

When the pinned note should be unpinned. Has to be later than created_at if this is provided. Has no effect if the note is not pinned.

required: - status x-validators: - name: Validate note body or document paths provided description: Validate that at least a note body or document paths are provided. possible_errors: - note_body_or_document_path_not_found - name: Validate note created at is equal to or before unpin at description: Validate that the note's created at date is equal to or before the unpin at date if both are provided. possible_errors: - note_unpin_at_earlier_than_creation_date OriginSupplyCharge: type: object properties: type: enum: - CHARGE - PAYMENT - REPAYMENT - CREDIT - SUPPLY_CHARGE type: string x-spec-enum-id: 06d6aba5cee32f9a description:

The type of the transaction.

x-enum-descriptions: CHARGE: Charge PAYMENT: Payment REPAYMENT: Repayment CREDIT: Credit SUPPLY_CHARGE: Supply Charge amount: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,10})?$ description:

The amount of the transaction. e.g. if the customer has a consumption charge worth 23.43, this equates to a transaction of type CHARGE of 23.43. Payments and repayments must be positive numbers. Generally charges and credits are also positive, but may be negative to represent reversed charges or credits, or if an incorrect estimated reading has resulted in a negative consumption charge. Provide this amount in the currency's major unit rather than its minor unit (for example euros rather than cents, or pounds rather than pence). These examples are illustrative only; the same applies to any currency that has a major and minor unit. For currencies without a minor unit, such as the Japanese yen, pass the value as-is.

billing_document_identifier: type: string description:

The identifier from the source system that groups a set of transactions together. This will be used in Kraken during the migration of historical statement transactions to create an archived billing document. For now this field is only required if HISTORICAL_STATEMENT_REQUIRE_SINGLE_BILLING_DOCUMENT_IDENTIFIER settings is ON and is meant for only historical_statements_transactions. Passing this to other transactions like current_statement_transactions or transactions_in_open_settlement_period will raise validation error.

display_note: type: string description:

The customer-facing note that can be displayed in a statement or email to the customer.

line_items: type: array items: $ref: '#/components/schemas/OriginLineItem' description:

For SUPPLY_CHARGE transactions only, line items contain details about the charge, e.g. standing/consumption charge, billing period, number of units etc.

note: type: string description:

Any additional notes about the transaction.

product_code: type: string description:

The product code for the product that the transaction is associated with.

x-validators: - name: Validate product code exists description: Validate that the product code exists in Kraken. possible_errors: - product_code_does_not_exist supply_point_identifier: type: string description:

Supply point identifier associated with the supply point this charge applies to.

tax_items: type: array items: $ref: '#/components/schemas/TaxItem' description:

For SUPPLY_CHARGE and CHARGE transactions only, tax items contain details about the tax. If not provided will be set to default zero tax.

transaction_date: type: string format: date description:

The date of the transaction.

x-validators: - name: Validate transaction date description: Validates that the transaction date provided in the payload is not in the future. possible_errors: - transaction_in_future transaction_id: type: string description:

The unique internal identifier for the transaction.

required: - amount - line_items - product_code - transaction_date - transaction_id - type x-validators: - name: Validates supply charge line item rate description: This validation only applies to transactions of type supply charge. Validates that product code is provided and a product exists with that code. Validates that line items are provided and each line item rate band exists for the product. possible_errors: [] - name: Validate that the given price per unit matches an existing rate price per unit description: Validate that the given price per unit matches an existing rate price per unit. If the existing rate is a dynamic rate (i.e. it has a NaN price per unit), then there must be a price per unit in the payload. possible_errors: [] - name: Validate line item number of units description: Validate that the line item number of units matches the number of days in the period provided for standing charges. possible_errors: [] - name: Validate that the total transaction amount is correct description: Ensure that the total line items amount matches transaction amount. possible_errors: - ledger_transaction_amount_does_not_match_with_line_item_net_amount_and_tax_amount - name: Ensure supply point identifier is provided when line items use rate_specification_code description: Validate that supply_point_identifier is provided when any line item contains a rate_specification_code, as the supply point is required for rate resolution. possible_errors: - supply_point_identifier_required_for_rate_specification_code - name: Validate that the line items do not overlap with any already charged periods description: Validate that the line item periods do not overlap with any already charged periods for a supply point. possible_errors: - line_items_overlap_already_charged_period OriginTransaction: oneOf: - $ref: '#/components/schemas/Credit' - $ref: '#/components/schemas/AusCharge' - $ref: '#/components/schemas/Payment' - $ref: '#/components/schemas/Repayment' - $ref: '#/components/schemas/OriginSupplyCharge' discriminator: propertyName: type mapping: CREDIT: '#/components/schemas/Credit' CHARGE: '#/components/schemas/AusCharge' PAYMENT: '#/components/schemas/Payment' REPAYMENT: '#/components/schemas/Repayment' SUPPLY_CHARGE: '#/components/schemas/OriginSupplyCharge' TransactionsCreated: type: object properties: results: type: array items: $ref: '#/components/schemas/TransactionAnnotatedWithStatus' description:

The response when the transaction was created successfully.

required: - results Note: type: object properties: body: type: string description:

The body of the note. Should include who/what created the note if this is required.

created_at: type: string format: date-time description:

The date and time the note was created.

document_paths: type: array items: $ref: '#/components/schemas/NoteDocument' description:

A list of relative paths in S3 for documents to be attached to the note.

More details on document path parameters can be found here.

external_id: type: string description:

Unique identifier for this note to avoid duplicate entries.

is_archived: type: boolean description:

If set to true, this will archive the note in the Kraken account support site page.

is_pinned: type: boolean description:

If set to true, this will pin the note to the top of the Kraken account support site page.

unpin_at: type: string format: date-time description:

When the pinned note should be unpinned. Has to be later than created_at if this is provided. Has no effect if the note is not pinned.

x-validators: - name: Validate note body or document paths provided description: Validate that at least a note body or document paths are provided. possible_errors: - note_body_or_document_path_not_found - name: Validate note created at is equal to or before unpin at description: Validate that the note's created at date is equal to or before the unpin at date if both are provided. possible_errors: - note_unpin_at_earlier_than_creation_date CreatePaymentInstructionError: type: object properties: error_detail: type: string description:

If payment instruction creation failed, then this field will provide details of the error.

external_account_number: type: string description:

The account number in the source system. This, along with the import_supplier, will be used to find the account in Kraken.

import_supplier: enum: - ORIGIN_SOLARFLEX_INACTIVE - ORIGIN - WIN_CONNECT_PARENT - ORIGIN_CNI - ORIGIN_BUSINESS - WIN_CONNECT - ORIGIN_SOLARFLEX - ORIGIN_BUSINESS_NO_CONTRACT type: string x-spec-enum-id: 9572ea198e3a9787 description:

The import supplier code that the account was imported on to. This, along with the external_account_number, will be used to find the account in Kraken.

x-enum-descriptions: ORIGIN_SOLARFLEX_INACTIVE: Origin SolarFlex Inactive ORIGIN: Origin WIN_CONNECT_PARENT: Win Connect Parent ORIGIN_CNI: Origin CNI ORIGIN_BUSINESS: Origin Zero Business Import Supplier WIN_CONNECT: WinConnect ORIGIN_SOLARFLEX: Origin SolarFlex ORIGIN_BUSINESS_NO_CONTRACT: Origin Business - No Contracts e.g. trustee reference: type: string description:

The reference of the mandate as known by the vendor.

maxLength: 128 required: - error_detail - external_account_number - import_supplier - reference x-validators: - name: Validate that account data is staged and account created description: Validate that an account exists for the external_account_number and import_supplier code. This means that the import data must already have been staged and processed into an account. possible_errors: - account_not_found - import_process_does_not_exist - name: Validate that migration is ongoing description: Validate whether or not an import supplier is open for further data migration. possible_errors: - import_supplier_migration_not_ongoing Payment: type: object properties: type: enum: - CHARGE - PAYMENT - REPAYMENT - CREDIT - SUPPLY_CHARGE type: string x-spec-enum-id: 06d6aba5cee32f9a description:

The type of the transaction.

x-enum-descriptions: CHARGE: Charge PAYMENT: Payment REPAYMENT: Repayment CREDIT: Credit SUPPLY_CHARGE: Supply Charge amount: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,10})?$ description:

The amount of the transaction. e.g. if the customer has a consumption charge worth 23.43, this equates to a transaction of type CHARGE of 23.43. Payments and repayments must be positive numbers. Generally charges and credits are also positive, but may be negative to represent reversed charges or credits, or if an incorrect estimated reading has resulted in a negative consumption charge. Provide this amount in the currency's major unit rather than its minor unit (for example euros rather than cents, or pounds rather than pence). These examples are illustrative only; the same applies to any currency that has a major and minor unit. For currencies without a minor unit, such as the Japanese yen, pass the value as-is.

billing_document_identifier: type: string description:

The identifier from the source system that groups a set of transactions together. This will be used in Kraken during the migration of historical statement transactions to create an archived billing document. For now this field is only required if HISTORICAL_STATEMENT_REQUIRE_SINGLE_BILLING_DOCUMENT_IDENTIFIER settings is ON and is meant for only historical_statements_transactions. Passing this to other transactions like current_statement_transactions or transactions_in_open_settlement_period will raise validation error.

display_note: type: string description:

The customer-facing note that can be displayed in a statement or email to the customer.

deprecated: true note: type: string description:

Any additional notes about the transaction.

payment_type: enum: - DD_FIRST_COLLECTION - DD_REGULAR_COLLECTION - DD_RE_PRESENTATION - DD_FINAL_COLLECTION - CREDIT_CARD - DEBIT_CARD - CHEQUE - BACS_DEPOSIT - ALLPAY_CASH - ALLPAY_CARD - ALLPAY_CHEQUE - PAYPOINT_CASH - PAYPOINT_CARD - PAYPOINT_CHEQUE - DCA_COLLECTION - BRISTOL_POUND - CASH - FUEL_DIRECT - BPAY - AUSTRALIA_POST - HEEA - HEEAS - CENTREPAY - EAPA_VOUCHER - URGS - BPOINT - EFT - ERRONEOUS_PAYMENT - PAYZONE - POST_OFFICE_CASH - POST_OFFICE_CARD - POST_OFFICE_CHEQUE - POST_OFFICE_SAVINGS_STAMPS - KONBINI - '' type: string x-spec-enum-id: e5c2d3475e079058 description:

The payment type for the transaction.

x-enum-descriptions: DD_FIRST_COLLECTION: DD_FIRST_COLLECTION DD_REGULAR_COLLECTION: DD_REGULAR_COLLECTION DD_RE_PRESENTATION: DD_RE_PRESENTATION DD_FINAL_COLLECTION: DD_FINAL_COLLECTION CREDIT_CARD: CREDIT_CARD DEBIT_CARD: DEBIT_CARD CHEQUE: CHEQUE BACS_DEPOSIT: BACS_DEPOSIT ALLPAY_CASH: ALLPAY_CASH ALLPAY_CARD: ALLPAY_CARD ALLPAY_CHEQUE: ALLPAY_CHEQUE PAYPOINT_CASH: PAYPOINT_CASH PAYPOINT_CARD: PAYPOINT_CARD PAYPOINT_CHEQUE: PAYPOINT_CHEQUE DCA_COLLECTION: DCA_COLLECTION BRISTOL_POUND: BRISTOL_POUND CASH: CASH FUEL_DIRECT: FUEL_DIRECT BPAY: BPAY AUSTRALIA_POST: AUSTRALIA_POST HEEA: HEEA HEEAS: HEEAS CENTREPAY: CENTREPAY EAPA_VOUCHER: EAPA_VOUCHER URGS: URGS BPOINT: BPOINT EFT: EFT ERRONEOUS_PAYMENT: ERRONEOUS_PAYMENT PAYZONE: PAYZONE POST_OFFICE_CASH: POST_OFFICE_CASH POST_OFFICE_CARD: POST_OFFICE_CARD POST_OFFICE_CHEQUE: POST_OFFICE_CHEQUE POST_OFFICE_SAVINGS_STAMPS: POST_OFFICE_SAVINGS_STAMPS KONBINI: Konbini ? '' : '' reason: type: string description:

The reason for the transaction.

reference: type: string description:

The reference for the transaction. This could be an external id to help identify this transaction.

transaction_date: type: string format: date description:

The date of the transaction.

x-validators: - name: Validate transaction date description: Validates that the transaction date provided in the payload is not in the future. possible_errors: - transaction_in_future transaction_id: type: string description:

The unique internal identifier for the transaction.

required: - amount - transaction_date - transaction_id - type Credit: type: object properties: type: enum: - CHARGE - PAYMENT - REPAYMENT - CREDIT - SUPPLY_CHARGE type: string x-spec-enum-id: 06d6aba5cee32f9a description:

The type of the transaction.

x-enum-descriptions: CHARGE: Charge PAYMENT: Payment REPAYMENT: Repayment CREDIT: Credit SUPPLY_CHARGE: Supply Charge amount: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,10})?$ description:

The amount of the transaction. e.g. if the customer has a consumption charge worth 23.43, this equates to a transaction of type CHARGE of 23.43. Payments and repayments must be positive numbers. Generally charges and credits are also positive, but may be negative to represent reversed charges or credits, or if an incorrect estimated reading has resulted in a negative consumption charge. Provide this amount in the currency's major unit rather than its minor unit (for example euros rather than cents, or pounds rather than pence). These examples are illustrative only; the same applies to any currency that has a major and minor unit. For currencies without a minor unit, such as the Japanese yen, pass the value as-is.

billing_document_identifier: type: string description:

The identifier from the source system that groups a set of transactions together. This will be used in Kraken during the migration of historical statement transactions to create an archived billing document. For now this field is only required if HISTORICAL_STATEMENT_REQUIRE_SINGLE_BILLING_DOCUMENT_IDENTIFIER settings is ON and is meant for only historical_statements_transactions. Passing this to other transactions like current_statement_transactions or transactions_in_open_settlement_period will raise validation error.

display_note: type: string description:

The customer-facing note that can be displayed in a statement or email to the customer.

note: type: string description:

Any additional notes about the transaction.

reason: type: string description:

The reason for the transaction.

transaction_date: type: string format: date description:

The date of the transaction.

x-validators: - name: Validate transaction date description: Validates that the transaction date provided in the payload is not in the future. possible_errors: - transaction_in_future transaction_id: type: string description:

The unique internal identifier for the transaction.

required: - amount - transaction_date - transaction_id - type AusCharge: type: object properties: type: enum: - CHARGE - PAYMENT - REPAYMENT - CREDIT - SUPPLY_CHARGE type: string x-spec-enum-id: 06d6aba5cee32f9a description:

The type of the transaction.

x-enum-descriptions: CHARGE: Charge PAYMENT: Payment REPAYMENT: Repayment CREDIT: Credit SUPPLY_CHARGE: Supply Charge amount: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,10})?$ description:

The amount of the transaction. e.g. if the customer has a consumption charge worth 23.43, this equates to a transaction of type CHARGE of 23.43. Payments and repayments must be positive numbers. Generally charges and credits are also positive, but may be negative to represent reversed charges or credits, or if an incorrect estimated reading has resulted in a negative consumption charge. Provide this amount in the currency's major unit rather than its minor unit (for example euros rather than cents, or pounds rather than pence). These examples are illustrative only; the same applies to any currency that has a major and minor unit. For currencies without a minor unit, such as the Japanese yen, pass the value as-is.

billing_document_identifier: type: string description:

The identifier from the source system that groups a set of transactions together. This will be used in Kraken during the migration of historical statement transactions to create an archived billing document. For now this field is only required if HISTORICAL_STATEMENT_REQUIRE_SINGLE_BILLING_DOCUMENT_IDENTIFIER settings is ON and is meant for only historical_statements_transactions. Passing this to other transactions like current_statement_transactions or transactions_in_open_settlement_period will raise validation error.

display_note: type: string description:

The customer-facing note that can be displayed in a statement or email to the customer.

note: type: string description:

Any additional notes about the transaction.

reason: type: string description:

The reason for the transaction.

tax_items: type: array items: $ref: '#/components/schemas/TaxItem' description:

For SUPPLY_CHARGE and CHARGE transactions only, tax items contain details about the tax. If not provided will be set to default zero tax.

transaction_date: type: string format: date description:

The date of the transaction.

x-validators: - name: Validate transaction date description: Validates that the transaction date provided in the payload is not in the future. possible_errors: - transaction_in_future transaction_id: type: string description:

The unique internal identifier for the transaction.

required: - amount - transaction_date - transaction_id - type ErrorCreatingTransactions: type: object properties: error_detail: type: string description:

If transaction creation failed, then this field will provide details of the error.

status: enum: - TRANSACTION_ADDED_TO_ACCOUNT - TRANSACTION_ALREADY_EXISTS - TRANSACTION_IMPORT_ERROR type: string x-spec-enum-id: 5a92d022962e1cea description:

The status of the transaction.

x-enum-descriptions: TRANSACTION_ADDED_TO_ACCOUNT: Transaction added to account TRANSACTION_ALREADY_EXISTS: Transaction already exists TRANSACTION_IMPORT_ERROR: Transaction import error transaction_data: allOf: - $ref: '#/components/schemas/TransactionData' description:

The data associated with the transaction that caused this error.

required: - error_detail - status - transaction_data TransactionAnnotatedWithStatus: type: object properties: added_transaction_id: type: integer description:

The transaction id.

status: enum: - TRANSACTION_ADDED_TO_ACCOUNT - TRANSACTION_ALREADY_EXISTS - TRANSACTION_IMPORT_ERROR type: string x-spec-enum-id: 5a92d022962e1cea description:

The status of the transaction.

x-enum-descriptions: TRANSACTION_ADDED_TO_ACCOUNT: Transaction added to account TRANSACTION_ALREADY_EXISTS: Transaction already exists TRANSACTION_IMPORT_ERROR: Transaction import error transaction_data: allOf: - $ref: '#/components/schemas/TransactionData' description:

The data associated with the transaction that caused this error.

required: - status - transaction_data TaxItem: type: object properties: amount: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,10})?$ description:

The amount of tax. Provide this amount in the currency's major unit rather than its minor unit (for example euros rather than cents, or pounds rather than pence). These examples are illustrative only; the same applies to any currency that has a major and minor unit. For currencies without a minor unit, such as the Japanese yen, pass the value as-is.

params: type: object default: {} description:

Additional parameters for the tax item.

rate: type: string format: decimal pattern: ^-?\d{0,15}(?:\.\d{0,5})?$ description:

The rate at which tax has been applied.

tax_type: type: string description:

The type of tax.

unit_type: enum: - PROPORTION - CURRENCY_PER_KWH type: string x-spec-enum-id: c3c821f5b0c08a37 description:

The tax unit type.

x-enum-descriptions: PROPORTION: Proportion CURRENCY_PER_KWH: Currency Per Kwh value_taxed: type: string format: decimal pattern: ^-?\d{0,15}(?:\.\d{0,5})?$ description:

The value that the tax is applied to.

required: - amount - rate - tax_type - unit_type - value_taxed securitySchemes: DRFKrakenTokenAuthentication: type: apiKey in: header name: Authorization description: JWT-based authentication DataImportViewerAPIKeyAuthentication: type: apiKey in: header name: Authorization description: Token-based authentication with required prefix "Token "