New features available! Check the changelog
Subscribfy
Subscriptions

Membership Management API

Backend API for managing subscription content, pause/cancel workflows, and generating customer portal URLs.

The Membership Management API allows you to programmatically manage customer subscriptions and memberships. Use this endpoint to retrieve subscription details, cancel, pause, or reactivate memberships from your own systems or third-party integrations.

Authentication

All requests require your Subscribfy API key. Go to Shopify > Apps > Subscribfy > Integration and copy the API Key.

Endpoint

All requests must be sent through your Shopify storefront domain using the App Proxy path.

PropertyValue
Base URLhttps://{your-store-domain}/apps/subscribfy-api/v1/membership/manage
MethodGET or POST
Content-Typeapplication/x-www-form-urlencoded

Example: https://yourstore.com/apps/subscribfy-api/v1/membership/manage

Do not use yourstore.myshopify.com. Always use your public storefront domain (custom domain or primary Shopify domain).

Required Parameters

Prop

Type

Subscription Types

TypeInternal NameDescription
1VIPStandard membership subscriptions
2ElitePremium membership tier
3Product SubscriptionRecurring product deliveries
4Try Before You BuyTBYB subscriptions

Available Actions

ActionDescriptionAdditional Parameters
getContentRetrieve subscription detailsNone
getCustomerMembershipManageURLGet portal URLNone
updateCancelContentCancel subscriptionreason (required)
updatePauseContentPause subscriptionperiod (required, 1-3 months)
updateReactivateContentReactivate subscriptionNone
forceRechargeManually retry billing for an active contractNone

forceRecharge is rate limited to one call every 3 minutes per contract and requires the contract to be ACTIVE. It immediately schedules a new billing attempt.

Action-Specific Parameters

Prop

Type

Response Format

Error Responses

Validation errors return HTTP 422 with the shape {"error": true, "message": "..."}. Runtime errors return HTTP 200 with {"error": "..."} or {"result": "error", "message": "..."}.

ErrorCause
Bad RequestMissing or invalid parameters
The parameter 'scid' is required when 'type' is 3.Missing scid for product subscription action
Invalid API keyAPI key not found or inactive
Shop not foundShop domain not recognized
Customer not foundCustomer ID/email not found
No membership foundNo membership exists for type 1/2
No subscription foundNo subscription exists for type 3/4
This action cannot be madeAction not allowed on this contract (e.g. gifted contract being paused by recipient)
Too many requests.Rate limit exceeded (10 second cooldown; 3 minutes for forceRecharge)
Problem when creating the url.Short URL service failed (opted-in shops only)

Examples

Get Membership Content (type=1)

curl -X POST "https://yourstore.com/apps/subscribfy-api/v1/membership/manage" \
  -d "key=your_api_key" \
  -d "cid=7834521098" \
  -d "email=customer@example.com" \
  -d "action=getContent" \
  -d "type=1"

Response:

{
  "membership": {
    "title": "VIP Membership",
    "status": "ACTIVE",
    "price": "29.00 USD billed every 1 month",
    "next_billing_date": "February 15, 2025",
    "CustomerMembershipManageURL": "https://yourstore.com/a/manage/abc123",
    "ShortCustomerMembershipManageURL": "https://sbcr.fy/x9k2"
  },
  "storeCreditNotification": {
    "pending_amount": "0.00",
    "store_credits_available_balance": "45.00"
  }
}

ShortCustomerMembershipManageURL is available only for shops that opted in for this feature. The field is omitted from the response when the shop is not enrolled. Reach out to support to enable short URLs for your account.

Get Product Subscriptions (type=3)

curl -X POST "https://yourstore.com/apps/subscribfy-api/v1/membership/manage" \
  -d "key=your_api_key" \
  -d "cid=7834521098" \
  -d "email=customer@example.com" \
  -d "action=getContent" \
  -d "type=3"

Response:

{
  "product_subscription": [
    {
      "scid": 456,
      "title": "Monthly Coffee Box",
      "status": "ACTIVE",
      "start_date": "2024-11-01",
      "price": "24.99 USD Delivery every 1 month",
      "next_billing_date": "February 1, 2025",
      "items": [
        {
          "title": "Premium Blend Coffee 250g",
          "main_img": "https://cdn.shopify.com/s/files/..."
        },
        {
          "title": "Artisan Roast 250g",
          "main_img": "https://cdn.shopify.com/s/files/..."
        }
      ]
    },
    {
      "scid": 457,
      "title": "Weekly Snack Box",
      "status": "PAUSED",
      "start_date": "2024-09-15",
      "price": "15.99 USD Delivery every 1 week",
      "items": [
        {
          "title": "Mixed Nuts Pack",
          "main_img": "https://cdn.shopify.com/s/files/..."
        }
      ]
    }
  ]
}

Get Customer Portal URL

curl -X POST "https://yourstore.com/apps/subscribfy-api/v1/membership/manage" \
  -d "key=your_api_key" \
  -d "cid=7834521098" \
  -d "email=customer@example.com" \
  -d "action=getCustomerMembershipManageURL" \
  -d "type=1"

Response:

{
  "membership": {
    "CustomerMembershipManageURL": "https://yourstore.com/a/manage/abc123",
    "ShortCustomerMembershipManageURL": "https://sbcr.fy/x9k2"
  }
}

ShortCustomerMembershipManageURL is only returned for shops that opted in for this feature.

Cancel Membership

