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. |
profile_fields |
array|object |
Holds any profile fields set on the membership. Each array item has a "slug" (string) and a "value" (either a boolean , an integer , float , string , or array ). |
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",
"date_created_gmt": "2019-04-17T09:51:02",
"start_date": "2019-04-17T17:51:02",
"start_date_gmt": "2019-04-17T09:51:02",
"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/",
"profile_fields": [],
"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/wp-json/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. |
profile_fields |
array|object |
Optional. Pass any profile fields to be set on the membership. Each array item has a "slug" (string) and a "value" (either a boolean , an integer , float , string , or array ). |
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",
"date_created_gmt": "2018-07-06T16:10:40",
"start_date": "2018-07-06T00:00:00",
"start_date_gmt": "2018-07-05T16: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/",
"profile_fields": [],
"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/wp-json/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",
"date_created_gmt": "2018-07-06T16:10:40",
"start_date": "2018-07-06T00:00:00",
"start_date_gmt": "2018-07-05T16: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/",
"profile_fields": [],
"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/wp-json/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",
"date_created_gmt": "2019-04-17T09:51:02",
"start_date": "2019-04-17T17:51:02",
"start_date_gmt": "2019-04-17T09:51:02",
"end_date": null,
"end_date_gmt": null,
"paused_date": "2019-04-17T18:05:18",
"paused_date_gmt": "2019-04-17T10:05:18",
"cancelled_date": null,
"cancelled_date_gmt": null,
"view_url": "http://skyverge.test/my-account/members-area/222/my-membership-content/",
"profile_fields": [],
"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/wp-json/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",
"date_created_gmt": "2019-04-17T07:29:34",
"start_date": "2019-04-17T15:29:34",
"start_date_gmt": "2019-04-17T07:29:34",
"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/wp-json/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",
"date_created_gmt": "2018-05-17T05:06:36",
"date_modified": "2018-08-24T16:15:26",
"date_modified_gmt": "2018-08-24T08:15:26",
"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/wp-json/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",
"date_created_gmt": "2018-05-17T05:06:36",
"date_modified": "2018-08-24T16:15:26",
"date_modified_gmt": "2018-08-24T08:15:26",
"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/wp-json/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. |