Plum Guide API - Integration Certification Plan

Overview

This certification plan outlines the requirements for partners integrating with the Plum Guide API v2. The API supports two integration paths depending on your pricing and availability management approach.

Key Concept: If you use the Length of Stay (LoS) Matrix endpoint, you do NOT need to use the individual pricing and availability endpoints. The matrix handles both comprehensively. Choose one path based on your system's capabilities.

Integration Paths

Path A: LoS Matrix Integration

The LoS Matrix provides a single endpoint to manage both pricing and availability through a CSV-based matrix upload. This is the recommended approach if your system can generate pricing matrices.

What it replaces:

• Custom nightly pricing endpoints
• Seasonal pricing endpoints
• Discount endpoints
• Availability restrictions

What you still need:

• Authentication
• Listings management
• Bookings management
• Webhooks (recommended)

---

Path B: Standard Integration

Use individual endpoints for granular control over pricing and availability. This path requires implementing multiple endpoints but offers more flexibility.

Required endpoints:

• Authentication
• Listings management
• Availability management (restrictions + blocked dates)
• Custom nightly pricing
• Seasonal pricing
• Discounts
• Fees (cleaning fee if applicable)
• Bookings management
• Webhooks (recommended)

---

Certification Requirements

Phase 1: Foundation (Required for ALL integrations)

1.1 Authentication

Acceptance Criteria:

• Successfully authenticate with valid credentials

• Store and reuse the token until expiry

• Implement token refresh before expiry

• Handle authentication errors gracefully

1.2 Listings Management

Acceptance Criteria:

• Create a listing with required fields (address, coordinates, currency)
• Map external property IDs (Integration ID, Airbnb ID, PM ID)
• Handle pagination correctly (limit 1-100, offset)
• Update listing configuration as needed

---

1.3 Bookings Management

Booking Statuses to Handle:

• Requested - Awaiting host approval (Request to Book)
• Confirmed - Payment processed, booking active (Instant Book or Host Approved the booking)
• Declined - Host rejected
• Cancelled - Booking cancelled

Acceptance Criteria:

• Retrieve and parse all booking fields correctly
• Handle all booking statuses
• Extract the guest proxy email for communication
• Implement pagination for large result sets
• Create test bookings in the sandbox for testing

1.4 Webhooks Configuration (Recommended)

Webhook Events to Handle:

• Booking Requested
• Booking Confirmed (Instant Book)
• Booking Approved
• Booking Declined
• Booking Cancelled

Acceptance Criteria:

• Configure webhook endpoint URL
• Receive and process webhook payloads
• Handle webhook delivery retries
• Implement idempotency for duplicate events
• Toggle webhooks without losing configuration

Phase 2A: LoS Matrix Integration Path

Complete this phase ONLY if using the LoS Matrix approach

2A.1 LoS Matrix Upload

Matrix Requirements:

• CSV format with dates and length-of-stay columns
• Idempotency key required (unique per matrix version)
• Optional currency code parameter
• Asynchronous processing (202 response)

Breakdown Matrix (Optional):

• Includes accommodation, fees, and taxes separately
• More detailed pricing breakdown for transparency

Acceptance Criteria:

• Generate a valid CSV matrix format
• Include all required date ranges
• Generate unique idempotency keys per upload
• Handle 202 async response correctly
• Handle 422 validation errors
• Verify matrix applied via the GET endpoint
• Delete and replace the matrix when needed

Phase 2B: Standard Integration Path

Complete this phase ONLY if NOT using the LoS Matrix approach

2B.1 Availability Management

Availability Restrictions:

• minDaysBeforeCheckin - Minimum advance booking days
• seasonalMinimumNights - Minimum night requirements
• changeOverDays - Allowed check-in/check-out days

Bulk Operation Limits:

• Maximum 100 date ranges per request
• Maximum 730 individual dates per request

Acceptance Criteria:

• Set seasonal availability restrictions
• Block specific date ranges
• Sync blocked dates from the external calendar
• Handle bulk operations within limits
• Remove availability when the property is delisted

---

2B.2 Custom Nightly Pricing

Acceptance Criteria:

• Set nightly prices for specific date ranges
• Override seasonal pricing with custom rates
• Handle pagination for large date ranges
• Bulk delete within limits (100 ranges / 730 dates)

---

2B.3 Seasonal Pricing

Seasonal Pricing Features:

• Base nightly rate per season
• Weekend rate differentiation
• Guest fee configuration

Acceptance Criteria:

• Define pricing seasons with date ranges
• Set base rates and weekend rates
• Configure additional guest fees
• Handle overlapping seasons correctly

---

2B.4 Discounts

Discount Types:

• Length of stay discounts (weekly, monthly)
• Early Bird discounts
• Last Minute discounts

Note: POST overrides any existing discount configuration

Acceptance Criteria:

• Configure length-of-stay discounts
• Set early bird / last minute promotions
• Understand discount override behavior

---

2B.5 Cleaning Fee

Acceptance Criteria:

• Set the cleaning fee amount
• Update the cleaning fee when changes

---

Certification Checklist Summary

Path A: LoS Matrix Integration

• Phase 1.1 - Authentication
• Phase 1.2 - Listings Management
• Phase 1.3 - Bookings Management
• Phase 1.4 - Webhooks Configuration
• Phase 2A.1 - LoS Matrix Upload

Path B: Standard Integration

• Phase 1.1 - Authentication
• Phase 1.2 - Listings Management
• Phase 1.3 - Bookings Management
• Phase 1.4 - Webhooks Configuration
• Phase 2B.1 - Availability Management
• Phase 2B.2 - Custom Nightly Pricing
• Phase 2B.3 - Seasonal Pricing
• Phase 2B.4 - Discounts
• Phase 2B.5 - Cleaning Fee

---

Testing Environment

Sandbox Testing

1. Use sandbox credentials for all testing
2. Create test bookings via POST /testdata/booking
3. Test all endpoints before production deployment
4. Verify webhook delivery to your test endpoint

---

Error Handling Requirements

All integrations must handle these response codes:

---

Pagination Standards

For endpoints returning lists:

• Default limit: 20 items
• Maximum limit: 100 items
• Use offset parameter for navigation
• Always check for additional pages

GET /v2/bookings?limit=50&offset=0
GET /v2/bookings?limit=50&offset=50

---

Support & Resources

• API Documentation: https://docs.api.plumguide.com/reference/getting-started
• Swagger UI: https://sandbox.api.plumguide.com/swagger/index.html
• Technical Support: [email protected]

---

Certification Process

1. Development - Implement against sandbox environment
2. Self-Testing - Complete all applicable test cases above
3. Review - Submit integration for Plum Guide review
4. Certification - Receive approval and production credentials
5. Go-Live - Deploy to production