curl -X POST "https://yourstore.com/apps/subscribfy-api/v1/membership/manage" \
  -d "key=your_api_key" \
  -d "cid=7834521098" \
  -d "email=customer@example.com" \
  -d "action=updateCancelContent" \
  -d "type=1" \
  -d "reason=Too expensive"

Response:

{
  "result": "success"
}

Pause Product Subscription

curl -X POST "https://yourstore.com/apps/subscribfy-api/v1/membership/manage" \
  -d "key=your_api_key" \
  -d "cid=7834521098" \
  -d "email=customer@example.com" \
  -d "action=updatePauseContent" \
  -d "type=3" \
  -d "scid=456" \
  -d "period=2"

Response:

{
  "result": "success"
}

Reactivate Subscription

curl -X POST "https://yourstore.com/apps/subscribfy-api/v1/membership/manage" \
  -d "key=your_api_key" \
  -d "cid=7834521098" \
  -d "email=customer@example.com" \
  -d "action=updateReactivateContent" \
  -d "type=3" \
  -d "scid=456"

Response:

{
  "result": "success"
}

Force Recharge

curl -X POST "https://yourstore.com/apps/subscribfy-api/v1/membership/manage" \
  -d "key=your_api_key" \
  -d "cid=7834521098" \
  -d "email=customer@example.com" \
  -d "action=forceRecharge" \
  -d "type=3" \
  -d "scid=456"

Response:

{
  "result": "success"
}

Code Examples

$apiKey = 'your_api_key';
$store = 'yourstore.com';

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => "https://{$store}/apps/subscribfy-api/v1/membership/manage",
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query([
        'key' => $apiKey,
        'cid' => '7834521098',
        'email' => 'customer@example.com',
        'action' => 'getContent',
        'type' => 1
    ]),
    CURLOPT_RETURNTRANSFER => true
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);

if (isset($data['error'])) {
    echo "Error: " . $data['error'];
} else {
    echo "Status: " . $data['membership']['status'];
    echo "Next billing: " . $data['membership']['next_billing_date'];
}
const axios = require('axios');

const apiKey = 'your_api_key';
const store = 'yourstore.com';

async function getMembershipContent(customerId, email) {
    try {
        const response = await axios.post(
            `https://${store}/apps/subscribfy-api/v1/membership/manage`,
            new URLSearchParams({
                key: apiKey,
                cid: customerId,
                email: email,
                action: 'getContent',
                type: '1'
            })
        );

        const { membership, storeCreditNotification } = response.data;
        console.log(`Status: ${membership.status}`);
        console.log(`Credits: ${storeCreditNotification.store_credits_available_balance}`);

        return response.data;
    } catch (error) {
        console.error('Error:', error.response?.data?.error || error.message);
    }
}

async function pauseSubscription(customerId, email, contractId, months) {
    const response = await axios.post(
        `https://${store}/apps/subscribfy-api/v1/membership/manage`,
        new URLSearchParams({
            key: apiKey,
            cid: customerId,
            email: email,
            action: 'updatePauseContent',
            type: '3',
            scid: contractId,
            period: months
        })
    );

    return response.data.result === 'success';
}
import requests

api_key = 'your_api_key'
store = 'yourstore.com'
base_url = f'https://{store}/apps/subscribfy-api/v1/membership/manage'

def get_membership(customer_id, email):
    response = requests.post(base_url, data={
        'key': api_key,
        'cid': customer_id,
        'email': email,
        'action': 'getContent',
        'type': 1
    })

    data = response.json()

    if 'error' in data:
        raise Exception(data['error'])

    return data

def cancel_membership(customer_id, email, reason):
    response = requests.post(base_url, data={
        'key': api_key,
        'cid': customer_id,
        'email': email,
        'action': 'updateCancelContent',
        'type': 1,
        'reason': reason
    })

    return response.json().get('result') == 'success'

def get_product_subscriptions(customer_id, email):
    response = requests.post(base_url, data={
        'key': api_key,
        'cid': customer_id,
        'email': email,
        'action': 'getContent',
        'type': 3
    })

    data = response.json()
    return data.get('product_subscription', [])

Response Field Reference

Membership Response (type=1, 2)

Prop

Type

Product Subscription Response (type=3)

Prop

Type

Rate Limits

  • Minimum 10 seconds between state-changing actions (updateCancelContent, updatePauseContent, updateReactivateContent) per contract
  • forceRecharge is limited to one call every 3 minutes per contract
  • getContent and getCustomerMembershipManageURL are not rate limited
  • Exceeding rate limit returns {"error": "Too many requests."}

Best Practices

  • Always verify customer identity - Both cid and email must match
  • Cache portal URLs - The management URL doesn't change frequently
  • Handle all error cases - Check for error key before processing response
  • Use scid for product subscriptions - Customers may have multiple subscriptions
  • Respect rate limits - Wait 10+ seconds between state-changing actions

Use Cases

Customer Service Integration

Integrate with Gorgias, Zendesk, or other helpdesk tools to display membership status and allow agents to manage subscriptions directly.

Custom Customer Portal

Build a branded self-service portal using the getContent action to fetch data and action endpoints to handle changes.

Churn Prevention

Intercept cancellation requests, offer alternatives (pause instead of cancel), and track cancellation reasons for analysis.

Questions? Contact support+developer@subscribfy.com

Was this page helpful?

On this page

AI Chat

Ask a question about Subscribfy