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 DisputeId¶

This endpoint retrieves a single dispute using the internal identifier for the dispute, the disputeId.

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputesV1/get_v1_tenants__tenantId__disputes__disputeId_

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¶

See DisputeV1Response.

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¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputesV1/get_v1_tenants__tenantId__disputes

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
AccountName	The name of the account on the dispute	Partial match supported
Status	Filter by one or more statuses. `0` for `Open`, `1` for `Closed`, `2` for `Cancel`	Multi-value; exact match per value
AssigneeId	The internal ID for the dispute's assignee	Multi-value; exact match per value
DepartmentId	The internal ID for the dispute's department. If DepartmentName is set, we ignore this filter	Full match only
DocumentNumber	The external document number on the dispute	Full match only
AccountNumber	The external account number on the dispute	Partial match supported
AccountNumber_eq	The external account number on the dispute. If both AccountNumber and AccountNumber_eq are supplied, both filters are applied	Full match only
PlatformAccountId	The internal platform account ID associated with the dispute	Full match only
UpdatedDate_lte	Return disputes last updated on or before this date (ISO 8601)	Date range (upper bound)
UpdatedDate_gte	Return disputes last updated on or after this date (ISO 8601)	Date range (lower bound)
PopulateDisputeNote	When `true`, the service performs one additional database query per dispute in the result page to fetch its notes. Avoid enabling this on large page sizes	Boolean flag
Sort	Default sort (when `Sort` is not provided) is `DisputeId` ascending. See Pagination & Filters
Page	See Pagination & Filters
PageSize	See Pagination & Filters

Behavior Notes¶

Status vs AssigneeId Multiple Values Filter - Status accepts multiple values via repeated query parameters (e.g., ?Status=0&Status=1). Disputes matching any of the supplied statuses are returned (OR logic). - AssigneeId accepts multiple values as a comma-delimited string in a single parameter (e.g., ?AssigneeId={id1},{id2}). Disputes matching any of the supplied assignee IDs are returned (OR logic).

Name-based filters (ReasonName, DepartmentName, CategoryName) - These filters work by first looking up config records whose descriptions match the provided value (partial, case-insensitive). If no matching config record is found, the endpoint returns an empty result set rather than an error.

Example Response¶

See Dispute List.

Creating a Dispute¶

This endpoint is used to create a new dispute.

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputesV1/post_v1_tenants__tenantId__disputes

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 '<request body>'

Example Request Body¶

{
  "documentNumber": "INV-789",
  "accountNumber": "ACT-123",
  "amount": 100.50,
  "reasonCode": "{reasonCode}",
  "assigneeId": "{assigneeId}",
  "poNumber": "PO-12345",
  "originSystem": "collections",
  "currencyCode": "USD"
}

Request Fields¶

See Shared Request Fields for fields accepted by both create and update. The following fields are only accepted on create:

Field	Type	Required	Description
`documentNumber`	string	Yes	The external document/invoice number the dispute is raised against
`accountNumber`	string	Yes	The external account number issuing the dispute
`accountName`	string	No	Display name of the account
`platformAccountId`	string	No	Billtrust platform account ID
`originSystem`	string	No	Identifier for the system creating the dispute

Example Response¶

See DisputeV1Response.

Updating a Dispute¶

This endpoint updates the dispute identified by the internal ID provided in the path.

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputesV1/put_v1_tenants__tenantId__disputes__disputeId_

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 '<request body>'

Example Request Body¶

{
  "amount": 100.50,
  "reasonId": "{reasonId}",
  "assigneeEmail": "{assigneeEmail}",
  "poNumber": "PO-12345"
}

Request Fields¶

See Shared Request Fields. The create-only fields (documentNumber, accountNumber, accountName, platformAccountId, originSystem) are not accepted here.

Example Response¶

See DisputeV1Response.

Partially Updating a Dispute¶

Applies a partial update to the dispute using a JSON Patch document (RFC 6902). Useful when you only want to change one or two fields without sending the full object.

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputesV1/patch_v1_tenants__tenantId__disputes__disputeId_

