Update a line item in a bulk Payable

Sometimes it can be necessary to update a bulk Payable that has incorrect information or that is missing a line item. By using a series of Wingspan API endpoints you can find the bulk Payable that needs to be updated and add or modify a line item to the bulk Payable.

The API endpoints that you will need to update a bulk Payable are:

Retrieve All Bulk Payable Batches: /payments/bulk/payable/batch
Retrieve Details of a Specific Bulk Payable Batch: /payments/bulk/payable/batch/{batchId}
Add a new item to a specific bulk payable batch: /payments/bulk/payable/batch/{batchId}/item
Modify a Specific Item in a Bulk Payable Batch: /payments/bulk/payable/batch/{batchId}/item/{batchItemId}

When either updating an existing line item or adding a new line item to a batch, you pass a series of parameters in each respective call. Most of the parameters are the same for either call, however, when updating a specific line item you must include the batchItemId.

Path Parameters :

batchId (type: string, required): A unique identifier for a batch.
batchItemId (type: string, required): Unique identifier for an item in a batch. This parameter is needed when updating a specific line item by using the /payments/bulk/payable/batch/{batchId}/item/{batchItemId} endpoint.

Body Parameters :

amount (type: number, required): The total monetary value associated with the batch.
bulkPayableBatchId (type: string, required): Identifier for the bulk payable batch this item is associated with.
dueDate (type: string, required): The date by which the payment should be completed.
lineItem (type: string, required): A brief of the line item.
payableStatus (type: string, required): The current payment status of the item.
bulkPayableItemMergeKey (type: string | null): Key used to merge payable items together.

Optional Fields:

attachmentId (type: string | null): Identifier for any attachment associated with the payable line item.
bulkPayableItemReference (type: string | null): A reference identifier for the payable item.
collaboratorEmail (type: string | null): Email address of the collaborator involved with the payable item. This field is required when
collaboratorExternalId (type: string | null): An external identifier for the Collaborator (payee).
collaboratorId (type: string | null): The Wingspan identifier for the Collaborator (payee).
lineItemDetail (type: string | null): Detailed information about the line item.
paidDate (type: string | null): The date on which the payment was made.
payableNotes (type: string | null): Any additional notes or comments regarding the payable item.
reimbursableExpense (type: boolean | null) : Indicator of whether the expense is reimbursable or not.

Before you begin

Before you begin the process of updating a bulk Payable, ensure that you have the following information for the line item that you want to add or modify.

The amount of money to be paid.
The due date of the Payable.
A line item description.
The attachment ID, if there is an attachment for the Payable.
The payee’s email address.
The Collaborator ID, if the payee already exists in your project.

To update a line item in a bulk Payable

Find the batch that you want to update by calling GET /payments/bulk/payable/batch. This call returns the batchId for all bulk Payables. The batchId is used in the proceeding calls to identify the batch.

Endpoint

POST https: //api.wingspan.app/payments/bulk/payable/batch

Headers:
- accept: application/json: Specifies the format of the response data.
- content-type: application/json: Indicates the media type of the resource/data.
- Authorization: Bearer <Your_Access_Token>: This header is required for authentication. Replace <Your_Access_Token> with your actual access token.
Request Body Parameters:

There are no body parameters for this call.

Response:

A successful request will return an appropriate success status code along with a JSON response containing details of all batch Payables.
In the JSON response, locate the batchId for the batch Payable that you want to update.
After you have the batchId, use it in the /payments/bulk/payable/batch/{batchId} call. This call is used to find specific information used to update or add a line item to a call.

Endpoint

GET https://api.wingspan.app/payments/bulk/payable/batch

Headers:
- accept: application/json: Specifies the format of the response data.
- content-type: application/json: Indicates the media type of the resource/data.
- Authorization: Bearer <Your_Access_Token>: This header is required for authentication. Replace <Your_Access_Token> with your actual access token.
Request Body Parameters:

There are no body parameters for this call.

Response:

A successful request returns an appropriate success status code along with a JSON response containing details of the batch Payable.
Search through the JSON response for the bulkPayableBatchId and the bulkPayableItemMergeKey as both are necessary for either updating or adding a line item to a Payable.
If you are updating a line item in the bulk Payable, also make note of the batchItemId for the line item that you need to update.
To update an existing line item in the bulk Payable, call PATCH /payments/bulk/payable/batch/{batchId}/item/{batchItemId}.

Endpoint

POST https://api.wingspan.app/payments/bulk/payable/batch/{batchId}/item/{batchItemId

