Dispute Reasons¶

All GET endpoints support an optional Accept-Language request header. When provided, the description field in the response is returned in the requested language if a translation exists. The response includes a Content-Language header indicating which language was applied.

Retrieving a Reason by ID¶

Swagger Page¶

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

Permission¶

Dispute Configuration : READ

Example Request¶

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

Example Response¶

See DisputeReasonV1Response.

Retrieving a Reason by Category Code and Reason Code¶

Swagger Page¶

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

Permission¶

Dispute Configuration : READ

Example Request¶

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

Example Response¶

See DisputeReasonV1Response.

Retrieving a List of Reasons¶

Swagger Page¶

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

Permission¶

Dispute Configuration : READ

Example Request¶

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

Query Parameters¶

Field	Type	Description
`Visibility`	string	Filter by visibility. `Internal`, `External`, or `All`. Pass as repeated params for multiple values: `?Visibility=Internal&Visibility=External`. Omit to return all reasons

Example Response¶

See Dispute Reason List.

Retrieving a List of Reasons by Category Code¶

Swagger Page¶

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

Permission¶

Dispute Configuration : READ

Example Request¶

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

Example Response¶

See Dispute Reason List.

Retrieving a List of Reasons by Category ID¶

Swagger Page¶

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

Permission¶

Dispute Configuration : READ

Example Request¶

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

Example Response¶

See Dispute Reason List.

Creating a Reason¶

Swagger Page¶

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

Permission¶

Dispute Configuration : CREATE

Example Request¶

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

Example Request Body¶

{
  "code": "DAMAGED",
  "description": "Damaged in Shipping",
  "active": true,
  "categoryId": "{categoryId}",
  "visibility": "Internal"
}

Request Fields¶

Field	Type	Required	Description
`code`	string	Yes	Unique identifier within the category. Stored as uppercase
`description`	string	No	Display description of the reason
`active`	boolean	No	Whether the reason is active; defaults to `false`
`categoryId`	string	No	Internal ID of the category this reason belongs to. Either `categoryId` or `categoryCode` must be provided
`categoryCode`	string	No	Code alternative to `categoryId`
`visibility`	string	No	Visibility of reason

Behavior Notes¶

If a reason with the same categoryId + code already exists, this endpoint updates it rather than returning an error.
code is trimmed and converted to uppercase before storage.

Example Response¶

See DisputeReasonV1Response.

Updating a Reason¶

Swagger Page¶

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

Permission¶

Dispute Configuration : UPDATE

Example Request¶

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

Example Request Body¶

{
  "description": "Damaged during Shipping",
  "active": true,
  "categoryId": "{categoryId}",
  "visibility": "Internal"
}

Request Fields¶

Field	Type	Required	Description
`description`	string	No	Updated display description
`active`	boolean	No	Whether the reason is active
`categoryId`	string	No	Updated category. Either `categoryId` or `categoryCode` must be provided
`categoryCode`	string	No	Code alternative to `categoryId`
`visibility`	string	No	`Internal`, `External`, or `All`

Behavior Notes¶

code is immutable, it cannot be changed after creation.
Cannot change visibility if the reason is linked to any open disputes.
Cannot change category or set active: false if this reason is configured as a category's default internal or external reason.

Example Response¶

See DisputeReasonV1Response.

Deleting a Reason by ID¶

Swagger Page¶

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

Permission¶

Dispute Configuration : DELETE

Example Request¶

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

Behavior Notes¶

Returns 409 Conflict if the reason is linked to any dispute (open or closed), or if it is configured as a category's default internal or external reason.

Deleting a Reason by Category Code and Reason Code¶

Swagger Page¶

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

Permission¶

Dispute Configuration : DELETE

Example Request¶

curl -X DELETE 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/categories/by-code/{categoryCode}/reasons/by-code/{reasonCode}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-Billtrust-Api-Key: <API key value>'

Behavior Notes¶

Returns 409 Conflict if the reason is linked to any dispute or configured as a category default.

Appendix¶

DisputeReasonV1Response¶

Returned by single-reason endpoints (Get by ID, Get by Category+Reason Code, Create, Update).

{
  "reasonId": "{reasonId}",
  "tenantId": "{tenantId}",
  "code": "DAMAGED",
  "description": "Damaged in Shipping",
  "active": true,
  "categoryId": "{categoryId}",
  "categoryName": "Shipping Error",
  "visibility": "Internal",
  "createUser": "{userId}",
  "createDate": "2021-03-28T15:30:21.242Z",
  "updateUser": "{userId}",
  "updateDate": "2021-03-28T15:30:21.242Z"
}

Dispute Reason List¶

Returned by list endpoints (List, List by Category Code, List by Category ID). An array of DisputeReasonV1Responses.

[
  {
    "reasonId": "{reasonId}",
    "tenantId": "{tenantId}",
    "code": "DAMAGED",
    "description": "Damaged in Shipping",
    "active": true,
    "categoryId": "{categoryId}",
    "categoryName": "Shipping Error",
    "visibility": "Internal",
    "createUser": "{userId}",
    "createDate": "2021-03-28T15:30:21.242Z",
    "updateUser": "{userId}",
    "updateDate": "2021-03-28T15:30:21.242Z"
  },
  ...
]