Disputes (v2)

Disputes (v2)¶

Platform dispute CRUD under /v2/tenants/{tenantId}/disputes. Use this surface for workspace-style integrations. v1 remains available for legacy callers — see Disputes.

v2 shares the same dispute records as v1 but exposes additional fields and list behavior. Notes, attachments, audits, and configuration APIs stay on v1 paths.

What differs from v1¶

Topic	v2 behavior
Assignee	Optional on create and update. Omit or blank → unassigned.
Department	Optional. If omitted and an assignee is present, department may be inferred from the assignee. Missing department alone is not an error.
Amount (create)	Must be greater than 0. When invoice total is available, amount must not exceed it.
Amount (update / PATCH)	Value ≤ 0 keeps the existing amount.
`buyerContact`	Optional `{ name, email, phone, language }`. See Buyer contact.
`billId`	Optional document-service bill id. See Bill id.
List filters	Richer multi-value, text modes, amount, dates, currency, assignee presence. See List filters.
Sort	Single allow-listed field only (default `-CreateDate`). Server adds `DisputeId` as a stable tie-break.
Paging	`page` ≥ 1; `pageSize` 1–100 (default 20). Same `x-pagination-*` response headers as v1.
Delete	Soft-delete; 204 even if the dispute is already gone (idempotent).

Closed and cancelled disputes can still be updated via the API (UI may enforce view-only).

Retrieving a Dispute by DisputeId¶

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v2#/DisputesV2/get_v2_tenants__tenantId__disputes__disputeId_

Permission¶

Dispute Management : READ

Example Request¶

curl -X GET 'https://arc-aegis.billtrust.com/dispute/v2/tenants/{tenantId}/disputes/{disputeId}?includeInvoiceDetails=true' \
    -H 'accept: application/json' \
    -H 'X-Billtrust-Api-Key: <API key value>'

Query Parameters¶

Field	Type	Description
`includeInvoiceDetails`	boolean	When `true`, includes live open balance (and invoice amount fallback for legacy rows without a stored snapshot)
`customerId`	integer	Optional billing customer id when loading invoice details
`includeDeleted`	boolean	When `true`, returns a soft-deleted dispute if present (intended for denormalization workers)

Example Response¶

See DisputeV2Response.

Retrieving a List of Disputes¶

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v2#/DisputesV2/get_v2_tenants__tenantId__disputes

Permission¶

Dispute Management : READ

Example Request¶

curl -X GET 'https://arc-aegis.billtrust.com/dispute/v2/tenants/{tenantId}/disputes?status=Open&assigneePresence=unassigned&documentNumber=INV-1,INV-2&sort=-CreateDate&page=1&pageSize=20' \
    -H 'accept: application/json' \
    -H 'X-Billtrust-Api-Key: <API key value>'

Request Filters¶

Multi-value id and status filters accept repeated query keys and/or CSV (OR match), for example ?status=Open&status=Closed or ?status=Open,Closed.

Field	Description	Match notes
`status`	One or more statuses as strings (`Open`, `Closed`, `Cancel`)	Multi-value; case-insensitive; unknown → 400
`assigneeId`	One or more assignee ids	Multi-value; when set, wins over `assigneePresence`
`assigneePresence`	`any` (default), `assigned`, or `unassigned`	Used only when `assigneeId` is omitted
`departmentId`	One or more department ids	Multi-value
`departmentName`	Department display name	Case-insensitive contains
`includeEmptyDepartment`	When `true` and a department filter is present, also include rows with empty department id and name	Boolean
`categoryId` / `reasonId`	One or more ids	Multi-value
`categoryName` / `reasonName`	Display name	Case-insensitive contains
`billId`	One or more document-service bill ids	Multi-value; exact match
`platformAccountId`	Platform account id	Exact
`accountNumber`, `accountName`, `documentNumber`, `poNumber`	Text filters	See Text filters
`currencyCode`	One or more ISO currency codes	Multi-value; case-insensitive exact match (no mode)
`createDate_gte` / `createDate_lte`	Create date bounds (ISO 8601)	Inclusive; gte > lte → 400
`updatedDate_gte` / `updatedDate_lte`	Update date bounds (ISO 8601)	Inclusive; gte > lte → 400
`amount`	Exact disputed amount	Numeric only; max 2 decimal places; not combinable with gt/lt
`amount_gt` / `amount_lt`	Exclusive bounds on amount	Alone or together as exclusive between (`gt` < `lt`); max 2 decimals
`populateDisputeNote`	When `true`, loads notes per dispute on the page (extra queries)	Boolean
`sort`	Single allow-listed field; prefix `-` for descending	Default `-CreateDate`. Allowed includes `CreateDate`, `UpdateDate`, `Status`, `Amount`, `InvoiceAmount`, account/document/PO fields, department/reason/category id and name, `AssigneeId`, `AssigneeName`
`page` / `pageSize`	Paging	`page` ≥ 1; `pageSize` 1–100

Text filters¶

For accountNumber, accountName, documentNumber, and poNumber:

Companion mode query: accountNumberMode, accountNameMode, documentNumberMode, poNumberMode
Modes: eq (default), startsWith, endsWith — always case-insensitive
eq only: repeated keys and/or CSV → OR any token (trim, drop empty, CI dedupe). Max 20 values per field after normalize (21+ → 400)
startsWith / endsWith: single value only (no CSV split; multiple keys → 400)
Values that contain commas are not supported for multi-value eq

