Issuing policies
Use the following endpoint to issue policies in BillingCenter:
- POST
billing/v1/accounts/{accountId}/issuances
Minimum creation criteria
The policy issuance request object consists of several required objects and one array. Some of these top-level entities have required fields. The following table details these entities and their required fields:
| Object | Description | Required fields |
|---|---|---|
charges |
An array of |
For each
|
paymentPlan |
An object specifying the policy’s payment plan. |
|
policy |
An object containing optional information about the policy. |
No required fields |
policyPeriod |
An object containing information on the policy period. |
|
Minimal policy issuance request
The following request provides an example of issuing a minimal policy on account
bc:101
POST /billing/v1/accounts/bc:101/issuances
{
"data": {
"attributes": {
"charges": [
{
"amount": {
"amount": "1200",
"currency": "USD"
},
"chargePattern": {
"id": "default_data:1",
}
},
{
"amount": {
"amount": "60",
"currency": "USD"
},
"chargePattern": {
"id": "default_data:6",
}
}
],
"paymentPlan": {
"id": "bc:SseFjlFaE9xxBLBG1ZRNR"
},
"policy": {},
"policyPeriod": {
"effectiveDate": "2023-12-11",
"expirationDate": "2024-12-11",
"policyNumber": "PA-234553"
}
}
}
}This request performs the following:
- Creates a personal auto policy with the policy number PA-234553
- Creates a policy period on that policy
- Sets the payment plan to an existing payment plan
- Creates two charges on the policy period: one $1200 premium charge and one $60 tax charge. The charge pattern is identified by the id.
policy object is always required, even
when there are no fields to specify. This is why the payload includes an empty
policy object.The issuance response object
POST /billing/v1/accounts/bc:101/issuances
{
"data": {
"attributes": {
"charges": [
{
"amount": {
"amount": "1200.00",
"currency": "usd"
},
"chargeDate": "2023-12-12T17:29:05.022Z",
"chargePattern": {
"displayName": "Premium",
"id": "default_data:1",
"type": "ChargePattern",
"uri": "/admin/v1/charge-patterns/default_data:1"
},
"holdStatus": {
"code": "none",
"name": "Not Held"
},
"id": "bc:SFy0AE8LdXyShiK08inYY",
"reversed": false,
"skipInvoiceItemCreation": false,
"totalInstallments": 9
},
{
"amount": {
"amount": "60.00",
"currency": "usd"
},
"chargeDate": "2023-12-12T17:29:05.022Z",
"chargePattern": {
"displayName": "Taxes",
"id": "default_data:6",
"type": "ChargePattern",
"uri": "/admin/v1/charge-patterns/default_data:6"
},
"holdStatus": {
"code": "none",
"name": "Not Held"
},
"id": "bc:SakMlRBrLNvF0Crvj2Mrl",
"reversed": false,
"skipInvoiceItemCreation": false,
"totalInstallments": 0
}
],
"createTime": "2023-12-12T17:29:05.022Z",
"executed": true,
"id": "bc:SZVcFGJg56XPQPrtq8HUG",
"paymentPlan": {
"displayName": "A Monthly 10% Down, 9 Max installments",
"id": "bc:SseFjlFaE9xxBLBG1ZRNR",
"type": "PaymentPlan",
"uri": "/admin/v1/payment-plans/bc:SseFjlFaE9xxBLBG1ZRNR"
},
"policy": {
"createTime": "2023-12-12T17:29:05.022Z",
"currency": {
"code": "usd",
"name": "USD"
},
"displayName": "PA-234553",
"doNotArchive": false,
"id": "bc:S6UbABC8vyTq2lKgu3GVK"
},
"policyPeriod": {
"assignedRisk": false,
"billingMethod": {
"code": "DirectBill",
"name": "Direct Bill"
},
"boundDate": "2023-12-11",
"cancelStatus": {
"code": "open",
"name": "Open"
},
"chargeHeld": false,
"closureStatus": {
"code": "open",
"name": "Open"
},
"confirmationNotificationState": {
"code": "DoNotNotify",
"name": "Do Not Notify"
},
"currency": {
"code": "usd",
"name": "USD"
},
"effectiveDate": "2023-12-11",
"eligibleForFullPayDiscount": false,
"equityBuffer": 30,
"equityWarningsEnabled": true,
"expirationDate": "2024-12-11",
"fullPayDiscountEvaluated": false,
"heldForInvoiceSending": false,
"holdInvoicingWhenDelinquent": false,
"id": "bc:S-r07gO0hbKuQwcUoeAWf",
"paymentDistributionEnabled": true,
"paymentPlan": {
"displayName": "A Monthly 10% Down, 9 Max installments",
"id": "bc:SseFjlFaE9xxBLBG1ZRNR",
"type": "PaymentPlan",
"uri": "/admin/v1/payment-plans/bc:SseFjlFaE9xxBLBG1ZRNR"
},
"pendingRemainingBalanceFix": false,
"policyNumber": "PA-234553",
"policyNumberLong": "PA-234553-1",
"retrieved": false,
"returnPremiumPlan": {
"displayName": "Default Return Premium Plan",
"id": "ret_premium_plan:1",
"type": "ReturnPremiumPlan",
"uri": "/admin/v1/return-premium-plans/ret_premium_plan:1"
},
"termConfirmed": true,
"termNumber": 1,
"westernMethod": false
}
},
"checksum": "0"
}
}Specifying additional information
When specifying policy and policy period details, take note of the following guidelines.
Overriding payer accounts and invoice streams - Invoice streams must be on the same account as the payer account. If you add an overriding payer account, the invoice stream will automatically be set to this payer’s default invoice stream. This can be set on either the policy period or on specific charges.
Policy number - The policy number for a newly issued policy must be unique.
Currency - Payment plans and delinquency plans have arrays of supported currencies. The payer account’s currency must be included in those arrays.
In a mono-currency instance of BillingCenter, any monetary amount specified
in a request must have the same currency as the payer account. This includes
charges, deposit requirements, and other monetary information provided in the
policyPeriod object. Additionally, the overriding payer account
and the account that owns the policy must both have the same currency.
In a multicurrency instance of BillingCenter, the currency of a charge can be different than the account's currency. However, as of this release, Cloud API does not support billing requests where the currency of any charge is different than the account's currency. For billing requests submitted through Cloud API, all charges must have the same currency as the associated account
Charge breakdowns - As of this release, Cloud API does not support adding charge breakdown information when issuing a policy.
Billing method - As of this release, the only supported billing method is direct bill.