Custom Integrations Guide

Extend WP Sell Services with custom e-commerce platforms, payment gateways, REST API controllers, and more. This guide documents the actual interfaces and extension patterns available in the plugin source code.

Extension Architecture

WP Sell Services provides six contract interfaces in src/Integrations/Contracts/ and several filter-based registration points. The free version ships with WooCommerce integration. The Pro version adds EDD, FluentCart, SureCart, and standalone adapters.

Extension Type	Interface/Filter	Free	Pro
E-commerce Platform	EcommerceAdapterInterface	WooCommerce	EDD, FluentCart, SureCart, Standalone
Payment Gateway	PaymentGatewayInterface	Test Gateway	Stripe, PayPal, Razorpay
Storage Provider	wpssstorageproviders	Local uploads	S3, GCS, DigitalOcean Spaces
Email Provider	wpssemailproviders	WordPress mail	SendGrid, Mailgun, SES
REST API Controller	wpssapicontrollers	20 controllers	Additional endpoints
Analytics Widget	wpssanalyticswidgets	None	Revenue, conversion, vendor analytics

E-Commerce Adapters

EcommerceAdapterInterface

Located at src/Integrations/Contracts/EcommerceAdapterInterface.php. All e-commerce integrations must implement this interface, which delegates to four specialized providers.

interface EcommerceAdapterInterface {
    public function get_id(): string;
    public function get_name(): string;
    public function is_active(): bool;
    public function init(): void;
    public function supports_feature( string $feature ): bool;
    public function get_order_provider(): OrderProviderInterface;
    public function get_product_provider(): ProductProviderInterface;
    public function get_checkout_provider(): CheckoutProviderInterface;
    public function get_account_provider(): AccountProviderInterface;
}

Provider Interfaces

OrderProviderInterface (src/Integrations/Contracts/OrderProviderInterface.php) — Handles order data retrieval: getorder(), getorderitem(), getcustomerorders(), getvendororders(), hasserviceitems(), getserviceitems(), updateitemmeta(), getitemmeta(), getcustomerdata(), handleorder_complete().

ProductProviderInterface (src/Integrations/Contracts/ProductProviderInterface.php) — Handles service-to-product mapping: isserviceproduct(), getservice(), getservicevendors(), getrequirements(), getdeliverytime(), setservicetype(), addservicetypeoption(), saveservicemeta(), syncwith_service().

CheckoutProviderInterface (src/Integrations/Contracts/CheckoutProviderInterface.php) — Handles cart and checkout: addcartitemdata(), validateaddtocart(), getcheckouturl(), carthasservices(), getcartservices(), processcheckout(), getthankyouredirect(), filterquantity_max().

AccountProviderInterface (src/Integrations/Contracts/AccountProviderInterface.php) — Handles user account integration: addmenuitems(), registerendpoints(), getaccounturl(), getordersurl(), getvendordashboardurl(), renderordersendpoint(), renderservicesendpoint(), rendernotificationsendpoint(), canaccessvendordashboard(), getloginurl(), getregister_url().

Creating a Custom Adapter

<?php
namespace MyPlugin;

use WPSellServices\Integrations\Contracts\EcommerceAdapterInterface;

class CustomPlatformAdapter implements EcommerceAdapterInterface {
    public function get_id(): string { return 'custom_platform'; }
    public function get_name(): string { return 'Custom Platform'; }
    public function is_active(): bool { return class_exists( 'CustomPlatform' ); }
    public function init(): void { /* Register platform hooks */ }
    public function supports_feature( string $feature ): bool {
        return in_array( $feature, [ 'checkout', 'orders' ], true );
    }
    public function get_order_provider(): OrderProviderInterface { return new CustomOrderProvider(); }
    public function get_product_provider(): ProductProviderInterface { return new CustomProductProvider(); }
    public function get_checkout_provider(): CheckoutProviderInterface { return new CustomCheckoutProvider(); }
    public function get_account_provider(): AccountProviderInterface { return new CustomAccountProvider(); }
}

// Register via filter
add_filter( 'wpss_ecommerce_adapters', function( $adapters ) {
    $adapters['custom_platform'] = new \MyPlugin\CustomPlatformAdapter();
    return $adapters;
} );

Adapter Selection Logic

The IntegrationManager (src/Integrations/IntegrationManager.php) selects the active adapter:

1. Reads ecommerceplatform from wpssgeneral settings
2. If set to a specific adapter ID and that adapter’s is_active() is true, uses it
3. If set to 'auto' (default), iterates all registered adapters and uses the first active one
4. After selection, calls $adapter->init() and fires wpssadapterinitialized

Payment Gateways

PaymentGatewayInterface

Located at src/Integrations/Contracts/PaymentGatewayInterface.php. Used for standalone payment processing without an e-commerce platform.

interface PaymentGatewayInterface {
    public function get_id(): string;
    public function get_name(): string;
    public function get_description(): string;
    public function is_enabled(): bool;
    public function supports_currency( string $currency ): bool;
    public function init(): void;
    public function create_payment( float $amount, string $currency, array $metadata = [] ): array;
    public function process_payment( string $payment_id ): array;
    public function process_refund( string $transaction_id, ?float $amount = null, string $reason = '' ): array;
    public function handle_webhook( array $payload ): array;
    public function get_settings_fields(): array;
    public function render_payment_form( float $amount, string $currency, int $order_id ): string;
}