Headers:
- Accept: application/json - This indicates that the client expects JSON format in the response.
- Content-Type: application/json - This indicates that the payload being sent in the request is in JSON format.
- Authorization: Bearer <Your_Access_Token> - This header is required for authentication. Replace <Your_Access_Token> with your actual access token to authenticate your request.
Path Parameters:
- batchId (type: string, required): A unique identifier for a batch.
- batchItemId (type: string, required): A unique identifier for an item within the specified batch.
Body Parameters:
- amount (type: number | null, required): The total monetary value associated with the batch item.
- dueDate (type: string | null, required): The date by which the payment for the batch item should be completed.
- bulkPayableBatchId (type: string | null, required): Identifier for the bulk payable batch the item is associated with.
- bulkPayableItemMergeKey (type: string | null, required): Key used to merge or link payable items together.
- bulkPayableItemReference (type: string | null): A reference identifier for the payable item in another system or context.
- collaboratorEmail (type: string | null): Email address of the collaborator involved with the payable item.
- collaboratorExternalId (type: string | null): An external identifier for the collaborator.
- collaboratorId (type: string | null): The internal identifier for the collaborator.
- attachmentId (type: string | null, optional): Identifier for any attachment associated with the payable batch item.
- lineItemDetail (type: string | null): Detailed information about the batch item.
- paidDate (type: string | null): The date on which the payment was made for the batch item.
- payableNotes (type: string | null): Any additional notes or comments regarding the batch item.
- payableStatus (type: string | null): The current payment status of the batch item.
- reimbursableExpense (type: boolean | null): Indicator of whether the batch item expense is reimbursable or not.
Example request
```
curl --request PATCH \
     --url https://api.wingspan.app/payments/bulk/payable/batch/{batchId}/item/{batchItemId} \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Authorization: Bearer <Your_Access_Token>' \
     --data '{
        "amount": 100.50,
        "attachmentId": "attach123",
        ...[other params]...
     }'
```
Response:

A successful request will return an appropriate success status code along with a JSON response containing details of the updated bulk Payable line item.
If you are adding a line item to the bulk Payable, call POST /payments/bulk/payable/batch/{batchId}/item

Endpoint

POST https://api.wingspan.app/payments/bulk/payable/batch/{batchId}/item

Headers:
- Accept: application/json - This indicates that the client expects a JSON format in the response.
- Content-Type: application/json - This indicates that the payload being sent in the request is in JSON format.
- Authorization: Bearer <Your_Access_Token> - This header is required for authentication. Replace <Your_Access_Token> with your actual access token to authenticate your request.
Path Parameters:
- batchId (type: string, required) : A unique identifier for the payable batch where the new item is to be added.
Body Parameters:

Required:
- amount (type: number): The total monetary value associated with the new batch item.
- bulkPayableBatchId (type: string): Identifier for the bulk payable batch the new item is to be associated with.
- dueDate (type: string): The date by which the payment for the new batch item should be completed.
- lineItem (type: string): A brief of the new batch item.
- payableStatus (type: string): The initial payment status of the new batch item.
- bulkPayableItemMergeKey (type: string | null): Key used to merge payable items together.
Optional:
- attachmentId (type: string | null): Identifier for any attachment associated with the new batch item.
- bulkPayableItemReference (type: string | null): A reference identifier for the new batch item in another system or context.
- collaboratorEmail (type: string | null): Email address of the collaborator involved with the new batch item.
- collaboratorExternalId (type: string | null): An external identifier for the collaborator involved with the new batch item.
- collaboratorId (type: string | null): The internal identifier for the collaborator involved with the new batch item.
- lineItemDetail (type: string | null): Detailed information about the new batch item.
- paidDate (type: string | null): The date on which the payment was made for the new batch item, if it was paid immediately upon creation.
- payableNotes (type: string | null): Any additional notes or comments regarding the new batch item.
- reimbursableExpense (type: boolean | null): Indicator of whether the new batch item expense is reimbursable or not.
Example request
```
curl --request POST \
     --url https://api.wingspan.app/payments/bulk/payable/batch/{batchId}/item \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Authorization: Bearer <Your_Access_Token>' \
     --data '{
        "amount": 100.50,
        "bulkPayableBatchId": "batch123",
        "dueDate": "2023-12-01",
        "lineItemDescription": "Sample Description",
        "payableStatus": "pending",
        ...[other params]...
     }'
```
Response:

A successful request will return an appropriate success status code along with a JSON response including the details of the newly created batch line item.