NAV Navbar
php

Introduction

The PHP examples in this documentation will assume you are using the WooCommerce client from Automattic to connect to the WooCommerce REST API, which you can require in your project via Composer:

$ composer require automattic/woocommerce

You will then need to configure and instantiate the client in your project, like so:

<?php

require __DIR__ . '/vendor/autoload.php';

use Automattic\WooCommerce\Client;

$woocommerce = new Client(
    'http://example.com',    // Your store URL
    'consumer_key',          // Your consumer key
    'consumer_secret',       // Your consumer secret
    [
        'wp_api'  => true,   // Enable the WP REST API integration
        'version' => 'wc/v3' // WooCommerce WP REST API version
    ]
);

?>

Welcome to the WooCommerce Memberships REST API documentation!

Since version 1.11.0, Memberships extends WooCommerce and builds upon the WordPress REST API to handle user memberships and memberships plans data through robust REST API endpoints.

Memberships currently supports v2 and v3 (added in 1.12.0) of the WooCommerce REST API extension for WordPress. All its endpoints will be added to the /wc/v2/ and /wc/v3/ routes.

This documentation showcases the available HTTP API methods and endpoints to perform valid requests, along with some examples in PHP.

If you spot a typo, an error, have a question, want to provide feedback or extend the documentation, please refer to the GitHub repository of this documentation.

Authentication

HTTP Basic Auth example:

<?php

require __DIR__ . '/vendor/autoload.php';

use Automattic\WooCommerce\Client;

$woocommerce = new Client(
    'https://example.com',
    'consumer_key',
    'consumer_secret',
    [
        'wp_api' => true,
        'version' => 'wc/v3'
    ]
);

?>

Occasionally, some servers may not parse the Authorization header correctly.

If you see a "Consumer key is missing" error when authenticating over SSL, likely you have a server issue. 

In this case, you may provide the consumer key/secret as query string parameters instead.

Example for servers that not properly parse the Authorization header:

<?php

require __DIR__ . '/vendor/autoload.php';

use Automattic\WooCommerce\Client;

$woocommerce = new Client(
    'https://example.com',
    'consumer_key',
    'consumer_secret',
    [
        'wp_api' => true,
        'version' => 'wc/v3',
        // Force Basic Authentication as query string true and using under HTTPS
        'query_string_auth' => true 
    ]
);

?>

Since Memberships REST API is built on top of the WordPress REST API and requires WooCommerce to function, authorization for performing HTTP requests successfully is handled by WooCommerce and WordPress.

WooCommerce includes two ways to authenticate with the WP REST API. It is also possible to authenticate using any WP REST API authentication plugin or method.

Follow instructions from the WooCommerce core REST API Authentication chapter for authentication guidelines.

Discovery

Available Routes

/memberships

The memberships root endpoint lists all routes, along with supported HTTP methods for each, made available by WooCommerce Memberships.

HTTP REQUEST

GET http://example.com/wp-json/wc/v3/memberships

User Memberships

The User Membership

A user membership is created when a customer gets access to a membership plan, therefore all user memberships are linked to one user and one membership plan only. Also, a membership has a status and a start date.

Data Structure

A user membership has the following data structure in the REST API:

Property Type Description
id int The unique identifier (integer) of the user membership.
customer_id int The unique identifier (integer) of the customer that owns the membership.
plan_id int The unique identifier (integer) of the membership plan the membership is for.
status string The current status (string) of the user membership.
order_id int|null The unique identifier (integer) of the order that may have granted access to the matching membership plan. If the user membership is not linked to an order, it will return null.
subscription_id int|null The unique identifier (integer) of a subscription that may be linked to the user membership. This property will exist only if the site is running WooCommerce Subscriptions alongside with Memberships. If there is no link to a subscription, the value will be null.1
product_id int|null The unique identifier (integer) of a product that may have granted access to the matching membership plan. If the user membership is not linked to a product, it will return null.
date_created datetime The date (in Atom format) when the user membership object was created, in the local timezone. This does not necessarily match with the start date.
date_created_gmt datetime The date (in Atom format) when the user membership object was created, in UTC. This does not necessarily match with the start date.
start_date datetime The date (in Atom format) when the membership starts, in the local timezone.
start_date_gmt datetime The date (in Atom format) when the membership starts, in UTC.
end_date datetime|null The date (in Atom format) when the ends, in the local timezone. This is null if the membership doesn't have an end date.
end_date_gmt datetime|null The date (in Atom format) when the ends, in UTC. This is null if the membership doesn't have an end date.
paused_date datetime|null The date (in Atom format) when the membership was last paused, in the local timezone. This is null if the membership was never paused. The value is not removed if the membership changes status.
paused_date_gmt datetime|null The date (in Atom format) when the membership was last paused, in UTC. This is null if the membership was never paused. The value is not removed if the membership changes status.
cancelled_date datetime|null The date (in Atom format) when the membership was cancelled, in the local timezone. This is null if the membership was not cancelled.
cancelled_date_gmt datetime|null The date (in Atom format) when the membership was cancelled, in UTC. This is null if the membership was not cancelled.
view_url string URL pointing to the site's Members Area accessible to the membership's owner.
meta_data array Holds any WordPress meta data set on the membership. Each array item has an "id" (integer), a "key" (string) and a "value" (either a boolean, an integer, or string, which could also represent serialized data).
links array An array of items linking to related objects accessible through the REST API.

