Subscriptions | Pocketsflow Help Center

A subscription allows customers to be billed automatically on a recurring basis. Pocketsflow provides webhooks to notify merchants about subscription events, allowing them to handle them programmatically.

Creating a Subscription

Creating a subscription in Pocketsflow is simple, follow these steps:

Go to products and click on "Create New" and select Subscription.
Define the information and billing interval (e.g., monthly, yearly).
Configure pricing and trial periods (if applicable).
Store the subscription ID and customer information in your database.
Setting Callback URL (important, see next section)

Setting a Callback URL for Subscriptions

When a customer subscribes to your product, Pocketsflow will redirect them to your callback URL with the following URL parameters:

bashCopyEdit?subscriptionId={id}&subscriptionCustomer={subCId}&redirect_status=succeeded

These parameters allow you to track successful subscriptions and associate them with customers in your system.

To set up the callback URL, go to the Developers page in your Pocketsflow dashboard and specify the URL where Pocketsflow should redirect customers after a successful subscription.

Webhooks for Subscriptions

Pocketsflow provides webhooks to notify you about subscription-related events.

Event Name	Description
`customer.subscription.created`	A new subscription has been created.
`customer.subscription.updated`	A subscription was updated (e.g., payment method updated, plan changed).
`customer.subscription.deleted`	A subscription was canceled or expired.
`customer.subscription.trial_will_end`	The subscription's trial period is about to end.
`customer.subscription.pause`	The subscription was paused.
`customer.subscription.resumed`	The subscription was resumed from a paused state.
`invoice.payment_succeeded`	A subscription invoice was successfully paid.
`invoice.payment_failed`	A subscription invoice payment failed.

Webhook Payload Examples

1. Subscription Created (`customer.subscription.created`)

When a subscription is successfully created, Pocketsflow sends this webhook.

{
  "webhookId": "8479823987483902",
  "subscription": {
    "id": "sub_1234567890"
  },
  "subscriptionCustomer": {
    "id": "cus_9876543210",
    "buyerEmail": "[email protected]",
    "country": "US",
    "stripeCustomerId": "cus_xxxxxxxxxxxxx",
    "stripeSubscriptionId": "sub_xxxxxxxxxxxxx",
    "subscriptionId": "sub_1234567890",
    "stripePriceId": "price_xxxxxxxxxxxxx"
  },
  "currency": "usd",
  "customer": {
    "email": "[email protected]"
  },
  "stripeSubscription": {
    "status": "active",
    "start_date": "2024-02-01T00:00:00Z",
    "current_period_end": "2024-03-01T00:00:00Z"
  },
  "subscriptionPaymentMethod": {
    "type": "card",
    "brand": "visa",
    "last4": "4242"
  }
}

2. Subscription Updated (`customer.subscription.updated`)

This webhook is triggered when the subscription details are updated.

{
  "webhookId": "8479823987483902",
  "subscription": {
    "id": "sub_1234567890"
  },
  "subscriptionCustomer": {
    "id": "cus_9876543210",
    "buyerEmail": "[email protected]",
    "country": "US",
    "stripeCustomerId": "cus_xxxxxxxxxxxxx",
    "stripeSubscriptionId": "sub_xxxxxxxxxxxxx",
    "subscriptionId": "sub_1234567890",
    "stripePriceId": "price_xxxxxxxxxxxxx"
  },
  "currency": "usd",
  "customer": {
    "email": "[email protected]"
  },
  "stripeSubscription": {
    "status": "active",
    "current_period_end": "2024-04-01T00:00:00Z"
  },
  "subscriptionPaymentMethod": {
    "type": "card",
    "brand": "mastercard",
    "last4": "5555"
  }
}

3. Subscription Deleted (`customer.subscription.deleted`)

Triggered when a subscription is canceled or expires.

{
  "webhookId": "8479823987483902",
  "subscription": {
    "id": "sub_1234567890"
  },
  "subscriptionCustomer": {
    "id": "cus_9876543210",
    "buyerEmail": "[email protected]",
    "country": "US",
    "stripeCustomerId": "cus_xxxxxxxxxxxxx",
    "stripeSubscriptionId": "sub_xxxxxxxxxxxxx",
    "subscriptionId": "sub_1234567890",
    "stripePriceId": "price_xxxxxxxxxxxxx"
  },
  "currency": "usd",
  "customer": {
    "email": "[email protected]"
  },
  "stripeSubscription": {
    "status": "canceled"
  }
}

For the rest of the webhooks, please log the body of the webhook to see what is returned and how you can use it.

Verifying the Webhook

To verify that the webhook came from Pocketsflow, use the following Node.js/Express example:

import express from 'express';
import crypto from 'crypto';

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = '${secret}';

app.post('/webhooks', (req, res) => {
  const receivedSignature = req.headers['x-pocketsflow-signature'];
  const expectedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (receivedSignature === expectedSignature) {
    console.log('Valid webhook received:', req.body);
    res.json({ status: 'success' });
  } else {
    console.error('Invalid webhook signature');
    res.status(401).json({ error: 'Invalid signature' });
  }
});

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});

Subscription Portal

Each user should have their Subscription Portal link which is provided to you in the last Step of the Subscription creation/editing page, where customers can:

Cancel their subscription
Update their payment method
Manage their billing details

Portal URL Format

https://merchant.pocketsflow.com/portal/{subscriptionId}/{subscriptionCustomerId}

Example

https://merchant.pocketsflow.com/portal/sub_1234567890/cus_9876543210

Webhooks