Create a Subscription

Overview

Create a recurring charge Subscription for a customer. Subscriptions can be created from a Subscription Plan template or configured directly with custom settings, including trial periods, discount phases, future start dates, and fixed-length terms.

Resource Access

User Permissions: Admin users only
Endpoint: POST /subscriptions

Arguments

Parameter	Type	Required	Description
linked_to	string	Yes	Merchant ID receiving recurring payments
linked_type	string	Yes	Type of linkage (always "MERCHANT")
buyer_details	object	Yes	Buyer identity and payment information (see below)
subscription_plan_id	string	No*	ID of Subscription Plan template to use
amount	integer	No*	Recurring amount in cents (required if no plan)
currency	string	No	Currency code (default: "USD")
billing_interval	string	No*	MONTHLY or YEARLY (required if no plan)
subscription_details	object	No	Billing preferences and trial/discount config
start_subscription_at	string	No	Future start date (ISO 8601 format)
total_billing_intervals	integer	No	Fixed number of billing cycles
nickname	string	No	Display name for subscription
tags	object	No	Custom key-value metadata

*Either subscription_plan_id OR (amount + billing_interval) is required

Buyer Details Object

Field	Type	Required	Description
identity_id	string	Yes	Buyer's Identity ID
instrument_id	string	Yes	Payment Instrument ID to charge
requested_delivery_methods	array	No	Email/SMS notification preferences
shipping_address	object	No	Shipping address for physical goods

Subscription Details Object

Field	Type	Required	Description
collection_method	string	No	BILL_AUTOMATICALLY or SEND_INVOICE
send_invoice	boolean	No	Send invoice notifications
send_receipt	boolean	No	Send receipt notifications
trial_details	object	No	Trial period configuration
discount_phase_details	object	No	Discount phase configuration

Example Request

curl -X POST \
  'https://api.ahrvo.network/payments/na/subscriptions' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "linked_to": "MUmerchant123",
    "linked_type": "MERCHANT",
    "subscription_plan_id": "SPsubscriptionPlan001",
    "buyer_details": {
      "identity_id": "IDidentityBuyer456",
      "instrument_id": "PIcreditCard789",
      "requested_delivery_methods": [
        {
          "type": "EMAIL",
          "destinations": ["customer@example.com"]
        }
      ]
    },
    "subscription_details": {
      "collection_method": "BILL_AUTOMATICALLY",
      "send_invoice": true,
      "send_receipt": true
    },
    "tags": {
      "customer_tier": "premium",
      "signup_source": "website"
    }
  }'

Example Response

{
  "id": "SUBsubscription123",
  "created_at": "2023-12-10T17:00:00Z",
  "updated_at": "2023-12-10T17:00:00Z",
  "amount": 19900,
  "currency": "USD",
  "linked_to": "MUmerchant123",
  "linked_type": "MERCHANT",
  "billing_interval": "MONTHLY",
  "nickname": null,
  "first_charge_at": "2023-12-24T17:00:00Z",
  "next_billing_date": {
    "year": 2023,
    "month": 12,
    "day": 24
  },
  "subscription_phase": "TRIAL",
  "state": "ACTIVE",
  "subscription_plan_id": "SPsubscriptionPlan001",
  "start_subscription_at": null,
  "total_billing_intervals": null,
  "expires_at": null,
  "subscription_details": {
    "collection_method": "BILL_AUTOMATICALLY",
    "send_invoice": true,
    "send_receipt": true,
    "trial_details": {
      "interval_type": "DAY",
      "interval_count": 14,
      "trial_start_at": "2023-12-10T17:00:00Z",
      "trial_end_at": "2023-12-24T17:00:00Z"
    },
    "discount_phase_details": null
  },
  "buyer_details": {
    "identity_id": "IDidentityBuyer456",
    "instrument_id": "PIcreditCard789",
    "requested_delivery_methods": [
      {
        "type": "EMAIL",
        "destinations": ["customer@example.com"]
      }
    ],
    "shipping_address": null
  },
  "tags": {
    "customer_tier": "premium",
    "signup_source": "website"
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/subscriptions/SUBsubscription123"
    },
    "merchant": {
      "href": "https://api.ahrvo.network/payments/na/merchants/MUmerchant123"
    },
    "subscription_plan": {
      "href": "https://api.ahrvo.network/payments/na/subscription_plans/SPsubscriptionPlan001"
    },
    "buyer_identity": {
      "href": "https://api.ahrvo.network/payments/na/identities/IDidentityBuyer456"
    },
    "payment_instrument": {
      "href": "https://api.ahrvo.network/payments/na/payment_instruments/PIcreditCard789"
    }
  }
}

Additional Information

Subscription Creation Methods:
1. From Subscription Plan (recommended):
  - Provide subscription_plan_id
  - Inherits amount, billing_interval, trial, discount from plan
  - Can override with custom values
2. Custom Configuration:
  - Provide amount + billing_interval
  - Manually configure all settings
  - More flexible, but more complex
