Merchants can interact with Simplee Memberships using either our Storefront or Admin API. These allow for custom storefront experiences, as well as back-end interactions with the app.

Overview

The Simplee Memberships API allows merchants and developers to retrieve membership data and manage memberships programmatically.

Using the API, you can:

Retrieve memberships
Search memberships by customer information
Filter memberships by status
Pause and resume memberships
Cancel memberships
Reactivate memberships
Update billing dates
Update shipping addresses
Change billing frequencies
Send payment update emails
Delete memberships

Authentication

All API requests require authentication using a Bearer token.

Include the following header with every request:

Authorization: Bearer YOUR_ADMIN_API_TOKEN

If the token is missing, invalid, disabled, or deleted, the API will return a 401 Unauthorized response.

Base URL

https://api.simplee.best/api/admin/v1

Store ID

Every request to the API requires your store's unique ID. This ID can be generated within the Simplee Memberships app, under Settings > API Access. By enabling and saving one of the API access tokeys, a unique Store ID will also be generated.

Use this ID whenever and endpoint asks for [store_id]

Retrieve Memberships

Endpoint

GET /shops/{store_id}/memberships

Example Request

GET https://api.simplee.best/api/admin/v1/shops/123456789/memberships

Response

The following is a sample response from this query. Multiple results will be included in a single response if no filtering or pagination options have been sent.

{             
   "id": 123,             
   "contract_number": 15263392286,             
   "member_number": 3,             
   "status": "active",             
   "status_extended": null,             
   "created_method": "Online Store",             
   "created_at": "2026-06-03",             
   "next_order_date": "2026-07-03",             
   "next_processing_date": "2026-07-03",             
   "billing_interval_type": "month",             
   "billing_interval_count": 1,             
   "customer_shopify_id": 8708556292382,             
   "customer_email": "customer@gmail.com",             
   "customer_fname": "Jim",             
   "customer_lname": "Beam",             
   "customer_phone": null,             
   "tag_customer": "Gold",             
   "tag_order": "Membership",             
   "payment_method": "credit_card",             
   "payment_name": "Jim Beam",             
   "payment_brand": "visa",             
   "payment_last_four": "1",             
   "payment_expiry": "12\/25",             
   "payment_email": "",             
   "payment_amount": 100,             
   "plan_name": null,             
   "order_count": 1,          
   "order_minimum": 0,          
   "order_maximum": 0,          
   "store_credit_amount": null,          
   "store_credit_type": null,          
   "product": {          
       "product_id": 9669336498462,         
       "product_variant_id": 49471542329630,                 
       "product_name": "Awesome Membership",                     
       "product_variant_title": "Default Title",                 
       "product_image_url": null             
   }         
}

Membership IDs vs Shopify Contract IDs

⚠️ Important

The API uses two different identifiers:

Field	Description
id	Internal Simplee Memberships ID
contract_number	Shopify Subscription Contract ID

When performing membership updates, use the membership's id value in the URL.

{   "id": 1022,   "contract_number": 54321 }

Correct:

PATCH /shops/{store_id}/memberships/1022

Incorrect:

PATCH /shops/{store_id}/memberships/54321

Filtering Memberships

Filter by Status

Retrieve active memberships:

GET /shops/{store_id}/memberships?status=active

Retrieve multiple statuses:

GET /shops/{store_id}/memberships?status=active,cancelled

Supported filter values:

active
cancelled
expiring
paused
expired
failed

Status Values Returned by the API

Membership records may return:

ACTIVE
CANCELLED
PAUSED
EXPIRED
FAILED

Note: Filter values are lowercase while returned status values are uppercase.

Filter by Contract ID

GET /shops/{store_id}/memberships?contract=1234

Filter by Customer Email

GET /shops/{store_id}/memberships?email=jane@example.com

Filter by Customer First Name

GET /shops/{store_id}/memberships?first_name=Jane

Performs a partial match on the customer's first name.

Filter by Customer Last Name

GET /shops/{store_id}/memberships?last_name=Doe

