Subscriptions API

Manage B2B subscriptions with automated billing, Shopify integration, and credit-based pricing.

Overview

The Subscriptions API provides:

• Full Lifecycle Management — Create, pause, cancel subscriptions
• Credit-Based Pricing — Dynamic pricing based on credit score
• Shopify Integration — Automatic draft order creation
• Automated Billing — APScheduler-powered recurring billing

Base URL

https://api.huntrecht.com/api/v1/subscriptions

Required Scopes

Scope	Permission
subscriptions:read	View subscriptions
subscriptions:write	Create/modify subscriptions

Create Subscription

POST /subscriptions

Create a new subscription with credit-based pricing.

Request Body

Field	Type	Required	Description
customer_id	string	Yes	Customer ID
product_id	string	Yes	Product ID
installments	integer	Yes	Number of installments (6, 12, 24)
start_date	string	No	ISO 8601 start date
quantity	integer	No	Product quantity (default: 1)

Example Request

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

Example Response

{
  "id": "sub_new123",
  "customer_id": "cust_abc123",
  "product_id": "prod_subscription_001",
  "status": "pending_approval",
  "credit_score": 720,
  "monthly_amount": 458.33,
  "interest_rate": 8.5,
  "total_amount": 5500.00,
  "installments": 12,
  "installments_paid": 0,
  "installments_remaining": 12,
  "next_billing_date": "2026-02-01T00:00:00Z",
  "shopify_draft_order_id": "gid://shopify/DraftOrder/123",
  "created_at": "2026-01-11T10:00:00Z",
  "start_date": "2026-02-01"
}

Credit-Based Pricing

Pricing is dynamically calculated based on customer credit score:

Credit Score	Risk Level	Interest Rate	Max Installments
750+	Excellent	5.0% - 7.0%	24
700-749	Good	7.0% - 9.0%	24
650-699	Fair	9.0% - 12.0%	12
600-649	Poor	12.0% - 18.0%	6
< 600	High Risk	Declined	N/A

Pricing Calculation

# Get credit score first
credit = client.credit_risk.get_score(customer_id="cust_abc123")

# Calculate subscription based on credit
subscription = client.subscriptions.create({
    "customer_id": "cust_abc123",
    "product_id": "prod_subscription_001",
    "installments": credit["recommended_terms"]["installments"][0]
})

List Subscriptions

GET /subscriptions

Retrieve subscriptions with filtering.

Query Parameters

Parameter	Type	Description
customer_id	string	Filter by customer
status	string	active, paused, pending_approval, cancelled, completed
product_id	string	Filter by product
page	integer	Page number
limit	integer	Results per page

Example Request

subscriptions = client.subscriptions.list(
    customer_id="cust_abc123",
    status="active",
    page=1,
    limit=20
)

Example Response

{
  "data": [
    {
      "id": "sub_abc123",
      "customer_id": "cust_abc123",
      "product_id": "prod_subscription_001",
      "status": "active",
      "monthly_amount": 458.33,
      "interest_rate": 8.5,
      "installments_paid": 3,
      "installments_remaining": 9,
      "next_billing_date": "2026-02-01T00:00:00Z",
      "created_at": "2026-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "has_more": false
  }
}

Get Subscription

GET /subscriptions/{subscription_id}

Retrieve subscription details including payment history.

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

Full Response

{
  "id": "sub_abc123",
  "customer_id": "cust_abc123",
  "product_id": "prod_subscription_001",
  "status": "active",
  "credit_score": 720,
  "monthly_amount": 458.33,
  "interest_rate": 8.5,
  "total_amount": 5500.00,
  "total_paid": 1375.00,
  "total_remaining": 4125.00,
  "installments": 12,
  "installments_paid": 3,
  "installments_remaining": 9,
  "next_billing_date": "2026-02-01T00:00:00Z",
  "payment_history": [
    {
      "id": "pay_001",
      "amount": 458.33,
      "status": "completed",
      "due_date": "2026-01-01T00:00:00Z",
      "paid_date": "2026-01-01T00:00:00Z"
    }
  ],
  "shopify_draft_order_id": "gid://shopify/DraftOrder/123",
  "shopify_orders": [
    {
      "order_id": "gid://shopify/Order/456",
      "installment_number": 1,
      "status": "paid"
    }
  ],
  "created_at": "2026-01-01T00:00:00Z",
  "start_date": "2026-01-01",
  "end_date": "2026-12-01"
}

Pause Subscription

POST /subscriptions/{subscription_id}/pause

Pause an active subscription.

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

Resume Subscription

POST /subscriptions/{subscription_id}/resume

Resume a paused subscription.

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

Cancel Subscription

DELETE /subscriptions/{subscription_id}

Cancel an active or paused subscription.

Request Parameters

Parameter	Type	Description
reason	string	Cancellation reason
immediate	boolean	Cancel immediately or at end of term

Example Request

subscription = client.subscriptions.cancel(
    subscription_id="sub_abc123",
    reason="Customer requested cancellation",
    immediate=False
)

Cancellation Response

{
  "id": "sub_abc123",
  "status": "cancelled",
  "cancelled_at": "2026-01-11T14:00:00Z",
  "cancellation_reason": "Customer requested cancellation",
  "remaining_balance": 4125.00,
  "refund_amount": 0,
  "early_termination_fee": 206.25,
  "final_payment_date": "2026-01-25"
}

Subscription Status Flow

stateDiagram-v2
    [*] --> pending_approval: Created
    pending_approval --> active: Credit Approved
    pending_approval --> rejected: Credit Denied
    active --> paused: Pause Requested
    paused --> active: Resume Requested
    active --> completed: All Installments Paid
    active --> cancelled: Cancellation Requested
    rejected --> [*]
    completed --> [*]
    cancelled --> [*]

Webhook Events

Event	Description
subscription.created	New subscription created
subscription.approved	Credit approved, subscription active
subscription.rejected	Credit denied
subscription.paused	Subscription paused
subscription.resumed	Subscription resumed
subscription.payment_due	Payment due reminder
subscription.payment_received	Payment received
subscription.completed	All installments paid
subscription.cancelled	Subscription cancelled

Shopify Draft Orders

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

{
  "id": "gid://shopify/DraftOrder/123",
  "name": "#DRAFT-001",
  "customer": {
    "id": "gid://shopify/Customer/456"
  },
  "line_items": [
    {
      "title": "Product Name",
      "quantity": 1,
      "price": "458.33"
    }
  ],
  "total_price": "458.33",
  "payment_terms": {
    "due_in_days": 30,
    "installments": [
      {"amount": "458.33", "due_at": "2026-02-01"}
    ]
  }
}

Next Steps

• Credit Risk Assessment
• Payment Processing
• Subscription Workflow Guide