Dispute are created when a customer contests billed features or usage. A dispute is tied to a usage record or a feature on an invoice. Only items that have been billed can be disputed. All operations for managing disputes respect customer limit-to’s.
Prerequisites
When working with disputes, there are some key pieces of information that come in handy:
- CustomerID – unique identifier for a customer within the system. Here are two ways to get CustomerID:
- Perform a CustomerSearch operation in the Customer web service by specifying the Name or Account Number of the customer you want to manage disputes for. CustomerID is contained in the response of the call to the operation.
- Query the CustomerSummary OData in the Customer web service and filter to the customer you want to manage disputes for. CustomerID is a field in the result set.
- InvoiceNumber – unique identifier for an invoice in the system.
- Query the Invoice OData in the Customer web service and filter by CustomerID to get a list of invoices. InvoiceNumber is a field on each invoice returned.
- FeatureID – unique identifier for a feature in the system.
- Query the InvoiceFeature OData in the Customer web service and filter by CustomerID and InvoiceNumber to get a list of billed features. FeatureID is a field on each billed feature returned.
- UsageRecordID – unique identifier for a usage record in a bill period.
- Query the UsageDetail OData in the Customer web service. CustomerID and UsageAlias need to be provided in the header of the request. UsageAlias can be obtained from the invoice record retrieved when getting an InvoiceNumber. UsageRecordID is a field on each usage detail row returned.
- ResolutionID – unique identifier for a dispute resolution in the system.
- Use the Dispute Resolution operation in the Balance web service to get a list of configured dispute resolutions in the system.
Creating a Dispute
A dispute must be created against either a specific usage record or a feature on an invoice for a customer. This can be accomplished using the Create Dispute operation in the Balance web service with some of the prerequisite information mentioned above.
Example:
POST /api/customer/{customerID}/dispute
Request body for creating a dispute on a feature:
{
"invoiceNumber": 1984950,
"amount": 4.95,
"description": "The customer says they shouldn't have been charged",
"resolutionID": 1,
"featureID": 10986,
"usageRecordID": null
}
Request body for creating a dispute on a usage record:
{
"invoiceNumber": 1984950,
"amount": 1.50,
"description": "The customer says they shouldn't have been charged",
"resolutionID": 1,
"featureID": null,
"usageRecordID": 465320
}
Get a list of Disputes for a Customer
To get a list of disputes for a customer, use the Search Disputes operation in the Balance web service.
Example:
GET /api/customer/{customerID}/dispute
Response:
{
"value": [
{
"adjustmentAmount": -9.99,
"adjustmentID": 1002,
"amount": 9.99,
"billPeriodID": 21180214,
"closeDate": "2016-09-09T13:35:09.1568626-04:00",
"description": "Customer is disputing invoice charge.",
"disputeID": 10003,
"disputeDate": "2016-09-09T13:35:09.1568626-04:00",
"feature": "MONTHLY FEE",
"featureID": 103254,
"invoiceCategoryid": 12,
"invoiceNumber": 1003324,
"lastModifiedDate": "2016-09-09T13:35:09.1568626-04:00",
"lastModifiedUser": "csr_user",
"resolution": "Approved",
"resolutionID": 303,
"reversalAdjustmentID": 1004,
"reversalFeeAdjustmentID": 10044,
"serviceID": 10430092,
"serviceNumber": 1234567890,
"usageBatchID": null,
"usageRecordNumber": null
}
]
}
Modifying a Dispute
After a dispute has been created, it can be modified using the Update Dispute operation in the Balance web service. Modifications can only be made on an open dispute. The request uses the JSON Patch document structure.
Example:
PATCH /api/customer/{customerID}/dispute/{disputeID}
Request body:
[
{
"op": "replace",
"path": "/amount",
"value": "1.25"
}
]
Working a Dispute
During the dispute process, a dispute can be adjusted, reversed, have a fee applied, closed, and reopened, all using the Balance web service.
Adjusting a Dispute
To adjust a dispute, use the Add Dispute Adjustment operation. This operation creates an adjustment in the system and updates the dispute with the adjustment ID.
Reversing a Dispute
Only disputes that have been adjusted can be reversed. The Add Dispute Reversal operation creates a reversal adjustment for the inverse amount of the adjustment on the dispute and updates the dispute with the reversal adjustment ID.
Applying a Fee to a Dispute
Only disputes that have been reversed can have a fee applied. The Add Dispute Reversal Fee operation creates a fee adjustment in the system and updates the dispute with the fee adjustment ID.
Closing a Dispute
After a dispute has served its purpose, it can be closed. The Close Dispute operation sets the close date on the dispute and prevents it from being modified.
Reopening a Dispute
Once a dispute is closed, it cannot be modified. However, if a change needs to be made to the dispute, then it must be reopened. The Reopen Dispute operation reopens the dispute and clears the resolution.
