Create a Subscription

What is a Subscription?

A subscription in Revolv3 is a recurring billing arrangement where customers are automatically charged at regular intervals (weekly, monthly, yearly, etc.). Instead of asking customers to pay each time, you set it up once and Revolv3 handles all future charges automatically. Common use cases:

SaaS products: Monthly software subscriptions (like $29.99/month)
Membership services: Gym memberships, streaming services, clubs
Recurring services: Monthly box subscriptions, maintenance plans
Installment plans: “Buy now, pay later” with multiple payments

Why use subscriptions?

Predictable revenue: Customers pay automatically, reducing churn
Better customer experience: No need to re-enter payment details
Automated billing: Revolv3 handles retries if payments fail
Flexible plans: Support trials, different billing cycles, multiple plans

How Recurring Billing Works

Here’s the flow:

Customer signs up: You create a subscription with their payment method
First charge: Revolv3 charges them immediately (or after a trial)
Automatic charges: On each billing date, Revolv3 automatically charges the customer
If payment fails: Revolv3 retries based on your settings (called “recycling”)
If all retries fail: Subscription status changes and you can notify the customer

Key concepts:

Billing cycle: How often you charge (weekly, monthly, etc.)
Billing plan: What you charge (amount, when it starts, how many cycles)
Trial period: Free period before billing starts
Payment method: The card or bank account that gets charged

Creating a Subscription

Let’s walk through creating a subscription step by step.

API Endpoint

POST {{Api Root}}/api/Subscriptions

Sample Subscription Request

Here’s a complete example for a monthly subscription service:

{
  "PaymentMethods": [
    {
      "Priority": 0,
      "TaxAmount": null,
      "OriginalNetworkTransactionId": null,
      "BillingAddress": {
        "AddressId": null,
        "AddressLine1": "100 Main Street",
        "AddressLine2": "",
        "City": "Irvine",
        "State": "CA",
        "PostalCode": "92602",
        "PhoneNumber": null,
        "Email": null,
        "Country": "US"
      },
      "BillingFirstName": "John",
      "BillingLastName": "Doe",
      "CreditCard": {
        "PaymentAccountNumber": "4111111111111111",
        "ExpirationDate": "1025",
        "SecurityCode": null
      },
      "MerchantPaymentMethodRefId": "payment-method-ref-id_hgays-2"
    }
  ],
  "Customer": {
    "FirstName": "John",
    "LastName": "Doe"
  },
  "ExistingPaymentMethod": null,
  "MerchantSubscriptionRefId": "1234-5678-9101",
  "BillingFrequency": {
    "IntervalCount": 1,
    "IntervalType": "Weeks"
  },
  "SubscriptionStatusType": "current",
  "SubscriptionCancelType": "immediate",
  "StartDate": "2024-04-26T00:00:00",
  "TrialDuration": 0,
  "SubscriptionBillingPlans": [
    {
      "Name": "Billing Plan 1",
      "Value": 10.99,
      "CycleCount": -1,
      "ValueType": "Standard",
      "StartCycleDelay": 0
    }
  ],
  "RecycleImmediatePayment": false
}

In this example, IntervalCount/IntervalType control how often billing occurs, and RecycleImmediatePayment determines whether to retry immediately if the first payment fails.

Understanding the Request Fields

Payment Methods

Field	Description
`PaymentMethods`	Array of payment methods. You can provide multiple methods (primary + backup).
`Priority`	`0` = primary (used first), `1` = backup (used if primary fails). You can have multiple backup methods.
`TaxAmount`	Optional tax amount for this payment method. If not provided, tax is calculated from merchant settings.
`BillingAddress`	Customer’s billing address (required for fraud prevention).
`BillingFirstName`, `BillingLastName`	Name on the payment method.
`CreditCard`	Card details. For subscriptions, you typically don’t need the CVV after the first charge.
`MerchantPaymentMethodRefId`	Your internal reference for tracking this payment method.

