openapi: 3.0.3 info: title: Kraken version: v1 paths: /v2/orders/: post: operationId: V2 Schedule Order description: Use this endpoint to schedule the placement of an order in Kraken. It accepts a request containing the necessary information for order placement, validates the data, and creates an order management task to be executed asynchronously. summary: Schedule the placement of an order in Kraken tags: - orders requestBody: content: application/json: schema: $ref: '#/components/schemas/ScheduleOrder' examples: ExamplePayload: value: external_order_id: ORD-12345678 accounts: - type: EXISTING account_identifier: acc-ref-001 account_number: A-12345678 businesses: - type: EXISTING business_identifier: biz-ref-001 company_name: Tentacle Corp company_number: '12345678' business_type: LTD order_lines: - type: CONTRACT_RENEWAL target_type: BUSINESS target_reference: biz-ref-001 contract: identifier: contract-001 valid_from_date: '2026-01-01' signed_at_date: '2025-12-15' valid_to_date: '2027-01-01' versions: [] subjects: - type: ACCOUNT identifier: acc-ref-001 summary: Example payload required: true security: - DataImportViewerAPIKeyAuthentication: [] - DRFKrakenTokenAuthentication: [] responses: '201': description: The payload has been successfully scheduled. '400': content: application/json: schema: $ref: '#/components/schemas/StandardizedValidationErrorResponse' examples: ScheduleOrderValidationErrorResponse: value: code: order_process_failed_validation detail: Order payload validation failed. domain: order_process summary: Schedule order validation error response description: If there are validation errors, a 400 Bad Request response will be returned detailing the errors. To resolve these errors, refer to the field definitions and validation rules. ScheduleOrderErrorResponse: value: non_field_errors: detail: The order with external order ID ORD-12345678 has already been processed. code: order_process_already_processed summary: Schedule order error response description: If an order has already been processed, a 400 Bad Request response will be returned. description: Validation errors occurred while processing the request. x-doc-alerts: [] /v2/orders/{external_order_id}/: get: operationId: V2 Order Status description: Use this endpoint to retrieve the current status of an order. The order is identified by its external_order_id. summary: Return the status of an order process parameters: - in: path name: external_order_id schema: type: string required: true tags: - orders security: - DataImportViewerAPIKeyAuthentication: [] - DRFKrakenTokenAuthentication: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ImportStatusResponse' examples: OrderStatusSuccessResponse(processed): value: status: PROCESSED created_at: '2025-04-17T00:00:00Z' modified_at: '2025-04-17T01:00:00Z' latest_error: null latest_event: event: ORDER_PROCESS_SUCCEEDED occurred_at: '2025-04-17T01:00:00Z' data: null summary: Order status success response (processed) description: A successful response for an order that has been processed. OrderStatusSuccessResponse(errored): value: status: ERRORED created_at: '2025-04-17T00:00:00Z' modified_at: '2025-04-17T01:30:00Z' latest_error: code: validation_error detail: Account number is invalid domain: accounts latest_event: event: ORDER_PROCESS_ERRORED occurred_at: '2025-04-17T01:30:00Z' data: code: validation_error detail: Account number is invalid domain: accounts summary: Order status success response (errored) description: A successful response for an order that has errored during processing. description: The status of the order. '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: OrderNotFoundResponse: value: detail: The requested resource was not found. code: not_found summary: Order not found response description: Returned when no order process exists for the given external_order_id. description: Order not found for the given external_order_id. '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: InvalidOrderProcessStatusResponse: value: detail: 'Order process has no status set for external_order_id: example-order-id' code: invalid_status_for_order_process summary: Invalid order process status response description: Returned when the order process has an invalid or missing status. description: The order process has an invalid or missing status. x-doc-alerts: [] components: schemas: AccountReference: type: object properties: namespace: type: string description:

The namespace refers to the particular context the reference exists in. For example, tentacle-energy.allpay-client-reference-numbers.

maxLength: 50 x-validators: - name: Validate account reference namespace description: Validate that the account reference namespace matches an available account reference namespace in Kraken. possible_errors: - invalid_reference_namespace value: type: string description:

The unique identifier for the account.

maxLength: 100 required: - namespace - value x-validators: - name: Validate account reference does not already exist description: Validate that the account reference does not already exist for any account in Kraken. possible_errors: - reference_already_exists Address: type: object properties: administrative_area: type: string default: '' description:

The top-level administrative subdivision. For example a US state, Australian state/territory, Italian region, UK constituent nation or Japanese prefecture.

maxLength: 512 country: type: string description:

The ISO 3166-1-alpha-2 code of the country that this address belongs to, for example AU (Australia) or GB (Great Britain).

maxLength: 2 delivery_point_identifier: type: string description:

The unique country specific identifier for an address. For example the UPRN in the UK or G-NAF ID in Australia.

maxLength: 11 x-validators: - name: Validate delivery point identifier description: Validate that the delivery point identifier contains only capital letters and numbers. possible_errors: - invalid_delivery_point_identifier dependent_locality: type: string default: '' description:

Dependent localities, neighbourhoods or boroughs. These are sometimes included in an address when the delivery point is outside the boundary of the main postal town that serves it.

maxLength: 512 locality: type: string default: '' description:

The city/town portion of an address. For example a US city, Australian suburb/town, Italian comune or UK postal town.

maxLength: 512 name: type: string default: '' description:

The recipient's name.

deprecated: true organization: type: string default: '' description:

The company or organization to which the address belongs.

deprecated: true postal_code: type: string default: '' description:

The code assigned to a geographical area representing a group of addresses. For example a US ZIP code, Australian postcode, Italian CAP code or UK postcode.

maxLength: 512 sorting_code: type: string default: '' description:

This is a non-geographic code used for recipients of large quantities of post, such as companies or government departments. An example is the French CEDEX code.

maxLength: 512 street_address: type: string default: '' description:

Free text field for the address. Either this field or the structured_address field should be provided, not both.

structured_street_address: type: object nullable: true description:

Structured address object. Fields for this object are territory dependent. Please speak to the tech team about uses of this field. Either this field or the street_address should be provided, not both.

required: - country x-validators: - name: Validate and normalize postcode description: Validate the postal code and normalize it to a standard format. possible_errors: - invalid_postcode - name: Validate address description: Validate that the address is in the correct format. possible_errors: - invalid_address AgreementIntermediaryDetails: type: object properties: external_id: type: string nullable: true description:

An external identifier for the intermediary relationship. This can be used to store a reference to this relationship in an external system (e.g., the source system during migration).

maxLength: 255 portfolio_number: type: string description:

The number of the intermediary portfolio to link this agreement to. The portfolio must exist before creating the agreement.

x-validators: - name: Validate the portfolio number description: Validate that the portfolio number matches the expected format (P- followed by 8 uppercase alphanumeric characters). possible_errors: - invalid_portfolio_number required: - portfolio_number AusAgreementAddOn: type: object properties: code: type: string description:

Code for addon that must have been configured for the product in kraken.

x-validators: - name: data-import--validation--contract-addon-has-valid-code--display-name description: data-import--validation--contract-addon-has-valid-code--help-text possible_errors: - addon_code_not_found required: - code AusEEPAExportContractedVolumeConfiguration: type: object properties: term_type: type: string description:

The type of the contract term.

is_variable: type: boolean default: true description:

Whether the contract term is variable in Kraken or not. If not, it must be amended by a new contract.

periods: type: array items: $ref: '#/components/schemas/AusEEPAExportContractedVolumePeriod' description:

A list of EEPA export contracted volume periods.

minItems: 1 x-validators: - name: Validate EEPA export contracted volume periods description: 'Validate that the EEPA export contracted volume periods form a valid term: no overlapping general periods, and no supply point repeated across overlapping periods.' possible_errors: - invalid_eepa_export_contracted_volume required: - periods - term_type AusEEPAExportContractedVolumePeriod: type: object properties: supply_point_external_identifiers: type: array items: type: string nullable: true description:

The external identifiers (NMIs) of the supply points this period applies to. Leave null to apply to all supply points not covered by a more specific period; when provided the list must not be empty.

minItems: 1 unit: type: string description:

The unit for the contracted export volume (e.g. kWh).

valid_from_date: type: string format: date description:

The date the period is valid from (inclusive).

valid_to_date: type: string format: date description:

The date the period is valid to (exclusive; the period ends before this date).

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

The contracted export volume cap for the period.

required: - supply_point_external_identifiers - unit - valid_from_date - valid_to_date - value x-validators: - name: Convert supply point external identifiers to IDs description: Convert each supply point external identifier (NMI) to the internal supply point ID by looking up the supply point in the database. A null value is left unchanged and applies the period to all supply points. possible_errors: - supply_point_not_found - name: Validate ⁨valid_to⁩ not before ⁨valid_from⁩ description: Validates that ⁨valid_to⁩, if given, is on or later than ⁨valid_from⁩. possible_errors: - start_date_later_than_end_date AusElectricityAgreement: type: object properties: market_name: enum: - AUS_ELECTRICITY type: string x-spec-enum-id: 497cd6e4782e8889 description:

The market name of the supply point.

x-enum-descriptions: AUS_ELECTRICITY: AUS_ELECTRICITY account_reference: type: string description:

The identifier of the account that owns this supply point. Must match one of the contract's subject accounts.

agreed_at: type: string format: date-time nullable: true description:

The datetime the agreement was agreed at.

business_contract_identifier: type: string nullable: true description:

The identifier of the business contract this agreement should be linked to.

characteristics: type: array items: $ref: '#/components/schemas/ProductCharacteristic' nullable: true description:

Characteristics of the agreed product that the customer has chosen.

x-validators: - name: Validate that each child has unique values for the ⁨code⁩ field description: Validate that each child has unique values for the ⁨code⁩ field. possible_errors: - children_with_duplicate_values effective_from: type: string format: date description:

The date from which the agreement is effective (inclusive), i.e. the agreement starts on the midnight of this date, such that this date becomes the first day covered by this agreement.

effective_to: type: string format: date nullable: true description:

The date to which the agreement is effective (exclusive), i.e. the agreement will end on the midnight of this date, such that the previous day is the last day covered by this agreement.

intermediary: allOf: - $ref: '#/components/schemas/AgreementIntermediaryDetails' nullable: true description:

Details about the intermediary relationship for this agreement. When provided, an intermediary link will be created between the agreement and the portfolio, establishing a business intermediary relationship.

product_addons: type: array items: $ref: '#/components/schemas/AusAgreementAddOn' nullable: true description:

A list of product addons that apply to the specific agreement.

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

Agreement rate overrides.

rates_agreed_at: type: string format: date-time nullable: true description:

The datetime the rates were agreed at.

supply_point_identifier: type: string description:

The identifier of the supply point to add the agreement to.

tariff_code: type: string description:

The code for the agreement tariff. Must match an existing tariff code of an active product.

x-validators: - name: Validate product code exists description: Validate that the product code exists in Kraken. possible_errors: - product_code_does_not_exist required: - account_reference - effective_from - market_name - supply_point_identifier - tariff_code x-validators: - name: Validate ⁨effective_to⁩ not before ⁨effective_from⁩ description: Validates that ⁨effective_to⁩, if given, is on or later than ⁨effective_from⁩. possible_errors: - start_date_later_than_end_date AusEmbeddedElectricityAgreement: type: object properties: market_name: enum: - AUS_EMBEDDED_ELECTRICITY type: string x-spec-enum-id: eaeb85db1513ab66 description:

The market name of the supply point.

x-enum-descriptions: AUS_EMBEDDED_ELECTRICITY: AUS_EMBEDDED_ELECTRICITY account_reference: type: string description:

The identifier of the account that owns this supply point. Must match one of the contract's subject accounts.

agreed_at: type: string format: date-time nullable: true description:

The datetime the agreement was agreed at.

business_contract_identifier: type: string nullable: true description:

The identifier of the business contract this agreement should be linked to.

characteristics: type: array items: $ref: '#/components/schemas/ProductCharacteristic' nullable: true description:

Characteristics of the agreed product that the customer has chosen.

x-validators: - name: Validate that each child has unique values for the ⁨code⁩ field description: Validate that each child has unique values for the ⁨code⁩ field. possible_errors: - children_with_duplicate_values effective_from: type: string format: date description:

The date from which the agreement is effective (inclusive), i.e. the agreement starts on the midnight of this date, such that this date becomes the first day covered by this agreement.

effective_to: type: string format: date nullable: true description:

The date to which the agreement is effective (exclusive), i.e. the agreement will end on the midnight of this date, such that the previous day is the last day covered by this agreement.

intermediary: allOf: - $ref: '#/components/schemas/AgreementIntermediaryDetails' nullable: true description:

Details about the intermediary relationship for this agreement. When provided, an intermediary link will be created between the agreement and the portfolio, establishing a business intermediary relationship.

product_addons: type: array items: $ref: '#/components/schemas/AusAgreementAddOn' nullable: true description:

A list of product addons that apply to the specific agreement.

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

Agreement rate overrides.

rates_agreed_at: type: string format: date-time nullable: true description:

The datetime the rates were agreed at.

supply_point_identifier: type: string description:

The identifier of the supply point to add the agreement to.

tariff_code: type: string description:

The code for the agreement tariff. Must match an existing tariff code of an active product.

x-validators: - name: Validate product code exists description: Validate that the product code exists in Kraken. possible_errors: - product_code_does_not_exist required: - account_reference - effective_from - market_name - supply_point_identifier - tariff_code x-validators: - name: Validate ⁨effective_to⁩ not before ⁨effective_from⁩ description: Validates that ⁨effective_to⁩, if given, is on or later than ⁨effective_from⁩. possible_errors: - start_date_later_than_end_date AusEmbeddedGasAgreement: type: object properties: market_name: enum: - AUS_EMBEDDED_GAS type: string x-spec-enum-id: 474da700104b555f description:

The market name of the supply point.

x-enum-descriptions: AUS_EMBEDDED_GAS: AUS_EMBEDDED_GAS account_reference: type: string description:

The identifier of the account that owns this supply point. Must match one of the contract's subject accounts.

agreed_at: type: string format: date-time nullable: true description:

The datetime the agreement was agreed at.

business_contract_identifier: type: string nullable: true description:

The identifier of the business contract this agreement should be linked to.

characteristics: type: array items: $ref: '#/components/schemas/ProductCharacteristic' nullable: true description:

Characteristics of the agreed product that the customer has chosen.

