Dispute Categories¶

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 Category by ID¶

Swagger Page¶

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

Permission¶

Dispute Configuration : READ

Example Request¶

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

Example Response¶

See DisputeCategoryV1Response.

Retrieving a Category by Code¶

Swagger Page¶

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

Permission¶

Dispute Configuration : READ

Example Request¶

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

Example Response¶

See DisputeCategoryV1Response.

Retrieving a List of Categories¶

Swagger Page¶

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

Permission¶

Dispute Configuration : READ

Example Request¶

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

Example Response¶

See Dispute Category List.

Creating a Category¶

Swagger Page¶

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

Permission¶

Dispute Configuration : CREATE

Example Request¶

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

Example Request Body¶

{
  "code": "SHIPPING",
  "description": "Shipping Mistakes",
  "defaultInternalReasonId": "{defaultInternalReasonId}",
  "defaultExternalReasonId": "{defaultExternalReasonId}"
}

Request Fields¶

Field	Type	Required	Description
`code`	string	Yes	Unique identifier for the category within the tenant. Stored as uppercase
`description`	string	No	Display description of the category
`defaultInternalReasonId`	string	No	Default reason applied to disputes when an internal reason is not explicitly provided. Must have `Internal` or `All` visibility
`defaultExternalReasonId`	string	No	Default reason applied to disputes when an external reason is not explicitly provided. Must have `External` or `All` visibility

Behavior Notes¶

If a category with the same code already exists for the tenant, this endpoint updates it rather than returning an error. Returns 201 on both create and upsert.
code is trimmed and converted to uppercase before storage. SHIPPING and shipping resolve to the same category.
defaultInternalReasonCode and defaultExternalReasonCode in the response are auto-populated from the provided reason IDs.

Example Response¶

See DisputeCategoryV1Response.

Updating a Category¶

Swagger Page¶

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

Permission¶

Dispute Configuration : UPDATE

Example Request¶

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

Example Request Body¶

{
  "description": "Shipping Errors",
  "defaultInternalReasonId": "{defaultInternalReasonId}",
  "defaultExternalReasonId": "{defaultExternalReasonId}"
}

Request Fields¶

Field	Type	Required	Description
`description`	string	No	Updated display description
`defaultInternalReasonId`	string	No	Updated default internal reason. Must have `Internal` or `All` visibility
`defaultExternalReasonId`	string	No	Updated default external reason. Must have `External` or `All` visibility

Example Response¶

See DisputeCategoryV1Response.

Deleting a Category by ID¶

Swagger Page¶

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

Permission¶

Dispute Configuration : DELETE

Example Request¶

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

Behavior Notes¶

Returns 409 Conflict if the category is referenced by any dispute reason. Remove or reassign those reasons before deleting.

Deleting a Category by Code¶

Swagger Page¶

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

Permission¶

Dispute Configuration : DELETE

Example Request¶

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

Behavior Notes¶

Returns 409 Conflict if the category is referenced by any dispute reason.

Appendix¶

DisputeCategoryV1Response¶

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

{
  "categoryId": "{categoryId}",
  "tenantId": "{tenantId}",
  "code": "SHIPPING",
  "description": "Shipping Mistakes",
  "defaultInternalReasonId": "{defaultInternalReasonId}",
  "defaultInternalReasonCode": "{defaultInternalReasonCode}",
  "defaultExternalReasonId": "{defaultExternalReasonId}",
  "defaultExternalReasonCode": "{defaultExternalReasonCode}",
  "createUser": "{userId}",
  "createDate": "2021-03-28T15:30:21.242Z",
  "updateUser": "{userId}",
  "updateDate": "2021-03-28T15:30:21.242Z"
}

Returned by Retrieving a List of Categories. An array of DisputeCategoryV1Responses.

[
  {
    "categoryId": "{categoryId}",
    "tenantId": "{tenantId}",
    "code": "SHIPPING",
    "description": "Shipping Mistakes",
    "defaultInternalReasonId": "{defaultInternalReasonId}",
    "defaultInternalReasonCode": "{defaultInternalReasonCode}",
    "defaultExternalReasonId": "{defaultExternalReasonId}",
    "defaultExternalReasonCode": "{defaultExternalReasonCode}",
    "createUser": "{userId}",
    "createDate": "2021-03-28T15:30:21.242Z",
    "updateUser": "{userId}",
    "updateDate": "2021-03-28T15:30:21.242Z"
  },
  ...
]

Dispute Categories¶

Retrieving a Category by ID¶

Swagger Page¶

Permission¶

Example Request¶

Example Response¶

Retrieving a Category by Code¶

Swagger Page¶

Permission¶

Example Request¶

Example Response¶

Retrieving a List of Categories¶

Swagger Page¶

Permission¶

Example Request¶

Example Response¶

Creating a Category¶

Swagger Page¶

Permission¶

Example Request¶

Example Request Body¶

Request Fields¶

Behavior Notes¶

Example Response¶

Updating a Category¶

Swagger Page¶

Permission¶

Example Request¶

Example Request Body¶

Request Fields¶

Example Response¶

Deleting a Category by ID¶

Swagger Page¶

Permission¶

Example Request¶

Behavior Notes¶

Deleting a Category by Code¶

Swagger Page¶

Permission¶

Example Request¶

Behavior Notes¶

Appendix¶

DisputeCategoryV1Response¶

Dispute Category List¶