Tip: If you already have a stored payment method (from a previous transaction), you can use ExistingPaymentMethod with a paymentMethodId instead of providing full card details.

Customer Information

Field	Description
`Customer`	Customer details. You can provide `FirstName` and `LastName`, or use an existing `customerId` (see below).
`ExistingPaymentMethod`	Optional. If you have a stored payment method ID, use it here instead of providing card details.

Subscription Configuration

Field	Description
`MerchantSubscriptionRefId`	Your internal subscription ID (like “SUB-12345”). Use this to match Revolv3’s response back to your system.
`BillingFrequency`	How often to charge:

intervalCount: Number of intervals (e.g., 1 = every 1 week)
intervalType: "Days", "Weeks", "Months", or "Years" | | SubscriptionStatusType | Initial status:
"current" = Active subscription
"canceled" = Cancelled (won’t bill)
"recycle" = Payment failed, will retry | | SubscriptionCancelType | How to handle cancellation:
"immediate" = Cancel right away, stop billing immediately
"endOfCycle" = Finish current billing period, then cancel | | StartDate | When the subscription starts (ISO 8601 format). First charge happens on this date (or after trial). | | TrialDuration | Number of days of free trial before billing starts. 0 = no trial, charge immediately. |

Billing Plans

Field	Description
`SubscriptionBillingPlans`	Array of billing plans. You can have multiple plans (e.g., setup fee + monthly fee).
`Name`	Name of the billing plan (for your records).
`Value`	Amount to charge for this plan.
`CycleCount`	How many times to charge:

-1 = Unlimited (charge forever)
12 = Charge 12 times, then stop | | ValueType | Type of charge:
"Standard" = Fixed amount
"Percentage" = Percentage of something
"Fixed" = Fixed fee | | StartCycleDelay | How many cycles to wait before this plan starts. 0 = start immediately. Useful for setup fees. |

Advanced Options

Field	Description
`RecycleImmediatePayment`	If the first payment fails, should Revolv3 retry immediately? `false` = wait for next billing cycle, `true` = retry right away.

Subscription Response

When you successfully create a subscription, Revolv3 returns details about the subscription and the first payment:

{
  "subscriptionId": 1899,
  "customerId": 5409,
  "merchantSubscriptionRefId": "1234-5678-9101",
  "networkTransactionId": "111789899749482",
  "subscriptionStatusType": "current",
  "subscriptionCancelType": "immediate",
  "initialBillDate": "4/26/2024",
  "nextBillDate": "5/3/2024",
  "taxAddress": null,
  "paymentMethodIds": [6064],
  "canceledAt": null,
  "billingPlans": [
    {
      "subscriptionBillingPlanId": 2300,
      "subscriptionId": 1899,
      "name": "Billing Plan 1",
      "value": 10.99,
      "startDate": "4/26/2024",
      "cyclesRemaining": -1,
      "cycleCount": -1,
      "valueType": "Standard"
    }
  ]
}

Understanding the Response

Field	Description
`subscriptionId`	Most important—save this! You’ll use it to manage the subscription (cancel, update, check status).
`customerId`	Customer ID (created automatically). Link this to your customer records.
`merchantSubscriptionRefId`	Your original reference ID, echoed back.
`networkTransactionId`	Transaction ID for the first payment. Store this for your records.
`subscriptionStatusType`	Current status: `"current"` (active), `"canceled"`, or `"recycle"` (payment failed, retrying).
`initialBillDate`	When the first charge happened (or will happen if there’s a trial).
`nextBillDate`	Important—when the next automatic charge will happen. Update this in your system.
`paymentMethodIds`	Array of payment method IDs used for this subscription.
`billingPlans`	Details of all billing plans in this subscription.
`cyclesRemaining`	How many billing cycles are left. `-1` = unlimited.

Important: Store the subscriptionId and nextBillDate in your database. You’ll need the subscription ID to manage the subscription, and the next bill date to show customers when they’ll be charged next.

