Skip to content

Commit 20e5e5d

Browse files
unfulviounfulvio
committed
Add full CRUD support documentation for user memberships
1 parent feb22c9 commit 20e5e5d

File tree

7 files changed

+225
-24
lines changed

7 files changed

+225
-24
lines changed

‎source/includes/_user_memberships.md‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -9,27 +9,27 @@ A user membership is created when a customer gets access to a membership plan, t
99
A user membership has the following data structure in the REST API:
1010

1111
Property | Type | Description
12-
-------------------- | --------------------------------| ------------
13-
`id` | <code>int</code> | The unique identifier (integer) of the user membership.
12+
-------------------- | --------------------------------| -----------
13+
`id` | <code>int</code> | _`read-only`_<br><br>The unique identifier (integer) of the user membership.
1414
`customer_id` | <code>int</code> | The unique identifier (integer) of the customer that owns the membership.
1515
`plan_id` | <code>int</code> | The unique identifier (integer) of the membership plan the membership is for.
1616
`status` | <code>string</code> | The current status (string) of the user membership.
17-
`order_id` | <code>int&#124;null</code> | 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`_.
18-
`subscription_id` | <code>int&#124;null</code> | 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`_.<sup><a href="#user-membership-data-subscriptions-inactive">1</a></sup>
17+
`order_id` | <code>int&#124;null</code> | 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`_.
1918
`product_id` | <code>int&#124;null</code> | 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`_.
20-
`date_created` | <code>datetime</code> | 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.
21-
`date_created_gmt` | <code>datetime</code> | The date (in Atom format) when the user membership object was created, in UTC. This does not necessarily match with the start date.
22-
`start_date` | <code>datetime</code> | The date (in Atom format) when the membership starts, in the local timezone.
19+
`subscription_id` | <code>int&#124;null</code> | 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`_.<sup><a href="#user-membership-data-subscriptions-inactive">1</a></sup>
20+
`date_created` | <code>datetime</code> | _`read-only`_<br><br>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.
21+
`date_created_gmt` | <code>datetime</code> | _`read-only`_<br><br>The date (in Atom format) when the user membership object was created, in UTC. This does not necessarily match with the start date.
22+
`start_date` | <code>datetime</code> | _`read-only`_<br><br>The date (in Atom format) when the membership starts, in the local timezone.
2323
`start_date_gmt` | <code>datetime</code> | The date (in Atom format) when the membership starts, in UTC.
24-
`end_date` | <code>datetime&#124;null</code> | The date (in Atom format) when the ends, in the local timezone. This is `null` if the membership doesn't have an end date.
24+
`end_date` | <code>datetime&#124;null</code> | _`read-only`_<br><br>The date (in Atom format) when the ends, in the local timezone. This is `null` if the membership doesn't have an end date.
2525
`end_date_gmt` | <code>datetime&#124;null</code> | The date (in Atom format) when the ends, in UTC. This is `null` if the membership doesn't have an end date.
26-
`paused_date` | <code>datetime&#124;null</code> | 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.
27-
`paused_date_gmt` | <code>datetime&#124;null</code> | 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.
26+
`paused_date` | <code>datetime&#124;null</code> | _`read-only`_<br><br>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.
27+
`paused_date_gmt` | <code>datetime&#124;null</code> | _`read-only`_<br><br>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.
2828
`cancelled_date` | <code>datetime&#124;null</code> | The date (in Atom format) when the membership was cancelled, in the local timezone. This is `null` if the membership was not cancelled.
2929
`cancelled_date_gmt` | <code>datetime&#124;null</code> | The date (in Atom format) when the membership was cancelled, in UTC. This is `null` if the membership was not cancelled.
30-
`view_url` | <code>string</code> | URL pointing to the site's Members Area accessible to the membership's owner.
31-
`meta_data` | <code>array</code> | 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).
32-
`links` | <code>array</code> | An array of items linking to related objects accessible through the REST API.
30+
`view_url` | <code>string</code> | _`read-only`_<br><br>URL pointing to the site's Members Area accessible to the membership's owner.
31+
`meta_data` | <code>array&#124;object</code> | 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).
32+
`links` | <code>array</code> | _`read-only`_<br><br>An array of items linking to related objects accessible through the REST API.
3333

3434

3535
**Notes:**

