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 (`include_pm` expands saved PM)
PATCH	`/subscriptions/:id`	Change default payment method + metadata (provider sync when supported)
PATCH	`/subscriptions/:id/billing-address`	Link/unlink subscription billing address
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
  }'

Product ↔ membership linkage

If the subscribed product has metadata.membership_type_id set to a tier id from /bridge-payment/memberships/tiers, the platform can materialize entity memberships (user / organization / project) when the subscription becomes active—see Memberships API. The subscription row’s product_id remains the stable link to catalog pricing; the membership points at subscription_id for lifecycle and cancellation.

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>

include_pm is not currently supported on this single-subscription endpoint. To expand payment method details, use GET /bridge-payment/subscriptions?include_pm=true and filter by id on your side, or call GET /bridge-payment/payment-methods/:id with the returned payment_method_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.)
`organization_id`	string	Optional organization scope (requires membership/access)
`project_id`	string	Filter subscriptions by project (access-checked)
`include_projects`	boolean	When `true`, include expanded `project` details (id, name, slug, billing_email) on each listed subscription
`include_pm`	boolean	When `true`, include an expanded `payment_method` object on each listed subscription
`limit`	number	Limit results (default: 100)
`offset`	number	Offset for pagination

organization_id and project_id can be used independently or together on GET /subscriptions.

include_pm scope

include_pm applies to GET /subscriptions (list endpoint). It does not apply to GET /subscriptions/:id.

include_projects scope

include_projects applies to GET /subscriptions (list endpoint). It does not apply to GET /subscriptions/:id.

Response

json

[
  {
    "id": "sub_123",
    "project_id": "proj_abc123",
    "status": "active",
    "total_cents": 2750,
    "billing_interval": "monthly",
    "next_billing_date": "2025-02-15T10:30:00Z",
    "project": {
      "id": "proj_abc123",
      "name": "Growth Website",
      "slug": "growth-website",
      "billing_email": "[email protected]"
    },
    "concept": "Premium Plan",
    "created_at": "2025-01-15T10:30:00Z"
  }
]

Patch subscription (payment method + metadata)

Swap the subscription’s saved payment method and optionally update metadata. The payment method must belong to the same user as the session (even for org-billed subscriptions). For organization subscriptions, the caller also needs a billing-capable org role (owner / admin / billing).

When the subscription exists at the provider, Bridge calls the provider’s subscription update API so the new PM becomes the default for the next cycle.

Request

http

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

Request Body

Field	Type	Description
`payment_method_id`	string	Internal Bridge PM id (must match subscription `provider_id`)
`metadata`	object	Replaces/merges subscription metadata (JSON)

Example

bash

curl -X PATCH "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"
  }'

Patch subscription billing address

Link or unlink a billing address on the subscription record (invoicing / fiscal trail). Address ownership is validated; org subscriptions allow addresses owned by the same organization.

http

PATCH /bridge-payment/subscriptions/:id/billing-address
Content-Type: application/json

Body: { "billing_address_id": "addr_..." | null } — provider sync follows the same pattern as payment methods where applicable.

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

Memberships API - Tiers, projects, orgs, access checks
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 ​

Product ↔ membership linkage ​

Guest Subscription ​

Get Subscription ​

Request ​

Response ​

List Subscriptions ​

Request ​

Query Parameters ​

Response ​

Patch subscription (payment method + metadata) ​

Request ​

Request Body ​

Example ​

Patch subscription billing address ​

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

Product ↔ membership linkage

Guest Subscription

Get Subscription

Request

Response

List Subscriptions

Request

Query Parameters

Response

Patch subscription (payment method + metadata)

Request

Request Body

Example

Patch subscription billing address

Cancel Subscription

Request

Request Body

Example

Reactivate Subscription

Request

Example

Get Guest Subscriptions

Request

Subscription States

Next Steps