Real-World Examples

Example 1: Simple Monthly Subscription

Scenario: $29.99/month SaaS product, no trial, charge immediately.

{
  "PaymentMethods": [
    {
      "Priority": 0,
      "BillingAddress": {
        "AddressLine1": "100 Main Street",
        "City": "Irvine",
        "State": "CA",
        "PostalCode": "92602",
        "Country": "US"
      },
      "BillingFirstName": "John",
      "BillingLastName": "Doe",
      "CreditCard": {
        "PaymentAccountNumber": "4111111111111111",
        "ExpirationDate": "1025"
      }
    }
  ],
  "Customer": {
    "FirstName": "John",
    "LastName": "Doe"
  },
  "MerchantSubscriptionRefId": "SAAS-12345",
  "BillingFrequency": {
    "intervalCount": 1,
    "intervalType": "Months"
  },
  "SubscriptionStatusType": "current",
  "StartDate": "2024-04-26T00:00:00",
  "TrialDuration": 0,
  "SubscriptionBillingPlans": [
    {
      "Name": "Monthly Plan",
      "Value": 29.99,
      "CycleCount": -1,
      "ValueType": "Standard"
    }
  ]
}

Result: Customer is charged $29.99 immediately, then automatically charged $29.99 on the 26th of each month.

Example 2: Subscription with Free Trial

Scenario: 14-day free trial, then $9.99/month.

{
  "TrialDuration": 14,
  "SubscriptionBillingPlans": [
    {
      "Name": "Monthly Plan",
      "Value": 9.99,
      "CycleCount": -1
    }
  ]
}

Result: Customer gets 14 days free, then charged $9.99/month starting on day 15.

Example 3: Setup Fee + Monthly Fee

Scenario: $50 setup fee (one-time) + $19.99/month.

{
  "SubscriptionBillingPlans": [
    {
      "Name": "Setup Fee",
      "Value": 50.0,
      "CycleCount": 1,
      "StartCycleDelay": 0
    },
    {
      "Name": "Monthly Fee",
      "Value": 19.99,
      "CycleCount": -1,
      "StartCycleDelay": 0
    }
  ]
}

Result: Customer is charged $50 + $19.99 immediately, then $19.99/month going forward.

Creating a Customer First (Optional)

You can create a customer record separately before creating a subscription. This is useful if:

You want to manage customers independently
A customer might have multiple subscriptions
You’re building a customer management system

API Endpoint

POST {{Api Root}}/api/Customers

Sample Request

{
  "FirstName": "John",
  "LastName": "White",
  "MerchantCustomerRefId": "CUST-12345" // Your internal customer ID
}

Sample Response

{
  "customerId": 5405, // ⭐ Use this in subscription requests
  "merchantCustomerRefId": "CUST-12345",
  "firstName": "John",
  "lastName": "White",
  "billingAddresses": [],
  "shippingAddresses": [],
  "taxAddresses": [],
  "subscriptions": []
}

Using Customer ID in Subscription

Once you have a customerId, use it in the subscription request:

{
  "Customer": {
    "Id": 5405 // Use existing customer instead of FirstName/LastName
  },
  // ... rest of subscription details
}

How Automatic Billing Works

Once a subscription is created, Revolv3 handles everything automatically:

On the billing date: Revolv3 automatically charges the customer’s payment method
If payment succeeds: Customer is charged, subscription continues, nextBillDate is updated
If payment fails:
- Status changes to "recycle"
- Revolv3 retries based on your merchant settings (typically after a few days)
- If retry succeeds: Status back to "current"
- If all retries fail: Status changes to "canceled" or "noncollectable"

You don’t need to do anything—Revolv3 handles the automatic charging. Just set up webhooks to be notified of status changes.

Best Practices