‎source/includes/membership_plans/_get.md‎ renamed to ‎source/includes/membership_plans/_read.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ $woocommerce->get( 'memberships/plans' );
88
?>
99
```
1010

11-
> The above command returns JSON data with an array of membership plans structured like this:
11+
> JSON response example for the above command, containing an array of membership plans data structured as follows:
1212
1313
```json
1414
[
@@ -99,7 +99,7 @@ $woocommerce->get( 'memberships/plans/<id>' );
9999
?>
100100
```
101101

102-
> The above command returns JSON data with a membership plan structured like this:
102+
> JSON response example for the request:
103103
104104
```json
105105
{
@@ -161,7 +161,7 @@ This endpoint retrieves a specific membership plan.
161161

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

164-
### URL Parameters
164+
### Available Parameters
165165

166166
Parameter | Value | Description
167167
--------- | ----------------- | ------------

‎source/includes/user_memberships/_create.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
## Create a User Membership
2+
3+
```php
4+
<?php
5+
6+
$user_membership_data = [
7+
'customer_id' => 1,
8+
'plan_id' => 222,
9+
];
10+
11+
$woocommerce->post( 'memberships/members', $user_membership_data );
12+
13+
?>
14+
```
15+
16+
> JSON response example for the above command containing user membership data for the newly created membership:
17+
18+
```json
19+
{
20+
"id": 1203,
21+
"customer_id": 1,
22+
"plan_id": 222,
23+
"status": "active",
24+
"order_id": null,
25+
"product_id": null,
26+
"subscription_id": null,
27+
"date_created": "2019-04-17T17:51:02+00:00",
28+
"date_created_gmt": "2019-04-17T09:51:02+00:00",
29+
"start_date": "2019-04-17T17:51:02+00:00",
30+
"start_date_gmt": "2019-04-17T09:51:02+00:00",
31+
"end_date": null,
32+
"end_date_gmt": null,
33+
"paused_date": null,
34+
"paused_date_gmt": null,
35+
"cancelled_date": null,
36+
"cancelled_date_gmt": null,
37+
"view_url": "http://skyverge.test/my-account/members-area/222/my-membership-content/",
38+
"meta_data": [],
39+
"_links": {
40+
"self": [
41+
{
42+
"href": "http://skyverge.test/wp-json/wc/v3/memberships/members/1203"
43+
}
44+
],
45+
"collection": [
46+
{
47+
"href": "http://skyverge.test/wp-json/wc/v3/memberships/members"
48+
}
49+
],
50+
"customer": [
51+
{
52+
"href": "http://skyverge.test/wp-json/wc/v3/customers/1"
53+
}
54+
]
55+
}
56+
}
57+
```
58+
59+
**`memberships/members`**
60+
61+
Issue a **POST** request to this endpoint to create a new user membership.
62+
63+
### HTTP Request
64+
65+
`POST http://example.com/api/wc/v3/memberships/members`
66+
67+
### User Membership properties
68+
69+
Attribute | Type | Description
70+
---------------------| --------------------------------| ------------
71+
`customer_id` | <code>int</code> | **Required**. ID of the customer that will become the owner of the user membership.
72+
`plan_id` | <code>int</code> | **Required**. ID of the membership plan to grant access to.
73+
`status` | <code>string</code> | _Optional_. The initial status of the user membership to be created. Defaults to _`active`_.
74+
`order_id` | <code>int</code> | _Optional_. The ID of the associated order that granted access.
75+
`product_id` | <code>int</code> | _Optional_. The ID of the associated product that granted access.
76+
`subscription_id` | <code>int</code> | _Optional_. The ID of the subscription the membership will be linked to.
77+
`start_date_gmt` | <code>datetime</code> | _Optional_. The date when the membership has started, in UTC. Defaults to the present time when the request is issued.
78+
`end_date_gmt` | <code>datetime</code> | _Optional_. The date when the membership will end, in UTC. If status is expired, defaults to the present time when the request is issued.
79+
`paused_date_gmt` | <code>datetime</code> | _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.
80+
`cancelled_date_gmt` | <code>datetime</code> | _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.
81+
`meta_data` | <code>array</code> | _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).
82+

‎source/includes/user_memberships/_delete.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
## Delete a User Membership
2+
3+
```php
4+
<?php
5+
6+
// replace <id> with the member ID to delete
7+
$woocommerce->delete( 'memberships/members/<id>', [ 'force' => true ] );
8+
9+
?>
10+
```
11+
12+
> 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:
13+
14+
```json
15+
{
16+
"deleted": true,
17+
"previous": {
18+
"id": 13,
19+
"customer_id": 1,
20+
"plan_id": 8,
21+
"status": "active",
22+
"order_id": 1200,
23+
"product_id": 848,
24+
"subscription_id": 1191,
25+
"date_created": "2019-04-17T15:29:34+00:00",
26+
"date_created_gmt": "2019-04-17T07:29:34+00:00",
27+
"start_date": "2019-04-17T15:29:34+00:00",
28+
"start_date_gmt": "2019-04-17T07:29:34+00:00",
29+
"end_date": null,
30+
"end_date_gmt": null,
31+
"paused_date": null,
32+
"paused_date_gmt": null,
33+
"cancelled_date": null,
34+
"cancelled_date_gmt": null,
35+
"view_url": "http://skyverge.test/my-account/members-area/13/my-membership-content/",
36+
"meta_data": []
37+
}
38+
}
39+
```
40+
41+
**`memberships/members/<id>`**
42+
43+
Issue a **DELETE** request to this endpoint to permanently delete a user membership.
44+
45+
### HTTP Request
46+
47+
`DELETE http://example.com/api/wc/v3/memberships/members/<id>`
48+
49+
### Available Parameters
50+
51+
Parameter | Type | Description
52+
--------- | ----------------- | ------------
53+
`id` | <code>int</code> | Integer matching the user membership ID to delete.

‎source/includes/user_memberships/_get.md‎ renamed to ‎source/includes/user_memberships/_read.md‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
## Get All User Memberships
1+
## Get User Memberships
22

33
```php
44
<?php
@@ -8,8 +8,7 @@ $woocommerce->get( 'memberships/members' );
88
?>
99
```
1010

11-
12-
> The above command returns JSON data with an array of user memberships structured like this:
11+
> JSON response example for the above command, containing an array of memberships data structured as follows:
1312
1413
```json
1514
[
@@ -84,7 +83,7 @@ Parameter | Type | Default | Descripti
8483
`include` | <code>int&#124;int[]</code> | _`null`_ | Ensure that the specified user memberships with given ID (integer) or IDs (array of integers) will be included in the results, if found.
8584

8685

87-
## Get One User Membership
86+
## Get a User Membership
8887

8988

9089
```php
@@ -96,7 +95,7 @@ $woocommerce->get( 'memberships/members/<id>' );
9695
?>
9796
```
9897

99-
> The above command returns JSON data with a user membership structured like this:
98+
> JSON response example for the request:
10099
101100
```json
102101
{
@@ -147,7 +146,7 @@ This endpoint retrieves a specific user membership.
147146

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

150-
### URL Parameters
149+
### Available Parameters
151150

152151
Parameter | Type | Description
153152
--------- | ----------------- | ------------

‎source/includes/user_memberships/_update.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
## Update a User Membership
2+
3+
```php
4+
<?php
5+
6+
$user_membership_data = [
7+
'status' => 'paused',
8+
];
9+
10+
$woocommerce->put( 'memberships/members', $user_membership_data );
11+
12+
?>
13+
```
14+
15+
> JSON response example:
16+
17+
```json
18+
{
19+
"id": 1203,
20+
"customer_id": 1,
21+
"plan_id": 222,
22+
"status": "paused",
23+
"order_id": null,
24+
"product_id": null,
25+
"subscription_id": null,
26+
"date_created": "2019-04-17T17:51:02+00:00",
27+
"date_created_gmt": "2019-04-17T09:51:02+00:00",
28+
"start_date": "2019-04-17T17:51:02+00:00",
29+
"start_date_gmt": "2019-04-17T09:51:02+00:00",
30+
"end_date": null,
31+
"end_date_gmt": null,
32+
"paused_date": "2019-04-17T18:05:18+00:00",
33+
"paused_date_gmt": "2019-04-17T10:05:18+00:00",
34+
"cancelled_date": null,
35+
"cancelled_date_gmt": null,
36+
"view_url": "http://skyverge.test/my-account/members-area/222/my-membership-content/",
37+
"meta_data": [],
38+
"_links": {
39+
"self": [
40+
{
41+
"href": "http://skyverge.test/wp-json/wc/v3/memberships/members/1203"
42+
}
43+
],
44+
"collection": [
45+
{
46+
"href": "http://skyverge.test/wp-json/wc/v3/memberships/members"
47+
}
48+
],
49+
"customer": [
50+
{
51+
"href": "http://skyverge.test/wp-json/wc/v3/customers/1"
52+
}
53+
]
54+
}
55+
}
56+
```
57+
58+
**`memberships/members/<id>`**
59+
60+
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.
61+
62+
### HTTP Request
63+
64+
`PUT http://example.com/api/wc/v3/memberships/members/<id>`

‎source/index.html.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,12 @@ includes:
1414
- authentication
1515
- discovery
1616
- user_memberships
17-
- user_memberships/get
17+
- user_memberships/create
18+
- user_memberships/read
19+
- user_memberships/update
20+
- user_memberships/delete
1821
- membership_plans
19-
- membership_plans/get
22+
- membership_plans/read
2023
- webhooks
2124
- errors
2225

0 commit comments

Comments
 (0)