Subscriptions

Subscriptions allow you to charge a customer on a recurring basis. Each subscription is linked to one or more price items (which belong to products). HL Hunt handles automatic billing, retry logic for failed payments, and lifecycle management including trials, pauses, and cancellations.

POST
/v1/subscriptions

Create a Subscription

Create a new subscription for a customer. Each item must include a price_id (from a product) and quantity. Optional: trial_days, billing_start_date, end_date, description, metadata, default_payment_method (pin a specific card for billing).

curl -X POST https://api.hlhunt.org/v1/subscriptions \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_8hJ4nPqRtV",
    "items": [
      { "price_id": "pri_9xR2vWyZaB", "quantity": 1 }
    ],
    "trial_days": 14,
    "description": "Pro Plan monthly",
    "default_payment_method": "pi_4kL9mNpQrS"
  }'
GET
/v1/subscriptions

List Subscriptions

Returns a paginated list of all subscriptions. Use ?status= to filter by ACTIVE, TRIALING, PAST_DUE, PAUSED, or CANCELED.

curl -X GET "https://api.hlhunt.org/v1/subscriptions?status=active&limit=20" \
  -H "Authorization: Bearer sk_live_your_api_key"
GET
/v1/subscriptions/{subscription_id}

Retrieve a Subscription

Retrieves the details of an existing subscription by its ID.

curl -X GET https://api.hlhunt.org/v1/subscriptions/sub_7vA0wYzBcD \
  -H "Authorization: Bearer sk_live_your_api_key"
PUT
/v1/subscriptions/{subscription_id}

Update a Subscription

Update a subscription's description, metadata, or default payment method. Pass default_payment_method with a payment instrument ID to pin a specific card for billing, or null to revert to auto-selection. Only non-canceled subscriptions can be updated.

curl -X PUT https://api.hlhunt.org/v1/subscriptions/sub_7vA0wYzBcD \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Enterprise Plan",
    "metadata": { "team": "engineering" },
    "default_payment_method": "pi_4kL9mNpQrS"
  }'
POST
/v1/subscriptions/{subscription_id}/pause

Pause a Subscription

Pause an active subscription. Billing will stop until the subscription is resumed. The customer will not be charged during the pause period. All pending billing cycles are voided.

curl -X POST https://api.hlhunt.org/v1/subscriptions/sub_7vA0wYzBcD/pause \
  -H "Authorization: Bearer sk_live_your_api_key"
POST
/v1/subscriptions/{subscription_id}/resume

Resume a Subscription

Resume a paused subscription. If the current billing period has not yet expired, the subscription is simply reactivated with no new charge (the customer already paid for this period). If the period expired while paused, a new billing cycle is created and charged immediately if a payment method is on file.

curl -X POST https://api.hlhunt.org/v1/subscriptions/sub_7vA0wYzBcD/resume \
  -H "Authorization: Bearer sk_live_your_api_key"
DELETE
/v1/subscriptions/{subscription_id}

Cancel a Subscription

Cancel an active or paused subscription. By default, cancellation takes effect at the end of the current billing period (cancel_at_period_end: true). Pass cancel_at_period_end: false to cancel immediately. All pending billing cycles are voided on immediate cancellation.

curl -X DELETE https://api.hlhunt.org/v1/subscriptions/sub_7vA0wYzBcD \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "cancel_at_period_end": true, "reason": "Customer requested" }'