Notes:

1 If WooCommerce Subscriptions is inactive this field will not exist.

Get All User Memberships

<?php 

$woocommerce->get( 'memberships/members' ); 

?>

The above command returns JSON data with an array of user memberships structured like this:

[
  {
    "id": 19,
    "customer_id": 80,
    "plan_id": 10,
    "status": "active",
    "order_id": 47,
    "product_id": 55,
    "subscription_id": null,
    "date_created": "2018-07-07T00:10:40+00:00",
    "date_created_gmt": "2018-07-06T16:10:40+00:00",
    "start_date": "2018-07-06T00:00:00+00:00",
    "start_date_gmt": "2018-07-05T16:00:00+00:00",
    "end_date": null,
    "end_date_gmt": null,
    "paused_date": null,
    "paused_date_gmt": null,
    "cancelled_date": null,
    "cancelled_date_gmt": null,
    "view_url": "http://skyverge.test/my-account/members-area/10/my-membership-content/",
    "meta_data": [],
    "_links": {
      "self": [
        {
          "href": "http://example.com/wp-json/wc/v3/memberships/members/19"
        }
      ],
      "collection": [
        {
          "href": "http://example.com/wp-json/wc/v3/memberships/members"
        }
      ],
      "customer": [
        {
          "href": "http://example.com/wp-json/wc/v3/customers/80"
        }
      ]
    }
  }
]

memberships/members

This endpoint retrieves all user memberships.

HTTP Request

GET http://example.com/api/wc/v3/memberships/members

Query Parameters

Parameter Type Default Description
customer int|string null List user memberships belonging to a specific user, specified by ID (integer), email address or login name (string).
order int null List user memberships created from a specific order, given by its ID (integer).
plan int|int[]|string null List user memberships belonging to specific plan or plans. The passed value can be an integer (the plan ID), a string (the plan slug) or an array of IDs to specify different plans at once.
product int null List user memberships created from the purchase of a specific product, given by its ID (integer).
status string any List user memberships with a specific status. By default all memberships of any status are listed.
subscription int null List user memberships associated with a specific subscription, given by its ID (integer).

Pagination Parameters

Parameter Type Default Description
page int 1 Main pagination parameter (integer). Only a given number of user memberships will be listed at any time, per page, according to the site settings.
per_page int null The default number of results to return per page. The default value is normally set by WordPress own settings.
offset int 0 Optional pagination parameter. If set will offset the results by the given number of user memberships specified (integer).
exclude int|int[] null Ensure that the specified user memberships with given ID (integer) or IDs (array of integers) will be excluded from the results, if found.
include int|int[] null Ensure that the specified user memberships with given ID (integer) or IDs (array of integers) will be included in the results, if found.

Get One User Membership

<?php 

// replace <id> with the requested member ID
$woocommerce->get( 'memberships/members/<id>' ); 

?>

The above command returns JSON data with a user membership structured like this:

{
  "id": 19,
  "customer_id": 80,
  "plan_id": 10,
  "status": "active",
  "order_id": 47,
  "product_id": 55,
  "subscription_id": null,
  "date_created": "2018-07-07T00:10:40+00:00",
  "date_created_gmt": "2018-07-06T16:10:40+00:00",
  "start_date": "2018-07-06T00:00:00+00:00",
  "start_date_gmt": "2018-07-05T16:00:00+00:00",
  "end_date": null,
  "end_date_gmt": null,
  "paused_date": null,
  "paused_date_gmt": null,
  "cancelled_date": null,
  "cancelled_date_gmt": null,
  "view_url": "http://skyverge.test/my-account/members-area/10/my-membership-content/",
  "meta_data": [],
  "_links": {
    "self": [
      {
        "href": "http://example.com/wp-json/wc/v3/memberships/members/19"
      }
    ],
    "collection": [
      {
        "href": "http://example.com/wp-json/wc/v3/memberships/members"
      }
    ],
    "customer": [
      {
        "href": "http://example.com/wp-json/wc/v3/customers/80"
      }
    ]
  }
}

