Line Item Updates
Details on the different ways to update line items in Canopy, including performing immediate updates and scheduling updates for future times, as well as important considerations and related API references.
Introduction
More details about what a line item is and what types of line items are available can be found here.
Once created, some properties of a line item can be updated. At the moment, only updating the status and the amount of a line item is allowed. The list of statuses that a line item can have, as well as a description of each status, can be found here.
How to update line items
Canopy provides two ways to update line items: one that allows the straight away update of the line item and another that allows scheduling the update operation at a future time. Both functionalities can be accessed through the API using Postman.
Straight away line item updates
The first way to update a line item, the straight away one, can be performed by using the following endpoint:
PUT /accounts/{{account_id}}/line_items/{{line_item_id}}
This endpoint can be used to update a given line item synchronously, at request time. In this case, the desired changes are applied to the line item as soon as the request is fulfilled.
Request format
The payload of the request to synchronously update a line item contains two attributes: the new status (line_item_status) and the new amount (original_amount_cents) of the line item to be updated. Both attributes can be omitted. If the new status is missing, the line item status will be updated by default to VALID. If a new amount is not provided, the line item amount won't change. A request payload example can be found below.
{
"line_item_status": "INVALID",
"original_amount_cents": 200
}
Response format
Regarding the response provided by the API, it contains comprehensive information about the updated line item, reflecting the changes that have been applied.
Check the API Reference for additional details.
Schedule line item updates
The second method to update a line item involves scheduling the update operation at a later time and can be accessed by calling the following endpoint:
PUT /accounts/{account_id}/line_items/{line_item_id}/schedule
This endpoint provides the asynchronous version, allowing the user to choose when to perform the update.
Request format
The request payload closely mirrors that of the endpoint used to update line items at request time but introduces an optional effective_at attribute. By means of this attribute, it is possible to specify the moment when the line item should be updated. If it is not included in the payload, the operation will be scheduled at the time of the request and executed around one minute later. A sample request payload is provided below.
{
"line_item_status": "INVALID",
"original_amount_cents": 200,
"effective_at": "2020-07-20T09:11:28+00:00"
}
Response format
The response encompasses a message confirming that the update operation was scheduled at the time specified in the request. Also, the response includes a Location header that mentions a URL to query the status of the operation (i.e., an endpoint that can be used to retrieve the line item).
Check the API Reference for additional details.
Nice-to-knows
When you want to update a line item, regardless of the selected method to perform this operation, you must take into account the fact that a line item cannot be changed if the line item is already in a final state.
For example, in the case of VALID payments, their status cannot be updated to PENDING.
Another aspect worth mentioning is the fact that if the status of a VALID payment needs to be updated to INVALID or DECLINED or VOID, the pattern to use is a payment reversal -- this ensures that immutability of a borrower's transaction history is not violated.
When scheduling a line item update, the provided effective_at should be newer than the account certified time.
Related Articles
Updated over 1 year ago