Admin Membership Calls
----------------------

Check the status of a membership (from an email addresss)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. note::
	This call uses a cached dataset for speed. If you want to check on the status of a member that has only just been modified use the `realtime=true` paramater

.. code-block:: http

	http https://api.sheepcrm.com/api/v1/$FLOCK/user/membership/  email==james@sheepcrm.com "Authorization: Bearer $API_KEY"
	HTTP/1.1 200 OK

	{
	    "active_memberships_for_display": [
	        "Membership Grade F"
	    ],
	    "first_name": "James",
	    "last_name": "Webster",
	    "member_since": "2019-01-01T00:00:00",
	    "member_till": "2021-01-01T00:00:00",
	    "member_till_plus_grace": "2021-12-31T00:00:00",
	    "membership_numbers": [
	        "EAB54"
	    ],
	    "membership_record_status": "active",
	    "person": "/example/person/5e3453b40b915a4c234a36ab/",
	    "photo": null,
	    "photo-avatar": null,
	    "primary_email": "james@sheepcrm.com"
	}


Create a membership record
^^^^^^^^^^^^^^^^^^^^^^^^^^

:member:
	The URI of the member (the person or organisation URI)

:membership_type:
	The URI of the membership type to create

:start_date:
	When the membership should start (default = today) - optional

:amount:
	membership price (if not the list price) - optional

:currency:
	membership currency (if not the list currency) - optional

 .. note::
 	As a safeguard the system won't let you create two memberships of the same type for the same contact starting on the same day.

.. code-block:: http

	http POST https://api.sheepcrm.com/api/v1/$FLOCK/member/ "Authorization: Bearer $API_KEY" membership_type=/example/membership_type/1234abc/ member=/example/person/5e3453b40b915a4c234a36ab/

	HTTP/1.1 201 CREATED
	{

	}


A membership URI is in the format `/{FLOCK}/member/{UID}/`, for convinience we'll user a variable `$MEMBER_URI` to represent that in the following examples. If you are copying the examples remove the leading and trailing slashes when exporting the variable.


Activate a pending membership
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: http

	http POST https://api.sheepcrm.com/api/v1/$MEMBER_URI/activate/ Authorization:"Bearer $API_KEY"



Cancel a membership
^^^^^^^^^^^^^^^^^^^

Types of cancellation:
 - **Default** is to cancel immediately with no reason. The status will be `cancelled` and the membership ends immediately.
 - **Early end** If the cancellation is for a future date that is earlier than the natural expiry or lapse date then provide a `when` value. The end date of the membership will be brought forward and auto renewal turned off. The membership will be active until the new end date after which it will appear as `lapsed`.
 - **Advise lapse** If the cancellation is a decision not to renew then the membership is not cancelled it is simple allowed to lapse and not renew. This will appear as `lapsed` in reports.

optional parameters

:reason:
	reason for cancellation
:when:
	when should the cancellation occur - default = immediate, date strings or `on_expiry` to allow a lapse



.. code-block:: http

	http POST https://api.sheepcrm.com/api/v1/$MEMBER_URI/cancel/  Authorization:"Bearer $API_KEY" reason='too expensive'  when='2021-12-'



Renew a membership
^^^^^^^^^^^^^^^^^^

.. code-block:: http

	http POST https://api.sheepcrm.com/api/v1/$MEMBER_URI/renew/ Authorization:"Bearer $API_KEY"




Remove payment plan from membership
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Remove the payment plan from the membership after checking that no future payments exist

.. code-block:: http

	http POST https://api.sheepcrm.com/api/v1/$MEMBER_URI/remove_payment_plan/ Authorization:"Bearer $API_KEY"



Unpack payment plan from membership
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create payments based on the schedule defined in the payment plan

.. code-block:: http

	http POST https://api.sheepcrm.com/api/v1/$MEMBER_URI/unpack_payment_plan/ Authorization:"Bearer $API_KEY"



Unpack payment plan from membership
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Delete any future payments that are associated with the payment plan

.. code-block:: http

	http POST https://api.sheepcrm.com/api/v1/$MEMBER_URI/delete_future_scheduled_payments/ Authorization:"Bearer $API_KEY"


Add a linked member
^^^^^^^^^^^^^^^^^^^

If the membership supports linked members

:linked_member_uri:
	The URI of the contact to be added as a linked member.
:force:
	force adding the linked member by removing a linked member to make room. true/false (defaults to false)

.. code-block:: http

	http POST https://api.sheepcrm.com/api/v1/$MEMBER_URI/linked_members/ Authorization:"Bearer $API_KEY"  linked_member_uri=/example/person/5c407b48d4069413d21d4d0e/

	{
	    "linked_members": [
	        "/example/person/5b5769f48b38805e2981d1ea/"
	    ],
	    "status": "OK"
	}


Storing additional data on a membership record
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The membership record has an `extra` field which can be used to store JSON formatted data. This data is not readily available to users within the CRM and is not exported.

.. code-block:: http

	http PUT https://api.sheepcrm.com/api/v1/$MEMBER_URI/ Authorization:"Bearer $API_KEY" extra='{"my-custom-field":"my value"}'
	HTTP/1.0 200 OK

	{
	    "errors": {},
	    "updates": {
	        "extra": "{\"my-custom-field\":\"my value\"}"
	    }
	}




Membership certificate
^^^^^^^^^^^^^^^^^^^^^^

Note: no auth required.

.. code-block:: http

	http GET https://api.sheepcrm.com/api/v1/public/$MEMBER_URI/certificate/


optional parameters

:template:
	Registered certificate template. default is `sheep-membership-certificate-a4`


Membership invoice
^^^^^^^^^^^^^^^^^^

Note: no auth required.

.. code-block:: http

	http GET https://api.sheepcrm.com/api/v1/public/$MEMBER_URI/invoice/


optional parameters

:template:
	Registered certificate template. default is `sheep-invoice-a4`

If no invoice exists for the membership a PDF with a missing invoice message will be returned.

Bulk Admin Membership Calls
---------------------------

Get all members
^^^^^^^^^^^^^^^

.. code-block:: http

	http GET https://api.sheepcrm.com/api/v1/$FLOCK/member/



Get all active members
^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: http

	http GET https://api.sheepcrm.com/api/v1/$FLOCK/member/?membership_record_status=active



Get all non-active members
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: http

	http GET https://api.sheepcrm.com/api/v1/$FLOCK/member/?membership_record_status__ne=active



Get all recently added members
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: http

	http GET https://api.sheepcrm.com/api/v1/$FLOCK/member/?created__gte=yesterday

.. code-block:: http

	http GET https://api.sheepcrm.com/api/v1/$FLOCK/member/?created__gte=2020-01-30



Automatic membership numbers
----------------------------

Read the membership number counter to a see the next number. An error packet with "not configured" will be returned if the membership number has not yet been set.

.. code-block:: http

	http GET https://api.sheepcrm.com/api/v1/$FLOCK/system/membership_number/ "Authorization: Bearer $API_KEY"
	HTTP/1.1 200 OK

	{
    	"auto_membership_number_next": 26
	}

Reset the counter to a new number

.. code-block:: http

	http POST https://api.sheepcrm.com/api/v1/$FLOCK/system/membership_number/ "Authorization: Bearer $API_KEY" reset_value=45
	HTTP/1.1 200 OK

	{
    	"auto_membership_number_next": 46
	}