Creating a Custom Gateway

The plugin includes a reference implementation at src/Integrations/Gateways/TestGateway.php (debug-only, auto-completes payments). Register your gateway via the wpsspaymentgateways filter (Plugin.php:813):

add_filter( 'wpss_payment_gateways', function( $gateways ) {
    $gateways['custom_pay'] = new \MyPlugin\CustomGateway();
    return $gateways;
} );

Key methods to implement:

• createpayment() should return ['success' => true, 'id' => '...', 'clientsecret' => '...']
• processpayment() should return ['success' => true, 'transactionid' => '...', 'status' => 'completed']
• processrefund() should return ['success' => true, 'refundid' => '...', 'status' => 'completed']
• getsettingsfields() returns an array of field definitions (type, label)
• renderpaymentform() returns HTML for the payment form

REST API Controllers

Custom controllers extend RestController (src/API/RestController.php) which provides:

• check_permissions( $request ) — Verifies user is logged in (returns 401 if not)
• checkadminpermissions( $request ) — Verifies manage_options capability (returns 403 if not)
• userownsresource( $resourceid, $resourcetype ) — Checks ownership for 'service' or 'order'
• paginatedresponse( $items, $total, $page, $perpage ) — Returns paginated response with X-WP-Total and X-WP-TotalPages headers

<?php
namespace MyPlugin;
use WPSellServices\API\RestController;

class CustomController extends RestController {
    protected $rest_base = 'custom';

    public function register_routes() {
        register_rest_route( $this->namespace, '/' . $this->rest_base, [
            [
                'methods'             => \WP_REST_Server::READABLE,
                'callback'            => [ $this, 'get_items' ],
                'permission_callback' => [ $this, 'check_permissions' ],
            ],
        ] );
    }

    public function get_items( \WP_REST_Request $request ): \WP_REST_Response {
        $items = []; // Your data retrieval logic
        return $this->paginated_response( $items, 0, 1, 10 );
    }
}

// Register the controller (filter at API.php:76)
add_filter( 'wpss_api_controllers', function( $controllers ) {
    $controllers[] = new \MyPlugin\CustomController();
    return $controllers;
} );

Provider Registration Filters [PRO]

// Storage providers (Plugin.php:837)
add_filter( 'wpss_storage_providers', function( $providers ) {
    $providers['custom_storage'] = new \MyPlugin\CustomStorageProvider();
    return $providers;
} );

// Email providers (Plugin.php:849)
add_filter( 'wpss_email_providers', function( $providers ) {
    $providers['custom_email'] = new \MyPlugin\CustomEmailProvider();
    return $providers;
} );

// Wallet providers (Plugin.php:825)
add_filter( 'wpss_wallet_providers', function( $providers ) {
    $providers['custom_wallet'] = new \MyPlugin\CustomWalletProvider();
    return $providers;
} );

// Analytics widgets (Plugin.php:861)
add_filter( 'wpss_analytics_widgets', function( $widgets ) {
    $widgets['custom_metric'] = new \MyPlugin\CustomAnalyticsWidget();
    return $widgets;
} );

Settings Tabs

Add custom tabs to admin settings using wpsssettingstabs filter (Settings.php:161) and the dynamic wpsssettingstab_{tab} action (Settings.php:985):

add_filter( 'wpss_settings_tabs', function( $tabs ) {
    $tabs['my_integration'] = 'My Integration';
    return $tabs;
} );

add_action( 'wpss_settings_tab_my_integration', function() {
    echo '<div class="wpss-settings-section"><h2>My Settings</h2>';
    // Your settings form here
    echo '</div>';
} );

Custom Field Types

Register custom field types for service requirements via the wpssregisterfield_types action (FieldManager.php:59). Default types: Text, Textarea, Select, MultiSelect, Radio, Checkbox, FileUpload, Date, Number.

add_action( 'wpss_register_field_types', function( $manager ) {
    $manager->register( new \MyPlugin\ColorPickerField() );
} );

Gutenberg Blocks

Register custom blocks via wpss_blocks filter (BlocksManager.php:93):

add_filter( 'wpss_blocks', function( $blocks ) {
    $blocks[] = [
        'name' => 'wpss/custom-block',
        'args' => [ 'title' => 'Custom Block', 'category' => 'wpss', 'render_callback' => 'render_my_block' ],
    ];
    return $blocks;
} );

How Pro Extends Free

The Pro plugin hooks into wpss_loaded to register all extensions:

What Pro Changes	Filter	Free Default	Pro Value
Gallery images	wpssservicemax_gallery	4	-1 (unlimited)
Service extras	wpssservicemax_extras	3	-1 (unlimited)
FAQ items	wpssservicemax_faq	5	-1 (unlimited)
Video URLs	wpssservicemax_videos	1	3
Requirements	wpssservicemax_requirements	5	-1 (unlimited)
Wizard features	wpssservicewizard_features	All false	AI titles, templates

Vendor Capabilities

The wpssvendor role includes: wpssvendor, wpssmanageservices, wpssmanageorders, wpssviewanalytics, wpssrespondtorequests, read, uploadfiles, edit_posts.

Related Documentation

• Hooks and Filters – Complete hooks reference with file locations
• REST API – API endpoints and authentication
• Theme Integration – Template overrides and styling