Subscriptions API

The Subscriptions API allows you to create and manage recurring payment subscriptions for both authenticated users and guest customers.

Base URL

https://your-instance.pubflow.com/bridge-payment

Authentication

Include one of the following in your requests:

Header: X-Session-ID: <session_id> (recommended)
Header: Authorization: Bearer <token>
Query Parameter: ?session_id=<session_id>
Guest: Provide guest_data in request body (no auth required)

Endpoints Overview

Method	Endpoint	Description
POST	`/subscriptions`	Create subscription
GET	`/subscriptions/:id`	Get subscription
GET	`/subscriptions`	List subscriptions
PUT	`/subscriptions/:id`	Update subscription
POST	`/subscriptions/:id/cancel`	Cancel subscription
POST	`/subscriptions/:id/reactivate`	Reactivate subscription
GET	`/subscriptions/guest/:email`	Get guest subscriptions

Create Subscription

Create a new recurring subscription.

Request

http

POST /bridge-payment/subscriptions
Content-Type: application/json
X-Session-ID: <session_id>

Request Body

Field	Type	Required	Description
`customer_id`	string	Yes	Customer ID
`product_id`	string	No	Product/plan ID (optional for custom)
`payment_method_id`	string	Yes	Payment method ID for billing
`provider_id`	string	No	Payment provider (default: "stripe")
`trial_days`	number	No	Trial period in days (default: 0)
Custom Pricing (when product_id is null)
`subtotal_cents`	number	No*	Base amount (*required for custom)
`tax_cents`	number	No	Tax amount (default: 0)
`discount_cents`	number	No	Discount amount (default: 0)
`total_cents`	number	No*	Final amount (*required for custom)
`currency`	string	No*	Currency code (*required for custom)
`billing_interval`	string	No*	Billing frequency (*required for custom)
`interval_multiplier`	number	No	Interval multiplier (default: 1)
Tracking Fields
`concept`	string	No	Subscription title/name
`description`	string	No	Subscription description
`reference_code`	string	No	Your internal reference
`category`	string	No	Subscription category
`tags`	string	No	Comma-separated tags
Guest Data
`guest_data`	object	No*	Guest customer data (*required for guests)
`guest_data.email`	string	Yes	Guest email
`guest_data.name`	string	Yes	Guest name

Billing Intervals

daily - Every day
weekly - Every week
monthly - Every month
quarterly - Every 3 months
yearly - Every year

Response

json

{
  "id": "sub_1234567890",
  "customer_id": "cust_abc123",
  "product_id": "prod_premium",
  "payment_method_id": "pm_card_123",
  "provider_id": "stripe",
  "provider_subscription_id": "sub_stripe_xyz789",
  "status": "active",
  "current_period_start": "2025-01-15T10:30:00Z",
  "current_period_end": "2025-02-15T10:30:00Z",
  "cancel_at_period_end": false,
  "trial_end": null,
  "subtotal_cents": 2500,
  "tax_cents": 250,
  "total_cents": 2750,
  "currency": "USD",
  "billing_interval": "monthly",
  "interval_multiplier": 1,
  "next_billing_date": "2025-02-15T10:30:00Z",
  "billing_status": "active",
  "concept": "Premium Monthly Plan",
  "is_guest_subscription": false,
  "created_at": "2025-01-15T10:30:00Z"
}

Examples

Product-Based Subscription

bash

curl -X POST "https://your-instance.pubflow.com/bridge-payment/subscriptions" \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: session_abc123" \
  -d '{
    "customer_id": "cust_user_123",
    "product_id": "prod_premium_monthly",
    "payment_method_id": "pm_card_visa_1234",
    "provider_id": "stripe",
    "trial_days": 14,
    "concept": "Premium Monthly Plan"
  }'

Custom Subscription

bash

curl -X POST "https://your-instance.pubflow.com/bridge-payment/subscriptions" \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: session_abc123" \
  -d '{
    "customer_id": "cust_user_123",
    "payment_method_id": "pm_card_visa_1234",
    "provider_id": "stripe",
    "subtotal_cents": 2500,
    "tax_cents": 250,
    "total_cents": 2750,
    "currency": "USD",
    "billing_interval": "monthly",
    "concept": "Custom Monthly Plan",
    "trial_days": 7
  }'

Guest Subscription

bash

