Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.surecart.com/llms.txt

Use this file to discover all available pages before exploring further.

These filters allow you to intercept and modify data before it’s sent to the SureCart API, and transform responses as they come back. This is useful for adding metadata, modifying request parameters, or transforming API responses.

​
surecart/request/model

Filter the model instance before an API request is made. This is the primary way to modify data being sent to the API for any model (checkouts, orders, customers, etc.).
​
Parameters
Filter Parameters
// Add metadata to every checkout
add_filter( 'surecart/request/model', function( $model, $request ) {
    // Only modify checkout models
    if ( ! $model instanceof \SureCart\Models\Checkout ) {
        return $model;
    }

    // Add tracking metadata
    $model['metadata'] = array_merge(
        (array) ( $model['metadata'] ?? [] ),
        [
            'source'      => 'wordpress',
            'landing_page' => $_COOKIE['landing_page'] ?? null,
            'utm_source'  => $_GET['utm_source'] ?? null,
            'utm_medium'  => $_GET['utm_medium'] ?? null,
            'utm_campaign' => $_GET['utm_campaign'] ?? null,
        ]
    );

    return $model;
}, 10, 2 );

​
Add Affiliate Tracking

// Pass affiliate data to checkout metadata
add_filter( 'surecart/request/model', function( $model, $request ) {
    if ( ! $model instanceof \SureCart\Models\Checkout ) {
        return $model;
    }

    // Get affiliate ID from cookie or session
    $affiliate_id = $_COOKIE['affiliate_id'] ?? null;
    
    if ( $affiliate_id ) {
        $model['metadata'] = array_merge(
            (array) ( $model['metadata'] ?? [] ),
            [
                'affiliate_id'  => sanitize_text_field( $affiliate_id ),
                'referral_date' => current_time( 'mysql' ),
            ]
        );
    }

    return $model;
}, 10, 2 );

​
Block Checkout Based on Conditions

// Block checkout from specific countries
add_filter( 'surecart/request/model', function( $model, $request ) {
    if ( ! $model instanceof \SureCart\Models\Checkout ) {
        return $model;
    }

    // Check if POST/PATCH request (creating or updating)
    if ( ! in_array( $request->get_method(), [ 'POST', 'PATCH' ], true ) ) {
        return $model;
    }

    $blocked_countries = [ 'XX', 'YY' ]; // Your blocked country codes
    $billing_country = $model['billing_address']['country'] ?? null;

    if ( $billing_country && in_array( $billing_country, $blocked_countries, true ) ) {
        return new \WP_Error(
            'country_blocked',
            __( 'Orders from your country are not currently accepted.', 'your-textdomain' ),
            [ 'status' => 403 ]
        );
    }

    return $model;
}, 10, 2 );

​
surecart/request/response

Filter the API response after it’s received. Use this to transform, enrich, or modify response data before it’s used.
​
Parameters
Filter Parameters
// Enrich customer responses with WordPress user data
add_filter( 'surecart/request/response', function( $response, $args, $endpoint ) {
    if ( strpos( $endpoint, 'customers' ) === false ) {
        return $response;
    }

    if ( is_object( $response ) && ! empty( $response->email ) ) {
        $wp_user = get_user_by( 'email', $response->email );
        if ( $wp_user ) {
            $response->wp_user_id = $wp_user->ID;
            $response->wp_roles = $wp_user->roles;
        }
    }

    return $response;
}, 10, 3 );

​
surecart/request/args

Filter the HTTP request arguments before sending. This allows you to modify headers, timeouts, or other HTTP-level settings.
​
Parameters
Filter Parameters
// Increase timeout for export endpoints
add_filter( 'surecart/request/args', function( $args, $endpoint ) {
    if ( strpos( $endpoint, 'exports' ) !== false ) {
        $args['timeout'] = 120; // 2 minutes for large exports
    }

    return $args;
}, 10, 2 );

​
surecart/request/endpoint

Filter the API endpoint URL before the request is made. 
add_filter( 'surecart/request/endpoint', function( $endpoint, $args ) {
    // Log endpoints in development
    if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
        error_log( 'SureCart API: ' . $endpoint );
    }

    return $endpoint;
}, 10, 2 );

Models

Hook into model hydration to modify data after it’s received.

Checkout

Higher-level checkout actions and filters.