memberships/members/<id>

This endpoint retrieves a specific user membership.

HTTP Request

GET http://example.com/api/wc/v3/memberships/members/<id>

URL Parameters

Parameter Type Description
id int Integer matching the requested user membership ID.

Membership Plans

The Membership Plan

A membership plan is a collection of settings and conditions according to which customers can get access to restricted content, products, get member only discounts and so on.

Data Structure

A membership plan has the following data structure in the REST API:

Property Type Description
id int The unique identifier (integer) of the membership plan.
name string The membership plan name.
slug string The membership plan slug (a unique string identifier).
status string The membership plan status (this usually matches standard WordPress post statuses, with publish or draft being the most common for plans).
access_method string The method that membership plan prescribes for users to gain access.
has_subscription bool Whether the plan has at least one subscription among the products that can grant access.1
has_subscription_installment bool Whether the plan uses the subscription for managing installment plans (the membership plan length is not directly tied to the subscription length).1
access_product_ids int[] An optional array of product IDs (integers) to products that will grant access to the membership plan upon purchase. If no products grant access to the membership plan, the value will be an empty array.
access_length_type string The access length type: specific (relative dates), fixed (fixed dates) or unlimited.
subscription_access_length_type string The access length type when the product that granted access to the plan is a subscription: subscription (access lasts as long as the subscription does), specific (relative dates), fixed (fixed dates) or unlimited.1
access_length int|null The length in seconds that a user membership created for this plan will have, by default. This could be null for unlimited memberships that have no set end (or may be tied to a subscription).
subcription_access_length int|null When access to the plan is tied to a subscription, the length in seconds that a corresponding user membership will have. This could be null if it lasts as long as the subscription is active or the plan does not have a subscription product that can grant access.1
access_start_date datetime|null If the plan length type is based on fixed dates, this will be the date when any user membership will start, otherwise it will be null.
access_start_date_gmt datetime|null If the plan length type is based on fixed dates, this will be the date when any user membership will start, otherwise it will be null.1
access_end_date datetime|null If the plan length type is fixed this will be a fixed date when any membership will end, otherwise it will be null.
access_end_date_gmt datetime|null If the plan length type is fixed this will be a fixed date when any membership will end, otherwise it will be null.
subscription_access_start_date datetime|null When access to the plan is tied to a subscription and the plan length type is based on fixed dates, this will be the date when any user membership will start, otherwise it will be null.1
subscription_access_start_date_gmt datetime|null When access to the plan is tied to a subscription and the plan length type is based on fixed dates, this will be the date when any user membership will start, otherwise it will be null.1
subscription_access_end_date datetime|null When access to the plan is tied to a subscription and the plan length type is fixed this will be a fixed date when any membership will end, otherwise it will be null.1
subscription_access_end_date_gmt datetime|null When access to the plan is tied to a subscription and the plan length type is fixed this will be a fixed date when any membership will end, otherwise it will be null.1
date_created datetime The date (in Atom format) when the membership plan object was created, in the local timezone.
date_created_gmt datetime The date (in Atom format) when the membership plan object was created, in UTC.
date_modified datetime The date (in Atom format) when the membership plan object was last modified, in the local timezone.
date_modified_gmt datetime The date (in Atom format) when the membership plan object was last modified, in UTC.
meta_data array Holds any WordPress meta data set on the plan. Each array item has an "id" (integer), a "key" (string) and a "value" (either a boolean, an integer, or string, which could also represent serialized data).
links array An array of items linking to related objects accessible through the REST API.

Notes:

1 If WooCommerce Subscriptions is inactive this field will not exist.

Get All Membership Plans

<?php 

$woocommerce->get( 'memberships/plans' ); 

?>

The above command returns JSON data with an array of membership plans structured like this:

[
  {
    "id": 55,
    "name": "Gold Membership Plan",
    "slug": "gold-membership-plan",
    "status": "publish",
    "access_method": "purchase",
    "has_subscription": false,
    "has_subscription_installment": false,
    "access_product_ids": [
      84,
      86
    ],
    "access_length_type": "specific",
    "subscription_access_length_type": "subscription",
    "access_length": 1209600,
    "access_start_date": null,
    "access_start_date_gmt": null,
    "access_end_date": null,
    "access_end_date_gmt": null,
    "subscription_access_start_date": null,
    "subscription_access_start_date_gmt": null,
    "subscription_access_end_date": null,
    "subscription_access_end_date_gmt": null,
    "date_created": "2018-05-17T13:06:36+00:00",
    "date_created_gmt": "2018-05-17T05:06:36+00:00",
    "date_modified": "2018-08-24T16:15:26+00:00",
    "date_modified_gmt": "2018-08-24T08:15:26+00:00",
    "meta_data": [],
    "_links": {
      "self": [
        {
          "href": "http://example.com/wp-json/wc/v3/memberships/plans/55"
        }
      ],
      "collection": [
        {
          "href": "http://example.com/wp-json/wc/v3/memberships/plans"
        }
      ],
      "products": [
        {
          "href": "http://example.com/wp-json/wc/v3/products/84"  
        },
        {
          "href": "http://example.com/wp-json/wc/v3/products/86"
        }
      ]
    }
  }
]