x-validators: - name: Validate that each child has unique values for the ⁨code⁩ field description: Validate that each child has unique values for the ⁨code⁩ field. possible_errors: - children_with_duplicate_values effective_from: type: string format: date description:

The date from which the agreement is effective (inclusive), i.e. the agreement starts on the midnight of this date, such that this date becomes the first day covered by this agreement.

effective_to: type: string format: date nullable: true description:

The date to which the agreement is effective (exclusive), i.e. the agreement will end on the midnight of this date, such that the previous day is the last day covered by this agreement.

intermediary: allOf: - $ref: '#/components/schemas/AgreementIntermediaryDetails' nullable: true description:

Details about the intermediary relationship for this agreement. When provided, an intermediary link will be created between the agreement and the portfolio, establishing a business intermediary relationship.

product_addons: type: array items: $ref: '#/components/schemas/AusAgreementAddOn' nullable: true description:

A list of product addons that apply to the specific agreement.

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

Agreement rate overrides.

rates_agreed_at: type: string format: date-time nullable: true description:

The datetime the rates were agreed at.

supply_point_identifier: type: string description:

The identifier of the supply point to add the agreement to.

tariff_code: type: string description:

The code for the agreement tariff. Must match an existing tariff code of an active product.

x-validators: - name: Validate product code exists description: Validate that the product code exists in Kraken. possible_errors: - product_code_does_not_exist required: - account_reference - effective_from - market_name - supply_point_identifier - tariff_code x-validators: - name: Validate ⁨effective_to⁩ not before ⁨effective_from⁩ description: Validates that ⁨effective_to⁩, if given, is on or later than ⁨effective_from⁩. possible_errors: - start_date_later_than_end_date AusEmbeddedUnmeteredElectricityAgreement: type: object properties: market_name: enum: - AUS_EMBEDDED_UNMETERED_ELECTRICITY type: string x-spec-enum-id: f42813c05e71afe0 description:

The market name of the supply point.

x-enum-descriptions: AUS_EMBEDDED_UNMETERED_ELECTRICITY: AUS_EMBEDDED_UNMETERED_ELECTRICITY account_reference: type: string description:

The identifier of the account that owns this supply point. Must match one of the contract's subject accounts.

agreed_at: type: string format: date-time nullable: true description:

The datetime the agreement was agreed at.

business_contract_identifier: type: string nullable: true description:

The identifier of the business contract this agreement should be linked to.

characteristics: type: array items: $ref: '#/components/schemas/ProductCharacteristic' nullable: true description:

Characteristics of the agreed product that the customer has chosen.

x-validators: - name: Validate that each child has unique values for the ⁨code⁩ field description: Validate that each child has unique values for the ⁨code⁩ field. possible_errors: - children_with_duplicate_values effective_from: type: string format: date description:

The date from which the agreement is effective (inclusive), i.e. the agreement starts on the midnight of this date, such that this date becomes the first day covered by this agreement.

effective_to: type: string format: date nullable: true description:

The date to which the agreement is effective (exclusive), i.e. the agreement will end on the midnight of this date, such that the previous day is the last day covered by this agreement.

intermediary: allOf: - $ref: '#/components/schemas/AgreementIntermediaryDetails' nullable: true description:

Details about the intermediary relationship for this agreement. When provided, an intermediary link will be created between the agreement and the portfolio, establishing a business intermediary relationship.

product_addons: type: array items: $ref: '#/components/schemas/AusAgreementAddOn' nullable: true description:

A list of product addons that apply to the specific agreement.

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

Agreement rate overrides.

rates_agreed_at: type: string format: date-time nullable: true description:

The datetime the rates were agreed at.

supply_point_identifier: type: string description:

The identifier of the supply point to add the agreement to.

tariff_code: type: string description:

The code for the agreement tariff. Must match an existing tariff code of an active product.

x-validators: - name: Validate product code exists description: Validate that the product code exists in Kraken. possible_errors: - product_code_does_not_exist required: - account_reference - effective_from - market_name - supply_point_identifier - tariff_code x-validators: - name: Validate ⁨effective_to⁩ not before ⁨effective_from⁩ description: Validates that ⁨effective_to⁩, if given, is on or later than ⁨effective_from⁩. possible_errors: - start_date_later_than_end_date AusEmbeddedUnmeteredGasAgreement: type: object properties: market_name: enum: - AUS_EMBEDDED_UNMETERED_GAS type: string x-spec-enum-id: 2908a0235ee48f24 description:

The market name of the supply point.

x-enum-descriptions: AUS_EMBEDDED_UNMETERED_GAS: AUS_EMBEDDED_UNMETERED_GAS account_reference: type: string description:

The identifier of the account that owns this supply point. Must match one of the contract's subject accounts.

agreed_at: type: string format: date-time nullable: true description:

The datetime the agreement was agreed at.

business_contract_identifier: type: string nullable: true description:

The identifier of the business contract this agreement should be linked to.

characteristics: type: array items: $ref: '#/components/schemas/ProductCharacteristic' nullable: true description:

Characteristics of the agreed product that the customer has chosen.

x-validators: - name: Validate that each child has unique values for the ⁨code⁩ field description: Validate that each child has unique values for the ⁨code⁩ field. possible_errors: - children_with_duplicate_values effective_from: type: string format: date description:

The date from which the agreement is effective (inclusive), i.e. the agreement starts on the midnight of this date, such that this date becomes the first day covered by this agreement.

effective_to: type: string format: date nullable: true description:

The date to which the agreement is effective (exclusive), i.e. the agreement will end on the midnight of this date, such that the previous day is the last day covered by this agreement.

intermediary: allOf: - $ref: '#/components/schemas/AgreementIntermediaryDetails' nullable: true description:

Details about the intermediary relationship for this agreement. When provided, an intermediary link will be created between the agreement and the portfolio, establishing a business intermediary relationship.

product_addons: type: array items: $ref: '#/components/schemas/AusAgreementAddOn' nullable: true description:

A list of product addons that apply to the specific agreement.

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

Agreement rate overrides.

rates_agreed_at: type: string format: date-time nullable: true description:

The datetime the rates were agreed at.

supply_point_identifier: type: string description:

The identifier of the supply point to add the agreement to.

tariff_code: type: string description:

The code for the agreement tariff. Must match an existing tariff code of an active product.

x-validators: - name: Validate product code exists description: Validate that the product code exists in Kraken. possible_errors: - product_code_does_not_exist required: - account_reference - effective_from - market_name - supply_point_identifier - tariff_code x-validators: - name: Validate ⁨effective_to⁩ not before ⁨effective_from⁩ description: Validates that ⁨effective_to⁩, if given, is on or later than ⁨effective_from⁩. possible_errors: - start_date_later_than_end_date AusEmbeddedWaterAgreement: type: object properties: market_name: enum: - AUS_EMBEDDED_WATER type: string x-spec-enum-id: 3fdb89ad8943b7b7 description:

The market name of the supply point.

x-enum-descriptions: AUS_EMBEDDED_WATER: AUS_EMBEDDED_WATER account_reference: type: string description:

The identifier of the account that owns this supply point. Must match one of the contract's subject accounts.

agreed_at: type: string format: date-time nullable: true description:

The datetime the agreement was agreed at.

business_contract_identifier: type: string nullable: true description:

The identifier of the business contract this agreement should be linked to.

characteristics: type: array items: $ref: '#/components/schemas/ProductCharacteristic' nullable: true description:

Characteristics of the agreed product that the customer has chosen.

x-validators: - name: Validate that each child has unique values for the ⁨code⁩ field description: Validate that each child has unique values for the ⁨code⁩ field. possible_errors: - children_with_duplicate_values effective_from: type: string format: date description:

The date from which the agreement is effective (inclusive), i.e. the agreement starts on the midnight of this date, such that this date becomes the first day covered by this agreement.

effective_to: type: string format: date nullable: true description:

The date to which the agreement is effective (exclusive), i.e. the agreement will end on the midnight of this date, such that the previous day is the last day covered by this agreement.

intermediary: allOf: - $ref: '#/components/schemas/AgreementIntermediaryDetails' nullable: true description:

Details about the intermediary relationship for this agreement. When provided, an intermediary link will be created between the agreement and the portfolio, establishing a business intermediary relationship.

product_addons: type: array items: $ref: '#/components/schemas/AusAgreementAddOn' nullable: true description:

A list of product addons that apply to the specific agreement.

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

Agreement rate overrides.

rates_agreed_at: type: string format: date-time nullable: true description:

The datetime the rates were agreed at.

supply_point_identifier: type: string description:

The identifier of the supply point to add the agreement to.

tariff_code: type: string description:

The code for the agreement tariff. Must match an existing tariff code of an active product.

x-validators: - name: Validate product code exists description: Validate that the product code exists in Kraken. possible_errors: - product_code_does_not_exist required: - account_reference - effective_from - market_name - supply_point_identifier - tariff_code x-validators: - name: Validate ⁨effective_to⁩ not before ⁨effective_from⁩ description: Validates that ⁨effective_to⁩, if given, is on or later than ⁨effective_from⁩. possible_errors: - start_date_later_than_end_date AusGasAgreement: type: object properties: market_name: enum: - AUS_GAS type: string x-spec-enum-id: 0c099a1ab65e563b description:

The market name of the supply point.

x-enum-descriptions: AUS_GAS: AUS_GAS account_reference: type: string description:

The identifier of the account that owns this supply point. Must match one of the contract's subject accounts.

agreed_at: type: string format: date-time nullable: true description:

The datetime the agreement was agreed at.

business_contract_identifier: type: string nullable: true description:

The identifier of the business contract this agreement should be linked to.

characteristics: type: array items: $ref: '#/components/schemas/ProductCharacteristic' nullable: true description:

Characteristics of the agreed product that the customer has chosen.

x-validators: - name: Validate that each child has unique values for the ⁨code⁩ field description: Validate that each child has unique values for the ⁨code⁩ field. possible_errors: - children_with_duplicate_values effective_from: type: string format: date description:

The date from which the agreement is effective (inclusive), i.e. the agreement starts on the midnight of this date, such that this date becomes the first day covered by this agreement.

effective_to: type: string format: date nullable: true description:

The date to which the agreement is effective (exclusive), i.e. the agreement will end on the midnight of this date, such that the previous day is the last day covered by this agreement.

intermediary: allOf: - $ref: '#/components/schemas/AgreementIntermediaryDetails' nullable: true description:

Details about the intermediary relationship for this agreement. When provided, an intermediary link will be created between the agreement and the portfolio, establishing a business intermediary relationship.

product_addons: type: array items: $ref: '#/components/schemas/AusAgreementAddOn' nullable: true description:

A list of product addons that apply to the specific agreement.

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

Agreement rate overrides.

rates_agreed_at: type: string format: date-time nullable: true description:

The datetime the rates were agreed at.

supply_point_identifier: type: string description:

The identifier of the supply point to add the agreement to.

tariff_code: type: string description:

The code for the agreement tariff. Must match an existing tariff code of an active product.

x-validators: - name: Validate product code exists description: Validate that the product code exists in Kraken. possible_errors: - product_code_does_not_exist required: - account_reference - effective_from - market_name - supply_point_identifier - tariff_code x-validators: - name: Validate ⁨effective_to⁩ not before ⁨effective_from⁩ description: Validates that ⁨effective_to⁩, if given, is on or later than ⁨effective_from⁩. possible_errors: - start_date_later_than_end_date AusPropertyRichAddress: type: object properties: administrative_area: enum: - ACT - NSW - NT - QLD - SA - TAS - VIC - WA type: string x-spec-enum-id: 0083aa6c13849f88 description:

Australian state.

x-enum-descriptions: ACT: ACT NSW: NSW NT: NT QLD: QLD SA: SA TAS: TAS VIC: VIC WA: WA country: type: string description:

The ISO 3166-1-alpha-2 code of the country that this address belongs to, for example AU (Australia) or GB (Great Britain).

maxLength: 2 delivery_point_identifier: type: string description:

The unique country specific identifier for an address. For example the UPRN in the UK or G-NAF ID in Australia.

maxLength: 11 x-validators: - name: Validate delivery point identifier description: Validate that the delivery point identifier contains only capital letters and numbers. possible_errors: - invalid_delivery_point_identifier dependent_locality: type: string default: '' description:

Dependent localities, neighbourhoods or boroughs. These are sometimes included in an address when the delivery point is outside the boundary of the main postal town that serves it.

maxLength: 512 locality: type: string description:

Australian suburb or town.

maxLength: 46 name: type: string default: '' description:

The recipient's name.

deprecated: true organization: type: string default: '' description:

The company or organization to which the address belongs.

deprecated: true postal_code: type: string description:

Australian postal code.

maxLength: 4 x-validators: - name: Validate and normalize postcode description: Validate the postal code and normalize it to a standard format. possible_errors: - invalid_postcode sorting_code: type: string default: '' description:

This is a non-geographic code used for recipients of large quantities of post, such as companies or government departments. An example is the French CEDEX code.

maxLength: 512 street_address: type: string default: '' description:

Free text field for the address. Either this field or the structured_address field should be provided, not both.

structured_street_address: allOf: - $ref: '#/components/schemas/AusStructuredStreetAddress' description:

Structured address object. Fields for this object are territory dependent. Please speak to the tech team about uses of this field. Either this field or the street_address should be provided, not both.

required: - administrative_area - country - locality - postal_code - structured_street_address x-validators: - name: Validate and normalize postcode description: Validate the postal code and normalize it to a standard format. possible_errors: - invalid_postcode - name: Validate address description: Validate that the address is in the correct format. possible_errors: - invalid_address AusSolarPpaAgreement: type: object properties: market_name: enum: - AUS_SOLAR_PPA type: string x-spec-enum-id: 7489e19a68f235c9 description:

The market name of the supply point.

x-enum-descriptions: AUS_SOLAR_PPA: AUS_SOLAR_PPA account_reference: type: string description:

The identifier of the account that owns this supply point. Must match one of the contract's subject accounts.

agreed_at: type: string format: date-time nullable: true description:

The datetime the agreement was agreed at.

business_contract_identifier: type: string nullable: true description:

The identifier of the business contract this agreement should be linked to.

characteristics: type: array items: $ref: '#/components/schemas/ProductCharacteristic' nullable: true description:

Characteristics of the agreed product that the customer has chosen.

x-validators: - name: Validate that each child has unique values for the ⁨code⁩ field description: Validate that each child has unique values for the ⁨code⁩ field. possible_errors: - children_with_duplicate_values effective_from: type: string format: date description:

The date from which the agreement is effective (inclusive), i.e. the agreement starts on the midnight of this date, such that this date becomes the first day covered by this agreement.

effective_to: type: string format: date nullable: true description:

The date to which the agreement is effective (exclusive), i.e. the agreement will end on the midnight of this date, such that the previous day is the last day covered by this agreement.

intermediary: allOf: - $ref: '#/components/schemas/AgreementIntermediaryDetails' nullable: true description:

Details about the intermediary relationship for this agreement. When provided, an intermediary link will be created between the agreement and the portfolio, establishing a business intermediary relationship.

product_addons: type: array items: $ref: '#/components/schemas/AusAgreementAddOn' nullable: true description:

A list of product addons that apply to the specific agreement.

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

Agreement rate overrides.

rates_agreed_at: type: string format: date-time nullable: true description:

The datetime the rates were agreed at.

supply_point_identifier: type: string description:

The identifier of the supply point to add the agreement to.

tariff_code: type: string description:

The code for the agreement tariff. Must match an existing tariff code of an active product.

x-validators: - name: Validate product code exists description: Validate that the product code exists in Kraken. possible_errors: - product_code_does_not_exist required: - account_reference - effective_from - market_name - supply_point_identifier - tariff_code x-validators: - name: Validate ⁨effective_to⁩ not before ⁨effective_from⁩ description: Validates that ⁨effective_to⁩, if given, is on or later than ⁨effective_from⁩. possible_errors: - start_date_later_than_end_date AusStructuredStreetAddress: type: object properties: building_or_property_name: type: string description:

Building or property name. No longer than 60 chars as two lines of 30 chars each. If more than 30 chars, there must be a \n after 30 chars.

maxLength: 60 x-validators: - name: Validate multiline max length description: Validates that the value has at most 2 lines and max 30 characters per line. possible_errors: - multiline_max_length_exceeded flat_or_unit_number: type: string description:

if supplied, flat_or_unit_type must be as well. limit of 7 characters, numbers and . with optional alphabetical prefix and suffix.

flat_or_unit_type: enum: - ANT - APT - ATM - BBQ - BLCK - BTSD - BLDG - BNGW - CAGE - CARP - CARS - CLUB - COOL - CTGE - DUP - FY - F - GRGE - HALL - HSE - KSK - LSE - LBBY - LOFT - LOT - MSNT - MB - 'OFF' - PTHS - REAR - RESV - RM - SEC - SHED - SHOP - SHRM - SIGN - SITE - SL - STOR - STR - STU - SUBS - SE - TNCY - TWR - TNHS - U - VLT - VLLA - WARD - WE - WKSH type: string x-spec-enum-id: 9306e5734ae7a103 description:

Flat or unit type.

x-enum-descriptions: ANT: Antenna APT: Apartment ATM: ATM BBQ: Barbeque BLCK: Block BTSD: Boatshed BLDG: Building BNGW: Bungalow CAGE: Cage CARP: Carpark CARS: Carspace CLUB: Club COOL: Coolroom CTGE: Cottage DUP: Duplex FY: Factory F: Flat GRGE: Garage HALL: Hall HSE: House KSK: Kiosk LSE: Lease LBBY: Lobby LOFT: Loft LOT: Lot MSNT: Maisonette MB: Marine Berth 'OFF': Office PTHS: Penthouse REAR: Rear RESV: Reserve RM: Room SEC: Section SHED: Shed SHOP: Shop SHRM: Showroom SIGN: Sign SITE: Site SL: Stall STOR: Store STR: Strata Unit STU: Studio SUBS: Substation SE: Suite TNCY: Tenancy TWR: Tower TNHS: Townhouse U: Unit VLT: Vault VLLA: Villa WARD: Ward WE: Warehouse WKSH: Workshop floor_or_level_number: type: string description:

if supplied, floor_or_level_type must be as well. limit of 5 characters, numbers and . with optional alphabetical prefix and suffix

maxLength: 7 floor_or_level_type: enum: - B - FL - G - L - LG - M - LL - OD - P - PTHS - PLF - PDM - RT - SB - UG - LB type: string x-spec-enum-id: 9810b2a79eb3d5cf description:

Floor or level type.

x-enum-descriptions: B: Basement FL: Floor G: Ground L: Level LG: Lower Ground M: Mezzanine LL: Lower Level OD: Observation Deck P: Parking PTHS: Penthouse PLF: Platform PDM: Podium RT: Rooftop SB: Sub-Basement UG: Upper Ground LB: Lobby house_number_1: type: integer description:

House number 1. If provided, street_name must be as well.

house_number_2: type: integer description:

House number 2. If provided, house_number_1 must be as well.

house_number_suffix_1: type: string description:

House number suffix 1. If provided, house_number_1 must be as well.

maxLength: 1 house_number_suffix_2: type: string description:

House number suffix 2. If provided, house_number_2 must be as well.

maxLength: 1 location_descriptor: type: string description:

A description of the location.

lot_number: type: string description:

Letters, numbers and ..

maxLength: 6 postal_delivery_number_prefix: type: string description:

Postal delivery number prefix. Alphabetical (Uppercase). If provided, postal_delivery_number_value must be as well.

maxLength: 3 x-validators: - name: Validate value contains only alphabetic capitals description: Validate the value contains only capital letters A-Z. possible_errors: - value_must_be_alphabetic_caps postal_delivery_number_suffix: type: string description:

Postal delivery number suffix. Alphabetical (Uppercase). If provided, postal_delivery_number_value must be as well.

maxLength: 3 x-validators: - name: Validate value contains only alphabetic capitals description: Validate the value contains only capital letters A-Z. possible_errors: - value_must_be_alphabetic_caps postal_delivery_number_value: type: integer description:

Postal delivery number value. If provided, postal_delivery_typ must be as well.

postal_delivery_type: enum: - CARE PO - CMA - CMB - CPA - GPO BOX - LOCKED BAG - MS - PO BOX - PRIVATE BAG - RSD - RMB - RMS type: string x-spec-enum-id: 4faa648b6a55c770 description:

Postal delivery type.

x-enum-descriptions: CARE PO: CARE PO CMA: CMA CMB: CMB CPA: CPA GPO BOX: GPO BOX LOCKED BAG: LOCKED BAG MS: MS PO BOX: PO BOX PRIVATE BAG: PRIVATE BAG RSD: RSD RMB: RMB RMS: RMS street_name: type: string description:

Street name.

maxLength: 45 street_suffix: enum: - CN - DE - E - EX - IN - LR - ML - N - NE - NW - OF - 'ON' - OT - OP - S - SE - SW - UP - W type: string x-spec-enum-id: f105f3c67a4f2af4 description:

Street suffix. If provided, street_name must be as well.

x-enum-descriptions: CN: Central DE: Deviation E: East EX: Extension IN: Inner LR: Lower ML: Mall N: North NE: North East NW: North West OF: 'Off' 'ON': 'On' OT: Outer OP: Overpass S: South SE: South East SW: South West UP: Upper W: West street_type: enum: - ACCS - ACRE - ALLY - ALWY - AMBL - ANCG - ANX - APP - ARC - ARTL - ART - AVE - BA - BANK - BASN - BAY - BCH - BEND - BLK - BWLK - BVD - BVDE - BOWL - BRCE - BRAE - BRAN - BRK - BRET - BDGE - BDWY - BROW - BYPA - BYWY - CAUS - CTR - CNWY - CH - CIR - CLT - CCT - CRCS - CL - CLR - CLDE - CMMN - CNCD - CON - CNN - CPS - CNR - CSO - CRSE - CT - CTYD - COVE - CRES - CRST - CRF - CRK - CRSS - CRSG - CRD - COWY - CUWY - CDS - CUT - CTTG - DALE - DASH - DELL - DENE - DEVN - DIP - DSTR - DIV - DOCK - DOM - DOWN - DWNS - DR - DRWY - ESMT - EDGE - ELB - END - ENT - ESP - EST - EXP - EXTN - FAWY - FTRK - FBRK - FLNE - FITR - FLAT - FLTS - FOLW - FTWY - FORD - FSHR - FK - FORM - FWY - FRNT - FRTG - GAP - GDN - GDNS - GTE - GTES - GTWY - GLD - GLEN - GRA - GRN - GRND - GR - GLY - HRBR - HVN - HETH - HTS - HRD - HWY - HILL - HLLW - HUB - INLT - INTG - INTN - ISLD - JNC - KEY - KEYS - KNOL - LADR - LDG - LANE - LNWY - LEAD - LEDR - LEES - LINE - LINK - LT - LKT - LOOP - LWR - LYNN - MALL - MANR - MART - MEAD - MNDR - MEW - MEWS - MILE - MWY - MT - NOOK - NTH - 'NULL' - OTLT - OTLK - OVAL - PLMS - PDE - PRDS - PARK - PKLD - PKWY - PART - PASS - PSGE - PATH - PHWY - PSLA - PIAZ - PL - PLAT - PLZA - PKT - PNT - PORT - PREC - PROM - PRST - QUAD - QDGL - QDRT - QY - QYS - RMBL - RAMP - RNGE - RCH - REEF - RES - REST - RTT - RTRN - RIDE - RDGE - RGWY - ROWY - RING - RISE - RSNG - RVR - RVWY - RVRA - RD - RDS - RDSD - RDWY - RNDE - RSBL - RTY - RND - RTE - ROW - ROWE - RUE - RUN - SWY - SHUN - SDNG - SKLN - SLPE - SND - STH - SPUR - SQ - STRS - SHWY - STPS - STRT - STAI - STRA - ST - STRP - SBWY - TARN - TCE - THOR - THRU - TLWY - TOP - TOR - TWRS - TRK - TRL - TRLR - TMWY - TVSE - TRI - TKWY - TUNL - TURN - UPAS - UPR - VALE - VLLY - VDCT - VIEW - VWS - VLL - VLGE - VLLS - VSTA - VUE - WADE - WALK - WKWY - WTRS - WTWY - WAY - WHRF - WOOD - WDS - WYND - YARD type: string x-spec-enum-id: 472734f6bfeb60b6 description:

Street type. If provided, street_name must be as well.

x-enum-descriptions: ACCS: Access ACRE: Acre ALLY: Alley ALWY: Alleyway AMBL: Amble ANCG: Anchorage ANX: Annex APP: Approach ARC: Arcade ARTL: Arterial ART: Artery AVE: Avenue BA: Banan BANK: Bank BASN: Basin BAY: Bay BCH: Beach BEND: Bend BLK: Block BWLK: Boardwalk BVD: Boulevard BVDE: Boulevarde BOWL: Bowl BRCE: Brace BRAE: Brae BRAN: Branch BRK: Break BRET: Brett BDGE: Bridge BDWY: Broadway BROW: Brow BYPA: Bypass BYWY: Byway CAUS: Causeway CTR: Centre CNWY: Centreway CH: Chase CIR: Circle CLT: Circlet CCT: Circuit CRCS: Circus CL: Close CLR: Cluster CLDE: Colonnade CMMN: Common CNCD: Concord CON: Concourse CNN: Connection CPS: Copse CNR: Corner CSO: Corso CRSE: Course CT: Court CTYD: Courtyard COVE: Cove CRES: Crescent CRST: Crest CRF: Crief CRK: Crook CRSS: Cross CRSG: Crossing CRD: Crossroad COWY: Crossway CUWY: Cruiseway CDS: Cul-de-sac CUT: Cut CTTG: Cutting DALE: Dale DASH: Dash DELL: Dell DENE: Dene DEVN: Deviation DIP: Dip DSTR: Distributor DIV: Divide DOCK: Dock DOM: Domain DOWN: Down DWNS: Downs DR: Drive DRWY: Driveway ESMT: Easement EDGE: Edge ELB: Elbow END: End ENT: Entrance ESP: Esplanade EST: Estate EXP: Expressway EXTN: Extension FAWY: Fairway FTRK: Fire Track FBRK: Firebreak FLNE: Fireline FITR: Firetrail FLAT: Flat FLTS: Flats FOLW: Follow FTWY: Footway FORD: Ford FSHR: Foreshore FK: Fork FORM: Formation FWY: Freeway FRNT: Front FRTG: Frontage GAP: Gap GDN: Garden GDNS: Gardens GTE: Gate GTES: Gates GTWY: Gateway GLD: Glade GLEN: Glen GRA: Grange GRN: Green GRND: Ground GR: Grove GLY: Gully HRBR: Harbour HVN: Haven HETH: Heath HTS: Heights HRD: Highroad HWY: Highway HILL: Hill HLLW: Hollow HUB: Hub INLT: Inlet INTG: Interchange INTN: Intersection ISLD: Island JNC: Junction KEY: Key KEYS: Keys KNOL: Knoll LADR: Ladder LDG: Landing LANE: Lane LNWY: Laneway LEAD: Lead LEDR: Leader LEES: Lees LINE: Line LINK: Link LT: Little LKT: Lookout LOOP: Loop LWR: Lower LYNN: Lynne MALL: Mall MANR: Manor MART: Mart MEAD: Mead MNDR: Meander MEW: Mew MEWS: Mews MILE: Mile MWY: Motorway MT: Mount NOOK: Nook NTH: North 'NULL': 'Null' OTLT: Outlet OTLK: Outlook OVAL: Oval PLMS: Palms PDE: Parade PRDS: Paradise PARK: Park PKLD: Parklands PKWY: Parkway PART: Part PASS: Pass PSGE: Passage PATH: Path PHWY: Pathway PSLA: Peninsula PIAZ: Piazza PL: Place PLAT: Plateau PLZA: Plaza PKT: Pocket PNT: Point PORT: Port PREC: Precinct PROM: Promenade PRST: Pursuit QUAD: Quad QDGL: Quadrangle QDRT: Quadrant QY: Quay QYS: Quays RMBL: Ramble RAMP: Ramp RNGE: Range RCH: Reach REEF: Reef RES: Reserve REST: Rest RTT: Retreat RTRN: Return RIDE: Ride RDGE: Ridge RGWY: Ridgeway ROWY: Right of Way RING: Ring RISE: Rise RSNG: Rising RVR: River RVWY: Riverway RVRA: Riviera RD: Road RDS: Roads RDSD: Roadside RDWY: Roadway RNDE: Ronde RSBL: Rosebowl RTY: Rotary RND: Round RTE: Route ROW: Row ROWE: Rowe RUE: Rue RUN: Run SWY: Service Way SHUN: Shun SDNG: Siding SKLN: Skyline SLPE: Slope SND: Sound STH: South SPUR: Spur SQ: Square STRS: Stairs SHWY: State Highway STPS: Steps STRT: Straight STAI: Strait STRA: Strand ST: Street STRP: Strip SBWY: Subway TARN: Tarn TCE: Terrace THOR: Thoroughfare THRU: Throughway TLWY: Tollway TOP: Top TOR: Tor TWRS: Towers TRK: Track TRL: Trail TRLR: Trailer TMWY: Tramway TVSE: Traverse TRI: Triangle TKWY: Trunkway TUNL: Tunnel TURN: Turn UPAS: Underpass UPR: Upper VALE: Vale VLLY: Valley VDCT: Viaduct VIEW: View VWS: Views VLL: Villa VLGE: Village VLLS: Villas VSTA: Vista VUE: Vue WADE: Wade WALK: Walk WKWY: Walkway WTRS: Waters WTWY: Waterway WAY: Way WHRF: Wharf WOOD: Wood WDS: Woods WYND: Wynd YARD: Yard BespokeRateConfiguration: type: object properties: term_type: type: string description:

The type of the contract term.

is_variable: type: boolean default: true description:

Whether the contract term is variable in Kraken or not. If not, it must be amended by a new contract.

schedules: type: array items: $ref: '#/components/schemas/BespokeRateSchedule' description:

The schedules of bespoke rates.

minItems: 1 x-validators: - name: Validate bespoke rates do not conflict description: Validate bespoke rates for the same target and rate do not conflict during the same period. The target of a bespoke rate is determined by the supply point identifier and product code. possible_errors: - overlapping_bespoke_rate_schedules - name: Validate bespoke rate schedules target consistently description: Validate that bespoke rate schedules either all target supply points via the supply_point_identifier field or none do. possible_errors: - inconsistent_bespoke_rate_schedule_targeting required: - schedules - term_type BespokeRateItem: type: object properties: identifier: type: string nullable: true description:

A unique identifier for the bespoke rate item.

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

The price per unit of the bespoke rate.

rate_specification_code: type: string description:

The rate specification code for the bespoke rate.

rate_specification_type: enum: - PRODUCT_RATE - SHARED_RATE - null type: string x-spec-enum-id: 94c4191a865cda34 nullable: true default: PRODUCT_RATE description:

The rate specification type for the bespoke rate.

x-enum-descriptions: PRODUCT_RATE: Product rate SHARED_RATE: Shared rate None: None variant_profile: allOf: - $ref: '#/components/schemas/VariantProfile' description:

The variant profile which the rate applies to.

required: - price_per_unit - rate_specification_code - variant_profile BespokeRateSchedule: type: object properties: identifier: type: string nullable: true description:

A unique identifier for the bespoke rate schedule.

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

A list of bespoke rates.

minItems: 1 x-validators: - name: Validate bespoke rate items are unique description: Validate that no two bespoke rate items in a schedule share the same rate specification code, rate specification type, and variant profile. possible_errors: - duplicate_bespoke_rate_items product_code: type: string description:

A product code for the schedule of bespoke rate.

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 nullable: true description:

The external identifier of the supply point that this bespoke rate schedule targets.

minLength: 1 valid_from: type: string format: date-time description:

The date the schedule of bespoke rates is valid from (inclusive).

valid_to: type: string format: date-time nullable: true description:

The date the schedule of bespoke rates is valid to (exclusive).

required: - items - product_code - valid_from x-validators: - name: Validate ⁨valid_to⁩ not before or equal to ⁨valid_from⁩ description: Validates that ⁨valid_to⁩, if given, is strictly later than ⁨valid_from⁩. possible_errors: - start_date_same_as_end_date - name: Validate each item represents a possible rate for the product description: Validate each item's rate specification, characteristic values, and scheme labels represent a rate defned on the product. possible_errors: - characteristic_code_not_found - invalid_characteristic_value - invalid_profile_variant_for_specification - product_specification_not_found_for_product - rate_specification_not_found_for_product - shared_rate_not_found - shared_rate_not_found_for_product - name: Validate that all required bespoke rates are present and no non-overridable rates are supplied description: Validates that bespoke rate schedules include all rate specifications marked as must-be-overridden and mandatory, and do not include any rate specifications marked as cannot-be-overridden. possible_errors: - bespoke_rate_cannot_be_overridden - missing_required_bespoke_rate BillDueDate: type: object properties: term_type: type: string description:

The type of the contract term.

is_variable: type: boolean default: true description:

Whether the contract term is variable in Kraken or not. If not, it must be amended by a new contract.

number_of_days: type: integer minimum: 0 description:

The number of days added to the issuance date to determine the due date.

type_of_days: enum: - WORKING - CALENDAR type: string x-spec-enum-id: ca64884b18199022 description: data-import--field-definition--bill-due-date--type-of-days--html x-enum-descriptions: WORKING: Working days CALENDAR: Calendar days required: - number_of_days - term_type - type_of_days BillingDocumentIssuanceFrequencyTerm: type: object properties: term_type: type: string description:

The type of the contract term.

frequency: enum: - DAILY - MONTHLY type: string x-spec-enum-id: 74dcc34556834abd description:

The rate at which a billing document is issued. For example, this can be daily or monthly.

x-enum-descriptions: DAILY: Daily MONTHLY: Monthly is_variable: type: boolean default: true description:

Whether the contract term is variable in Kraken or not. If not, it must be amended by a new contract.

multiplier: type: integer description:

The multiplier for the issuance frequency. For example, for a frequency of monthly and a multiplier of 2, a billing document should be issued every 2 months.

period_start_day: type: integer description:

The day of the month on which the billing period starts in Kraken.

period_start_month: type: integer description:

The month of the year on which the billing period starts in Kraken.

required: - frequency - multiplier - period_start_day - period_start_month - term_type BillingInformation: type: object properties: billing_address: allOf: - $ref: '#/components/schemas/Address' description:

The billing address for the account. The payload can specify an address in this format or use the the billing_address1 etc fields, but not both.

billing_attention_of: type: string description:

Extra recipient information for when this account represents a large organisation (e.g. "The Bursar" or "Accounts Payable"). If provided, it will be used for producing statements.

maxLength: 256 billing_customer_reference: type: string description:

Customer-specified reference to use in communications (e.g. "Energy supply"). If provided, it will be used for producing statements.

maxLength: 256 billing_email: type: string format: email nullable: true description:

If populated the bill/invoice communications will be emailed to this email address.

maxLength: 254 billing_name: type: string description:

Optional billing name to be used on the account. If provided, it will be used for producing statements. If not, the customer names will be used.

maxLength: 510 billing_sub_name: type: string description:

Optional billing sub-name to be used on the account. Use this field if the name needs to be split into multiple lines. If provided, it will be used for producing statements.

maxLength: 256 BusinessDetail: type: object properties: key: enum: - abn - acn - frmp - anzsic type: string x-spec-enum-id: cf8b0ced1c78b621 description:

The key for the business detail. Keys need to be registered before import. If a value is provided for a key that is not registered then an error will be raised.

x-enum-descriptions: abn: abn acn: acn frmp: frmp anzsic: anzsic value: description:

The value for the business detail. This must match the type the registered key is expecting.

required: - key - value x-validators: - name: Validate that the value for the business details key has the correct type description: Validate that the value given has the type that matches the type configured for the registered business detail key. possible_errors: - business_detail_incorrect_value_type - name: Validate the business details value description: Validate that business detail value complies with any validation required by their corresponding detail key. possible_errors: - business_detail_failed_validation BusinessPortfolio: type: object properties: billing_name: type: string description:

Optional billing name to be used on the account. If provided, it will be used for producing statements. If not, the customer names will be used.

maxLength: 510 notes: type: array items: $ref: '#/components/schemas/Note' description:

List of notes that should be applied at the portfolio level instead of the individual account.

portfolio_references: type: array items: $ref: '#/components/schemas/PortfolioReference' description:

List of references to the portfolio that this account belongs to.

minItems: 1 portfolio_settings: allOf: - $ref: '#/components/schemas/PortfolioSettings' nullable: true description:

This object allows for setting portfolio settings during data migration. This object is only available where the is_portfolio_lead flag is true. Any other account type will fail validation.

required: - portfolio_references x-validators: - name: Validate portfolio reference provided correctly description: Validate that a portfolio reference is provided if portfolio settings have been provided and that a portfolio reference is not provided if the import supplier is set to create new portfolios. possible_errors: - portfolio_references_missing - portfolio_references_provided - name: Validate no duplicate portfolio reference namespaces description: Validate that there are no duplicate portfolio reference namespaces in the payload. possible_errors: - duplicate_portfolio_references BusinessUser: type: object properties: address: allOf: - $ref: '#/components/schemas/AusPropertyRichAddress' description:

The customer's address. If provided, this will be stored on the account user record.

alternative_phone_numbers: type: array items: $ref: '#/components/schemas/CustomerAlternativeNumber' description:

A list of the customer's alternative phone numbers.

business_roles: type: array items: enum: - EZ_BROKER - RECEIVES_INVOICES - RECEIVES_SALES - FLAGGED_LS - PRIMARY_NO_COMMS - TRUSTEE_BILL - NOMINATED_BILL - EZ_DFPP_RO - BSP_USER - BUSINESS_NO_COMMS - MSBG_NO_COMMS - MSBG_COMMS - TRUSTEE_MAND - MSP_USER - NOMINATED_NONE - CDR_REPRESENTATIVE - NO_EMAIL - BUSINESS_COMMS - RECEIVES_DUNNING - EZ_CUSTOMER - EZ_ADMIN - EZ_DFPP_RW - RESI_SECONDARY - ADMIN - OUTAGE_CONTACT - LIFE_SUPPORT_CONTACT - TRUSTEE_NONE - TRUSTEE - BUSI_FINANCIALLY - RECEIVES_SERVICE - NOMINATED_MAND type: string description: |- * `EZ_BROKER` - EZ_BROKER * `RECEIVES_INVOICES` - RECEIVES_INVOICES * `RECEIVES_SALES` - RECEIVES_SALES * `FLAGGED_LS` - FLAGGED_LS * `PRIMARY_NO_COMMS` - PRIMARY_NO_COMMS * `TRUSTEE_BILL` - TRUSTEE_BILL * `NOMINATED_BILL` - NOMINATED_BILL * `EZ_DFPP_RO` - EZ_DFPP_RO * `BSP_USER` - BSP_USER * `BUSINESS_NO_COMMS` - BUSINESS_NO_COMMS * `MSBG_NO_COMMS` - MSBG_NO_COMMS * `MSBG_COMMS` - MSBG_COMMS * `TRUSTEE_MAND` - TRUSTEE_MAND * `MSP_USER` - MSP_USER * `NOMINATED_NONE` - NOMINATED_NONE * `CDR_REPRESENTATIVE` - CDR_REPRESENTATIVE * `NO_EMAIL` - NO_EMAIL * `BUSINESS_COMMS` - BUSINESS_COMMS * `RECEIVES_DUNNING` - RECEIVES_DUNNING * `EZ_CUSTOMER` - EZ_CUSTOMER * `EZ_ADMIN` - EZ_ADMIN * `EZ_DFPP_RW` - EZ_DFPP_RW * `RESI_SECONDARY` - RESI_SECONDARY * `ADMIN` - ADMIN * `OUTAGE_CONTACT` - OUTAGE_CONTACT * `LIFE_SUPPORT_CONTACT` - LIFE_SUPPORT_CONTACT * `TRUSTEE_NONE` - TRUSTEE_NONE * `TRUSTEE` - TRUSTEE * `BUSI_FINANCIALLY` - BUSI_FINANCIALLY * `RECEIVES_SERVICE` - RECEIVES_SERVICE * `NOMINATED_MAND` - NOMINATED_MAND x-spec-enum-id: a9dfece01fff4a96 x-enum-descriptions: EZ_BROKER: EZ_BROKER RECEIVES_INVOICES: RECEIVES_INVOICES RECEIVES_SALES: RECEIVES_SALES FLAGGED_LS: FLAGGED_LS PRIMARY_NO_COMMS: PRIMARY_NO_COMMS TRUSTEE_BILL: TRUSTEE_BILL NOMINATED_BILL: NOMINATED_BILL EZ_DFPP_RO: EZ_DFPP_RO BSP_USER: BSP_USER BUSINESS_NO_COMMS: BUSINESS_NO_COMMS MSBG_NO_COMMS: MSBG_NO_COMMS MSBG_COMMS: MSBG_COMMS TRUSTEE_MAND: TRUSTEE_MAND MSP_USER: MSP_USER NOMINATED_NONE: NOMINATED_NONE CDR_REPRESENTATIVE: CDR_REPRESENTATIVE NO_EMAIL: NO_EMAIL BUSINESS_COMMS: BUSINESS_COMMS RECEIVES_DUNNING: RECEIVES_DUNNING EZ_CUSTOMER: EZ_CUSTOMER EZ_ADMIN: EZ_ADMIN EZ_DFPP_RW: EZ_DFPP_RW RESI_SECONDARY: RESI_SECONDARY ADMIN: ADMIN OUTAGE_CONTACT: OUTAGE_CONTACT LIFE_SUPPORT_CONTACT: LIFE_SUPPORT_CONTACT TRUSTEE_NONE: TRUSTEE_NONE TRUSTEE: TRUSTEE BUSI_FINANCIALLY: BUSI_FINANCIALLY RECEIVES_SERVICE: RECEIVES_SERVICE NOMINATED_MAND: NOMINATED_MAND description:

A list of business roles to be assigned to the customer. These apply to all accounts the business has access to.

contact_emails: type: array items: type: string format: email description:

A list of additional email addresses to associate with the customer account. These can be used for sending communications to the customer. Each email must be a valid email address.

credit_assessment_id: type: string nullable: true description:

Customers credit assessment id.

credit_result: type: string nullable: true description:

The credit result from the provider.

credit_risk_bracket: enum: - LOW - MID - HIGH - UNKNOWN - '' - null type: string x-spec-enum-id: e6b98b6c312ff7bf nullable: true description:

The deemed credit risk bracket for this customer.

x-enum-descriptions: LOW: Low MID: Medium HIGH: High UNKNOWN: Unknown '': '' None: None credit_score: type: integer maximum: 9999 minimum: 0 nullable: true description:

Customers credit score.

date_of_birth: type: string format: date nullable: true description:

The customer's date of birth.

deceased: enum: - Reported - Confirmed - '' type: string x-spec-enum-id: f90e7d899a971044 default: '' description:

Whether the customer is deceased or not. Defaults to an empty string if not provided.

x-enum-descriptions: Reported: Reported Confirmed: Confirmed '': '' details: nullable: true description:

Generic solution for storing additional customer data that is not covered by the other fields in the payload. This is often in the form of market or territory specific information. For example, in much of Europe it is a requirement to store the user's fiscal code. Namespaces (the keys in the object) need to be registered before import. If a value is provided for a namespace that is not registered then an error will be raised.

deprecated: true x-use-instead: user_details x-validators: - name: Validate user details description: Validates that the user detail namespace and value are allowed for the customer. The user detail namespace (the key in the JSON object) must already have been set up in Kraken. The value (the value in the JSON object) must be the correct data type. possible_errors: - customer_detail_failed_validation - customer_detail_incorrect_value_type - customer_detail_not_registered email: type: string format: email nullable: true description:

The customer's email address. This is the email address they will use to log into their online portal. Defaults to an empty string if not provided. Cannot be longer that 254 characters.

maxLength: 254 x-validators: - name: Validate email address is not test address description: Validates that a customer email address is not a test email address. An email address is considered a test address if it starts with "test@"" or "xxx@"" or ends with "@test.com", "@test.co.uk", ".xxx" or ".xx". possible_errors: - possible_test_email_address - name: Validate email is not internal description: Validates that a customer email address does not use an internal Kraken handler. For example, if an instance of Kraken has registered info@kraken.info as an internal email address, then the customer email address must not match this. possible_errors: - internal_email_address family_name: type: string default: '' description:

The customer's family name.

maxLength: 255 given_name: type: string default: '' description:

The customer's given name.

maxLength: 255 label: type: string nullable: true description:

A free text field to help identify the user (e.g. a job title).

landline: type: string nullable: true default: '' description:

The customer's landline phone number.

maxLength: 32 x-validators: - name: Validate phone number description: Validates that a phone number conforms to the norms of the region from which the migration is taking place. possible_errors: - invalid_phone_number mobile: type: string nullable: true default: '' description:

The customer's personal mobile number.

maxLength: 32 x-validators: - name: Validate phone number description: Validates that a phone number conforms to the norms of the region from which the migration is taking place. possible_errors: - invalid_phone_number salutation: type: string nullable: true default: '' description:

The customer's preferred salutation.

maxLength: 128 title: type: string nullable: true default: '' description:

The customer's preferred title.

maxLength: 20 unable_to_read_meters: type: boolean default: false description:

Whether the customer is unable to read their meters themselves. Defaults to False.

user_details: type: array items: $ref: '#/components/schemas/CustomerUserDetail' description:

Generic solution for storing additional customer data that is not covered by the other fields in the payload. This is often in the form of market or territory specific information. For example, in much of Europe it is a requirement to store the user's fiscal code. Namespaces (the keys in the object) need to be registered before import. If a value is provided for a namespace that is not registered then an error will be raised.

x-validators: - name: Validate required customer details namespaces provided description: No required namespaces configured. Validation skipped. possible_errors: - required_customer_details_namespace_missing required: - business_roles x-validators: - name: Ensures only user_details or details are provided description: Ensures that only user_details or details are provided, not both. possible_errors: - customer_details_and_user_details_both_provided - name: Validate no contact details for occupier description: Validates that a customer identified as "The Occupier" does not have contact details. If contact details are provided it implies that the identity of the customer is known, and it therefore not an unknown occupier. possible_errors: - contact_details_for_occupier - name: Validate that the customer's name is not "The Occupier" description: Validate that the customer's name is not "The Occupier". To indicate an occupier account, use the unknown_occupier flag at the account-level. possible_errors: - customer_may_not_be_named_the_occupier CharacteristicOverride: type: object properties: characteristic_code: type: string description:

The code for the characteristic.

override_value: description:

The override value for the characteristic.

product_code: type: string nullable: true description:

Optional product code. If specified, the override applies only to this product.

x-validators: - name: Validate product code exists description: Validate that the product code exists in Kraken. possible_errors: - product_code_does_not_exist required: - characteristic_code - override_value x-validators: - name: Validate characterisctic code exist description: Validate that the characterisctic code exists in Kraken. possible_errors: - characteristic_code_not_found - name: null description: null possible_errors: - invalid_characteristic_for_product CharacteristicOverrideConfiguration: type: object properties: term_type: type: string description:

The type of the contract term.

is_variable: type: boolean default: true description:

Whether the contract term is variable in Kraken or not. If not, it must be amended by a new contract.

overrides: type: array items: $ref: '#/components/schemas/CharacteristicOverride' description:

The characterisctics associated with the characterisctic override.

required: - overrides - term_type CollateralRequired: type: object properties: term_type: type: string description:

The type of the contract term.

amount: type: integer minimum: 0 description:

The amount set up as collateral as condition for account creation.

interest_policy: type: string description:

The type of interest policy of required collateral.

is_variable: type: boolean default: true description:

Whether the contract term is variable in Kraken or not. If not, it must be amended by a new contract.

reason: type: string description:

The reason for setting up required collateral.

required: - amount - reason - term_type ContractMetaData: type: object properties: term_type: type: string description:

The type of the contract term.

is_variable: type: boolean default: true description:

Whether the contract term is variable in Kraken or not. If not, it must be amended by a new contract.

metadata: type: object description:

Additional metadata about the contract.

x-validators: - name: Validate provided dictionary content types description: Validates that provided dictionary contents are of the specified key type and value type. possible_errors: [] required: - metadata - term_type ContractRenewal: type: object properties: type: enum: - CONTRACT_RENEWAL - ENROLLMENT type: string x-spec-enum-id: 478cba0b1c92d277 description:

The type of order line. Determines which order line serializer is used for validation.

x-enum-descriptions: CONTRACT_RENEWAL: CONTRACT_RENEWAL ENROLLMENT: ENROLLMENT agreements: type: array items: $ref: '#/components/schemas/ContractRenewalAgreementByMarketName' description:

List of agreements to create against pre-existing supply points on the business's accounts as part of this contract renewal.

contract: allOf: - $ref: '#/components/schemas/OrderManagementContractWithSubjects' description:

The contract details for a contract renewal order line.

target_reference: type: string description:

The account_identifier or business_identifier of the target entity in the payload that this order line applies to.

target_type: enum: - ACCOUNT - BUSINESS - SALES_INFO type: string x-spec-enum-id: 62f22d5e5f0f624b description:

The type of entity that target_reference points to.

x-enum-descriptions: ACCOUNT: ACCOUNT BUSINESS: BUSINESS SALES_INFO: SALES_INFO required: - contract - target_reference - target_type - type ContractRenewalAgreementByMarketName: oneOf: - $ref: '#/components/schemas/AusElectricityAgreement' - $ref: '#/components/schemas/AusEmbeddedElectricityAgreement' - $ref: '#/components/schemas/AusEmbeddedWaterAgreement' - $ref: '#/components/schemas/AusGasAgreement' - $ref: '#/components/schemas/AusEmbeddedUnmeteredGasAgreement' - $ref: '#/components/schemas/AusEmbeddedGasAgreement' - $ref: '#/components/schemas/AusSolarPpaAgreement' - $ref: '#/components/schemas/AusEmbeddedUnmeteredElectricityAgreement' discriminator: propertyName: market_name mapping: AUS_ELECTRICITY: '#/components/schemas/AusElectricityAgreement' AUS_EMBEDDED_ELECTRICITY: '#/components/schemas/AusEmbeddedElectricityAgreement' AUS_EMBEDDED_WATER: '#/components/schemas/AusEmbeddedWaterAgreement' AUS_GAS: '#/components/schemas/AusGasAgreement' AUS_EMBEDDED_UNMETERED_GAS: '#/components/schemas/AusEmbeddedUnmeteredGasAgreement' AUS_EMBEDDED_GAS: '#/components/schemas/AusEmbeddedGasAgreement' AUS_SOLAR_PPA: '#/components/schemas/AusSolarPpaAgreement' AUS_EMBEDDED_UNMETERED_ELECTRICITY: '#/components/schemas/AusEmbeddedUnmeteredElectricityAgreement' ContractSalesRecord: type: object properties: affiliate_organisation_name: type: string description:

The affiliate organisation name associated with the contract.

maxLength: 128 x-validators: - name: Validate affiliate organisation exists description: Validate that an affiliate organisation exists in Kraken for the given name. possible_errors: - affiliate_organisation_does_not_exist sales_channel: enum: - DIRECT - PRICE_COMPARISON - TELESALES - DIGI_TELESALES - EVENTS - FIELD_SALES - AGGREGATOR - PARTNERSHIPS - NEW_TENANT - MOVE_IN - WORKPLACE_POP_UP - BROKER - PARENT_POWER - PEOPLE_POWER - GIFT_OF_KIT - HIGH_REFERRER - SUPPLIER_OF_LAST_RESORT - ACQUISITION - WORKS_WITH_OCTOPUS - LANDLORD - DEBT_COLLECTION_AGENCY type: string x-spec-enum-id: f4ccf4dcda60c174 description:

The sales channel associated with the contract

x-enum-descriptions: DIRECT: Direct PRICE_COMPARISON: Price comparison TELESALES: Telesales DIGI_TELESALES: Digital telesales EVENTS: Events FIELD_SALES: Field sales AGGREGATOR: Aggregator PARTNERSHIPS: Partnerships NEW_TENANT: New tenant MOVE_IN: Move in WORKPLACE_POP_UP: Workplace pop-up BROKER: Broker PARENT_POWER: Parent power PEOPLE_POWER: People power GIFT_OF_KIT: Gift of kit HIGH_REFERRER: High referrer SUPPLIER_OF_LAST_RESORT: Supplier of last resort ACQUISITION: Acquisition WORKS_WITH_OCTOPUS: Works with octopus LANDLORD: Landlord DEBT_COLLECTION_AGENCY: Debt collection agency x-validators: - name: Sales channel matches affiliate organisation description: Validates that when an affiliate_organisation_name is provided, the sales_channel is in the set of channels configured for that organisation. possible_errors: - sales_channel_does_not_match_affiliate_organisation ContractSubject: type: object properties: effective_from: type: string format: date description:

The date from which this account is a subject of the contract. If supplied, it must fall within the contract's validity period. Optional.

effective_to: type: string format: date nullable: true description:

The date until which this account is a subject of the contract. If supplied, it must fall within the contract's validity period. Optional.

identifier: type: string description:

The identifier of the account in the payload to use as a contract subject.

type: enum: - ACCOUNT type: string x-spec-enum-id: 3e0122dd7c474703 description:

The type of entity that identifier points to. Currently only ACCOUNT is supported.

x-enum-descriptions: ACCOUNT: Account required: - identifier - type x-validators: - name: Validate ⁨effective_to⁩ not before ⁨effective_from⁩ description: Validates that ⁨effective_to⁩, if given, is on or later than ⁨effective_from⁩. possible_errors: - start_date_later_than_end_date - name: Validate contract subject effective_from is provided when effective_to is description: Validates that a contract subject's effective_from is provided whenever an effective_to is supplied. possible_errors: - required ContractVersion: type: object properties: applicable_at_date: type: string format: date description:

The date on which this contract version become applicable at.

terms: type: array items: $ref: '#/components/schemas/Terms' description:

The terms for this version of the contract.

required: - applicable_at_date - terms ContractedVolumeConfiguration: type: object properties: term_type: type: string description:

The type of the contract term.

is_variable: type: boolean default: true description:

Whether the contract term is variable in Kraken or not. If not, it must be amended by a new contract.

periods: type: array items: $ref: '#/components/schemas/ContractedVolumePeriod' description:

A list of contracted volume periods.

minItems: 1 x-validators: - name: Validate periods do not overlap per market description: Validate that sequential contracted volume periods for the same market do not overlap possible_errors: - overlapping_contracted_volume_periods required: - periods - term_type ContractedVolumePeriod: type: object properties: market_name: enum: - AUS_EMBEDDED_GAS - AUS_EMBEDDED_UNMETERED_GAS - AUS_GAS - AUS_EMBEDDED_ELECTRICITY - AUS_EMBEDDED_WATER - AUS_EMBEDDED_UNMETERED_ELECTRICITY - AUS_ELECTRICITY - AUS_SOLAR_PPA - SIMPLE_SERVICES type: string x-spec-enum-id: 2efb600dcd89ea97 description:

The market name for the contracted volume.

x-enum-descriptions: AUS_EMBEDDED_GAS: AUS_EMBEDDED_GAS AUS_EMBEDDED_UNMETERED_GAS: AUS_EMBEDDED_UNMETERED_GAS AUS_GAS: AUS_GAS AUS_EMBEDDED_ELECTRICITY: AUS_EMBEDDED_ELECTRICITY AUS_EMBEDDED_WATER: AUS_EMBEDDED_WATER AUS_EMBEDDED_UNMETERED_ELECTRICITY: AUS_EMBEDDED_UNMETERED_ELECTRICITY AUS_ELECTRICITY: AUS_ELECTRICITY AUS_SOLAR_PPA: AUS_SOLAR_PPA SIMPLE_SERVICES: SIMPLE_SERVICES unit: type: string description:

The units for the contracted volume.

valid_from_date: type: string format: date description:

The datetime the contracted volume is valid from.

valid_to_date: type: string format: date description:

The datetime the contracted volume is valid to.

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

The value of the contracted volume.

required: - market_name - unit - valid_from_date - valid_to_date - value x-validators: - name: Validate ⁨valid_to⁩ not before ⁨valid_from⁩ description: Validates that ⁨valid_to⁩, if given, is on or later than ⁨valid_from⁩. possible_errors: - start_date_later_than_end_date CorrectivePeriod: type: object properties: term_type: type: string description:

The type of the contract term.

is_variable: type: boolean default: true description:

Whether the contract term is variable in Kraken or not. If not, it must be amended by a new contract.

market_configs: type: array items: $ref: '#/components/schemas/CorrectivePeriodMarketConfig' description:

Market configurations for corrective periods

minItems: 1 required: - market_configs - term_type CorrectivePeriodMarketConfig: type: object properties: length: type: integer minimum: 1 description:

Length of the corrective period.

length_unit: enum: - DAY - WEEK - MONTH - YEAR type: string x-spec-enum-id: aaeac18e78076e3b description:

Unit of time for the corrective period length (DAY, WEEK, MONTH, YEAR).