Subscription States:
- NOT_STARTED: Future-dated, hasn't begun yet
- ACTIVE: Currently active and billing
- PAST_DUE: Payment failed, awaiting retry
- CANCELED: Subscription canceled, no future charges
- EXPIRED: Fixed-term subscription completed
Subscription Phases:
- TRIAL: In free trial period (no charges)
- DISCOUNT: In discounted pricing phase
- EVERGREEN: Regular recurring billing
- FIXED: Fixed-term subscription (ends after X cycles)
- NONE: No special phase
First Charge At: When first payment occurs
- If trial: After trial ends
- If no trial: Immediately or at start_subscription_at
- Can be future-dated
Billing Intervals:
- MONTHLY: Charge every month on same day
- YEARLY: Charge once per year
Collection Methods:
- BILL_AUTOMATICALLY: Auto-charge payment instrument
  - Credit card charged automatically
  - Best for B2C, reduces churn
- SEND_INVOICE: Manual invoice payment
  - Customer pays manually
  - Best for B2B, enterprise
Trial Details: Free trial period
- Inherited from subscription plan or custom
- interval_type: DAY, MONTH, or YEAR
- interval_count: Number of intervals
- Customer not charged during trial
- Example: 14-day trial = {interval_type: "DAY", interval_count: 14}
Discount Phase: Introductory pricing
- Reduced price for first X billing cycles
- Starts after trial (if both configured)
- amount: Discounted price in cents
- billing_interval_count: How many cycles
Future Start Date: Schedule subscription
- Use start_subscription_at for future date
- Subscription state: NOT_STARTED
- Becomes ACTIVE on start date
- Useful for planned launches, contract start dates
Fixed-Length Subscriptions: Limited duration
- Use total_billing_intervals for finite subscription
- Example: 12 = 12 monthly payments, then expires
- State becomes EXPIRED after final payment
- Good for contracts, limited offers
Payment Instrument: What gets charged
- Must be valid credit card or bank account
- Must belong to buyer identity
- Verified before subscription creation

Use Cases

SaaS Free Trial

{
  "subscription_plan_id": "SPpro_plan",
  "buyer_details": {
    "identity_id": "IDcustomer123",
    "instrument_id": "PIcreditCard456"
  }
}

Uses plan's 14-day trial
Auto-charges $49/month after trial
Customer can cancel anytime

Custom Gym Membership

{
  "amount": 5900,
  "billing_interval": "MONTHLY",
  "linked_to": "MUgym_merchant",
  "linked_type": "MERCHANT",
  "buyer_details": {
    "identity_id": "IDmember789",
    "instrument_id": "PIdebitCard012"
  },
  "subscription_details": {
    "collection_method": "BILL_AUTOMATICALLY",
    "send_receipt": true
  }
}

$59/month gym membership
No trial
Auto-charge, send receipt

Annual Contract Starting Next Month

{
  "subscription_plan_id": "SPenterprise_annual",
  "start_subscription_at": "2024-01-01T00:00:00Z",
  "total_billing_intervals": 1,
  "buyer_details": {
    "identity_id": "IDcompany456",
    "instrument_id": "PIbankAccount789"
  },
  "subscription_details": {
    "collection_method": "SEND_INVOICE"
  }
}

Starts January 1st
One-time annual payment
Invoice-based (manual payment)

12-Month Payment Plan

{
  "amount": 9900,
  "billing_interval": "MONTHLY",
  "total_billing_intervals": 12,
  "linked_to": "MUretailer",
  "linked_type": "MERCHANT",
  "buyer_details": {
    "identity_id": "IDshopper123",
    "instrument_id": "PIcard456"
  }
}

$99/month for 12 months
Expires after 12th payment
Financing-style subscription

Best Practices

Use Subscription Plans: Reusable templates simplify management
Verify Payment Instrument: Ensure valid before creating subscription
Set Delivery Methods: Email receipts improve customer experience
Tag for Organization: Track signup source, customer tier, campaign
Trial Periods: Industry standard 14-30 days for SaaS
Future Start Dates: Align with contract terms, billing cycles
Test First: Create test subscription before production
Handle Webhooks: Listen for subscription state changes
Grace Periods: Configure retry logic for failed payments
Customer Communication: Email when subscription created, trial ending

Common Workflows

Checkout Flow

Customer selects plan on pricing page
Collects payment information
Creates Identity for customer
Creates Payment Instrument (credit card)
Creates Subscription with plan ID
Redirect to success page
Send welcome email

Failed Payment Recovery

Subscription goes PAST_DUE
Retry payment automatically (3-5 attempts)
Email customer about failed payment
Update payment instrument if needed
Subscription returns to ACTIVE or gets CANCELED

POST /subscription_plans: Create reusable plan template
GET /subscriptions: List all subscriptions
GET /subscriptions/{id}: Fetch subscription details
PUT /subscriptions/{id}: Update subscription
DELETE /subscriptions/{id}: Cancel subscription
POST /subscriptions/{id}/subscription_balance_entries: Apply credit

Overview​

Resource Access​

Arguments​

Buyer Details Object​

Subscription Details Object​

Example Request​

Example Response​

Additional Information​

Use Cases​

SaaS Free Trial​

Custom Gym Membership​

Annual Contract Starting Next Month​

12-Month Payment Plan​

Best Practices​

Common Workflows​

Checkout Flow​

Failed Payment Recovery​

Related Endpoints​