Using WPResidence API for Invoice Management: A Step-by-Step Guide

Modern real estate platforms require robust financial management systems to handle transactions between property owners, agents, and clients. The WPResidence API offers comprehensive endpoints for managing invoices programmatically, enabling developers to automate billing workflows and integrate with accounting systems. This guide explores how to leverage these API endpoints for efficient invoice management.

What Are Invoices in WPResidence?

In WPResidence, invoices are financial records stored as custom post types (wpestate_invoice) that document transactions for various services:

• Property Listings: Fees for publishing property listings
• Featured Listings: Charges for upgrading to featured status
• Membership Packages: Subscription fees for agents/agencies
• Reservation Fees: Payments for property bookings

Each invoice contains:

• Basic information (date, amount, status)
• Buyer and seller details
• Reference to the purchased item
• Payment status tracking
• Transaction IDs for external payment systems

Invoices play a critical role in tracking financial transactions, generating reports, and maintaining transparent billing records for all parties involved in real estate transactions.

Listing Invoices: Retrieving Data via API

WPResidence real estate theme provides multiple endpoints for retrieving invoice data with robust filtering capabilities.

All Invoices Endpoint (Administrator Access)

Endpoint: POST /wpresidence/v1/invoices

This endpoint returns all invoices and requires administrator privileges.

Request Parameters

{
  "page": 1,
  "posts_per_page": 20,
  "start_date": "2023-01-01",
  "end_date": "2023-12-31",
  "type": "Reservation fee",
  "status": "confirmed",
  "billing_type": "One Time",
  "price_min": 100,
  "price_max": 5000
}

Key filtering parameters:

• page: Pagination control (default: 1)
• posts_per_page: Results per page (default: 10, max: 100)
• start_date/end_date: Date range for invoice creation
• type: Invoice type filter (Listing, Upgrade to Featured, Publish Listing with Featured, Package, Reservation fee)
• status: Payment status filter (confirmed, issued, etc.)
• billing_type: Billing type filter (One Time, Recurring)
• price_min/price_max: Price range filters

Customer Invoices Endpoint

Endpoint: GET /wpresidence/v1/owner/{user_id}/invoices

This endpoint retrieves invoices for a specific customer/owner.

Request Parameters

• user_id: (Required) The user ID in path
• Query parameters support the same filters as the all invoices endpoint

Personal Invoices Endpoint

Endpoint: GET /wpresidence/v1/my-invoices

This endpoint returns invoices for the currently authenticated user.

Response Structure

{
  "status": "success",
  "invoices": [
    {
      "id": 12345,
      "title": "Invoice #12345",
      "date": "2023-03-15 14:30:45",
      "status": "1",
      "status_text": "Paid",
      "type": "Reservation fee",
      "type_display": "Reservation fee",
      "item_id": "789",
      "item_price": 1250.00,
      "purchase_date": "2023-03-15",
      "invoice_period": "not aplicable",
      "billing_type": "One Time",
      "billing_type_display": "One Time",
      "author": 42,
      "property_id": 567
    },
    // Additional invoices...
  ],
  "pagination": {
    "current_page": 1,
    "posts_per_page": 20,
    "total_posts": 45,
    "total_pages": 3,
    "has_previous": false,
    "has_next": true
  },
  "totals": {
    "total_confirmed": 7500.00,
    "total_issued": 2750.00
  },
  "filters": {
    "type": "Reservation fee",
    "status": "confirmed",
    "start_date": "2023-01-01",
    "end_date": "2023-12-31"
  }
}

Viewing Invoice Information

To retrieve detailed information about a specific invoice, use the single invoice endpoint.

Endpoint: GET /wpresidence/v1/invoice/{id}

Where {id} is the invoice post ID.

Request Parameters

• id: (Required) The invoice ID (path parameter)

Authentication and Permissions

Access is restricted to:

• The invoice author
• The buyer associated with the invoice
• Administrators

Response Example

{
  "status": "success",
  "invoice": {
    "id": 12345,
    "title": "Invoice #12345",
    "date": "2023-03-15 14:30:45",
    "status": "1",
    "status_text": "Paid",
    "type": "Reservation fee",
    "type_display": "Reservation fee",
    "item_id": "789",
    "item_price": 1250.00,
    "purchase_date": "2023-03-15",
    "invoice_period": "not aplicable",
    "billing_type": "One Time",
    "billing_type_display": "One Time",
    "author": 42,
    "property_id": 567,
    
    // Additional invoice metadata may be included based on type
    "buyer_details": {
      "id": 123,
      "name": "John Smith",
      "email": "john@example.com"
    },
    "property_details": {
      "id": 567,
      "title": "Luxury Apartment Downtown"
    }
  }
}

Adding a New Invoice (Request Structure & Fields)

New invoices can be created using the invoice creation endpoint.

Endpoint: POST /wpresidence/v1/invoice/add

Authentication Requirements

• Valid JWT token in request header
• User must be an administrator

Required Fields

• billing_for: Type of billing (Listing, Upgrade to Featured, Publish Listing with Featured, Package, Reservation fee)
• type: Billing type (1 = One Time, 2 = Recurring)
• item_id: ID of the item being billed (property, membership package, or booking)
• buyer_id: ID of the user being billed

Full Request Example

{
  "billing_for": "Reservation fee",
  "type": 1,
  "item_id": 789,
  "buyer_id": 123,
  "is_featured": 0,
  "is_upgrade": 0,
  "txn_id": "pay_2344567abcdef"
}

Optional Fields

• is_featured: Whether the property is featured (0 or 1)
• is_upgrade: Whether this is an upgrade (0 or 1)
• txn_id: External transaction ID for payment tracking

Response