x-enum-descriptions: DAY: DAY WEEK: WEEK MONTH: MONTH YEAR: YEAR market_name: enum: - AUS_EMBEDDED_GAS - AUS_EMBEDDED_UNMETERED_GAS - AUS_GAS - AUS_EMBEDDED_ELECTRICITY - AUS_EMBEDDED_WATER - AUS_EMBEDDED_UNMETERED_ELECTRICITY - AUS_ELECTRICITY - AUS_SOLAR_PPA - SIMPLE_SERVICES type: string x-spec-enum-id: 2efb600dcd89ea97 description:

Market name (e.g., ELECTRICITY, GAS) the corrective period applies to.

x-enum-descriptions: AUS_EMBEDDED_GAS: AUS_EMBEDDED_GAS AUS_EMBEDDED_UNMETERED_GAS: AUS_EMBEDDED_UNMETERED_GAS AUS_GAS: AUS_GAS AUS_EMBEDDED_ELECTRICITY: AUS_EMBEDDED_ELECTRICITY AUS_EMBEDDED_WATER: AUS_EMBEDDED_WATER AUS_EMBEDDED_UNMETERED_ELECTRICITY: AUS_EMBEDDED_UNMETERED_ELECTRICITY AUS_ELECTRICITY: AUS_ELECTRICITY AUS_SOLAR_PPA: AUS_SOLAR_PPA SIMPLE_SERVICES: SIMPLE_SERVICES supply_point_ids: type: array items: type: integer minimum: 1 nullable: true description:

Supply Point IDs the corrective period applies to.

minItems: 1 required: - length - length_unit - market_name CustomerAlternativeNumber: type: object properties: phone_number: type: string nullable: true default: '' description:

A customer's alternative phone number.

maxLength: 32 x-validators: - name: Validate phone number description: Validates that a phone number conforms to the norms of the region from which the migration is taking place. possible_errors: - invalid_phone_number CustomerUserDetail: type: object properties: namespace: enum: - external_user_id type: string x-spec-enum-id: 6bb07f5044ea9b8a description:

The namespace of the customer user detail.

x-enum-descriptions: external_user_id: external_user_id value: description:

The value of the customer user detail.

required: - namespace - value x-validators: - name: Validate user details description: Validates that the user detail namespace and value are allowed for the customer. The user detail namespace (the key in the JSON object) must already have been set up in Kraken. The value (the value in the JSON object) must be the correct data type. possible_errors: - customer_detail_failed_validation - customer_detail_incorrect_value_type - customer_detail_not_registered DelayerDays: type: object properties: term_type: type: string description:

The type of the contract term.

days: type: integer minimum: 1 description:

The number of days between when a reactive payment is triggered and when it should be taken.

is_variable: type: boolean default: true description:

Whether the contract term is variable in Kraken or not. If not, it must be amended by a new contract.

strategy: enum: - FIXED - WORKING_DAYS type: string x-spec-enum-id: b62f1d43e0839f86 description:

The strategy used to count the delayer days.

x-enum-descriptions: FIXED: Calendar days WORKING_DAYS: Working days required: - days - strategy - term_type EffectivePeriod: type: object properties: end_date: type: string format: date description:

The effective period end date (exclusive).

start_date: type: string format: date description:

The effective period start date (inclusive).

required: - start_date ErrorResponse: type: object properties: code: type: string description:

The code for the error.

detail: type: string description:

A description of the error.

required: - code - detail ExistingAccount: type: object properties: type: enum: - EXISTING - NEW type: string x-spec-enum-id: 3c90de91ea29153f description:

The type of account target. Determines which account serializer is used for validation.

x-enum-descriptions: EXISTING: EXISTING NEW: NEW account_identifier: type: string description:

An internal reference identifier for this account target within the order payload.

account_number: type: string description:

The account number of the existing account in Kraken.

x-validators: - name: Validate account number format description: Validate that the account number matches the expected Kraken account number format (A- followed by 8 hexadecimal characters). possible_errors: - invalid_account_number_format business_reference: type: string description:

The business_identifier of the business target in the payload that this account belongs to.

required: - account_identifier - account_number - type ExistingBusiness: type: object properties: type: enum: - EXISTING - NEW type: string x-spec-enum-id: 3c90de91ea29153f description:

The type of business target. Determines which business serializer is used for validation.

x-enum-descriptions: EXISTING: EXISTING NEW: NEW business_identifier: type: string description:

An internal reference identifier for this business target within the order payload.

business_type: enum: - SOLE_TRADER - LTD - PTY_LTD - PARTNERSHIP - CHARITY - PLC - LLP - TRUST - TRADING_AS - GOVERNMENT - NON_PROFIT - CHURCH - HOMEOWNER_ASSOCIATION - TBD type: string x-spec-enum-id: 8cd3a9d2ed8d5378 description:

The type of business this account related to. The business type can only be provided for business accounts.

x-enum-descriptions: SOLE_TRADER: Sole trader LTD: Limited PTY_LTD: Proprietary Limited Company PARTNERSHIP: Partnership CHARITY: Charity PLC: Public limited company LLP: Limited liability partnership TRUST: Trust TRADING_AS: Trading as GOVERNMENT: Government NON_PROFIT: Non profit CHURCH: Church HOMEOWNER_ASSOCIATION: Homeowner association TBD: To be determined company_name: type: string description:

The company name for a business account.

maxLength: 255 company_number: type: string description:

The company number for a business account.

maxLength: 100 x-validators: - name: Validate company number description: Validate the company number and standardize its format. possible_errors: - invalid_company_number details: type: array items: $ref: '#/components/schemas/BusinessDetail' description:

Generic solution for storing additional business data that is not covered by the other fields in the payload. This is often in the form of market or territory specific information. Keys must be registered in Kraken and will have a value type the value for the key must confirm to.

x-validators: - name: Validate that each child has unique values for the ⁨key⁩ field description: Validate that each child has unique values for the ⁨key⁩ field. possible_errors: - children_with_duplicate_values parent_business_reference: type: string description:

The business_identifier of another business target in the payload that is the parent of this business, used to express business hierarchies.

portfolios: type: array items: $ref: '#/components/schemas/BusinessPortfolio' description:

Information about the portfolios associated with this business.

segment_name: x-spec-enum-id: 4f53cda18c2baa0c description:

The segment to which the business belongs.

x-comment: Choices for this field are dynamic, once appropriate values have been configured they will be rendered here. users: type: array items: $ref: '#/components/schemas/BusinessUser' description:

List of the business users associated with the business.

required: - business_identifier - type x-validators: - name: Validate that lookup identifiers are provided for an existing business description: 'Validate that at least one viable lookup mechanism is provided for an existing business: either all core fields (company_name, company_number, business_type) or at least one entry in details.' possible_errors: - business_lookup_identifier_required GuaranteeOfOriginConfiguration: type: object properties: term_type: type: string description:

The type of the contract term.

guarantee_of_origin_percentage: enum: - 0 - 25 - 50 - 75 - 100 type: integer x-spec-enum-id: fb9427e17f642d36 description: data-import--field-definition--guarantee-of-origin-configuration--guarantee-of-origin-percentage-help x-enum-descriptions: '0': '0' '25': '25' '50': '50' '75': '75' '100': '100' is_variable: type: boolean default: true description:

Whether the contract term is variable in Kraken or not. If not, it must be amended by a new contract.

required: - guarantee_of_origin_percentage - term_type ImportEvent: type: object properties: data: type: object nullable: true description:

Additional data associated with the import event, such as error codes and details.

event: type: string description:

The type of import event.

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

The date and time when the import event was recorded.

required: - event - occurred_at ImportStatusResponse: type: object properties: created_at: type: string format: date-time description:

The date and time when the import process was created.

kraken_identifier: type: string nullable: true description:

The unique identifier assigned to this import within Kraken.

latest_error: allOf: - $ref: '#/components/schemas/LatestError' nullable: true description:

The most recent error that occurred during the import process, if any.

latest_event: allOf: - $ref: '#/components/schemas/ImportEvent' description:

The most recent import event associated with the import process, if any.

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

The date and time when the import process was last modified.

status: type: string description:

The current status of the import process.

required: - created_at - latest_event - modified_at - status IndexationOption: type: object properties: escalation_start_date: type: string format: date description:

Date the indexation applies from.

index_code: type: string description:

The code for the relevant index.

required: - escalation_start_date - index_code LatePaymentFees: type: object properties: term_type: type: string description:

The type of the contract term.

flat_fee_amount: type: integer minimum: 0 description:

The flat amount added to each late payment fee, in the lowest denomination for the currency.

interest_policy_name: enum: - '' - RBA type: string x-spec-enum-id: 755d70bd45dbabbb description:

The interest policy to use for late payment fee calculations.

x-enum-descriptions: '': '---------' RBA: RBA is_variable: type: boolean default: true description:

Whether the contract term is variable in Kraken or not. If not, it must be amended by a new contract.

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

The percentage fee to be applied as part of the late payment fee calculations.

percentage_interval_days: type: integer minimum: 0 description:

The interval the percentage fee rate represents in days (365 = annual).

required: - flat_fee_amount - percentage_fee - percentage_interval_days - term_type LatestError: type: object properties: code: type: string nullable: true description:

The error code identifying the type of error that occurred.

detail: type: string nullable: true description:

A detailed description of the error that occurred.

domain: type: string nullable: true description:

The domain or context in which the error occurred.

Metadata: type: object properties: key: type: string description:

The key on which the metadata will be stored on.

maxLength: 1024 value: description:

A json object containing any arbitrary piece of data to store in relation to the account.

required: - key - value MinimumContractLength: type: object properties: term_type: type: string description:

The type of the contract term.

contract_identifier: type: string description:

Unique identifier of the contract.

is_variable: type: boolean default: true description:

Whether the contract term is variable in Kraken or not. If not, it must be amended by a new contract.

length: type: integer minimum: 1 description:

Minimum length of the contract.

unit_of_time: enum: - WEEK - MONTH - YEAR type: string x-spec-enum-id: 2dd8361d760ce9df description:

Unit of time used to measure the length of the contract.

x-enum-descriptions: WEEK: Week MONTH: Month YEAR: Year required: - contract_identifier - length - term_type - unit_of_time NewAccount: type: object properties: type: enum: - EXISTING - NEW type: string x-spec-enum-id: 3c90de91ea29153f description:

The type of account target. Determines which account serializer is used for validation.

x-enum-descriptions: EXISTING: EXISTING NEW: NEW account_identifier: type: string description:

An internal reference identifier for this account target within the order payload.

account_type: enum: - Business - Domestic - Business Occupier - Occupier - Managed type: string x-spec-enum-id: ff3f2524baf2f6e8 description: data-import--field-definition--order-new-account--account-type--html x-enum-descriptions: Business: Business Domestic: Domestic Business Occupier: Business Occupier Occupier: Occupier Managed: Managed billing_information: allOf: - $ref: '#/components/schemas/BillingInformation' description: data-import--field-definition--base-account--billing-information--html brand_code: enum: - ORIGIN - ORIGIN_ZERO - FIRST_ENERGY type: string x-spec-enum-id: 48b17e6cf5372987 description: data-import--field-definition--order-new-account--brand-code--html x-enum-descriptions: ORIGIN: Origin ORIGIN_ZERO: Origin Zero FIRST_ENERGY: 1st Energy business_reference: type: string description:

The business_identifier of the business target in the payload that this account belongs to.

metadata: type: array items: $ref: '#/components/schemas/Metadata' description:

An array of key value pairs for storing generic metadata relating to an account. Metadata is externally focused and is not used for any logic within Kraken. Its main motivation is to provide a simple persistence mechanism for clients building their own integrations with Kraken. If a customer already exists in Kraken with existing metadata for the provided key, the value associated with this key will be overwritten.

references: type: array items: $ref: '#/components/schemas/AccountReference' description:

List of account references for the account. An example may be a secondary account number.

required: - account_identifier - account_type - billing_information - brand_code - type NewBusiness: type: object properties: type: enum: - EXISTING - NEW type: string x-spec-enum-id: 3c90de91ea29153f description:

The type of business target. Determines which business serializer is used for validation.

x-enum-descriptions: EXISTING: EXISTING NEW: NEW business_identifier: type: string description:

An internal reference identifier for this business target within the order payload.

business_type: enum: - SOLE_TRADER - LTD - PTY_LTD - PARTNERSHIP - CHARITY - PLC - LLP - TRUST - TRADING_AS - GOVERNMENT - NON_PROFIT - CHURCH - HOMEOWNER_ASSOCIATION - TBD type: string x-spec-enum-id: 8cd3a9d2ed8d5378 description:

The type of business this account related to. The business type can only be provided for business accounts.

x-enum-descriptions: SOLE_TRADER: Sole trader LTD: Limited PTY_LTD: Proprietary Limited Company PARTNERSHIP: Partnership CHARITY: Charity PLC: Public limited company LLP: Limited liability partnership TRUST: Trust TRADING_AS: Trading as GOVERNMENT: Government NON_PROFIT: Non profit CHURCH: Church HOMEOWNER_ASSOCIATION: Homeowner association TBD: To be determined company_name: type: string description:

The company name for a business account.

maxLength: 255 company_number: type: string description:

The company number for a business account.

maxLength: 100 x-validators: - name: Validate company number description: Validate the company number and standardize its format. possible_errors: - invalid_company_number details: type: array items: $ref: '#/components/schemas/BusinessDetail' description:

Generic solution for storing additional business data that is not covered by the other fields in the payload. This is often in the form of market or territory specific information. Keys must be registered in Kraken and will have a value type the value for the key must confirm to.

x-validators: - name: Validate that each child has unique values for the ⁨key⁩ field description: Validate that each child has unique values for the ⁨key⁩ field. possible_errors: - children_with_duplicate_values parent_business_reference: type: string description:

The business_identifier of another business target in the payload that is the parent of this business, used to express business hierarchies.

portfolios: type: array items: $ref: '#/components/schemas/BusinessPortfolio' description:

Information about the portfolios associated with this business.

segment_name: x-spec-enum-id: 4f53cda18c2baa0c description:

The segment to which the business belongs.

x-comment: Choices for this field are dynamic, once appropriate values have been configured they will be rendered here. users: type: array items: $ref: '#/components/schemas/BusinessUser' description:

List of the business users associated with the business.

maxItems: 1 required: - business_identifier - type 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 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 Order: type: object properties: accounts: type: array items: $ref: '#/components/schemas/OrderAccount' description:

A list of account targets for the order.

businesses: type: array items: $ref: '#/components/schemas/OrderBusiness' description:

A list of business targets for the order.

external_order_id: type: string description:

A unique identifier for the order in the external system.

order_lines: type: array items: $ref: '#/components/schemas/OrderLine' description:

A list of order lines describing the operations to perform.

sales_info: allOf: - $ref: '#/components/schemas/SalesInfo' description:

Sales information associated with the order.

required: - accounts - businesses - external_order_id - order_lines x-validators: - name: Validate that each business's parent reference resolves description: Validate that every parent_business_reference refers to another business in the payload, that no business references itself as its own parent, and that no chain of parent references forms a cycle. possible_errors: - circular_parent_business_reference - dangling_parent_business_reference - self_referencing_parent_business - name: Validate that all businesses are targeted by an order line description: Validate that every business in the payload is either directly targeted by an order line or has an ancestor (via parent_business_reference) that is targeted by an order line. possible_errors: - orphaned_businesses - name: Validate that contract renewal order lines target an existing business description: Validate that any contract renewal order line with target_type of BUSINESS references a business with type of EXISTING. possible_errors: - contract_renewal_business_target_must_be_existing - name: Validate that enrollment order lines target a new business description: Validate that any enrollment order line with target_type of BUSINESS references a business with type of NEW. possible_errors: - enrollment_business_target_must_be_new - name: Validate that existing account numbers are unique description: Validate that each existing account number appears at most once in the accounts list. possible_errors: - duplicate_existing_account_number - name: Validate that contract-level sales info is not provided description: When order-level sales info is required, sales_info and the deprecated sales_record must not be set on any contract in the order. Provide sales info at the order level instead. possible_errors: [] OrderAccount: oneOf: - $ref: '#/components/schemas/ExistingAccount' - $ref: '#/components/schemas/NewAccount' discriminator: propertyName: type mapping: EXISTING: '#/components/schemas/ExistingAccount' NEW: '#/components/schemas/NewAccount' OrderBusiness: oneOf: - $ref: '#/components/schemas/ExistingBusiness' - $ref: '#/components/schemas/NewBusiness' discriminator: propertyName: type mapping: EXISTING: '#/components/schemas/ExistingBusiness' NEW: '#/components/schemas/NewBusiness' OrderLine: oneOf: - $ref: '#/components/schemas/ContractRenewal' discriminator: propertyName: type mapping: CONTRACT_RENEWAL: '#/components/schemas/ContractRenewal' OrderManagementContractWithSubjects: type: object properties: identifier: type: string description:

The contract's unique identifier.

sales_record: allOf: - $ref: '#/components/schemas/ContractSalesRecord' description:

Sales record details about the contract.

deprecated: true x-use-instead: sales_info signed_at_date: type: string format: date description:

The date on which the contract was signed.

subjects: type: array items: $ref: '#/components/schemas/ContractSubject' description:

A list of accounts to use as the subject of the contract.

minItems: 1 valid_from_date: type: string format: date description: '

The date from which the contract is valid. This is an inclusive date. Example: If valid_from is October 1, 2024, then the contract is valid on October 1, 2024 and following dates.

' valid_to_date: type: string format: date nullable: true description: '

The date on which the contract expires. This is an exclusive date. Example: If valid_to is October 1, 2025, then the contract is not valid on October 1, 2025 or following dates.

' versions: type: array items: $ref: '#/components/schemas/ContractVersion' description:

The versions of this contract, each version is a collection of terms and the date they are applicable. Only two versions can be provided, one which starts on the same date as the contract is valid from and one other future dated version to be scheduled.

maxItems: 2 required: - identifier - signed_at_date - subjects - valid_from_date x-validators: - name: Validate that contract versions include a version for the current terms description: Validate that the earliest version in the list of contract versions provided has an applicable_at_date that is equal to the contract valid_from_date. possible_errors: - contract_versions_does_not_include_current - name: Validate contract subject periods fall within the contract description: Validates that each contract subject's supplied valid_from and valid_to dates fall within the contract's own validity period. possible_errors: - invalid_period PartnerCommission: type: object properties: term_type: type: string description:

The type of the contract term.

configurations: type: array items: $ref: '#/components/schemas/PartnerCommissionConfig' description:

List of partner commission configurations to associate with this contract term.

minItems: 1 x-validators: - name: Validate partner commission numbers exist description: Validate that all partner commission numbers in the term configurations exist in Kraken. possible_errors: - not_found is_variable: type: boolean default: true description:

Whether the contract term is variable in Kraken or not. If not, it must be amended by a new contract.

required: - configurations - term_type PartnerCommissionConfig: type: object properties: apply_uplift: type: boolean default: false description:

Whether to apply a product uplift for this partner commission. Defaults to false.

override_trailing_percentage: type: string format: decimal pattern: ^-?\d{0,3}(?:\.\d{0,2})?$ nullable: true description:

Optional override for the trailing commission percentage. Overrides the default percentage on the partner commission.

override_unit_amount: type: string format: decimal pattern: ^-?\d{0,8}(?:\.\d{0,8})?$ nullable: true description:

Optional override for the unit-based commission rate. Overrides the default unit amount on the partner commission.

partner_commission_number: type: string description:

The unique identifier of the partner commission (e.g. OPC-XXXXXXXX or TPC-XXXXXXXX).

maxLength: 20 required: - partner_commission_number PaysByDirectDebitTerm: type: object properties: term_type: type: string description:

The type of the contract term.

is_variable: type: boolean default: true description:

Whether the contract term is variable in Kraken or not. If not, it must be amended by a new contract.

pays_by_direct_debit: type: boolean description:

Whether the customer pays by direct debit.

required: - pays_by_direct_debit - term_type PortfolioReference: type: object properties: namespace: enum: - external-portfolio-reference-id - portfolio-label type: string x-spec-enum-id: 9c7783add2be9a67 description:

The namespace refers to the particular context the reference exists in. This must be one of the following options below if a portfolio reference is being provided.

x-enum-descriptions: external-portfolio-reference-id: external-portfolio-reference-id portfolio-label: portfolio-label value: type: string description:

The unique identifier for the portfolio.

maxLength: 100 required: - namespace - value PortfolioSettings: type: object properties: collective_billing: type: boolean default: false description:

Set all accounts on the portfolio to be billed collectively. This value can only be provided if the account is the portfolio lead account.

collective_payments: type: boolean default: false description:

Set all accounts on the portfolio to pay collectively. This value can only be provided if the account is the portfolio lead account.

delegate_billing_schedule_to_children: type: boolean default: false description:

When using collective billing, use the child account's billing options to determine when we charge and prepare billing documents (as opposed to using the lead account's options). This value can only be provided if the account is the portfolio lead account.

send_collective_bill_constituent_messages: type: boolean default: false description:

When using collective billing, send collective bill constituent messages to each member of the collective bill. This value can only be provided if the account is the portfolio lead account.

ProductCharacteristic: oneOf: - $ref: '#/components/schemas/SalesChannelCharacteristic' discriminator: propertyName: code mapping: sales_channel: '#/components/schemas/SalesChannelCharacteristic' x-validators: - name: Validate that characteristics.code and characteristics.value are valid description: Ensure that the characteristic code exists and the characteristic value is valid for the given code. possible_errors: - characteristic_code_not_found - invalid_characteristic_value ProductRateOverrideConfiguration: type: object properties: term_type: type: string description:

The type of the contract term.

indexation_options: allOf: - $ref: '#/components/schemas/IndexationOption' description:

The indexation options for the product rate override.

is_variable: type: boolean default: true description:

Whether the contract term is variable in Kraken or not. If not, it must be amended by a new contract.

schedules: type: array items: $ref: '#/components/schemas/ProductRateOverrideSchedule' description:

The schedule associated with the product rate override.

required: - schedules - term_type ProductRateOverrideItemByRateBand: type: object properties: price_per_unit: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,5})?$ description:

The price per unit of the item.

product_code: type: string description:

The product code of the item.

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

The override rate of the item.

required: - price_per_unit - product_code - rate_band x-validators: - name: Validate that the rate band is valid for the product code description: Validate that the rate band provided matches the rate band for the product's rates with the provided product code. possible_errors: - rate_band_not_found_for_product ProductRateOverrideItemByVariantProfile: type: object properties: characteristic_values: type: object description:

The characteristic values of the product rate override item.

x-validators: - name: Validate provided dictionary content types description: Validates that provided dictionary contents are of the specified key type and value type. possible_errors: [] price_per_unit: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,5})?$ description:

The override rate of the item.

product_code: type: string description:

The product code of the item.

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

The rate specification code of the item.

scheme_labels: type: object description:

The scheme labels of the product rate override item.

x-validators: - name: Validate provided dictionary content types description: Validates that provided dictionary contents are of the specified key type and value type. possible_errors: [] required: - price_per_unit - product_code - rate_specification_code x-validators: - name: Validate that the rate band is valid for the product code description: Validate that the rate band provided matches the rate band for the product's rates with the provided product code. possible_errors: - characteristic_code_not_found - invalid_characteristic_value - invalid_variant_profile_for_product - product_specification_not_found_for_product - rate_specification_not_found_for_product ProductRateOverrideSchedule: type: object properties: effective_from: type: string format: date-time description: '

The date on which the schedule goes into effect. This is an inclusive date. Example: If the effective_from is October 1, 2024, then the schedule is valid on October 1, 2024 and following dates.

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

The items specified by rate band affected by the override during this schedule.

variant_items: type: array items: $ref: '#/components/schemas/ProductRateOverrideItemByVariantProfile' description:

The items specified by characteristic values affected by the override during this schedule.

required: - effective_from x-validators: - name: Validate that rate override schedule item must include rate overrides. description: Validate that rate override schedule item must include at least 'items' or 'characteristic_items' values. possible_errors: - rate_override_items_required PromotionAssignmentSchedule: type: object properties: discount_targets: type: object additionalProperties: type: array items: $ref: '#/components/schemas/PromotionAssignmentTarget' description:

Mapping of discount code to a list of targets the discount applies to.

params: type: object description: '

Optional parameters for the promotion assignment schedule. Supports the following keys: promotion_start_date — an ISO 8601 datetime string (e.g. 2024-01-15T00:00:00+00:00) that overrides the date used when calculating promotion eligibility (e.g. months since sign-up). If omitted, the date is derived from the customer''s agreement.

' promotion_code: type: string description:

The promotion code to apply.

required: - discount_targets - promotion_code x-validators: - name: Promotion assignment discount targets are valid description: Validates that the promotion exists, discounts are defined in the promotion, target types match the discount target type, and target identifiers are valid. possible_errors: - discount_not_in_promotion - invalid_input_data - promotion_not_registered - rate_source_provider_not_registered - source_data_not_supported_for_fixed_rate - source_data_reference_mismatch - target_identifier_invalid - target_type_mismatch - target_type_not_registered - name: Promotion assignment params are valid description: Validates that the params field contains only valid values. If promotion_start_date is provided, it must be a valid ISO 8601 datetime string. possible_errors: - invalid_promotion_start_date PromotionAssignmentTarget: type: object properties: displayed_on_bill: type: boolean default: true description:

Whether this discount should be displayed as a line item on customer bills. Defaults to true. Set to false to hide the discount from bills while still applying it.

identifier: type: string description:

The identifier for the target. Format is <product_specification_identifier>:<specification_code> (e.g., for rate specifications or shared rates).

source_data: type: object description: '

Optional configuration data used by rate providers to resolve discount rates. The structure depends on the rate provider (e.g., {"bespoke_amount": "0.05"} for bespoke rates).

' target_type: type: string description:

The type of target being discounted. Use rate_specification to target a product catalog rate specification, or shared_rate to target a shared rate.

required: - identifier - target_type PromotionAssignmentTerm: type: object properties: term_type: type: string description:

The type of the contract term.

is_variable: type: boolean default: true description:

Whether the contract term is variable in Kraken or not. If not, it must be amended by a new contract.

schedules: type: array items: $ref: '#/components/schemas/PromotionAssignmentSchedule' description:

The list of promotion assignment schedules.

minItems: 1 required: - schedules - term_type RateGroupEligibilityConfiguration: type: object properties: term_type: type: string description:

The type of the contract term.

is_variable: type: boolean default: true description:

Whether the contract term is variable in Kraken or not. If not, it must be amended by a new contract.

schedules: type: array items: $ref: '#/components/schemas/RateGroupEligibilitySchedule' description:

Rate group eligibility schedules.

time_series_specification_schedules: type: array items: $ref: '#/components/schemas/TimeSeriesSpecificationEligibilitySchedule' description:

Shared rate eligibility schedules.

required: - schedules - term_type - time_series_specification_schedules RateGroupEligibilitySchedule: type: object properties: effective_period: allOf: - $ref: '#/components/schemas/EffectivePeriod' description:

The effective period of the schedule.

is_eligible: type: boolean description:

Whether the rate group is eligible for charging to the customer.

product_code: type: string description:

Product code.

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

The unique rate group code for the product.

supply_point_identifier: type: string description:

Optional supply point identifier to restrict this schedule to a specific supply point.

required: - effective_period - is_eligible - product_code - rate_group_code x-validators: - name: Validate that the rate group code is valid for the product code description: Validate that the rate group code provided matches the rate group for the product with the provided product code. possible_errors: - rate_group_not_found_for_product SalesChannelCharacteristic: type: object properties: code: enum: - sales_channel type: string x-spec-enum-id: 03e433a571effc5f description:

The code for the product's characteristic.

x-enum-descriptions: sales_channel: sales_channel value: enum: - PARTNERSHIPS - AGGREGATOR - EVENTS - WORKPLACE_POP_UP - GIFT_OF_KIT - TELESALES - LANDLORD - DEBT_COLLECTION_AGENCY - NEW_TENANT - FIELD_SALES - HIGH_REFERRER - PARENT_POWER - WORKS_WITH_OCTOPUS - SUPPLIER_OF_LAST_RESORT - DIGI_TELESALES - DIRECT - ACQUISITION - PRICE_COMPARISON - BROKER - MOVE_IN - PEOPLE_POWER type: string x-spec-enum-id: 2c5347e84652fd95 description:

The value for the product's characteristic.