Performs a partial match on the customer's last name.

Pagination

Example:

GET /shops/{store_id}/memberships?pageSize=50&page=1

Parameter	Description
pageSize	Number of results returned per page
page	Page number

Limits:

Default page size: 20
Maximum page size: 100

Sorting

Example:

GET /shops/{store_id}/memberships?sort=create_date desc

Supported sort fields:

create_date
next_order_date
member_number
contract_id

Example:

GET /shops/{store_id}/memberships?sort=next_order_date asc

Membership Response Fields

Membership Information

id
contract_number
member_number
status
status_extended
created_method
created_at
next_order_date
next_processing_date
billing_interval_type
billing_interval_count
last_payment_status

Customer Information

customer_shopify_id
customer_email
customer_fname
customer_lname
customer_phone

Plan Information

plan_name
product.product_name
payment_amount
plan_currency_code

Payment Information

payment_method
payment_name
payment_brand
payment_last_four
payment_expiry
payment_email

Updating Memberships

Endpoint

PATCH /shops/{store_id}/memberships/{membership_id}

The request body must include a type field that determines the action performed.

Cancel Membership

Cancels a membership while allowing access until the end of the current billing period.

{   "type": "cancelled" }

Cancel Membership and Remove Access Immediately

Cancels the membership and removes access immediately.

{   "type": "cancelled-removeaccess" }

Pause Membership

Pauses future billing.

{   "type": "paused" }

Resume Membership

Resumes a paused membership.

{   "type": "resumed" }

Reactivate Membership

Reactivates a cancelled membership using a new billing date.

{   "type": "reactive",   "next_order_date": "2026-08-01" }

Change Next Billing Date

Updates the next billing date.

{   "type": "next_order_date",   "next_order_date": "2026-09-15" }

Update Shipping Address

Updates the shipping address associated with a membership.

{   
   "type": "edit_shipping_address",
   "shipping_address": {
     "first_name": "Jane",
     "last_name": "Doe",
     "company": "Acme Inc",
     "address1": "123 Main St",
     "address2": "Suite 4",
     "city": "Toronto",
     "province": "Ontario",
     "province_code": "ON",
     "zip": "M5V 1A1",
     "country": "Canada",
     "phone": "416-555-0100"
   } 
}

Change Billing Frequency

Updates the billing interval for a membership.

Example: Change a monthly membership to every 3 months.

{
   "type": "change_frequency",
   "billing_interval": "month",
   "billing_interval_count": 3 
}

Supported interval values:

day
week
month
year

Send a Payment Update Email

Sends a payment update email to the customer.

{   "type": "update_payment_email" }

Successful response:

{
   "data": "Payment update email sent successfully.",
   "success": true 
}

Possible responses:

{
   "data": "Customer payment method not found. Update the payment method first, then retry." 
}

{
   "data": "No supported payment gateway found for this shop." 
}

Delete a Membership

Permanently deletes a membership.

{   "type": "deleted" }

⚠️ This action permanently removes the membership record.

Successful Responses

Most update operations return:

{   "success": true,   "data": "Operation completed successfully." }

Error Responses

401 Unauthorized

{   "error": "Invalid or disabled API token." }

403 Forbidden

{   "error": "Token does not belong to this shop." }

404 Not Found

{   "error": "Shop not found." }

{   "error": "Membership not found." }

422 Validation Error

{   "error": "Invalid type." }

{   "error": "The next_order_date field is required." }

{   "error": "The billing_interval field is required." }

{   "error": "The billing_interval_count must be at least 1." }

{   "error": "The shipping_address field is required." }

Shopify Synchronization

Simplee Memberships automatically synchronizes supported membership updates with Shopify Subscription Contracts when applicable.

This includes:

Membership status changes
Next billing date changes
Membership reactivations
Membership resumptions
Billing frequency changes
Shipping address updates

If a membership is not connected to a Shopify Subscription Contract, the membership may still be updated within Simplee Memberships, but Shopify synchronization will be skipped.