Permission¶

Dispute Management : UPDATE

Example Request¶

curl -X PATCH 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/disputes/{disputeId}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json-patch+json' \
    -H 'X-Billtrust-Api-Key: <API key value>' \
    -d '<request body>'

Example Request Body¶

[
  { "op": "replace", "path": "/status", "value": 1 },
  { "op": "replace", "path": "/resolutionId", "value": "{resolutionId}" }
]

Request Fields¶

The request body is an array of patch operations. Each operation has:

Field	Description
`op`	Operation type: `replace`, `add`, or `remove`
`path`	The field to target as a JSON Pointer (e.g. `/amount`, `/assigneeId`)
`value`	The new value (required for `replace` and `add`)

Patchable fields match Shared Request Fields. The same immutable-field rules apply as on Update, documentNumber, accountNumber, disputeCode, platformAccountId, and originSystem cannot be changed.

Example Response¶

See DisputeV1Response.

Deleting a Dispute¶

This endpoint deletes the dispute identified by the internal ID provided.

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputesV1/delete_v1_tenants__tenantId__disputes__disputeId_

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 AccountNumber and a List of DocumentNumbers¶

Returns disputes for a specific account scoped to a list of document numbers.

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputesV1/post_v1_tenants__tenantId__accounts__accountNumber__disputes_by_document_numbers

Permission¶

Dispute Management : READ

Example Request¶

curl -X POST '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 '<request body>'

Example Request Body¶

{
  "documentNumbers": ["INV-789", "INV-790"],
  "status": 0,
  "page": 1,
  "pageSize": 20
}

Request Fields¶

Field	Type	Required	Description
`documentNumbers`	string[]	Yes	List of document numbers to filter by
`status`	integer	No	`0` = Open, `1` = Closed, `2` = Cancel. Accepts a single value only
`page`	integer	No	Page number; defaults to `1`
`pageSize`	integer	No	Records per page; defaults to `20`

Example Response¶

See Dispute List.

Retrieving Disputes Using a List of DisputeIds¶

Returns disputes for a given set of internal dispute Ids.

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputesV1/post_v1_tenants__tenantId__disputes_by_dispute_ids

Permission¶

Dispute Management : READ

Example Request¶

curl -X POST '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 '<request body>'

Example Request Body¶

{
  "disputeIds": ["{disputeId1}", "{disputeId2}"],
  "page": 1,
  "pageSize": 20
}

Request Fields¶

Field	Type	Required	Description
`disputeIds`	string[]	Yes	List of internal dispute IDs to retrieve
`page`	integer	No	Page number; defaults to `1`
`pageSize`	integer	No	Records per page; defaults to `20`

Example Response¶

See Dispute List.

Dispute Summary by Reason for Account¶

Returns the total disputed amount for each reason code associated with a given account number.

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputesV1/get_v1_tenants__tenantId__accounts__accountNumber__disputes_summary_by_reason

Permission¶

Dispute Management : READ

Example Request¶

curl -X GET 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/accounts/{accountNumber}/disputes/summary/by-reason' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-Billtrust-Api-Key: <API key value>'

Example Response¶

See DisputeSummaryByReasonResponse.

Summary for Assigned User¶

Returns an aggregate summary of all disputes assigned to the currently authenticated user, grouped by currency code.

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputesV1/get_v1_tenants__tenantId__disputes_summary_assignee

Permission¶

Dispute Management : READ

Example Request¶

curl -X GET 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/disputes/summary/assignee' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-Billtrust-Api-Key: <API key value>'

Example Response¶

See DisputeSummaryResponse.

Summary for Assigned User Grouped by Account¶

Returns a paginated list of accounts with open disputes assigned to the currently authenticated user, along with aggregated totals per account.

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputesV1/get_v1_tenants__tenantId__disputes_summary_assignee_by_account

Permission¶

Dispute Management : READ

Example Request¶

curl -X GET 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/disputes/summary/assignee/by-account?sort=-TotalAmount&page=1&pageSize=20' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-Billtrust-Api-Key: <API key value>'

Query Parameters¶

