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 read-only

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.
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.
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
date_created datetime read-only

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 read-only

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 read-only

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 read-only

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 read-only

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 read-only

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 read-only

URL pointing to the site's Members Area accessible to the membership's owner.
meta_data array|object 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 read-only

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.

Create a User Membership

<?php 

$user_membership_data = [
  'customer_id' => 1,
  'plan_id' => 222,
];

$woocommerce->post( 'memberships/members', $user_membership_data ); 

?>

JSON response example for the above command containing user membership data for the newly created membership:

{
    "id": 1203,
    "customer_id": 1,
    "plan_id": 222,
    "status": "active",
    "order_id": null,
    "product_id": null,
    "subscription_id": null,
    "date_created": "2019-04-17T17:51:02+00:00",
    "date_created_gmt": "2019-04-17T09:51:02+00:00",
    "start_date": "2019-04-17T17:51:02+00:00",
    "start_date_gmt": "2019-04-17T09:51:02+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/222/my-membership-content/",
    "meta_data": [],
    "_links": {
        "self": [
            {
                "href": "http://skyverge.test/wp-json/wc/v3/memberships/members/1203"
            }
        ],
        "collection": [
            {
                "href": "http://skyverge.test/wp-json/wc/v3/memberships/members"
            }
        ],
        "customer": [
            {
                "href": "http://skyverge.test/wp-json/wc/v3/customers/1"
            }
        ]
    }
}

memberships/members

Issue a POST request to this endpoint to create a new user membership.

HTTP Request

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

User Membership properties

Attribute Type Description
customer_id int Required. ID of the customer that will become the owner of the user membership.
plan_id int Required. ID of the membership plan to grant access to.
status string Optional. The initial status of the user membership to be created. Defaults to active.
order_id int Optional. The ID of the associated order that granted access.
product_id int Optional. The ID of the associated product that granted access.
subscription_id int Optional. The ID of the subscription the membership will be linked to.
start_date_gmt datetime Optional. The date when the membership has started, in UTC. Defaults to the present time when the request is issued.
end_date_gmt datetime Optional. The date when the membership will end, in UTC. If status is expired, defaults to the present time when the request is issued.
paused_date_gmt datetime Optional. The date when the membership has been paused since, in UTC. If status is paused, defaults to the present time when the request is issued.
cancelled_date_gmt datetime Optional. The date when the membership has been cancelled, in UTC. If status is cancelled, defaults to the present time when the request is issued.
meta_data array Optional. Pass any WordPress post meta data to be 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).

Get User Memberships

<?php 

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

?>

JSON response example for the above command, containing an array of memberships data structured as follows:

[
  {
    "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 a User Membership

<?php 

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

?>

JSON response example for the request:

{
  "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>

Available Parameters

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

Update a User Membership

<?php 

$user_membership_data = [
  'status' => 'paused',
];

$woocommerce->put( 'memberships/members', $user_membership_data ); 

?>

JSON response example:

{
    "id": 1203,
    "customer_id": 1,
    "plan_id": 222,
    "status": "paused",
    "order_id": null,
    "product_id": null,
    "subscription_id": null,
    "date_created": "2019-04-17T17:51:02+00:00",
    "date_created_gmt": "2019-04-17T09:51:02+00:00",
    "start_date": "2019-04-17T17:51:02+00:00",
    "start_date_gmt": "2019-04-17T09:51:02+00:00",
    "end_date": null,
    "end_date_gmt": null,
    "paused_date": "2019-04-17T18:05:18+00:00",
    "paused_date_gmt": "2019-04-17T10:05:18+00:00",
    "cancelled_date": null,
    "cancelled_date_gmt": null,
    "view_url": "http://skyverge.test/my-account/members-area/222/my-membership-content/",
    "meta_data": [],
    "_links": {
        "self": [
            {
                "href": "http://skyverge.test/wp-json/wc/v3/memberships/members/1203"
            }
        ],
        "collection": [
            {
                "href": "http://skyverge.test/wp-json/wc/v3/memberships/members"
            }
        ],
        "customer": [
            {
                "href": "http://skyverge.test/wp-json/wc/v3/customers/1"
            }
        ]
    }
}

memberships/members/<id>

Issue a PUT request to this endpoint to update an existing user membership. You can pass the same properties as when creating a user membership, to update them.

HTTP Request

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

Delete a User Membership

<?php 

// replace <id> with the member ID to delete
$woocommerce->delete( 'memberships/members/<id>', [ 'force' => true ] ); 

?>

JSON response example for the request, containing a flag to confirm deletion and user membership data pertaining to the deleted user membership before the deletion was executed:

{
    "deleted": true,
    "previous": {
        "id": 13,
        "customer_id": 1,
        "plan_id": 8,
        "status": "active",
        "order_id": 1200,
        "product_id": 848,
        "subscription_id": 1191,
        "date_created": "2019-04-17T15:29:34+00:00",
        "date_created_gmt": "2019-04-17T07:29:34+00:00",
        "start_date": "2019-04-17T15:29:34+00:00",
        "start_date_gmt": "2019-04-17T07:29:34+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/13/my-membership-content/",
        "meta_data": []
    }
}

memberships/members/<id>

Issue a DELETE request to this endpoint to permanently delete a user membership.

HTTP Request

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

Available Parameters

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

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' ); 

?>

JSON response example for the above command, containing an array of membership plans data structured as follows:

[
  {
    "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>' ); 

?>

JSON response example for the request:

{
  "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>

Available 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