curl -X POST "https://your-instance.pubflow.com/bridge-payment/subscriptions" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method_id": "pm_card_123",
    "provider_id": "stripe",
    "total_cents": 1000,
    "currency": "USD",
    "billing_interval": "monthly",
    "concept": "Monthly Donation",
    "guest_data": {
      "email": "[email protected]",
      "name": "John Doe"
    }
  }'

Get Subscription

Retrieve a specific subscription by ID.

Request

http

GET /bridge-payment/subscriptions/:id
X-Session-ID: <session_id>

Response

Returns complete subscription object.

List Subscriptions

List all subscriptions for authenticated user.

Request

http

GET /bridge-payment/subscriptions
X-Session-ID: <session_id>

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status (active, canceled, etc.)
`limit`	number	Limit results (default: 100)
`offset`	number	Offset for pagination

Response

json

[
  {
    "id": "sub_123",
    "status": "active",
    "total_cents": 2750,
    "billing_interval": "monthly",
    "next_billing_date": "2025-02-15T10:30:00Z",
    "concept": "Premium Plan",
    "created_at": "2025-01-15T10:30:00Z"
  }
]

Update Subscription

Update subscription details.

Request

http

PUT /bridge-payment/subscriptions/:id
Content-Type: application/json
X-Session-ID: <session_id>

Request Body

Field	Type	Description
`payment_method_id`	string	Update payment method
`subtotal_cents`	number	Update subtotal
`tax_cents`	number	Update tax
`total_cents`	number	Update total
`concept`	string	Update concept
`metadata`	object	Update metadata

Example

bash

curl -X PUT "https://your-instance.pubflow.com/bridge-payment/subscriptions/sub_123" \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: session_abc123" \
  -d '{
    "payment_method_id": "pm_new_card_456"
  }'

Cancel Subscription

Cancel a subscription.

Request

http

POST /bridge-payment/subscriptions/:id/cancel
Content-Type: application/json
X-Session-ID: <session_id>

Request Body

Field	Type	Description
`cancel_at_period_end`	boolean	Cancel at end of period (default: true)

Example

bash

# Cancel at end of billing period
curl -X POST "https://your-instance.pubflow.com/bridge-payment/subscriptions/sub_123/cancel" \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: session_abc123" \
  -d '{
    "cancel_at_period_end": true
  }'

# Cancel immediately
curl -X POST "https://your-instance.pubflow.com/bridge-payment/subscriptions/sub_123/cancel" \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: session_abc123" \
  -d '{
    "cancel_at_period_end": false
  }'

Reactivate Subscription

Reactivate a canceled subscription.

Request

http

POST /bridge-payment/subscriptions/:id/reactivate
X-Session-ID: <session_id>

Example

bash

curl -X POST "https://your-instance.pubflow.com/bridge-payment/subscriptions/sub_123/reactivate" \
  -H "X-Session-ID: session_abc123"

Get Guest Subscriptions

List subscriptions for a guest email.

Request

http

GET /bridge-payment/subscriptions/guest/:email

No authentication required.

Subscription States

active - Currently active, billing normally
trialing - In trial period, no charges yet
past_due - Payment failed, retrying
canceled - Subscription ended
paused - Temporarily suspended

Next Steps

Payments API - View subscription payments
Payment Methods API - Manage payment methods
Webhooks API - Handle subscription events

Subscriptions API ​

Base URL ​

Authentication ​

Endpoints Overview ​

Create Subscription ​

Request ​

Request Body ​

Billing Intervals ​

Response ​

Examples ​

Product-Based Subscription ​

Custom Subscription ​

Guest Subscription ​

Get Subscription ​

Request ​

Response ​

List Subscriptions ​

Request ​

Query Parameters ​

Response ​

Update Subscription ​

Request ​

Request Body ​

Example ​

Cancel Subscription ​

Request ​

Request Body ​

Example ​

Reactivate Subscription ​

Request ​

Example ​

Get Guest Subscriptions ​

Request ​

Subscription States ​

Next Steps ​

Subscriptions API

Base URL

Authentication

Endpoints Overview

Create Subscription

Request

Request Body

Billing Intervals

Response

Examples

Product-Based Subscription

Custom Subscription

Guest Subscription

Get Subscription

Request

Response

List Subscriptions

Request

Query Parameters

Response

Update Subscription

Request

Request Body

Example

Cancel Subscription

Request

Request Body

Example

Reactivate Subscription

Request

Example

Get Guest Subscriptions

Request

Subscription States

Next Steps