Field	Type	Description
`sort`	string	Fields to sort by; defaults to `-TotalAmount`. Prepend `-` for descending
`page`	integer	Page number; defaults to `1`
`pageSize`	integer	Records per page; defaults to `20`

Example Response¶

See DisputeSummaryForAccountResponse.

Summary for Assignee's Department¶

Returns an aggregate summary of all disputes across the authenticated user's entire department, grouped by currency code.

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputesV1/get_v1_tenants__tenantId__disputes_summary_department

Permission¶

Dispute Management : READ

Example Request¶

curl -X GET 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/disputes/summary/department' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-Billtrust-Api-Key: <API key value>'

Example Response¶

See DisputeSummaryResponse.

Summary for Assignee's Department Grouped by Account¶

Returns a paginated list of accounts with open disputes in the authenticated user's department, with aggregated totals per account.

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputesV1/get_v1_tenants__tenantId__disputes_summary_department_by_account

Permission¶

Dispute Management : READ

Example Request¶

curl -X GET 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/disputes/summary/department/by-account?sort=-TotalAmount&page=1&pageSize=5' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-Billtrust-Api-Key: <API key value>'

Query Parameters¶

Field	Type	Description
`sort`	string	Fields to sort by; defaults to `-TotalAmount`. Prepend `-` for descending
`page`	integer	Page number; defaults to `1`
`pageSize`	integer	Records per page; defaults to `5`

Example Response¶

See DisputeSummaryForAccountResponse.

Summary for Assignee's Department Grouped by Assignee¶

Returns a paginated list of assignees in the authenticated user's department with aggregated dispute totals per assignee.

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputesV1/get_v1_tenants__tenantId__disputes_summary_department_by_assignee

Permission¶

Dispute Management : READ

Example Request¶

curl -X GET 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/disputes/summary/department/by-assignee?sort=-TotalAmount&page=1&pageSize=5' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-Billtrust-Api-Key: <API key value>'

Query Parameters¶

Field	Type	Description
`sort`	string	Fields to sort by; defaults to `-TotalAmount`. Prepend `-` for descending
`page`	integer	Page number; defaults to `1`
`pageSize`	integer	Records per page; defaults to `5`

Example Response¶

See DisputeSummaryForAssigneeResponse.

Total Disputed Amount for a Document¶

Returns the total disputed amount across all open disputes for a specific document and account combination.

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputesV1/get_v1_tenants__tenantId__accounts__accountNumber__documents__documentNumber__disputes_summary

Permission¶

Dispute Management : READ

Example Request¶

curl -X GET 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/accounts/{accountNumber}/documents/{documentNumber}/disputes/summary' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-Billtrust-Api-Key: <API key value>'

Behavior Notes¶

Only open disputes are included in the total. Closed and cancelled disputes are excluded.
currencyCode in the response is taken from the first matching dispute. If disputes for the same document were created with different currency codes, the result may not reflect a true multi-currency total.

Example Response¶

See DisputedDocumentAmountV1Response.

Appendix¶

Shared Request Fields¶

Accepted by both Create and Update. All fields are optional.

Field	Type	Description
`amount`	decimal	The disputed amount
`reasonId`	string	Internal ID of the dispute reason
`reasonCode`	string	Code alternative to `reasonId`
`categoryId`	string	Internal ID of the dispute category
`categoryCode`	string	Code alternative to `categoryId`
`externalReasonId`	string	ID of an external (buyer-facing) reason
`externalReasonCode`	string	Code alternative to `externalReasonId`; requires `externalReasonCategoryCode`
`externalReasonCategoryCode`	string	Required when using `externalReasonCode`
`assigneeId`	string	Internal ID of the assignee
`assigneeEmail`	string	Email alternative to `assigneeId`
`departmentId`	string	Internal ID of the department
`departmentCode`	string	Code alternative to `departmentId`
`resolutionId`	string	Required when `status` is `Closed`
`resolutionCode`	string	Code alternative to `resolutionId`
`status`	integer	`0` = Open (default), `1` = Closed, `2` = Cancel
`poNumber`	string	Purchase order number associated with the document
`currencyCode`	string	Currency code; defaults to tenant default if omitted or invalid
`isValid`	boolean	Whether the dispute is considered valid
`closedDate`	datetime	Closed timestamp