x-enum-descriptions: PARTNERSHIPS: PARTNERSHIPS AGGREGATOR: AGGREGATOR EVENTS: EVENTS WORKPLACE_POP_UP: WORKPLACE_POP_UP GIFT_OF_KIT: GIFT_OF_KIT TELESALES: TELESALES LANDLORD: LANDLORD DEBT_COLLECTION_AGENCY: DEBT_COLLECTION_AGENCY NEW_TENANT: NEW_TENANT FIELD_SALES: FIELD_SALES HIGH_REFERRER: HIGH_REFERRER PARENT_POWER: PARENT_POWER WORKS_WITH_OCTOPUS: WORKS_WITH_OCTOPUS SUPPLIER_OF_LAST_RESORT: SUPPLIER_OF_LAST_RESORT DIGI_TELESALES: DIGI_TELESALES DIRECT: DIRECT ACQUISITION: ACQUISITION PRICE_COMPARISON: PRICE_COMPARISON BROKER: BROKER MOVE_IN: MOVE_IN PEOPLE_POWER: PEOPLE_POWER required: - code - value SalesInfo: type: object properties: affiliate_link_identifier: type: string description:

The affiliate link's identifier, used to attribute the sale to an affiliate.

affiliate_organisation_name: type: string description:

The name of the affiliate organisation the sale is attributed to. When provided alongside sales_channel, the channel must be valid for the organisation.

affiliate_query_params: description:

Arbitrary affiliate tracking parameters captured at sign-up, stored as a JSON object.

date_of_sale: type: string format: date description:

The date the sale was made (ISO 8601, YYYY-MM-DD).

offer_group_identifier: type: string format: uuid description:

The identifier (UUID) of the offer group associated with the sale.

referral_code: type: string description:

The referral code the customer signed up with (the referring account's code).

sales_channel: enum: - DIRECT - PRICE_COMPARISON - TELESALES - DIGI_TELESALES - EVENTS - FIELD_SALES - AGGREGATOR - PARTNERSHIPS - NEW_TENANT - MOVE_IN - WORKPLACE_POP_UP - BROKER - PARENT_POWER - PEOPLE_POWER - GIFT_OF_KIT - HIGH_REFERRER - SUPPLIER_OF_LAST_RESORT - ACQUISITION - WORKS_WITH_OCTOPUS - LANDLORD - DEBT_COLLECTION_AGENCY type: string x-spec-enum-id: f4ccf4dcda60c174 description:

The sales channel the sale is attributed to. Must be a valid configured sales channel.

x-enum-descriptions: DIRECT: Direct PRICE_COMPARISON: Price comparison TELESALES: Telesales DIGI_TELESALES: Digital telesales EVENTS: Events FIELD_SALES: Field sales AGGREGATOR: Aggregator PARTNERSHIPS: Partnerships NEW_TENANT: New tenant MOVE_IN: Move in WORKPLACE_POP_UP: Workplace pop-up BROKER: Broker PARENT_POWER: Parent power PEOPLE_POWER: People power GIFT_OF_KIT: Gift of kit HIGH_REFERRER: High referrer SUPPLIER_OF_LAST_RESORT: Supplier of last resort ACQUISITION: Acquisition WORKS_WITH_OCTOPUS: Works with octopus LANDLORD: Landlord DEBT_COLLECTION_AGENCY: Debt collection agency sales_subchannel: type: string description:

An optional sub-segmentation of the sales channel. Only available while self-serve sales channels are disabled.

urn: type: string description:

Unique reference number from a 3rd party enrollment, e.g. UN60031712.

required: - date_of_sale - sales_channel x-validators: - name: Sales channel matches affiliate organisation description: Validates that when an affiliate_organisation_name is provided, the sales_channel is in the set of channels configured for that organisation. possible_errors: - sales_channel_does_not_match_affiliate_organisation ScheduleOrder: type: object properties: payload: allOf: - $ref: '#/components/schemas/Order' description:

The payload to be used during creation.

task_params: allOf: - $ref: '#/components/schemas/TaskParameters' description:

The parameters that control when and how Kraken will execute this task.

required: - payload - task_params StandardizedError: type: object properties: attr: type: string description:

The attribute that the error relates to, if applicable.

code: type: string description:

The code for the error.

detail: type: string description:

A description of the error.

required: - attr - code - detail StandardizedValidationErrorResponse: type: object properties: code: type: string description:

The code for the error.

detail: type: string description:

A description of the error.

errors: type: array items: $ref: '#/components/schemas/StandardizedError' description:

A list of field-specific errors.

required: - code - detail - errors SupplyPointTaxAdjustment: type: object properties: adjustment_type: enum: - EXEMPTION - REDUCTION type: string x-spec-enum-id: '7048963418647159' description:

The type of tax adjustment (EXEMPTION or REDUCTION).

x-enum-descriptions: EXEMPTION: Exemption REDUCTION: Reduction effective_from_date: type: string format: date description:

The date the tax adjustment is effective from.

effective_to_date: type: string format: date nullable: true description:

The date the tax adjustment is effective to (inclusive, optional).

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

The normalised percentage of energy use on the supply point that qualifies for the tax adjustment (between 0 and 1).

supply_point_external_identifier: type: string description:

The external identifier of the supply point this tax adjustment applies to.

maxLength: 255 tax_category: type: string description:

The category of tax this adjustment applies to.

maxLength: 50 tax_subcategory: type: string default: '' description:

The subcategory of tax this adjustment applies to (optional).

maxLength: 50 required: - adjustment_type - effective_from_date - qualifying_usage - supply_point_external_identifier - tax_category x-validators: - name: Convert supply point external identifier to ID description: Convert the supply point external identifier to the internal supply point ID by looking up the supply point in the database. possible_errors: - supply_point_not_found - name: Validate ⁨effective_to⁩ not before ⁨effective_from⁩ description: Validates that ⁨effective_to⁩, if given, is on or later than ⁨effective_from⁩. possible_errors: - start_date_later_than_end_date TaskParameters: type: object properties: is_dry_run: type: boolean default: false description:

Whether a scheduled account creation task is part of a dry run.

schedule_window_end: type: string format: date-time nullable: true description:

The end of a window in which a scheduled account creation task can be executed.

x-validators: - name: Validate that schedule_window_end does not exceed 4 days in the future description: Validate that the schedule_window_end is not more than 4 days in the future. possible_errors: - schedule_window_end_too_far_in_future schedule_window_start: type: string format: date-time nullable: true description:

The start of a window in which a scheduled account creation task can be executed.

x-validators: - name: Validate that schedule_window_start is not in the past. description: Validate that the schedule_window_start is not in the past. possible_errors: - schedule_window_start_in_past x-validators: - name: Populate start and end date times, and ensures start is before end description: Populates schedule_window_start and schedule_window_end with default values if necessary. Also ensures that the schedule_window_start is before the schedule_window_end. possible_errors: - schedule_window_start__after_end TaxAdjustmentConfiguration: type: object properties: term_type: type: string description:

The type of the contract term.

adjustments: type: array items: $ref: '#/components/schemas/SupplyPointTaxAdjustment' description:

A list of tax adjustments for supply points.

minItems: 0 x-validators: - name: Validate tax adjustments do not overlap description: Validate that tax adjustments for the same supply point, adjustment type, tax category, and tax subcategory do not have overlapping effective periods. possible_errors: - overlapping_tax_adjustments is_variable: type: boolean default: true description:

Whether the contract term is variable in Kraken or not. If not, it must be amended by a new contract.

required: - adjustments - term_type TerminationFee: type: object properties: term_type: type: string description:

The type of the contract term.

amount: type: integer description:

The fee amount in the lowest currency unit. For example, this amount could be represented in cents, pence, etc.

fee_type: enum: - FLAT - WHOLE_MONTHS_REMAINING - WHOLE_DAYS_REMAINING type: string x-spec-enum-id: ac778cd433d63345 description:

The type, or nature, of the fee. For example, the fee can be flat or pertain to the amount of time remaining in the contract.

x-enum-descriptions: FLAT: contracts--terms--termination-fee-fee-type-flat WHOLE_MONTHS_REMAINING: Per month remaining WHOLE_DAYS_REMAINING: Per day remaining is_variable: type: boolean default: true description:

Whether the contract term is variable in Kraken or not. If not, it must be amended by a new contract.

supply_type: enum: - ELECTRICITY - GAS - UNMETERED_GAS - UNMETERED_ELECTRICITY - EMBEDDED_WATER - EMBEDDED_ELECTRICITY - EMBEDDED_GAS - SOLAR_PPA type: string x-spec-enum-id: b30233ba99cda713 description:

The supply type being terminated.

x-enum-descriptions: ELECTRICITY: Electricity GAS: Gas UNMETERED_GAS: Unmetered Gas UNMETERED_ELECTRICITY: Unmetered Electricity EMBEDDED_WATER: Embedded Water EMBEDDED_ELECTRICITY: Embedded Electricity EMBEDDED_GAS: Embedded Gas SOLAR_PPA: Solar PPA required: - amount - fee_type - term_type x-validators: - name: Validate that ⁨supply_type⁩ and ⁨market_name⁩ are not both provided description: Validate that ⁨supply_type⁩ and ⁨market_name⁩ are not both provided. possible_errors: - fields_are_mutually_exclusive Terms: oneOf: - $ref: '#/components/schemas/BespokeRateConfiguration' - $ref: '#/components/schemas/BillDueDate' - $ref: '#/components/schemas/BillingDocumentIssuanceFrequencyTerm' - $ref: '#/components/schemas/CharacteristicOverrideConfiguration' - $ref: '#/components/schemas/CollateralRequired' - $ref: '#/components/schemas/ContractMetaData' - $ref: '#/components/schemas/ContractedVolumeConfiguration' - $ref: '#/components/schemas/CorrectivePeriod' - $ref: '#/components/schemas/DelayerDays' - $ref: '#/components/schemas/GuaranteeOfOriginConfiguration' - $ref: '#/components/schemas/LatePaymentFees' - $ref: '#/components/schemas/MinimumContractLength' - $ref: '#/components/schemas/PartnerCommission' - $ref: '#/components/schemas/PaysByDirectDebitTerm' - $ref: '#/components/schemas/ProductRateOverrideConfiguration' - $ref: '#/components/schemas/PromotionAssignmentTerm' - $ref: '#/components/schemas/RateGroupEligibilityConfiguration' - $ref: '#/components/schemas/TrancheTargetResidualFee' - $ref: '#/components/schemas/TaxAdjustmentConfiguration' - $ref: '#/components/schemas/TerminationFee' - $ref: '#/components/schemas/AusEEPAExportContractedVolumeConfiguration' discriminator: propertyName: term_type mapping: BESPOKE_RATE_CONFIGURATION: '#/components/schemas/BespokeRateConfiguration' BILL_DUE_DATE: '#/components/schemas/BillDueDate' ISSUANCE_FREQUENCY: '#/components/schemas/BillingDocumentIssuanceFrequencyTerm' CHARACTERISTIC_OVERRIDE: '#/components/schemas/CharacteristicOverrideConfiguration' COLLATERAL_REQUIRED: '#/components/schemas/CollateralRequired' CONTRACT_METADATA: '#/components/schemas/ContractMetaData' CONTRACTED_VOLUME_CONFIGURATION: '#/components/schemas/ContractedVolumeConfiguration' CORRECTIVE_PERIOD: '#/components/schemas/CorrectivePeriod' DELAYER_DAYS: '#/components/schemas/DelayerDays' GUARANTEE_OF_ORIGIN_CONFIGURATION: '#/components/schemas/GuaranteeOfOriginConfiguration' LATE_PAYMENT_FEES: '#/components/schemas/LatePaymentFees' MINIMUM_CONTRACT_LENGTH: '#/components/schemas/MinimumContractLength' PARTNER_COMMISSION: '#/components/schemas/PartnerCommission' PAYS_BY_DIRECT_DEBIT: '#/components/schemas/PaysByDirectDebitTerm' PRODUCT_RATE_OVERRIDE_SCHEDULE: '#/components/schemas/ProductRateOverrideConfiguration' PROMOTION_ASSIGNMENT: '#/components/schemas/PromotionAssignmentTerm' RATE_GROUP_ELIGIBILITY: '#/components/schemas/RateGroupEligibilityConfiguration' TRANCHE_TARGET_RESIDUAL_FEE: '#/components/schemas/TrancheTargetResidualFee' TAX_ADJUSTMENT_CONFIGURATION: '#/components/schemas/TaxAdjustmentConfiguration' TERMINATION_FEE: '#/components/schemas/TerminationFee' EEPA_EXPORT_CONTRACTED_VOLUME: '#/components/schemas/AusEEPAExportContractedVolumeConfiguration' TimeSeriesSpecificationEligibilitySchedule: type: object properties: effective_period: allOf: - $ref: '#/components/schemas/EffectivePeriod' description:

The effective period of the schedule.

is_eligible: type: boolean description:

Whether the rate group is eligible for charging to the customer.

product_code: type: string description:

Product code.

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:

Optional supply point identifier to restrict this schedule to a specific supply point.

time_series_specification_code: type: string description:

The unique shared rate code for the product.

required: - effective_period - is_eligible - product_code - time_series_specification_code x-validators: - name: data-import--validation--shared-rate-exists-for-product description: Validate that the shared rate code provided matches the shared rate for the product with the provided product code. possible_errors: - product_specification_not_found_for_product - time_series_not_found_for_product TrancheTargetResidualFee: type: object properties: term_type: type: string description:

The type of the contract term.

contract_identifier: type: string description:

Contract identifier

is_variable: type: boolean default: true description:

Whether the contract term is variable in Kraken or not. If not, it must be amended by a new contract.

markets: type: array items: $ref: '#/components/schemas/TrancheTargetResidualFeeMarket' description:

Markets

required: - contract_identifier - markets - term_type TrancheTargetResidualFeeMarket: type: object properties: amount: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,8})?$ description:

Residual fee amount

market_name: type: string description:

The market the residual fee applies to

unit: type: string description:

Residual fee unit

required: - amount - market_name - unit VariantProfile: type: object properties: characteristic_values: type: object description:

A dictionary of characteristic values which the rate applies to.

x-validators: - name: Validate provided dictionary content types description: Validates that provided dictionary contents are of the specified key type and value type. possible_errors: [] scheme_labels: type: object description:

A dictionary of scheme labels which the rate applies to.

x-validators: - name: Validate provided dictionary content types description: Validates that provided dictionary contents are of the specified key type and value type. possible_errors: [] - name: Validate that scheme labels have the correct format description: Validate that scheme labels have the the following format 'scheme-type:identifier' where 'scheme-type' is one of 'time_of_use', 'register'. possible_errors: - invalid_scheme_label_format 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 " tags: - name: orders x-title: Orders description: APIs for placing and managing orders. x-documentation-order: 8