/memberships/plans

This endpoint retrieves all membership plans.

HTTP Request

GET http://example.com/api/wc/v3/memberships/plans

Query Parameters

Parameter Value Default Description
status string publish List membership plans with a specific post status. By default only membership plans that have been publicly published are listed.

Pagination Parameters

Parameter Value Default Description
page int 1 Main pagination parameter (integer). Only a given number of membership plans will be listed at any time, per page, according to the site settings.
per_page int null The default number of results to return per page. The default value is normally set by WordPress own settings.
offset int 0 Optional pagination parameter. If set will offset the results by the given number of membership plans specified (integer).
exclude int|int[] null Ensure that the specified membership plans with given ID (integer) or IDs (array of integers) will be excluded from the results, if found.
include int|int[] null Ensure that the specified membership plans with given ID (integer) or IDs (array of integers) will be included in the results, if found.

Get One Membership Plan

<?php 

// replace <id> with the requested plan ID
$woocommerce->get( 'memberships/plans/<id>' ); 

?>

The above command returns JSON data with a membership plan structured like this:

{
  "id": 55,
  "name": "Gold Membership Plan",
  "slug": "gold-membership-plan",
  "status": "publish",
  "access_method": "purchase",
  "has_subscription": false,
  "has_subscription_installment": false,
  "access_product_ids": [
    84,
    86
  ],
  "access_length_type": "specific",
  "subscription_access_length_type": "subscription",
  "access_length": 1209600,
  "access_start_date": null,
  "access_start_date_gmt": null,
  "access_end_date": null,
  "access_end_date_gmt": null,
  "subscription_access_start_date": null,
  "subscription_access_start_date_gmt": null,
  "subscription_access_end_date": null,
  "subscription_access_end_date_gmt": null,
  "date_created": "2018-05-17T13:06:36+00:00",
  "date_created_gmt": "2018-05-17T05:06:36+00:00",
  "date_modified": "2018-08-24T16:15:26+00:00",
  "date_modified_gmt": "2018-08-24T08:15:26+00:00",
  "meta_data": [],
  "_links": {
    "self": [
      {
        "href": "http://example.com/wp-json/wc/v3/memberships/plans/55"
      }
    ],
    "collection": [
      {
        "href": "http://example.com/wp-json/wc/v3/memberships/plans"
      }
    ],
    "products": [
      {
        "href": "http://example.com/wp-json/wc/v3/products/84"  
      },
      {
        "href": "http://example.com/wp-json/wc/v3/products/86"
      }
    ]
  }
}

/memberships/plans/<id>

This endpoint retrieves a specific membership plan.

HTTP Request

GET http://example.com/api/wc/v3/memberships/plans/<id>

URL Parameters

Parameter Value Description
id int Integer matching the requested membership plan ID.

WebHooks

WooCommerce Memberships extends WooCommerce with custom webhooks that are triggered when changes occur to User Memberships or Membership Plan objects.

User Membership WebHooks

Each of the following webhooks will send a corresponding user membership object as payload.

Name Description
user_membership.created Triggered when a user membership is created, via any means.
user_membership.updated Triggered when a user membership is changed or modified (e.g. status change, update in admin, etc.).
user_membership.transferred Triggered when a user membership is transferred from a user to another (the user owner of the membership has changed).
user_membership.created Triggered when a user membership has been permanently deleted.

Membership Plan WebHooks

Each of the following webhooks will send a corresponding membership plan object as payload.

Name Description
membership_plan.created Triggered when a membership plan has been created.
membership_plan.updated Triggered when a membership plan has been updated (with one of its properties modified or just saved without data change).
membership_plan.deleted Triggered when a membership plan has been moved to the trash (not permanently deleted, but assumed so unless restored).
membership_plan.restored Triggered when a membership plan is moved back from the trash (not necessarily as published, could be in draft status or other status).

Errors

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Authentication error.
404 Not Found -- The specified item could not be found.
405 Method Not Allowed -- The HTTP method you used isn't supported by the specified endpoint.
500 Internal Server Error -- Something may be wrong with the site or the server.
php