Different filter fields are **AND**ed together.

Example Response¶

An array of DisputeV2Response objects, plus standard pagination headers (see Pagination and Filters).

Creating a Dispute¶

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v2#/DisputesV2/post_v2_tenants__tenantId__disputes

Permission¶

Dispute Management : CREATE

Example Request¶

curl -X POST 'https://arc-aegis.billtrust.com/dispute/v2/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}",
  "currencyCode": "USD",
  "originSystem": "workspace",
  "buyerContact": {
    "name": "Jane Buyer",
    "email": "jane.buyer@example.com",
    "phone": "+1-555-0100",
    "language": "en"
  },
  "billId": "{optionalBillId}"
}

Request fields callers should know¶

Field	Required	Notes
`documentNumber`	Yes	Invoice/document number
`accountNumber`	Yes	Account number
`amount`	Yes (conceptually)	Must be > 0; rejected if it exceeds invoice total when billing data is available
`assigneeId` / `assigneeEmail`	No	Omit for unassigned
`departmentId` / `departmentCode`	No	Optional; may be inferred from assignee
Reason / category (id or code)	Same rules as v1	Internal and external reason visibility rules still apply
`buyerContact`	No	See Buyer contact
`billId`	No	See Bill id
`originSystem`, `platformAccountId`, `accountName`, `poNumber`, `currencyCode`, status/resolution fields	No	Same general meanings as v1

Example Response¶

201 Created with DisputeV2Response. Location header points at /v2/tenants/{tenantId}/disputes/{disputeId}.

Updating a Dispute¶

Full replace-style update (PUT). Immutable create-time fields (documentNumber, accountNumber, accountName, platformAccountId, originSystem, disputeCode, invoiceAmount) are preserved from the stored dispute.

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v2#/DisputesV2/put_v2_tenants__tenantId__disputes__disputeId_

Permission¶

Dispute Management : UPDATE

Example Request¶

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

Behavior Notes¶

Amount: omitted or ≤ 0 keeps the existing amount; a positive amount is validated (including invoice ceiling when available).
Assignee: omit/null clears assignee (unassign).
Buyer contact: null/omit keeps existing; empty object clears; object with fields replaces.
Bill id: can be set only when not already stored; changing an existing value returns 400.

Example Response¶

See DisputeV2Response.

Partially Updating a Dispute¶

JSON Patch (RFC 6902), same pattern as v1.

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v2#/DisputesV2/patch_v2_tenants__tenantId__disputes__disputeId_

Permission¶

Dispute Management : UPDATE

Example Request¶

curl -X PATCH 'https://arc-aegis.billtrust.com/dispute/v2/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": "/amount", "value": 75.00 },
  { "op": "remove", "path": "/buyerContact" }
]

Behavior Notes¶

remove /buyerContact or replace /buyerContact with null clears buyer contact (unlike full PUT null/omit, which keeps it).
Amount and bill id rules match Update.

Example Response¶

See DisputeV2Response.

Deleting a Dispute¶

Soft-deletes the dispute. Returns 204 No Content whether the dispute was deleted now or was already missing/deleted (idempotent).

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v2#/DisputesV2/delete_v2_tenants__tenantId__disputes__disputeId_

Permission¶

Dispute Management : DELETE

Example Request¶

curl -X DELETE 'https://arc-aegis.billtrust.com/dispute/v2/tenants/{tenantId}/disputes/{disputeId}' \
    -H 'accept: application/json' \
    -H 'X-Billtrust-Api-Key: <API key value>'

Buyer contact¶

Optional object on create/update/response:

Field	Description
`name`	Buyer name
`email`	Buyer email
`phone`	Buyer phone
`language`	Free-form locale tag (for example `en`, `en-gb`, `fr-ca`); not validated against a fixed list

Bill id¶

billId identifies the document-service bill the dispute is against.

Create: optional. If omitted and both accountNumber and documentNumber are present, the service may resolve the newest matching bill automatically.
Update: fill-in only when the stored value is empty; changing a set value is rejected.
List: filter with multi-value billId.
Response: included on v2 payloads (not on the v1 JSON contract).

DisputeV2Response¶

Same core fields as v1, plus buyerContact and billId. invoiceAmount is the create-time snapshot when available.

{
  "disputeId": "{disputeId}",
  "disputeCode": "D-INV-789-01",
  "tenantId": "{tenantId}",
  "categoryId": "{categoryId}",
  "categoryName": "Shipping Error",
  "reasonId": "{reasonId}",
  "reasonName": "Damaged in Shipping",
  "assigneeId": null,
  "assigneeName": null,
  "departmentId": null,
  "departmentName": null,
  "status": 0,
  "amount": 100.50,
  "invoiceAmount": 500.00,
  "isValid": true,
  "documentNumber": "INV-789",
  "accountNumber": "ACT-123",
  "accountName": "test-account",
  "currencyCode": "USD",
  "originSystem": "workspace",
  "billId": "{billId}",
  "buyerContact": {
    "name": "Jane Buyer",
    "email": "jane.buyer@example.com",
    "phone": "+1-555-0100",
    "language": "en"
  },
  "openBalance": null,
  "createDate": "2026-03-27T18:01:42.847Z",
  "updateDate": "2026-03-27T18:01:42.847Z"
}