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

FAQ

What is an invoice in WPResidence, and what kinds of charges does it represent?

In WPResidence, an invoice is a financial record stored as a custom post type (wpestate_invoice) that documents a transaction for platform services. Common invoice types include fees for publishing property listings, upgrading a listing to featured status, membership package subscriptions, and reservation fees for bookings.

Each invoice can store core billing data such as date, amount, and payment status, along with buyer and seller details, a reference to the purchased item (for example, a property or booking), and transaction IDs used by external payment systems.

How do I retrieve invoices via the WPResidence API, and what filters are available?

WPResidence provides multiple endpoints to retrieve invoices depending on who is requesting the data. Administrators can fetch all invoices using POST /wpresidence/v1/invoices, a specific owner/customer’s invoices using GET /wpresidence/v1/owner/{user_id}/invoices, and an authenticated user can fetch their own invoices using GET /wpresidence/v1/my-invoices.

The retrieval endpoints support practical filters including pagination (page, posts_per_page), invoice creation date range (start_date, end_date), invoice type (Listing, Upgrade to Featured, Publish Listing with Featured, Package, Reservation fee), payment status (for example confirmed, issued), billing type (One Time or Recurring), and price range constraints (price_min, price_max).

How can I view the full details of a specific invoice, and who is allowed to access it?

To fetch full details for a single invoice, call GET /wpresidence/v1/invoice/{id}, where {id} is the invoice post ID. The response can include invoice metadata such as type, billing type, item references, and related details like buyer_details and property_details when applicable.

Access to this endpoint is restricted to the invoice author, the buyer associated with the invoice, or an administrator. If the requester does not meet those requirements, the API will reject the request.

How do I create, update, or delete an invoice via the WPResidence API?

Create invoices with POST /wpresidence/v1/invoice/add. This requires a valid JWT token and administrator privileges. Required fields include billing_for (for example Listing or Reservation fee), type (1 for One Time, 2 for Recurring), item_id (property, package, or booking ID), and buyer_id; optional fields include is_featured, is_upgrade, and txn_id for external payment tracking.

Update invoices using PUT /wpresidence/v1/invoice/edit/{id}, which also requires an admin JWT token. You can change fields such as pay_status (0 Not Paid, 1 Paid), invoice_type, biling_type (as shown in the request example), item_price, and author_id. Delete invoices permanently with DELETE /wpresidence/v1/invoice/delete/{id}, again restricted to administrators with a valid JWT token.

When linking invoices to properties, bookings, agents, or agencies, which fields should I rely on?

For property-related invoices (such as listings and featured upgrades), WPResidence links the invoice to a property by using item_id as the property ID. For reservation fee invoices, item_id represents the booking ID, and the booking then links back to the underlying property.

For agent and agency relationships, buyer_id identifies who is being billed (which may be an agent or an agency user), and the invoice author field indicates the invoice creator (which may also be the agency or agent, depending on your workflow).