The access API is a handful of PHP functions that give a user an access group, take it away, and read what the user holds and may open. WooCommerce, registration and the Members screen call the same functions.

The Groups panel on Rosa Iqbal's member page: AI Weekly — Reader, active, added by hand and backdated, and AI Weekly — Free, active, granted on registration
Each row on a member's Groups panel is a grant; smartmembers_get_grants( 42 ) returns these two.

Use them when access comes from something Smart Members doesn't know about: another cart, an invite code, a partner's system. They ship in the free plugin and are available from plugins_loaded on.

smartmembers_grant()

smartmembers_grant( int $user_id, int|string $group, array $context = array() ): Grant|WP_Error

$group is an ID or the exact name. Returns a SmartMembers\Access\Grant, or a WP_Error saying why nothing was written.

$context keyWhat it does
sourceWho granted it. Default manual. Used by revoke.
source_object, source_idThe object in your system. With source, makes the call idempotent.
started_atMySQL datetime; default now. Drip counts from it.
expires_atMySQL datetime (UTC), or null for never. Empty uses the group's Membership length.
trial_untilWithout a status, stores the grant as trial.
statusDefault active.
tied_toExternal object the grant lives and dies with, such as a subscription.
actorThe person responsible. Defaults to the current user.

A live grant from the same source object is returned as is, so a retried webhook cannot grant twice. Otherwise smartmembers_should_grant may veto, the group's rules run (active, availability dates, member caps), the row is written, roles sync and smartmembers_access_granted fires.

// Error codes
invalid_user                  // user ID was 0 or negative
group_not_found               // no group with that ID or name
grant_vetoed                  // smartmembers_should_grant returned false
group_inactive                // the group is switched off
group_not_yet_available       // outside the group's availability dates
group_no_longer_available
group_full                    // member cap reached
group_user_limit_reached      // per-user cap reached
grant_held                    // revoked by another source; not revived automatically
member_not_found, grant_failed, grant_raced   // database write failed

$grant = smartmembers_grant( $user_id, 672, array(
    'source'        => 'gift-form',
    'source_object' => 'entry',
    'source_id'     => (string) $entry_id,
    'expires_at'    => gmdate( 'Y-m-d H:i:s', strtotime( '+30 days' ) ),
) );

if ( is_wp_error( $grant ) ) {
    error_log( $grant->get_error_code() . ': ' . $grant->get_error_message() );
    return;
}

smartmembers_revoke()

smartmembers_revoke( int $user_id, int|string $group, array $context = array() ): bool

Returns true when at least one live grant was revoked, and fires smartmembers_access_revoked for each.

$context keyWhat it does
sourceOnly revoke grants from this source. Left out, or manual, revokes every grant for the group.
source_object, source_id, tied_toNarrow to one object.
reasonexpired marks it expired; anything else, cancelled. Default revoked.
quietTrue skips the "access ended" email.

Warning: A bare smartmembers_revoke( 42, 672 ) removes every Reader grant Rosa holds, including one she bought. Pass the source you granted with.

smartmembers_revoke( $user_id, 672, array(
    'source'        => 'gift-form',
    'source_object' => 'entry',
    'source_id'     => (string) $entry_id,
    'reason'        => 'gift_cancelled',
) );

smartmembers_get_grants()

Every grant a user holds, live or not; an empty array for a blocked user. is_live() says whether a grant opens content now.

smartmembers_get_grants( int $user_id ): Grant[]

// Grant properties: id, user_id, access_group_id, status, source, source_object,
// source_id, tied_to, started_at, expires_at, paused_at, trial_until, seat_of, actor.
// Methods: is_live(), to_array().

foreach ( smartmembers_get_grants( 42 ) as $grant ) {
    printf( "%d %s %s\n", $grant->access_group_id, $grant->source, $grant->is_live() ? 'live' : 'ended' );
}
// 671 registration live
// 672 manual live

Checking access

// Full answer. $object_type: 'post', 'url' (pass the path) or 'archive'. 0 = visitor.
smartmembers_check_access( int $user_id, string $object_type = 'post', int|string $object_id = 0 ): AccessResult

// Yes or no. null = current user. Note the argument order.
smartmembers_can_access( ?int $user_id, int|string $object_id, string $object_type = 'post' ): bool

// Live grant for any of the groups (IDs or names, case-insensitive).
smartmembers_user_holds_group( int $user_id, array $groups ): bool

// The refusal HTML Smart Members would show.
smartmembers_restriction_message( AccessResult $result, int $post_id = 0 ): string

// Member rather than staff (manage_options or edit_posts is never a member).
smartmembers_user_is_member( ?int $user_id = null ): bool

// Feature available on this site. Unknown slugs return false.
smartmembers_capability_available( string $slug ): bool

// AccessResult: allowed, reason, unlocks_at, required_groups, rule_id, mode, message
// reason: public | granted | no_group | expired | paused | dripping | denied | logged_out
// mode:   hide | hide_content | redirect

smartmembers_check_access( 0, 'post', 1595 );
// allowed: false, reason: logged_out, required_groups: [672], mode: hide_content
A Deep Dive post on the AI Weekly site as a logged-out visitor sees it: the first lines, the members-only message and a button to buy AI Weekly — Reader
That AccessResult on the page.

A dripping result means the member holds the group but the post is not open yet; unlocks_at holds the date, and the page shows it instead of the group's redirect or substitute page.

Blocking and caches

// Refuse every group without deleting grants. Fires smartmembers_user_blocked.
smartmembers_block_user( int $user_id, ?int $actor = null ): bool

// Restore everything, dates and sources included. Fires smartmembers_user_unblocked.
smartmembers_unblock_user( int $user_id ): bool

smartmembers_user_is_blocked( int $user_id ): bool

// Grant and revoke call this already; use it after writing grants another way.
smartmembers_flush_access_cache( ?int $user_id = null )

Behaviour to know about

  • Staff see everything. Test with a member ID or 0.
  • Expiry takes effect on read. Within the hour, smartmembers_expire_grants revokes the grant with reason expired, and smartmembers_access_revoked fires.
  • The member login and registration pages are always open, even under a whole-site rule.
  • Don't write rules directly. Filter them with smartmembers_compiled_access_rules.
  • From another server, receive the call in a WordPress plugin and call smartmembers_grant() there.

Related articles