Admin Dispute Mediation

Admins play a crucial role in resolving disputes fairly and maintaining marketplace integrity. This guide explains how administrators manage, investigate, and resolve disputes using the WP Sell Services dispute system.

Admin Role in Disputes

Responsibilities

Marketplace administrators:

Review Disputes: Evaluate submitted disputes objectively
Investigate Claims: Examine evidence from both parties
Make Decisions: Determine fair resolutions
Implement Solutions: Process refunds and apply resolutions
Maintain Standards: Ensure platform policies are followed

Neutral Mediation

Admins must remain:

Impartial: No bias toward buyers or vendors
Objective: Base decisions on evidence
Fair: Apply policies consistently
Professional: Maintain courteous communication

Accessing Disputes

Admin Dispute Dashboard

Navigate to WordPress Admin → WP Sell Services → Disputes.

Dashboard Shows:

List of all disputes
Current status of each
Order reference numbers
Parties involved
Date opened
Quick action buttons

Viewing Dispute Details

Click any dispute to view:

Dispute Information:

Dispute ID
Order ID and details
Initiating party
Reason and description
Current status
Creation and update timestamps

Party Information:

Buyer details
Vendor details
Order history for context

Evidence:

All submitted evidence (JSON stored)
Evidence type (text, image, file, link)
Submission timestamps
Submitter user IDs

Managing Dispute Status

Available Status Transitions

Admins can change dispute status using update_status():

// Update status with optional note
$dispute_service->update_status( $dispute_id, 'pending_review', 'Reviewing evidence' );

Status Options

Status	Use When
`open`	Initial submission, awaiting responses
`pending_review`	Evidence complete, awaiting admin action
`escalated`	Needs higher-level review
`resolved`	Decision made, being implemented
`closed`	Finalized and complete

Adding Status Notes

Status notes help track decision process:

// Note is stored in evidence JSON as type 'status_note'
$dispute_service->update_status(
    $dispute_id,
    'escalated',
    'Escalating due to high order value and conflicting evidence'
);

Notes are visible to admins and optionally to parties.

Reviewing Evidence

Evidence Access

Get all evidence for a dispute:

$evidence = $dispute_service->get_evidence( $dispute_id );

Returns array of evidence items with:

Unique ID
User ID of submitter
Evidence type
Content (text, attachment ID, or URL)
Description
Timestamp

Evidence Types

text: Written explanations

Stored directly in content field
Searchable

image: Image attachment

Content is WordPress attachment ID
Use wpgetattachment_url() to display

file: Document attachment

Content is WordPress attachment ID
Use wpgetattachment_url() to download

link: External URL

Content is sanitized URL
Opens in new tab

Evaluating Evidence

Consider:

Relevance: Does evidence relate to the claim?
Authenticity: Does evidence appear legitimate?
Timing: When was evidence created/submitted?
Consistency: Does evidence align with other facts?

Resolution Types

Admins select from 5 resolution types when resolving disputes.

Full Refund

Constant: DisputeService::RESOLUTIONREFUND Value: 'fullrefund'

When to Use:

Complete non-delivery by vendor
Work completely unusable
Severe quality issues
Vendor violated major terms

Order Impact:

Order status → ‘refunded’
Buyer receives full refund
Vendor receives nothing

Partial Refund

Constant: DisputeService::RESOLUTIONPARTIALREFUND Value: 'partial_refund'

When to Use:

Some work completed but incomplete
Quality below promised but partially usable
Both parties share fault

Order Impact:

Order status → ‘partially_refunded’
Buyer receives partial refund
Vendor receives remaining amount

Favor Vendor

Constant: DisputeService::RESOLUTIONFAVORVENDOR Value: 'favor_vendor'

When to Use:

Vendor met all requirements
Buyer’s complaint is unreasonable
Work matches description
Evidence supports vendor

Order Impact:

Order status → ‘completed’
Vendor receives full payment
No refund to buyer

Favor Buyer

Constant: DisputeService::RESOLUTIONFAVORBUYER Value: 'favor_buyer'

When to Use:

Vendor clearly at fault
Requirements not met
Deliverables substandard

Order Impact:

Order status → ‘refunded’
Similar to full refund

Mutual Agreement

Constant: DisputeService::RESOLUTIONMUTUAL Value: 'mutualagreement'

When to Use:

Both parties negotiated solution
Custom arrangement reached
Standard resolutions don’t fit

Order Impact:

Order status → ‘completed’
Custom payment split if needed

Resolving Disputes

Resolution Method

Use the resolve() method:

$result = $dispute_service->resolve(
    $dispute_id,
    DisputeService::RESOLUTION_PARTIAL_REFUND,
    'Vendor delivered partial work. Splitting payment 50/50.',
    get_current_user_id(), // Admin ID
    50.00 // Refund amount
);

Resolution Parameters

$dispute_id (int): Dispute to resolve
$resolution (string): Resolution type constant
$notes (string): Explanation for decision
$resolved_by (int): Admin user ID
$refund_amount (float): Amount to refund (if applicable)

What Happens Automatically

When you call resolve():

✓ Dispute status → ‘resolved’
✓ Resolution type stored
✓ Resolution notes saved
✓ Resolved timestamp recorded
✓ Refund amount stored in evidence
✓ Order status updated via handle_resolution()
✓ Parties notified via wpssdisputeresolved action
✓ Returns true on success

Refund Processing

Refund Information Storage

Refund amounts are stored in evidence JSON:

{
  "id": "refund_123",
  "type": "refund_info",
  "refund_amount": 75.00,
  "created_at": "2026-02-12 14:30:00"
}

Actual Refund Processing

Important: The resolve() method does NOT process actual payment refunds. It only:

Updates dispute status
Records refund amount
Updates order status

You must separately:

Process refund through WooCommerce
Or handle refund via payment gateway
Or credit buyer’s wallet (if using Pro wallet feature)

Order Status After Resolution

The handle_resolution() private method updates order status:

switch ( $resolution ) {
    case RESOLUTION_REFUND:
    case RESOLUTION_FAVOR_BUYER:
        // Order → 'refunded'
        break;

    case RESOLUTION_PARTIAL_REFUND:
        // Order → 'partially_refunded'
        break;

    case RESOLUTION_FAVOR_VENDOR:
    case RESOLUTION_MUTUAL:
        // Order → 'completed'
        break;
}

Adding Evidence as Admin

Admins can add evidence on behalf of parties or from investigation:

$dispute_service->add_evidence(
    $dispute_id,
    get_current_user_id(), // Your admin ID
    'text',
    'Admin note: Verified with buyer via phone call.',
    'Verbal confirmation from buyer'
);

Evidence Parameters

$dispute_id (int): Dispute ID
$user_id (int): User ID adding evidence (use your admin ID)
$type (string): ‘text’, ‘image’, ‘file’, ‘link’
$content (string): Content or attachment ID
$description (string): Optional description

Evidence During Closed Status

Evidence cannot be added if dispute status is ‘closed’:

if ( $dispute->status === DisputeService::STATUS_CLOSED ) {
    // add_evidence() returns false
}

Dispute Queries

Get All Disputes

$disputes = $dispute_service->get_all( [
    'status'   => 'open', // Optional filter
    'limit'    => 20,
    'offset'   => 0,
    'order_by' => 'created_at',
    'order'    => 'DESC',
] );

Get User’s Disputes

$user_disputes = $dispute_service->get_by_user( $user_id, [
    'status' => 'resolved',
    'limit'  => 10,
] );

Returns disputes where user is:

Dispute initiator, OR
Order customer, OR
Order vendor

Count by Status

$counts = $dispute_service->count_by_status();
// Returns:
// [
//     'open' => 5,
//     'pending_review' => 3,
//     'resolved' => 120,
//     'escalated' => 1,
//     'closed' => 98,
// ]

WordPress Hooks

Action: wpssdisputeopened

Fires when dispute is created:

add_action( 'wpss_dispute_opened', function( $dispute_id, $order_id, $opened_by, $data ) {
    // Send custom notifications
    // Log to external system
    // Trigger Slack alert
}, 10, 4 );

Action: wpssdisputeevidence_added

Fires when evidence is submitted:

add_action( 'wpss_dispute_evidence_added', function( $dispute_id, $user_id ) {
    // Notify admin of new evidence
}, 10, 2 );

Action: wpssdisputestatus_changed

Fires on status updates:

add_action( 'wpss_dispute_status_changed', function( $dispute_id, $status, $old_status ) {
    // Track status transitions
    // Update external systems
}, 10, 3 );

Action: wpssdisputeresolved

Fires when dispute is resolved:

add_action( 'wpss_dispute_resolved', function( $dispute_id, $resolution, $dispute, $refund_amount ) {
    // Process actual refund here
    // Send resolution emails
    // Update analytics
}, 10, 4 );

Best Practices

Fair Mediation

Review All Evidence: Don’t rush to judgment
Stay Neutral: No favorites
Document Reasoning: Always explain decisions
Be Consistent: Apply same standards to all
Communicate Clearly: Use professional language

Investigation Process

Read Order Details: Understand what was purchased
Review Service Description: What was promised?
Check Requirements: What did buyer provide?
Examine Deliverables: What did vendor deliver?
Read Messages: Full conversation context
Evaluate Evidence: Who has stronger case?

Resolution Writing

Good Resolution Note:

After reviewing evidence, I'm issuing a 50% partial refund.

Reasoning:
- Logo design delivered matches service description
- However, source files promised in Premium package not provided
- Vendor delivered 2 of 3 included revisions
- Delivery was 3 days late

Resolution:
- Buyer receives $50 refund (50%)
- Vendor receives $50 payment (50%)
- Order marked as completed

This decision is final.

Poor Resolution Note:

50% refund seems fair.

Always explain your reasoning clearly.

Troubleshooting

Can’t Update Status

Check:

Dispute exists: get( $dispute_id ) returns object?
Status is valid: Use STATUS_ constants
User has admin capability

Resolve Method Returns False

Common Causes:

Dispute ID doesn’t exist
Dispute already resolved
Invalid resolution type
Database error (check error logs)

Evidence Not Showing

Verify:

Evidence stored as JSON in database
Evidence column is longtext type
JSON is valid and decodable
Call get_evidence() method, not direct DB query

Admin Dispute Mediation

Admin Role in Disputes

Responsibilities

Neutral Mediation

Accessing Disputes

Admin Dispute Dashboard

Viewing Dispute Details

Managing Dispute Status

Available Status Transitions

Status Options

Adding Status Notes

Reviewing Evidence

Evidence Access

Evidence Types

Evaluating Evidence

Resolution Types

Full Refund

Partial Refund

Favor Vendor

Favor Buyer

Mutual Agreement

Resolving Disputes

Resolution Method

Resolution Parameters

What Happens Automatically

Refund Processing

Refund Information Storage

Actual Refund Processing

Order Status After Resolution

Adding Evidence as Admin

Evidence Parameters

Evidence During Closed Status

Dispute Queries

Get All Disputes

Get User’s Disputes

Count by Status

WordPress Hooks

Action: wpssdisputeopened

Action: wpssdisputeevidence_added

Action: wpssdisputestatus_changed

Action: wpssdisputeresolved

Best Practices

Fair Mediation

Investigation Process

Resolution Writing

Troubleshooting

Can’t Update Status

Resolve Method Returns False

Evidence Not Showing

Related Documentation