Skip to content

Dispute Service

Swagger documentation:

API Gateway Address: https://arc-aegis.billtrust.com/dispute
Lane Platform
Auth X-Billtrust-Api-Key or X-Billtrust-Auth
Key source Self-serve via Authentication

See Connect if you also call External APIs (Ingest / Remittance)—those use a different host and key.

Dispute Overview

The Dispute Service is used to create, read, update, and delete information about disputes and dispute configuration.

Dispute CRUD is available on two API versions under the same gateway host:

Version Base path Use when
v1 (legacy) /v1/tenants/{tenantId}/disputes Existing integrations; frozen request/response contract
v2 (platform) /v2/tenants/{tenantId}/disputes Workspace / platform clients that need optional assignee, buyer contact, bill id, and richer list filters

Configuration resources (reasons, categories, departments, assignees, resolutions, notes, attachments, audits, notification settings) remain on v1 paths only. Summary endpoints used by assignee workflows also remain under v1.

See Disputes for v1 and Disputes (v2) for the platform contract.

Dispute Concepts

Dispute

A dispute represents a claim made by an account that part or all of the outstanding balance on an invoice should not be owed. Attributes of a dispute include

  • Dispute Code - The identifier for the dispute. Usually this will be in the format D-<document number>-## where ## is a 2 digit sequence starting at 01
  • Status - The dispute's status can be either Open (0) or Closed (1) or Cancel (2). A Closed dispute can be either Valid or Invalid and will have a Resolution and a Closed Date.
  • Document Number - Sometimes referred to as the Invoice Number, this represents the tenant's external identifier for the document being disputed.
  • PO Number - The purchase order associated with the document
  • Account Number - The tenant's external identifier for the account issuing the dispute.
  • Amount - The amount being disputed. On v2 create, amount must be greater than zero (and must not exceed the invoice total when billing data is available).
  • Invoice Amount - Create-time snapshot of the invoice total when billing lookup succeeds. Returned on get/list; not refreshed on later updates. Live open balance is separate and only returned when invoice details are requested on get-by-id.
  • Category - A grouping used for dispute reasons. These are usually broad ideas, such as Order Mistakes, Shipping Problems, and Pricing.
  • Reason - A specific reason for a dispute. Each reason belongs to a specific dispute category. An example would be a reason of 'Shipment Never Arrived' under the 'Shipping Problems' category.
  • Department - The department at your organization that will act on a dispute. Examples include Shipping or Accounts Payable. On v2, department is optional; when omitted and an assignee is set, it may be inferred from the assignee's departments.
  • Assignee - The person at your organization assigned to act on a dispute. On v1, assignee is part of the legacy create/update flow. On v2, assignee is optional (disputes may be unassigned).
  • Buyer Contact (v2 only) - Optional structured contact on the dispute: name, email, phone, and free-form language (for example en, en-gb, fr-ca).
  • Bill Id (v2 only on the API) - Document-service identifier for the bill the dispute is against. On create, you may supply it or let the service resolve the newest matching bill from account + document number. Once set, it cannot be changed.
  • Resolution - An action that can be taken to resolve a dispute. Each resolution has a description of the resolution as well as a flag indicating that the resolution was done because the dispute was a valid dispute or not. This can include things like Coupon Issued, Replacement Sent, or Customer Paid.
  • Note - A text comment attached to a dispute. Notes have a visibility setting: Internal notes are visible only to your organization's AR/collections team, while All notes are also visible to external parties such as buyers.
  • Attachment - A file attached to a dispute. Like notes, attachments have a visibility setting (Internal or All). Uploaded files go through an asynchronous virus scan before becoming available for download.