Disputes¶
A dispute represents a claim made by an account that part or all of the outstanding balance on an invoice should not be owed. A dispute is made against a document number and account number.
Retrieving a Dispute by ID¶
This endpoint retrieves a single dispute using the internal identifier for the dispute (usually a GUID).
Swagger Page¶
Permission¶
Dispute Management : READ
Example Request¶
curl -X GET 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/disputes/{disputeId}' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-Billtrust-Api-Key: <API key value>'
Example Response¶
{
"disputeId": "{disputeId}",
"disputeCode": "D-INV-789-01",
"tenantId": "{tenantId}",
"categoryId": "{categoryId}",
"categoryName": "Shipping Error",
"externalReasonCategoryId": null,
"externalReasonCategoryName": null,
"reasonId": "{reasonId}",
"reasonName": "Damaged in Shipping",
"externalReasonId": null,
"externalReasonName": null,
"assigneeId": "{assigneeId}",
"assigneeName": "Steve Rogers",
"departmentId": "{departmentId}",
"departmentName": "Shipping",
"status": 0,
"amount": 100.50,
"isValid": false,
"resolutionId": null,
"closedDate": null,
"platformAccountId": null,
"documentNumber": "INV-789",
"poNumber": "PO-12345",
"accountNumber": "ACT-123",
"accountName": "test-account",
"createUser": "{userId}",
"createDate": "2021-03-27T18:01:42.847Z",
"updateUser": "{userId}",
"updateDate": "2021-03-27T18:01:42.847Z",
"userId": "{assigneeUserId}",
"currencyCode": "USD",
"resolutionCode": null,
"originSystem": "collections"
}
Retrieving a List of Disputes¶
This endpoint returns a list of disputes that match the supplied filter criteria. If no filters are provided, all disputes for the tenant will be returned.
Swagger Page¶
Permission¶
Dispute Management : READ
Example Request¶
curl -X GET 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/disputes?AccountNumber=ACT-123&DocumentNumber=INV-789&Sort=-CreateDate' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-Billtrust-Api-Key: <API key value>'
Request Filters¶
| Field | Description | Match Type |
|---|---|---|
| ReasonName | The description of the dispute's reason | Partial match supported |
| DepartmentName | The description of the dispute's department | Partial match supported |
| CategoryName | The description of the dispute's category | Partial match supported |
| Status | 0 for Open, 1 for Closed, 2 for Cancel |
Full match only |
| AssigneeId | The internal ID for the dispute's assignee | Full match only |
| DepartmentId | The internal ID for the dispute's department | Full match only |
| DocumentNumber | The external document number on the dispute | Full match only |
| AccountNumber | The external account number on the dispute | Full match only |
| Sort | See Pagination & Filters | |
| Page | See Pagination & Filters | |
| PageSize | See Pagination & Filters |
Example Response¶
[
{
"disputeId": "{disputeId}",
"disputeCode": "D-INV-789-01",
"tenantId": "{tenantId}",
"categoryId": "{categoryId}",
"categoryName": "Shipping Error",
"externalReasonCategoryId": null,
"externalReasonCategoryName": null,
"reasonId": "{reasonId}",
"reasonName": "Damaged in Shipping",
"externalReasonId": null,
"externalReasonName": null,
"assigneeId": "{assigneeId}",
"assigneeName": "Steve Rogers",
"departmentId": "{departmentId}",
"departmentName": "Shipping",
"status": 0,
"amount": 100.50,
"isValid": false,
"resolutionId": null,
"closedDate": null,
"platformAccountId": null,
"documentNumber": "INV-789",
"poNumber": "PO-12345",
"accountNumber": "ACT-123",
"accountName": "test-account",
"createUser": "{userId}",
"createDate": "2021-03-27T18:01:42.847Z",
"updateUser": "{userId}",
"updateDate": "2021-03-27T18:01:42.847Z",
"userId": "{assigneeUserId}",
"currencyCode": "USD",
"resolutionCode": null,
"originSystem": "collections"
},
...
]
Creating a Dispute¶
This endpoint is used to create a new dispute using internal IDs and/or external codes. In order to successfully create a dispute,
the following must be provided: a dispute reason, a documentNumber, an accountNumber and a valid amount greater than 0.
Regarding dispute reason, it can be provided in several ways
- internal reason ID/code through reasonId or reasonCode fields
- external reason ID/code through externalReasonId or externalReasonCode fields
When providing external reason, it should belong to a category with a default internal reason set.
Swagger Page¶
Permission¶
Dispute Management : CREATE
Example Request¶
curl -X POST 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/disputes' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-Billtrust-Api-Key: <API key value>' \
-d '{ "amount": 100.50, "accountNumber": "ACT-123", "documentNumber": "INV-789", "reasonCode": "{reasonCode}", "assigneeId": "{assigneeId}", "poNumber": "PO-12345" }'
Example Response¶
{
"disputeId": "{disputeId}",
"disputeCode": "D-INV-789-01",
"tenantId": "{tenantId}",
"categoryId": "{categoryId}",
"categoryName": "Shipping Error",
"externalReasonCategoryId": null,
"externalReasonCategoryName": null,
"reasonId": "{reasonId}",
"reasonName": "Damaged in Shipping",
"externalReasonId": null,
"externalReasonName": null,
"assigneeId": "{assigneeId}",
"assigneeName": "Steve Rogers",
"departmentId": "{departmentId}",
"departmentName": "Shipping",
"status": 0,
"amount": 100.50,
"isValid": false,
"resolutionId": null,
"closedDate": null,
"platformAccountId": null,
"documentNumber": "INV-789",
"poNumber": "PO-12345",
"accountNumber": "ACT-123",
"accountName": "test-account",
"createUser": "{userId}",
"createDate": "2021-03-27T18:01:42.847Z",
"updateUser": "{userId}",
"updateDate": "2021-03-27T18:01:42.847Z",
"userId": "{assigneeUserId}",
"currencyCode": "USD",
"resolutionCode": null,
"originSystem": "collections"
}
Updating a Dispute¶
This endpoint updates the dispute identified by the internal ID provided in the path. Similar to the create endpoint, internal/external IDs and/or internal/external codes can be used in the request body.
Swagger Page¶
Permission¶
Dispute Management : UPDATE
Example Request¶
curl -X PUT 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/disputes/{disputeId}' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-Billtrust-Api-Key: <API key value>' \
-d '{ "amount": 100.50, "reasonId": "{reasonId}", "assigneeEmail": "{assigneeEmail}", "poNumber": "PO-12345" }'
Example Response¶
{
"disputeId": "{disputeId}",
"disputeCode": "D-INV-789-01",
"tenantId": "{tenantId}",
"categoryId": "{categoryId}",
"categoryName": "Shipping Error",
"externalReasonCategoryId": null,
"externalReasonCategoryName": null,
"reasonId": "{reasonId}",
"reasonName": "Damaged in Shipping",
"externalReasonId": null,
"externalReasonName": null,
"assigneeId": "{assigneeId}",
"assigneeName": "Steve Rogers",
"departmentId": "{departmentId}",
"departmentName": "Shipping",
"status": 0,
"amount": 100.50,
"isValid": false,
"resolutionId": null,
"closedDate": null,
"platformAccountId": null,
"documentNumber": "INV-789",
"poNumber": "PO-12345",
"accountNumber": "ACT-123",
"createUser": "{userId}",
"createDate": "2021-03-27T18:01:42.847Z",
"updateUser": "{userId}",
"updateDate": "2021-03-29T14:31:20.000Z",
"userId": "{assigneeUserId}",
"currencyCode": "USD",
"resolutionCode": null,
"originSystem": "collections"
}
Deleting a Dispute¶
This endpoint deletes the dispute identified by the internal ID provided. Deleting a dispute is different than closing a dispute and should only be used if the dispute was created in error. Real disputes that are no longer being worked on should be updated to have a status of closed instead.
Swagger Page¶
Permission¶
Dispute Management : DELETE
Example Request¶
curl -X DELETE 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/disputes/{disputeId}' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-Billtrust-Api-Key: <API key value>'
Retrieving disputes using list of document number and account number¶
This endpoint retrieves a list of disputes for the given tenant using list of document number and account number.
Swagger Page¶
Permission¶
Dispute Management : READ
Example Request¶
curl -X GET 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/accounts/{accountNumber}/disputes/by-document-numbers' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-Billtrust-Api-Key: <API key value>' \
-d '{ "status": "Open", "documentNumbers": [ "INV-789","doc-2"], "page": 1, "pageSize": 20}'
Example Response¶
[
{
"disputeId": "{disputeId}",
"disputeCode": "D-INV-789-01",
"tenantId": "{tenantId}",
"categoryId": "{categoryId}",
"categoryName": "Shipping Error",
"externalReasonCategoryId": null,
"externalReasonCategoryName": null,
"reasonId": "{reasonId}",
"reasonName": "Damaged in Shipping",
"externalReasonId": null,
"externalReasonName": null,
"assigneeId": "{assigneeId}",
"assigneeName": "Steve Rogers",
"departmentId": "{departmentId}",
"departmentName": "Shipping",
"status": 0,
"amount": 100.50,
"isValid": false,
"resolutionId": null,
"closedDate": null,
"platformAccountId": null,
"documentNumber": "INV-789",
"poNumber": "PO-12345",
"accountNumber": "ACT-123",
"createUser": "{userId}",
"createDate": "2021-03-27T18:01:42.847Z",
"updateUser": "{userId}",
"updateDate": "2021-03-29T14:31:20.000Z",
"userId": "{assigneeUserId}",
"currencyCode": "USD",
"resolutionCode": null,
"originSystem": "collections"
}
]
Retrieving disputes using list of dispute ids¶
This endpoint retrieves a list of disputes for the given tenant using list of dispute ids.
Swagger Page¶
Permission¶
Dispute Management : READ
Example Request¶
curl -X GET 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/disputes/by-dispute-ids' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-Billtrust-Api-Key: <API key value>' \
-d '{ "disputeIds": [ "01" ], "page": 1, "pageSize": 20'
Example Response¶
[
{
"disputeId": "01",
"disputeCode": "D-INV-789-01",
"tenantId": "{tenantId}",
"categoryId": "{categoryId}",
"categoryName": "Shipping Error",
"externalReasonCategoryId": null,
"externalReasonCategoryName": null,
"reasonId": "{reasonId}",
"reasonName": "Damaged in Shipping",
"externalReasonId": null,
"externalReasonName": null,
"assigneeId": "{assigneeId}",
"assigneeName": "Steve Rogers",
"departmentId": "{departmentId}",
"departmentName": "Shipping",
"status": 0,
"amount": 100.50,
"isValid": false,
"resolutionId": null,
"closedDate": null,
"platformAccountId": null,
"documentNumber": "INV-789",
"poNumber": "PO-12345",
"accountNumber": "ACT-123",
"createUser": "{userId}",
"createDate": "2021-03-27T18:01:42.847Z",
"updateUser": "{userId}",
"updateDate": "2021-03-29T14:31:20.000Z",
"userId": "{assigneeUserId}",
"currencyCode": "USD",
"resolutionCode": null,
"originSystem": "collections"
}
]