Skip to main content

​
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:
  1. Customer signs up: You create a subscription with their payment method
  2. First charge: Revolv3 charges them immediately (or after a trial)
  3. Automatic charges: On each billing date, Revolv3 automatically charges the customer
  4. If payment fails: Revolv3 retries based on your settings (called “recycling”)
  5. 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, // 0 = primary payment method
      "TaxAmount": null, // Optional: tax amount for this payment method
      "OriginalNetworkTransactionId": null, // For linked transactions
      "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", // Format: MMYY
        "SecurityCode": null // Optional for subscriptions
      },
      "MerchantPaymentMethodRefId": "payment-method-ref-id_hgays-2"
    }
  ],
  "Customer": {
    "FirstName": "John",
    "LastName": "Doe"
  },
  "ExistingPaymentMethod": null, // Or use a paymentMethodId if you have one
  "MerchantSubscriptionRefId": "1234-5678-9101", // Your internal subscription ID
  "BillingFrequency": {
    "intervalCount": 1, // Charge every 1 interval
    "intervalType": "Weeks" // Options: Days, Weeks, Months, Years
  },
  "SubscriptionStatusType": "current", // current, canceled, or recycle
  "SubscriptionCancelType": "immediate", // immediate or endOfCycle
  "StartDate": "2024-04-26T00:00:00", // When subscription starts
  "TrialDuration": 0, // Days of free trial (0 = no trial)
  "SubscriptionBillingPlans": [
    {
      "Name": "Billing Plan 1",
      "Value": 10.99, // Amount to charge
      "CycleCount": -1, // -1 = unlimited cycles, or specify number
      "ValueType": "Standard", // Standard, Percentage, or Fixed
      "StartCycleDelay": 0 // Cycles to wait before this plan starts
    }
  ],
  "RecycleImmediatePayment": false // Whether to retry immediately if first payment fails
}

​
Understanding the Request Fields

​
Payment Methods

FieldDescription
PaymentMethodsArray of payment methods. You can provide multiple methods (primary + backup).
Priority0 = primary (used first), 1 = backup (used if primary fails). You can have multiple backup methods.
TaxAmountOptional tax amount for this payment method. If not provided, tax is calculated from merchant settings.
BillingAddressCustomer’s billing address (required for fraud prevention).
BillingFirstName, BillingLastNameName on the payment method.
CreditCardCard details. For subscriptions, you typically don’t need the CVV after the first charge.
MerchantPaymentMethodRefIdYour 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

FieldDescription
CustomerCustomer details. You can provide FirstName and LastName, or use an existing customerId (see below).
ExistingPaymentMethodOptional. If you have a stored payment method ID, use it here instead of providing card details.

​
Subscription Configuration

FieldDescription
MerchantSubscriptionRefIdYour internal subscription ID (like “SUB-12345”). Use this to match Revolv3’s response back to your system.
BillingFrequencyHow 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

FieldDescription
SubscriptionBillingPlansArray of billing plans. You can have multiple plans (e.g., setup fee + monthly fee).
NameName of the billing plan (for your records).
ValueAmount to charge for this plan.
CycleCountHow 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

FieldDescription
RecycleImmediatePaymentIf 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, // ⭐ Save this! You'll need it for managing the subscription
  "customerId": 5409, // Customer ID (created automatically if you didn't provide one)
  "merchantSubscriptionRefId": "1234-5678-9101", // Your reference ID
  "networkTransactionId": "111789899749482", // Transaction ID for the first payment
  "subscriptionStatusType": "current", // Active subscription
  "subscriptionCancelType": "immediate",
  "initialBillDate": "4/26/2024", // Date of first charge
  "nextBillDate": "5/3/2024", // Date of next automatic charge
  "taxAddress": null,
  "paymentMethodIds": [6064], // Payment methods associated with this subscription
  "canceledAt": null, // Will have a date if cancelled
  "billingPlans": [
    {
      "subscriptionBillingPlanId": 2300,
      "subscriptionId": 1899,
      "name": "Billing Plan 1",
      "value": 10.99,
      "startDate": "4/26/2024",
      "cyclesRemaining": -1, // -1 = unlimited
      "cycleCount": -1,
      "valueType": "Standard"
    }
  ]
}

​
Understanding the Response

FieldDescription
subscriptionIdMost important—save this! You’ll use it to manage the subscription (cancel, update, check status).
customerIdCustomer ID (created automatically). Link this to your customer records.
merchantSubscriptionRefIdYour original reference ID, echoed back.
networkTransactionIdTransaction ID for the first payment. Store this for your records.
subscriptionStatusTypeCurrent status: "current" (active), "canceled", or "recycle" (payment failed, retrying).
initialBillDateWhen the first charge happened (or will happen if there’s a trial).
nextBillDateImportant—when the next automatic charge will happen. Update this in your system.
paymentMethodIdsArray of payment method IDs used for this subscription.
billingPlansDetails of all billing plans in this subscription.
cyclesRemainingHow 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": [/* card details */],
  "Customer": {"FirstName": "John", "LastName": "Doe"},
  "MerchantSubscriptionRefId": "SAAS-12345",
  "BillingFrequency": {
    "intervalCount": 1,
    "intervalType": "Months" // Monthly
  },
  "SubscriptionStatusType": "current",
  "StartDate": "2024-04-26T00:00:00",
  "TrialDuration": 0, // No trial
  "SubscriptionBillingPlans": [{
    "Name": "Monthly Plan",
    "Value": 29.99,
    "CycleCount": -1, // Unlimited
    "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, // 14 days free
  "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.00,
      "CycleCount": 1, // Charge once
      "StartCycleDelay": 0 // Charge immediately
    },
    {
      "Name": "Monthly Fee",
      "Value": 19.99,
      "CycleCount": -1, // Unlimited
      "StartCycleDelay": 0 // Also start immediately
    }
  ]
}
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:
  1. On the billing date: Revolv3 automatically charges the customer’s payment method
  2. If payment succeeds: Customer is charged, subscription continues, nextBillDate is updated
  3. 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

  1. Store subscription IDs: You’ll need them to manage subscriptions (cancel, update, check status)
  2. Set up webhooks: Get notified when payments succeed, fail, or subscriptions are cancelled
  3. Handle payment failures: Have a plan for when automatic charges fail (notify customer, pause service, etc.)
  4. Use trials wisely: Free trials increase sign-ups but require good onboarding
  5. Set customer expectations: Tell them when they’ll be charged and how much
  6. Monitor nextBillDate: Keep this updated in your system so customers know when they’ll be charged
  7. 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

ActionAPI EndpointPurpose
Create a SubscriptionPOST /api/SubscriptionsSet up recurring billing with automatic charges
Retrieve Subscription DetailsGET /api/Subscriptions/{subscriptionId}Get current status, next bill date, etc.
Create a Customer (Optional)POST /api/CustomersCreate a customer record before creating subscription

​
Next Steps