DisputeV1Response¶

Returned by single-dispute endpoints (Get by ID, Create, Update).

{
  "disputeId": "{disputeId}",
  "disputeCode": "D-INV-789-01",
  "tenantId": "{tenantId}",
  "categoryId": "{categoryId}",
  "categoryName": "Shipping Error",
  "categoryCode": "SHIP",
  "externalReasonCategoryId": null,
  "externalReasonCategoryName": null,
  "externalReasonCategoryCode": null,
  "reasonId": "{reasonId}",
  "reasonName": "Damaged in Shipping",
  "reasonCode": "DAMAGED",
  "externalReasonId": null,
  "externalReasonName": null,
  "externalReasonCode": null,
  "assigneeId": "{assigneeId}",
  "assigneeName": "Steve Rogers",
  "assigneeEmail": "steve.rogers@avengers.com",
  "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",
  "invoiceAmount": null,
  "openBalance": null,
  "disputeNote": null
}

DisputedDocumentAmountV1Response¶

Returned by Total Disputed Amount for a Document.

{
  "disputedAmount": 1250.50,
  "currencyCode": "USD",
  "documentNumber": "INV-789",
  "accountNumber": "ACT-123"
}

DisputeSummaryByReasonResponse¶

Returned by Dispute Summary by Reason for Account. One entry per reason code.

[
  {
    "reasonCode": "DAMAGED",
    "reasonDesc": "Damaged in Shipping",
    "disputeAmount": 2500.00
  },
  {
    "reasonCode": "LATE",
    "reasonDesc": "Late Delivery",
    "disputeAmount": 1200.50
  }
]

DisputeSummaryResponse¶

Returned by Summary for Assigned User and Summary for Assignee's Department. One entry per currency code. All values are 0 when no disputes exist.

[
  {
    "totalAmount": 7300.50,
    "count": 4,
    "largestDisputedAmount": 2500.00,
    "currencyCode": "USD",
    "departmentId": "{departmentId}"
  }
]

DisputeSummaryForAccountResponse¶

Returned by Summary for Assigned User Grouped by Account and Summary for Assignee's Department Grouped by Account. One entry per account.

[
  {
    "totalAmount": 5000.00,
    "count": 3,
    "currencyCode": "USD",
    "accountNumber": "ACT-123",
    "accountName": "test-account",
    "departmentId": "{departmentId}"
  }
]

DisputeSummaryForAssigneeResponse¶

Returned by Summary for Assignee's Department Grouped by Assignee. One entry per assignee.

[
  {
    "firstName": "Steve",
    "lastName": "Rogers",
    "assigneeId": "{assigneeId}",
    "email": "steve.rogers@avengers.com",
    "count": 3,
    "totalAmount": 5000.00,
    "currencyCode": "USD",
    "departmentId": "{departmentId}"
  }
]

Dispute List¶

Returned by list endpoints (List, by-document-numbers, by-dispute-ids). An array of DisputeV1Responses.

[
  {
    "disputeId": "{disputeId}",
    "disputeCode": "D-INV-789-01",
    "tenantId": "{tenantId}",
    "categoryId": "{categoryId}",
    "categoryName": "Shipping Error",
    "categoryCode": "SHIP",
    "externalReasonCategoryId": null,
    "externalReasonCategoryName": null,
    "externalReasonCategoryCode": null,
    "reasonId": "{reasonId}",
    "reasonName": "Damaged in Shipping",
    "reasonCode": "DAMAGED",
    "externalReasonId": null,
    "externalReasonName": null,
    "externalReasonCode": null,
    "assigneeId": "{assigneeId}",
    "assigneeName": "Steve Rogers",
    "assigneeEmail": "steve.rogers@avengers.com",
    "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",
    "invoiceAmount": null,
    "openBalance": null,
    "disputeNote": null
  },
  ...
]