Store subscription IDs: You’ll need them to manage subscriptions (cancel, update, check status)
Set up webhooks: Get notified when payments succeed, fail, or subscriptions are cancelled
Handle payment failures: Have a plan for when automatic charges fail (notify customer, pause service, etc.)
Use trials wisely: Free trials increase sign-ups but require good onboarding
Set customer expectations: Tell them when they’ll be charged and how much
Monitor nextBillDate: Keep this updated in your system so customers know when they’ll be charged
Support multiple payment methods: Allow customers to add backup payment methods in case primary fails

Common Questions

Q: Can I change the billing amount after creating a subscription? A: Yes, you can update billing plans via the API. Changes take effect on the next billing cycle. Q: What happens if a payment fails? A: Revolv3 automatically retries based on your merchant settings. If all retries fail, the subscription status changes and you can notify the customer. Q: Can I pause a subscription? A: You can cancel it and create a new one later, or update the status. There’s no built-in “pause” but you can work around it. Q: How do I cancel a subscription? A: Use the cancel subscription endpoint. You can choose immediate cancellation or end-of-cycle. Q: Can I charge different amounts each month? A: Yes, you can update the billing plan amount, but it’s easier to use multiple billing plans or update before each cycle.

Summary

Action	API Endpoint	Purpose
Create a Subscription	`POST /api/Subscriptions`	Set up recurring billing with automatic charges
Retrieve Subscription Details	`GET /api/Subscriptions/{subscriptionId}`	Get current status, next bill date, etc.
Create a Customer (Optional)	`POST /api/Customers`	Create a customer record before creating subscription

Next Steps

Canceling Subscriptions — Learn how to cancel or pause subscriptions
Billing Plans — Understand billing plan options in detail
Payment Methods — Learn about storing payment methods for subscriptions
Webhooks — Set up notifications for subscription events

Getting Started

Authentication & Security

Core Concepts & Data Models

Integration Flows

Plugins

API Reference

Webhooks & Event Handling

Error Codes & Troubleshooting

Testing & Sandbox

Certification & Go-Live Checklist

Appendix / Glossary

FAQ

What is a Subscription?

How Recurring Billing Works

Creating a Subscription

API Endpoint

Sample Subscription Request

Understanding the Request Fields

Payment Methods

Customer Information

Subscription Configuration

Billing Plans

Advanced Options

Subscription Response

Understanding the Response

Real-World Examples

Example 1: Simple Monthly Subscription

Example 2: Subscription with Free Trial

Example 3: Setup Fee + Monthly Fee

Creating a Customer First (Optional)

API Endpoint

Sample Request

Sample Response

Using Customer ID in Subscription

How Automatic Billing Works

Best Practices

Common Questions

Summary

Next Steps

​What is a Subscription?

​How Recurring Billing Works

​Creating a Subscription

​API Endpoint

​Sample Subscription Request

​Understanding the Request Fields

​Payment Methods

​Customer Information

​Subscription Configuration

​Billing Plans

​Advanced Options

​Subscription Response

​Understanding the Response

​Real-World Examples

​Example 1: Simple Monthly Subscription

​Example 2: Subscription with Free Trial

​Example 3: Setup Fee + Monthly Fee

​Creating a Customer First (Optional)

​API Endpoint

​Sample Request

​Sample Response

​Using Customer ID in Subscription

​How Automatic Billing Works

​Best Practices

​Common Questions

​Summary

​Next Steps

What is a Subscription?

How Recurring Billing Works

Creating a Subscription

API Endpoint

Sample Subscription Request

Understanding the Request Fields

Payment Methods

Customer Information

Subscription Configuration

Billing Plans

Advanced Options

Subscription Response

Understanding the Response

Real-World Examples

Example 1: Simple Monthly Subscription

Example 2: Subscription with Free Trial

Example 3: Setup Fee + Monthly Fee

Creating a Customer First (Optional)

API Endpoint

Sample Request

Sample Response

Using Customer ID in Subscription

How Automatic Billing Works

Best Practices

Common Questions

Summary

Next Steps