Skip to main content

Subscription Workflow Guide

Complete guide to setting up and managing B2B subscriptions.

Overview​

B2B subscriptions enable customers to purchase products with flexible installment plans, with pricing dynamically calculated based on credit score.

Workflow Sequence​

sequenceDiagram
    participant C as Customer
    participant H as Huntrecht
    participant Credit as Credit Engine
    participant S as Shopify
    participant P as Payment Processor
    
    C->>H: Create Subscription Request
    H->>Credit: Get Credit Score
    Credit-->>H: Score & Risk Level
    H->>H: Calculate Monthly Amount
    H->>S: Create Draft Order
    H-->>C: Subscription Details
    C->>H: Approve Subscription
    H->>P: Process First Payment
    P-->>H: Payment Confirmed
    H->>S: Convert to Order

Step 1: Check Customer Credit​

Before creating a subscription, verify the customer's credit score:

credit = client.credit_risk.get_score(customer_id="cust_abc123")

if credit['risk_level'] == 'high':
    print("Customer not eligible for subscription")
else:
    max_installments = min(credit['recommended_terms']['installments'])
    print(f"Max installments: {max_installments}")

Step 2: Create Subscription​

subscription = client.subscriptions.create({
    "customer_id": "cust_abc123",
    "product_id": "prod_subscription_001",
    "installments": 12,
    "start_date": "2026-02-01"
})

print(f"Subscription ID: {subscription['id']}")
print(f"Monthly Amount: ${subscription['monthly_amount']}")
print(f"Interest Rate: {subscription['interest_rate']}%")

Step 3: Subscription States​

StateDescriptionNext Action
pending_approvalAwaiting credit approvalAuto-approved or manual
approvedCredit approvedCustomer confirmation
activeActive subscriptionProcess payments
pausedTemporarily pausedResume or cancel
completedAll installments paidNone
cancelledSubscription endedCannot restart

Step 4: Payment Processing​

The system automatically processes payments:

# View payment schedule
subscription = client.subscriptions.get("sub_abc123")
print(subscription["payment_schedule"])

Payment Schedule Example​

{
  "subscription_id": "sub_abc123",
  "monthly_amount": 458.33,
  "total_amount": 5500.00,
  "payments": [
    {"installment": 1, "due_date": "2026-02-01", "amount": 458.33, "status": "pending"},
    {"installment": 2, "due_date": "2026-03-01", "amount": 458.33, "status": "pending"},
    {"installment": 3, "due_date": "2026-04-01", "amount": 458.33, "status": "pending"}
  ]
}

Step 5: Manage Subscription​

Pause Subscription​

subscription = client.subscriptions.pause(
    subscription_id="sub_abc123",
    reason="Temporary financial constraints",
    resume_date="2026-03-01"
)

Resume Subscription​

subscription = client.subscriptions.resume("sub_abc123")

Cancel Subscription​

subscription = client.subscriptions.cancel(
    subscription_id="sub_abc123",
    reason="Customer requested",
    immediate=False  # Continue until end of billing period
)

Shopify Integration​

Draft Order Creation​

When a subscription is created, a Shopify draft order is automatically generated:

{
  "id": "gid://shopify/DraftOrder/123",
  "name": "#DRAFT-SUB-001",
  "customer": {
    "id": "gid://shopify/Customer/456",
    "email": "buyer@company.com"
  },
  "line_items": [
    {
      "title": "Industrial Equipment",
      "quantity": 1,
      "price": "458.33"
    }
  ],
  "total_price": "458.33",
  "payment_terms": {
    "due_in_days": 30,
    "type": "installment",
    "installments": 12
  }
}

Convert to Order​

After first payment, the draft order converts to a regular Shopify order:

{
  "id": "gid://shopify/Order/789",
  "name": "#1001",
  "financial_status": "paid",
  "fulfillment_status": "unfulfilled"
}

Webhook Events​

Subscribe to these events for real-time updates:

EventDescription
subscription.createdNew subscription created
subscription.approvedCredit approved
subscription.activeSubscription is active
subscription.payment_duePayment due reminder
subscription.payment_receivedPayment processed
subscription.pausedSubscription paused
subscription.cancelledSubscription cancelled
subscription.completedAll installments complete

Complete Workflow Example​

#!/usr/bin/env python3
"""
Complete Subscription Workflow Example
"""

from huntrecht import HuntrechtClient
import os

def create_subscription_workflow(customer_id, product_id, installments):
    client = HuntrechtClient(
        client_id=os.environ.get("HUNTRECHT_CLIENT_ID"),
        client_secret=os.environ.get("HUNTRECHT_CLIENT_SECRET")
    )
    
    # Step 1: Check credit
    print("Step 1: Checking credit score...")
    credit = client.credit_risk.get_score(customer_id=customer_id)
    print(f"  Score: {credit['score']} ({credit['risk_level']})")
    
    if credit['risk_level'] == 'high':
        print("  ✗ Customer not eligible")
        return None
    
    # Step 2: Create subscription
    print("\nStep 2: Creating subscription...")
    subscription = client.subscriptions.create({
        "customer_id": customer_id,
        "product_id": product_id,
        "installments": installments
    })
    print(f"  ID: {subscription['id']}")
    print(f"  Monthly: ${subscription['monthly_amount']}")
    print(f"  Total: ${subscription['total_amount']}")
    
    # Step 3: Check status
    print("\nStep 3: Checking subscription status...")
    status = client.subscriptions.get(subscription['id'])
    print(f"  Status: {status['status']}")
    print(f"  Next billing: {status['next_billing_date']}")
    
    # Step 4: View payment schedule
    print("\nStep 4: Payment schedule...")
    for payment in status.get('payment_history', [])[:3]:
        print(f"  - Installment {payment['installment_number']}: ${payment['amount']} ({payment['status']})")
    
    return subscription

# Run workflow
result = create_subscription_workflow(
    customer_id="cust_abc123",
    product_id="prod_subscription_001",
    installments=12
)

Next Steps​