{
  "status": "success",
  "message": "Invoice created successfully.",
  "invoice": {
    "id": 12345,
    "title": "Invoice #12345",
    "date": "2023-03-15 14:30:45",
    "status": "0",
    "status_text": "Not Paid",
    "type": "Reservation fee",
    // Additional invoice details...
  }
}

Updating an Invoice

Invoices can be updated through the invoice update endpoint.

Endpoint: PUT /wpresidence/v1/invoice/edit/{id}

Where {id} is the invoice post ID.

Authentication and Permissions

• Valid JWT token
• User must be an administrator

Request Example

{
  "pay_status": 1,
  "invoice_type": "Reservation fee",
  "biling_type": "One Time",
  "item_price": 1350.00,
  "author_id": 42
}

Updateable Fields

• pay_status: Payment status (0 = Not Paid, 1 = Paid)
• invoice_type: Type of invoice
• biling_type: Billing type (One Time or Recurring)
• item_price: Price amount
• author_id: ID of the invoice creator

Response

{
  "status": "success",
  "message": "Invoice updated successfully",
  "invoice_id": 12345,
  "changes": {
    "pay_status": {
      "from": "0",
      "to": "1"
    },
    "item_price": {
      "from": 1250.00,
      "to": 1350.00
    }
  },
  "invoice": {
    // Updated invoice details...
  }
}

Removing an Invoice from the System

Invoices can be permanently deleted using the invoice deletion endpoint.

Endpoint: DELETE /wpresidence/v1/invoice/delete/{id}

Where {id} is the invoice post ID.

Authentication and Permissions

• Valid JWT token
• User must be an administrator

Response

{
  "status": "success",
  "message": "Invoice deleted successfully",
  "invoice_id": 12345,
  "deleted_invoice": {
    // Details of the deleted invoice...
  }
}

Linking Invoices to Properties & Agencies

Invoice-Property Relationships

Invoices can be linked to properties through:

1. Direct Reference: For property-related invoices (listings, featured upgrades), the item_id refers to the property ID
2. Via Booking: For reservation fee invoices, the booking ID is stored, which links to a property

Invoice-Agency/Agent Relationships

Invoices maintain relationships with agencies and agents through:

1. Buyer Association: The buyer_id field can reference an agent or agency user
2. Author Reference: The invoice creator (author) may be the agency/agent

Creating Property-Linked Invoices

When creating an invoice for a property listing:

{
  "billing_for": "Listing",
  "type": 1,
  "item_id": 567, // Property ID
  "buyer_id": 123, // Property owner/agent
  "is_featured": 0,
  "is_upgrade": 0
}

For booking/reservation fees:

{
  "billing_for": "Reservation fee",
  "type": 1,
  "item_id": 789, // Booking ID
  "buyer_id": 123, // Guest/tenant
  "is_featured": 0,
  "is_upgrade": 0
}

Debugging API Errors

Common Error Types

1. Authentication Errors
   • jwt_auth_failed: Invalid/missing JWT token
   • rest_forbidden: User lacks required permissions
   • insufficient_permissions: Only administrators can create invoices
2. Validation Errors
   • missing_required_fields: Required fields missing from request
   • invalid_billing_type: Billing type not allowed
   • invalid_buyer: Specified buyer does not exist
   • invalid_item: Specified item does not exist
   • invalid_status: Invalid pay_status value
   • invalid_price: Price cannot be negative
3. Resource Errors
   • invalid_invoice: Invoice not found or wrong post type
   • invoice_creation_failed: Error during invoice creation
   • deletion_failed: Failed to delete invoice

Troubleshooting Techniques

1. Validate Request Format
   • Check JSON structure and field types
   • Ensure all required fields are present
   • Verify enum values match expected values
2. Check Authentication
   • Verify JWT token is current and valid
   • Confirm user has administrator privileges
3. Test with Postman or Similar Tools
   • Create collection of requests for each endpoint
   • Save example payloads for reuse
   • Isolate and test individual fields when debugging
4. Enable Detailed Error Responses
   • WP_DEBUG can provide more detailed error messages
   • Check server error logs for PHP warnings/errors

Best Practices for Error Handling

1. Progressive Testing
   • Start with minimal valid requests, then add fields
   • Keep a library of known-good request examples
   • Create test cases for different invoice types
2. Implement Robust Client-Side Validation
   • Validate required fields before submission
   • Check field formats (dates, emails, numbers)
   • Show user-friendly error messages
3. Log API Interactions
   • Record requests, responses, and timestamps
   • Include context data like user IDs and session info
   • Implement error notification system for critical failures

Best Practices for Invoice Management via API

1. Implement Proper Authorization
   • Use JWT tokens securely
   • Implement role-based access control
   • Only grant necessary permissions to users
2. Optimize Data Retrieval
   • Use field filtering to reduce payload size
   • Implement pagination for large datasets
   • Cache common queries when appropriate
3. Transaction Safety
   • Implement idempotency for financial operations
   • Use transaction IDs to prevent duplicate payments
   • Record audit trails for all financial changes
4. Integration with External Systems
   • Create adapters for accounting systems
   • Implement webhooks for real-time updates
   • Design consistent error handling across systems
5. Testing and Validation
   • Create comprehensive test suites
   • Test edge cases and error conditions
   • Validate financial calculations

Conclusion

The WPResidence API provides robust tools for programmatically managing invoices, allowing developers to create streamlined financial workflows for real estate platforms. By familiarizing yourself with the available endpoints, required parameters, and best practices, you can develop powerful integrations that automate invoice creation, tracking, and reporting.

When implemented correctly, the invoice management API can significantly improve your real estate platform’s financial capabilities by reducing manual data entry, minimizing errors, and offering better insights into your business’s economic health.

Official documentation is here : https://www.postman.com/universal-eclipse-339362/wpresidence/overview