- v1.0.0-latest-prod
Clients can create, read, update, and remove various domain objects through BillingEventEndpoint and SubscriptionEndpoint.
However, key processes described in this section have dedicated endpoints to kick off their execution.
|
Tip
|
See the Billing API spec for request and response details. |
The Subscription Billing Job is the central flow in the Billing Service.
This flow creates BillingEvents for Subscriptions that are due or past due on their billing date. The precise limitations of which subscriptions are processed by the job can be seen in SubscriptionStatusBillingJobGenerator.
After BillingEvents are created, this flow defers to its subdivision, the Billing Job, starting from NewChargeBillingRequestGenerator.
|
Important
|
If this flow was engaged as a subdivision of the Subscription Billing Job, it does not execute in its entirety.
Only the new charge requests are created and processed, excluding refunds and retries.
This subflow starts from `NewChargeBillingRequestGenerator.
|
The Billing Job collects BillingEvents and RefundEvents to process the due payments and refunds, potentially engage tax calculation logic, and update related entities such as subscriptions and entitlements based on the results of the execution.
It does not create new BillingEvents or RefundEvents and therefore requires the desired Billing objects to be created beforehand, either by the user or as part of other processes.
This flow can be kicked off with an API request to BillingJobEndpoint#initiateBillingJob. Parameter restrictions of the Billing Job, such as the date range, types of requests to process, etc., can be supplied in the request body.
In practice, The Billing Job is a collective name for four similar processes which follow most of the same logic and diverge in very few places:
Processing new CHARGE-type billing
Processing retries of CHARGE-type billing
Processing new REFUND-type billing
Processing retries of REFUND-type billing
|
Tip
|
Each of these processes can be disabled by setting a respective parameter on the InitiateBillingJob request object to false.
|
While the processes have their distinctions, they can be grouped together for effective understanding:
Learn more about how retries for both charge and refund billing are processed in Retries.
With new billing requests, the same logic is applicable for both types, with CHARGE requests operated by BillingEvent entities and REFUNDs using RefundEvents.
The various stages of the flow, among others the BillingProcessingRequest creation, execution of the payment transaction, and result finalization, are interconnected via a series of messages.
A prior stage is expected to send a message with the necessary information for the next stage’s handler to proceed.