This page walks through environment configuration necessities and possible options for various parts of BillingServices.
This section highlights changes to other services that were introduced to support BillingServices. It highlights key areas to customize if a need to change defaults on how Billing is deployed arises.
Both Admin and Commerce gateway now contain configuration that allows requests to be routed to Billing. This means BillingServices can be put behind their ingress and behave in-line with other microservices. However, we recognize there are valid scenarios where it will be deployed separately and urge clients to review our configuration for Billing in the gateways.
Regularly, BillingServices is deployed at port 8467 when run in a granular composition.
An AuthClient dedicated to Billing was added alongside this service’s introduction.
The following properties can be changed to configure how Billing communicates with other services:
spring.security.oauth2.client.registration.billingclient.authorization-grant-type
spring.security.oauth2.client.registration.billingclient.client-id
spring.security.oauth2.client.registration.billingclient.client-secret
spring.security.oauth2.client.provider.billingclient.token-uri
To create a scheduled job that kicks off a daily Subscription Billing Job to bill due or past due subscriptions, add this row into the scheduledjob schema.
INSERT INTO scheduledjob.blc_scheduled_job ("id", "type", "timing_type", "name", "enabled", "executed", "cron", "manage_in_admin", "trk_tenant_id", "trk_archived")
VALUES ('billDueSubscriptionsId', 'BILL_DUE_SUBSCRIPTIONS', 'CRON', 'Bill Due Subscriptions', 'Y', 'N', '0 0 * * *', 'Y', '${blcTenantId}', 'N');BillingProperties:
broadleaf.billing.dead-letter-queue.enabled
Description: Enables the DeadLetter queue functionality.
Default value: false
broadleaf.billing.query.partition-size
Description: Sets partition size for EntityUtils#findByIdUsingPartitioning queries
Default value: 50
broadleaf.billing.query.enable-transaction-query-read-optimization
Description: Enables optimizing transactional behavior in some queries
Default value: true
broadleaf.billing.create-billing-event.allow-tax-persistence-from-request
Description: Allows persistence of BillingTaxDetails when creating BillingEvents from an external request
Default value: false
broadleaf.billing.create-billing-event.allow-adjustment-persistence-from-request
Description: Allows persistence of BillingEventAdjustments when creating BillingEvents from an external request
Default value: false
broadleaf.billing.create-billing-event.allow-payment-transaction-detail-persistence-from-request
Description: Allows persistence of PaymentTransactionDetails when creating BillingEvents from an external request
Default value: false
broadleaf.billing.jpa.id.type
Description: Allows setting the type of id fields (primary keys) in the database that should be expected and supported by the system
Note: This property is not displayed in the BillingProperties file. It can be found in IdFieldType
Default value: 'ULID'
broadleaf.billing.jpa.json.type
Description: Allows setting the type of json fields in the database that should be expected and supported by the system. Sets the liquibase structure variant type
Note: This property is not displayed in the BillingProperties file. It can be found in JsonFieldType
Default value: 'STRING'
broadleaf.billing.liquibase.parameters.tablespace
Description: Allows setting the name of the liquibase tablespace for this service’s database
Note: This property is not displayed in the BillingProperties file. It can be found in BillingEnvironmentPostProcessor
Default value: "pg_default"
broadleaf.billing.liquibase.parameters.indexspace
Description:Allows setting the name of the liquibase indexspace for this service’s database
Note: This property is not displayed in the BillingProperties file. It can be found in BillingEnvironmentPostProcessor
Default value: "pg_default"
BillingJobProperties:
|
Important
|
Note the absence of the broadleaf. prefix to these properties.
|
billing.job.request-generator-limit
Description: Informs the number of requests processed at once in various stages of Billing and Subscription Billing Jobs
Default value: 50
billing.job.gateway-error-retry-limit
Description: Sets the number of retries after gateway errors
Default value: 0
billing.job.tax-calculation-error-retry-limit
Description: Sets the number of retries after tax calculation errors
Default value: 1
billing.job.default-payment-retry-schedule-code
Description: ID (i.e. code) value of the default payment retry schedule
billing.job.default-payment-retry-schedule
Description: The BillingRetrySchedule object of the default payment retry schedule
Default value: BillingRetrySchedule(id="default-payment-retry-schedule", tryAccountsFromWallet=true, retryAttemptCount=3, retries=[IntervalBillingRetrySpecs(retryAfterDays=3),IntervalBillingRetrySpecs(retryAfterDays=3),IntervalBillingRetrySpecs(retryAfterDays=3)])
billing.job.default-refund-retry-schedule-code
Description: ID (i.e. code) value of the default refund retry schedule
billing.job.default-refund-retry-schedule
Description: The BillingRetrySchedule object of the default refund retry schedule
Default value: BillingRetrySchedule(id="default-refund-retry-schedule", tryAccountsFromWallet=false, retryAttemptCount=3, retries=[IntervalBillingRetrySpecs(retryAfterDays=3),IntervalBillingRetrySpecs(retryAfterDays=3),IntervalBillingRetrySpecs(retryAfterDays=3)])
billing.job.execute-only-tax-calculation
Description: Determines if the Billing Job should only execute tax calculation and not process payments.
Default value: false
billing.job.payment-gateway-config.[payment gateway name].should-call-processor-if-transaction-not-found
Description: Determines whether it is safe to re-send a transaction request to the processor if the processor is not aware of this transaction. This is typically engaged after an unknown transaction result is received on the first attempt.
Default value: false
billing.job.payment-gateway-config.[payment gateway name].alternative-gateway-type-values
Description: List of gateway names, including alternative names, for each gateway. This is used to partition requests by gateway type in situations where various sources may use different names for a given gateway.
BillingCacheProperties:
`broadleaf.billing.cache.by-id-ttl
Description: Time-to-live of the caching mechanism for DefaultBillingRetryScheduleService#readByIdWithCache
Default value: Duration.ofMinutes(5)
SkuToEntitlementLookupServiceProperties:
broadleaf.billing.sku-to-entitlement-lookup-service.api-lookup-enabled
Description: Enables using the Catalog Entitlement Provider to retrieve SKU to Entitlements mapping.
Default value: false
|
Note
|
Properties for various providers - SavedPaymentMethod Provider, PaymentTransactionExecution Provider, CatalogEntitlement Provider - are discussed on the Providers page. |
SubscriptionConfigurationProperties:
|
Important
|
Note the absence of the broadleaf. prefix to these properties.
|
subscription.grace-period-days
Description: Sets the number of grace period days since payment to allow refunds for a subscription
Default value: 5
subscription.optimistic-lock-try-count
Description: Sets the number of retries to attempt after a CustomOptimisticLockException
Default value: 3
|
Note
|
The Entitlement Provider properties are discussed on the Providers page |
|
Important
|
Note the absence of the broadleaf. prefix to these properties.
|
DeadLetterProperties:
deadletter.notification.number-of-dead-letters-to-render
Description: Sets the number of DeadLetters to be rendered by the deprecated and unused methods in DeadLetterService
Default value: 5
deadletter.stack-trace.max-length
Description: Sets the maximum length for the stack trace contained in a DeadLetter
Default value: 255
deadletter.message.max-length
Description: Sets the maximum length for the error message contained in a DeadLetter
Default value: 255
deadletter.message.uniform-handler-supported
Description: List of classes supported to be handled by the UndeterminedMessageDeadLetterRetryHandler
Default value: []
BillingProperties#DeadLetterQueue:
broadleaf.billing.dead-letter-queue.enabled
Description: Enables the DeadLetter queue functionality.
Default value: false