Arcadia Bundle (Beta) API
The Bundle (Beta) API from Arcadia — 8 operation(s) for bundle (beta).
The Bundle (Beta) API from Arcadia — 8 operation(s) for bundle (beta).
openapi: 3.0.3
info:
title: Arcadia API Reference Auth Bundle (Beta) API
version: 0.3.0
contact:
email: platformsupport@arcadia.com
servers:
- url: https://api.arcadia.com
security:
- bearerAuth: []
tags:
- name: Bundle (Beta)
paths:
/bundle/utility_remittance/utility_credentials/{utility_credential_id}/enroll:
post:
tags:
- Bundle (Beta)
summary: Utility Remittance - Enroll into Utility Remittance
description: 'Enroll all Utility Accounts associated with the provided Utility Credential into Utility Remittance.
Enrollment is an asynchronous process. Track status changes through the associated [Bundle Enrollment](showutilityremittanceenrollment).'
operationId: enrollUtilityRemittance
parameters:
- $ref: '#/components/parameters/utilityCredentialIdInPathParam'
- $ref: '#/components/parameters/arcVersionInHeaderParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BundleEnrollmentRequestBodyParams'
responses:
'200':
description: Success
headers:
Arcadia-Version:
$ref: '#/components/headers/ArcVersion'
content:
application/json:
schema:
$ref: '#/components/schemas/BundleEnrollmentsArray'
'422':
description: Unprocessable Entity
headers:
Arcadia-Version:
$ref: '#/components/headers/ArcVersion'
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/UtilityRemittanceEnrollError'
- $ref: '#/components/schemas/BundleEnrollmentInvalidUtilityAccountIdsError'
- $ref: '#/components/schemas/BundleEnrollmentMissingUtilityAccountIdsError'
- $ref: '#/components/schemas/UnpermittedParametersError'
- $ref: '#/components/schemas/InvalidResourceError'
/bundle/utility_remittance/utility_credentials/{utility_credential_id}/remove:
delete:
tags:
- Bundle (Beta)
summary: Utility Remittance - Remove from Utility Remittance
description: 'Remove all Utility Accounts associated with the provided Utility Credential from Utility Remittance.
Removal is an asynchronous process. Track status changes through the associated [Bundle Enrollment](showutilityremittanceenrollment). Removal will trigger the `utility_remittance_removed` Webhook Event.'
operationId: removeUtilityRemittance
parameters:
- $ref: '#/components/parameters/utilityCredentialIdInPathParam'
- $ref: '#/components/parameters/arcVersionInHeaderParam'
responses:
'200':
description: Success
headers:
Arcadia-Version:
$ref: '#/components/headers/ArcVersion'
content:
application/json:
schema:
$ref: '#/components/schemas/BundleEnrollmentsArray'
'422':
description: Unprocessable Entity
headers:
Arcadia-Version:
$ref: '#/components/headers/ArcVersion'
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BundleUnenrollError'
- $ref: '#/components/schemas/InvalidResourceError'
/bundle/utility_remittance/utility_statements/{utility_statement_id}/utility_remittance_items:
post:
tags:
- Bundle (Beta)
summary: Utility Remittance - Create a Utility Remittance Item
description: 'Creates and schedules a Utility Remittance Item for a Utility Statement.
You can specify a date for remittance using `scheduled_at`. Note that `scheduled_at` must be a date in the future. If the date you specify falls on a weekend or a banking holiday, remittance will be scheduled for the next business day. If `scheduled_at` is omitted, remittance will be scheduled for the next business day.
When creating a Utility Remittance Item, you can specify how much to remit for the corresponding Utility Statement by specifying `amount_cents`. In most cases, this should correspond to the `utility_charge` on a Utility Statement. If `amount_cents` is omitted, the Utility Remittance Item will be created using the `utility_charge` on the specified Utility Statement. At this time, `amount_cents` cannot exceed 3000000 cents ($30,000). Note that overpaying or underpaying the amount on a Utility Statement comes with risk. This field should be used with caution.
Please note that this endpoint is rate limited to 200 requests per 10 seconds. You will receive a 429 error if you exceed this limit. Please wait and try again. The `RateLimit-Reset` header will indicate when you can make another request.'
operationId: createUtilityRemittanceItem
parameters:
- $ref: '#/components/parameters/utilityStatementIdInPathParam'
- $ref: '#/components/parameters/arcVersionInHeaderParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BundleUtilityRemittanceItemCreateRequestBodyParams'
responses:
'201':
description: Success
headers:
Arcadia-Version:
$ref: '#/components/headers/ArcVersion'
content:
application/json:
schema:
$ref: '#/components/schemas/UtilityRemittanceItem'
'403':
description: ForbiddenError
headers:
Arcadia-Version:
$ref: '#/components/headers/ArcVersion'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: UtilityStatementNotFoundError
headers:
Arcadia-Version:
$ref: '#/components/headers/ArcVersion'
content:
application/json:
schema:
$ref: '#/components/schemas/UtilityStatementNotFoundError'
'422':
description: Unprocessable Entity
headers:
Arcadia-Version:
$ref: '#/components/headers/ArcVersion'
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/UtilityRemittanceItemCreateError'
- $ref: '#/components/schemas/UnpermittedParametersError'
- $ref: '#/components/schemas/InvalidResourceError'
'429':
description: Too Many Requests
headers:
Arcadia-Version:
$ref: '#/components/headers/ArcVersion'
RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
RateLimit-Period:
$ref: '#/components/headers/RateLimitPeriod'
RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ThrottledError'
/bundle/utility_remittance/utility_remittance_items/{utility_remittance_item_id}:
get:
tags:
- Bundle (Beta)
summary: Utility Remittance - Get a Utility Remittance Item.
description: Returns a single Utility Remittance Item specified by ID.
operationId: getUtilityRemittanceItem
parameters:
- $ref: '#/components/parameters/utilityRemittanceItemIdInPathParam'
- $ref: '#/components/parameters/arcVersionInHeaderParam'
responses:
'200':
description: Success
headers:
Arcadia-Version:
$ref: '#/components/headers/ArcVersion'
content:
application/json:
schema:
$ref: '#/components/schemas/UtilityRemittanceItem'
'422':
description: Unprocessable Entity
headers:
Arcadia-Version:
$ref: '#/components/headers/ArcVersion'
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/InvalidResourceError'
/bundle/utility_remittance/utility_account/{utility_account_id}/enrollment:
get:
tags:
- Bundle (Beta)
summary: Utility Remittance - Get a Bundle Enrollment
description: Returns the Bundle Enrollment for a Utility Account.
operationId: showUtilityRemittanceEnrollment
parameters:
- $ref: '#/components/parameters/utilityAccountIdInPathParam'
- $ref: '#/components/parameters/arcVersionInHeaderParam'
responses:
'200':
description: Success
headers:
Arcadia-Version:
$ref: '#/components/headers/ArcVersion'
content:
application/json:
schema:
$ref: '#/components/schemas/BundleEnrollment'
'422':
description: Unprocessable Entity
headers:
Arcadia-Version:
$ref: '#/components/headers/ArcVersion'
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/InvalidResourceError'
/sandbox/bundle/utility_remittance/utility_credentials/{utility_credential_id}/accept:
post:
tags:
- Bundle (Beta)
summary: Sandboxed Only, Utility Remittance - Accept pending Utility Remittance enrollment
description: 'Only available when using sandboxed API keys.
Updates the Bundle Enrollments [created by the enroll into Utility Remittance endpoint](enrollutilityremittance) for each Utility Account associated with this Utility Credential. The status will change from `pending_enrollment` to `enrolled` and trigger the `utility_remittance_enrolled` Webhook Event.
'
operationId: sandboxUtilityRemittanceAccept
parameters:
- $ref: '#/components/parameters/utilityCredentialIdInPathParam'
- $ref: '#/components/parameters/arcVersionInHeaderParam'
responses:
'200':
description: Success
headers:
Arcadia-Version:
$ref: '#/components/headers/ArcVersion'
content:
application/json:
schema:
$ref: '#/components/schemas/BundleEnrollmentsArray'
'403':
description: ForbiddenError
headers:
Arcadia-Version:
$ref: '#/components/headers/ArcVersion'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'422':
description: Unprocessable Entity
headers:
Arcadia-Version:
$ref: '#/components/headers/ArcVersion'
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/SandboxBundleEnrollmentError'
- $ref: '#/components/schemas/InvalidResourceError'
/sandbox/bundle/utility_remittance/utility_credentials/{utility_credential_id}/reject:
post:
tags:
- Bundle (Beta)
summary: Sandboxed Only, Utility Remittance - Reject pending Utility Remittance enrollment
description: 'Only available when using sandboxed API keys.
Updates the Bundle Enrollments [created by the enroll into Utility Remittance endpoint](enrollutilityremittance) for each Utility Account associated with this Utility Credential. The status will change from `pending_enrollment` to `ineligible` and trigger the `utility_remittance_not_available` Webhook Event.
'
operationId: sandboxUtilityRemittanceReject
parameters:
- $ref: '#/components/parameters/utilityCredentialIdInPathParam'
- $ref: '#/components/parameters/arcVersionInHeaderParam'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- ineligibility_reasons
properties:
ineligibility_reasons:
type: array
items:
$ref: '#/components/schemas/IneligibilityReasonEnum'
responses:
'200':
description: Success
headers:
Arcadia-Version:
$ref: '#/components/headers/ArcVersion'
content:
application/json:
schema:
$ref: '#/components/schemas/BundleEnrollmentsArray'
'403':
description: ForbiddenError
headers:
Arcadia-Version:
$ref: '#/components/headers/ArcVersion'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'422':
description: Unprocessable Entity
headers:
Arcadia-Version:
$ref: '#/components/headers/ArcVersion'
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/SandboxBundleRejectReasonsError'
- $ref: '#/components/schemas/UnpermittedParametersError'
- $ref: '#/components/schemas/SandboxBundleEnrollmentError'
- $ref: '#/components/schemas/InvalidResourceError'
/sandbox/bundle/utility_remittance/utility_credentials/{utility_credential_id}/remove:
post:
tags:
- Bundle (Beta)
summary: Sandboxed Only, Utility Remittance - Remove active or pending removal Utility Remittance enrollment
description: 'Only available when using sandboxed API keys.
Updates the Bundle Enrollments [created by the enroll into Utility Remittance endpoint](enrollutilityremittance) for each Utility Account associated with this Utility Credential. The status will change from `enrolled` or `pending_removal` to `removed` and trigger the `utility_remittance_removed` Webhook Event.
'
operationId: sandboxUtilityRemittanceRemove
parameters:
- $ref: '#/components/parameters/utilityCredentialIdInPathParam'
- $ref: '#/components/parameters/arcVersionInHeaderParam'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- removal_reason
properties:
removal_reason:
type: string
enum:
- organization_requested
- dropped_cant_login
- dropped_no_remittance_scheduled
responses:
'200':
description: Success
headers:
Arcadia-Version:
$ref: '#/components/headers/ArcVersion'
content:
application/json:
schema:
$ref: '#/components/schemas/BundleEnrollmentsArray'
'403':
description: ForbiddenError
headers:
Arcadia-Version:
$ref: '#/components/headers/ArcVersion'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'422':
description: Unprocessable Entity
headers:
Arcadia-Version:
$ref: '#/components/headers/ArcVersion'
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/SandboxBundleRemoveReasonError'
- $ref: '#/components/schemas/UnpermittedParametersError'
- $ref: '#/components/schemas/SandboxBundleEnrollmentError'
- $ref: '#/components/schemas/InvalidResourceError'
components:
schemas:
SandboxBundleRemoveReasonError:
required:
- error
properties:
error:
type: object
required:
- description
- type
- details
properties:
description:
type: string
enum:
- Unsupported reason parameter provided.
type:
type: string
enum:
- BAD_REQUEST
additionalProperties: false
SandboxBundleEnrollmentError:
required:
- error
properties:
error:
type: object
required:
- description
- type
- details
properties:
description:
type: string
enum:
- No Utility Accounts to accept for this Utility Credential.
- No Utility Accounts to reject for this Utility Credential.
- No Utility Accounts to remove for this Utility Credential.
type:
type: string
enum:
- BAD_REQUEST
details:
type: object
nullable: true
additionalProperties: false
BundleEnrollmentInvalidUtilityAccountIdsError:
required:
- error
properties:
error:
type: object
required:
- description
- type
- details
properties:
description:
type: string
enum:
- Request included utility_account_ids not valid for the specified Utility Credential
type:
type: string
enum:
- BAD_REQUEST
details:
anyOf:
- type: object
required:
- utility_credential_id
- excess_utility_account_ids
properties:
utility_credential_id:
type: integer
excess_utility_account_ids:
type: array
items:
type: integer
additionalProperties: false
BundleEnrollmentRequestBodyParams:
required:
- utility_account_ids
properties:
utility_account_ids:
description: The list of Utility Account IDs associated with the provided Utility Credential to enroll in the Bundle product. To ensure no unintended Utility Accounts are enrolled in Bundle, we require every non-closed Utility Account associated with a Utility Credential to be explicitly provided in this parameter. We do not support Bundle for a subset of non-closed Utility Accounts associated with a Utility Credential at this time.
type: array
items:
type: number
example:
- 12345
- 67890
additionalProperties: false
BundleEnrollmentMissingUtilityAccountIdsError:
required:
- error
properties:
error:
type: object
required:
- description
- type
- details
properties:
description:
type: string
enum:
- Must provide all non-closed utility_account_ids associated with the provided Utility Credential
type:
type: string
enum:
- BAD_REQUEST
details:
anyOf:
- type: object
required:
- utility_credential_id
- missing_utility_account_ids
properties:
utility_credential_id:
type: integer
missing_utility_account_ids:
type: array
items:
type: integer
additionalProperties: false
IneligibilityReason:
required:
- resolvable
- reason
properties:
resolvable:
type: boolean
description: If `true`, signifies that corrective action can be taken to resolve this Ineligibility Reason. If `false`, this Ineligibility Reason cannot be resolved
example: false
reason:
$ref: '#/components/schemas/IneligibilityReasonEnum'
additionalProperties: false
BundleEnrollmentsArray:
type: array
items:
$ref: '#/components/schemas/BundleEnrollment'
UtilityStatementNotFoundError:
required:
- error
properties:
error:
type: string
enum:
- Couldn't find UtilityStatement
additionalProperties: false
InvalidResourceError:
required:
- error
properties:
error:
type: object
required:
- description
- type
- details
properties:
description:
type: string
enum:
- The requested resource is not valid
type:
type: string
enum:
- BAD_REQUEST
details:
type: object
required:
- resource
properties:
resource:
type: string
enum:
- user
- utility_statement
- utility_credential
- utility_account
- utility_remittance_item
- invoice
- payment_method
resource_id:
type: integer
additionalProperties: false
ForbiddenError:
required:
- error
properties:
error:
enum:
- Access denied
additionalProperties: false
BundleUnenrollError:
required:
- error
properties:
error:
type: object
required:
- description
- type
- details
properties:
description:
type: string
enum:
- No Utility Accounts to unenroll for this Utility Credential.
type:
type: string
enum:
- BAD_REQUEST
details:
type: object
nullable: true
additionalProperties: false
UnpermittedParametersError:
required:
- error
properties:
error:
type: object
required:
- description
- type
- details
properties:
description:
type: string
enum:
- Request included unpermitted parameters
type:
type: string
enum:
- BAD_REQUEST
details:
type: object
required:
- unpermitted_parameters
properties:
unpermitted_parameters:
type: array
items:
type: string
additionalProperties: false
BundleEnrollment:
required:
- client_user_id
- utility_account_id
- product_key
- status
- ineligibility_reasons
- removal_reason
- start_date
- override_email
- sandboxed
properties:
client_user_id:
description: Your organization's unique key provided to associate Arcadia resources with your user.
type: string
example: fff57dc7-3a2b-4395-8a62-e3486d46dabe
utility_account_id:
description: Unique `id` generated by Arcadia to identify the Utility Account associated with this resource.
type: integer
example: 1234
product_key:
type: string
enum:
- hosted_payments
- utility_remittance
status:
anyOf:
- type: 'null'
- type: string
enum:
- enrolled
- pending_enrollment
- ineligible
- pending_removal
- removed
example: enrolled
ineligibility_reasons:
description: Reasons, if any, that an Account was ineligible for Bundle. This array will always be present but may be empty.
type: array
items:
$ref: '#/components/schemas/IneligibilityReason'
removal_reason:
anyOf:
- type: 'null'
- type: string
enum:
- organization_requested
- dropped_cant_login
- dropped_payment_decline
- dropped_no_remittance_scheduled
- moved
example: null
start_date:
description: Date the Bundle Enrollment was approved.
format: date
type: string
nullable: true
override_email:
description: Email address generated by Arcadia to override the user's email address on file with their Utility.
example: apb0123456@a.arcadiapower.com
type: string
nullable: true
sandboxed:
description: If `true`, this resource is in the sandboxed environment. If `false`, this resource is in the live environment.
type: boolean
example: false
additionalProperties: false
BundleUtilityRemittanceItemCreateRequestBodyParams:
properties:
scheduled_at:
description: You can specify a date for remittance using `scheduled_at`. Note that `scheduled_at` must be a date in the future. If the date you specify falls on a weekend or a banking holiday, remittance will be scheduled for the next business day. If `scheduled_at` is omitted, remittance will be scheduled for the next business day.
type: string
format: date
example: '2021-07-28'
amount_cents:
description: You can specify how much to remit for this Utility Statement using `amount_cents`. In most cases, this should correspond to the `utility_charge` on a Utility Statement. If `amount_cents` is omitted, the Utility Remittance Item will be created using the `utility_charge` on the specified Utility Statement. At this time, `amount_cents` cannot exceed 3000000 cents ($30,000). Note that overpaying or underpaying the amount on a Utility Statement comes with risk. This field should be used with caution.
type: integer
example: '8000'
additionalProperties: false
UtilityRemittanceItemCreateError:
required:
- error
properties:
error:
type: object
required:
- description
- type
- details
properties:
description:
type: string
enum:
- Utility Remittance Item must be scheduled at least one day from now
- Utility Statement has already been scheduled for remittance
- A Utility Remittance Item cannot be created for a Utility Account not enrolled in Utility Remittance
- 'Invalid parameter: scheduled_at must be provided as an ISO date format and be a valid date.'
- Utility Remittance Item amount_cents must be greater than 0
type:
type: string
enum:
- BAD_REQUEST
details:
type: object
nullable: true
additionalProperties: false
ThrottledError:
required:
- error
properties:
error:
type: string
pattern: '^Rate limit exceeded. Try again at '
additionalProperties: false
SandboxBundleRejectReasonsError:
required:
- error
properties:
error:
type: object
required:
- description
- type
- details
properties:
description:
type: string
enum:
- One or more unsupported reasons provided.
type:
type: string
enum:
- BAD_REQUEST
additionalProperties: false
IneligibilityReasonEnum:
type: string
enum:
- 2fa
- ebill_ineligible_incorrect_credentials
- ebill_ineligible_third_party
- gas_only
- inactive_utility_account
- incomplete_utility_account
- missing_payment_method
- past_due
- payment_arrangement
- sdg&e_paperless_gas_account
- sibling_account_ineligible
- solar_non_approved_utility
- enrolled_in_mutually_exclusive_bundle_feature
UtilityRemittanceItem:
required:
- id
- utility_statement_id
- client_user_id
- amount_cents
- status
- created_at
- updated_at
- scheduled_at
- remitted_at
- sandboxed
properties:
id:
description: Unique `id` generated by Arcadia to identify this resource.
type: number
utility_statement_id:
description: Unique `id` generated by Arcadia to identify the Utility Statement associated with this resource.
type: number
client_user_id:
description: Your organization's unique key provided to associate Arcadia resources with your user.
type: string
example: fff57dc7-3a2b-4395-8a62-e3486d46dabe
amount_cents:
description: Monetary amount of this Utility Remittance Item. Given in cents.
type: integer
status:
type: string
enum:
- scheduled
- remitted
- void
created_at:
description: Date and time at which this resource was created. Given in UTC.
type: string
format: date-time
updated_at:
description: Date and time at which this resource was most recently updated. Given in UTC.
type: string
format: date-time
scheduled_at:
description: Date and time this Utility Remittance Item is scheduled to be remitted to the user's associated Utility. Given in UTC.
format: date-time
type: string
nullable: true
remitted_at:
description: Date and time this Utility Remittance Item was successfully remitted to the user's associated Utility. Given in UTC.
format: date-time
type: string
nullable: true
sandboxed:
description: If `true`, this resource is in the sandboxed environment. If `false`, this resource is in the live environment.
type: boolean
example: 'false'
additionalProperties: false
UtilityRemittanceEnrollError:
required:
- error
properties:
error:
type: object
required:
- description
- type
- details
properties:
description:
type: string
enum:
- The utility_remittance feature is not available for this UtilityAccount.
- The utility_remittance feature is not ready yet. Please refer to UtilityAccount#FeatureAvailability for updates.
- No Utility Accounts to enroll for this Utility Credential.
type:
type: string
enum:
- BAD_REQUEST
details:
type: object
nullable: true
additionalProperties: false
headers:
RateLimitReset:
description: The time in which you can retry a request. Given in epoch time.
schema:
type: integer
example: 1690895650
required: true
RateLimitLimit:
description: The number of requests that can be made to the API in the RateLimit Period
schema:
type: integer
example: 200
required: true
ArcVersion:
description: The Arcadia-Version for the response
schema:
type: string
example: '2022-10-13'
required: true
RateLimitPeriod:
description: The number of seconds your application has to perform the number of requests specified by RateLimit Limit
schema:
type: integer
example: 10
required: true
parameters:
utilityStatementIdInPathParam:
name: utility_statement_id
in: path
required: true
schema:
type: integer
utilityAccountIdInPathParam:
name: utility_account_id
in: path
required: true
schema:
type: integer
utilityCredentialIdInPathParam:
name: utility_credential_id
in: path
required: true
schema:
type: integer
utilityRemittanceItemIdI
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/arcadia/refs/heads/main/openapi/arcadia-bundle-beta-api-openapi.yml