Subscriptions

Create and manage recurring billing subscriptions with automatic payment processing.

Overview

The Subscriptions API enables you to:

🔁 Create recurring subscriptions - Daily, weekly, monthly, yearly
💳 Automatic billing - Payments process automatically
⏸️ Pause & resume - Temporarily pause subscriptions
⏭️ Skip payments - Skip upcoming billing cycles
🔄 Auto-retry failed payments - Intelligent retry logic
📧 Dunning notifications - Automatic payment failure alerts
📊 Payment history - Complete transaction history

Create a Subscription

Endpoint

POST /api/v1/recurring

Request

curl -X POST https://dev.auxcore.net/api/v1/recurring \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "merchant_123",
    "customerId": "cust_456",
    "amount": 29.99,
    "currency": "USD",
    "frequency": "monthly",
    "startDate": "2026-02-01",
    "paymentMethod": {
      "type": "card",
      "card": {
        "number": "4111111111111111",
        "expiryMonth": "12",
        "expiryYear": "2027",
        "cvv": "123"
      }
    },
    "customer": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@example.com",
      "phone": "5551234567"
    },
    "billing": {
      "address": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zip": "10001",
      "country": "US"
    },
    "metadata": {
      "plan": "premium",
      "source": "website"
    }
  }'

Parameters

Field	Type	Description	Required
`merchantId`	string	Your merchant ID	Yes
`customerId`	string	Your customer ID	Yes
`amount`	decimal	Recurring amount	Yes
`currency`	string	Currency code (USD, EUR, etc.)	Yes
`frequency`	string	`daily`, `weekly`, `monthly`, `yearly`	Yes
`startDate`	date	First billing date (ISO 8601)	Yes
`paymentMethod`	object	Payment method details	Yes
`customer`	object	Customer information	Yes
`billing`	object	Billing address	Yes
`endDate`	date	Optional end date	No
`maxCycles`	integer	Maximum billing cycles	No
`metadata`	object	Custom key-value pairs	No

Response

{
  "success": true,
  "data": {
    "subscriptionId": "sub_abc123",
    "status": "active",
    "amount": 29.99,
    "currency": "USD",
    "frequency": "monthly",
    "startDate": "2026-02-01T00:00:00Z",
    "nextPaymentDate": "2026-02-01T00:00:00Z",
    "customerId": "cust_456",
    "paymentMethod": {
      "type": "card",
      "last4": "1111",
      "brand": "Visa"
    },
    "createdAt": "2026-01-28T16:00:00Z"
  }
}

Subscription Frequencies

Frequency	Description	Example
`daily`	Every day	Daily newspaper
`weekly`	Every 7 days	Weekly box subscription
`monthly`	Same day each month	SaaS subscriptions
`yearly`	Same day each year	Annual memberships

Get Subscription

Endpoint

GET /api/v1/recurring/:subscriptionId

curl https://dev.auxcore.net/api/v1/recurring/sub_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Response:

{
  "success": true,
  "data": {
    "subscriptionId": "sub_abc123",
    "status": "active",
    "amount": 29.99,
    "currency": "USD",
    "frequency": "monthly",
    "startDate": "2026-02-01T00:00:00Z",
    "nextPaymentDate": "2026-03-01T00:00:00Z",
    "lastPaymentDate": "2026-02-01T00:00:00Z",
    "lastPaymentStatus": "approved",
    "totalPayments": 1,
    "totalAmount": 29.99,
    "failedPayments": 0,
    "customer": {
      "customerId": "cust_456",
      "email": "john@example.com",
      "name": "John Doe"
    },
    "paymentMethod": {
      "type": "card",
      "last4": "1111",
      "brand": "Visa",
      "expiryMonth": "12",
      "expiryYear": "2027"
    }
  }
}

List Subscriptions

Endpoint

GET /api/v1/recurring

Query Parameters

Parameter	Type	Description
`page`	integer	Page number
`limit`	integer	Items per page
`status`	string	Filter by status
`customerId`	string	Filter by customer
`frequency`	string	Filter by frequency

curl "https://dev.auxcore.net/api/v1/recurring?status=active&limit=50" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Update Subscription

Endpoint

PUT /api/v1/recurring/:subscriptionId

curl -X PUT https://dev.auxcore.net/api/v1/recurring/sub_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -d '{
    "amount": 39.99,
    "metadata": {
      "plan": "premium-plus"
    }
  }'

Updatable Fields:

amount - Change recurring amount
frequency - Change billing frequency
paymentMethod - Update payment method
metadata - Update custom data

Pause Subscription

Temporarily pause a subscription without cancelling it.

Endpoint

POST /api/v1/recurring/:subscriptionId/pause

curl -X POST https://dev.auxcore.net/api/v1/recurring/sub_abc123/pause \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Response:

{
  "success": true,
  "data": {
    "subscriptionId": "sub_abc123",
    "status": "paused",
    "pausedAt": "2026-01-28T16:30:00Z",
    "message": "Subscription paused. No payments will be processed."
  }
}

Resume Subscription

Resume a paused subscription.

Endpoint

POST /api/v1/recurring/:subscriptionId/resume

curl -X POST https://dev.auxcore.net/api/v1/recurring/sub_abc123/resume \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Skip Next Payment

Skip the upcoming billing cycle without pausing the subscription.

Endpoint

POST /api/v1/recurring/:subscriptionId/skip-next

curl -X POST https://dev.auxcore.net/api/v1/recurring/sub_abc123/skip-next \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Response:

{
  "success": true,
  "data": {
    "subscriptionId": "sub_abc123",
    "skippedPaymentDate": "2026-03-01T00:00:00Z",
    "nextPaymentDate": "2026-04-01T00:00:00Z",
    "message": "Next payment skipped successfully"
  }
}

Cancel Subscription

Cancel a subscription immediately or at the end of the billing period.

Endpoint

POST /api/v1/recurring/:subscriptionId/cancel

Cancel Immediately

curl -X POST https://dev.auxcore.net/api/v1/recurring/sub_abc123/cancel \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -d '{
    "immediate": true,
    "reason": "Customer request"
  }'

Cancel at Period End

curl -X POST https://dev.auxcore.net/api/v1/recurring/sub_abc123/cancel \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID": your-tenant-id" \
  -d '{
    "immediate": false,
    "reason": "Customer downgrading"
  }'

Subscription Statuses

Status	Description
`active`	Subscription is active and billing
`paused`	Temporarily paused by customer/merchant
`cancelled`	Cancelled - no future payments
`expired`	Reached end date or max cycles
`past_due`	Failed payment - in retry
`unpaid`	Failed all retry attempts

Payment History

Get complete payment history for a subscription.

Endpoint

GET /api/v1/recurring/:subscriptionId/payments

curl https://dev.auxcore.net/api/v1/recurring/sub_abc123/payments \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Response:

{
  "success": true,
  "data": {
    "subscriptionId": "sub_abc123",
    "payments": [
      {
        "paymentDate": "2026-02-01T00:00:00Z",
        "amount": 29.99,
        "status": "approved",
        "transactionId": "txn_payment_1"
      },
      {
        "paymentDate": "2026-03-01T00:00:00Z",
        "amount": 29.99,
        "status": "declined",
        "retryScheduled": true,
        "retryDate": "2026-03-02T00:00:00Z"
      }
    ],
    "total": 2
  }
}

Auto-Retry Logic

When a payment fails, AuxVault automatically retries:

Attempt	Delay	Description
1	Immediate	First attempt
2	1 day	First retry
3	3 days	Second retry
4	5 days	Final retry

After 4 failed attempts, subscription status becomes unpaid.

Learn more about auto-retry →

Webhooks

subscription.created

{
  "type": "subscription.created",
  "data": {
    "subscriptionId": "sub_abc123",
    "amount": 29.99,
    "frequency": "monthly"
  }
}

subscription.payment_succeeded

{
  "type": "subscription.payment_succeeded",
  "data": {
    "subscriptionId": "sub_abc123",
    "transactionId": "txn_payment_1",
    "amount": 29.99,
    "nextPaymentDate": "2026-03-01T00:00:00Z"
  }
}

subscription.payment_failed

{
  "type": "subscription.payment_failed",
  "data": {
    "subscriptionId": "sub_abc123",
    "amount": 29.99,
    "declineReason": "insufficient_funds",
    "retryScheduled": true,
    "retryDate": "2026-03-02T00:00:00Z"
  }
}

subscription.cancelled

{
  "type": "subscription.cancelled",
  "data": {
    "subscriptionId": "sub_abc123",
    "reason": "Customer request",
    "cancelledAt": "2026-01-28T17:00:00Z"
  }
}

Best Practices

✅ DO:

Validate payment method before creating subscription
Handle webhooks for payment failures
Notify customers before charging
Provide pause/resume options
Allow payment method updates
Track failed payments

❌ DON'T:

Don't create duplicate subscriptions - check existing first
Don't ignore failed payments - implement dunning
Don't cancel immediately - offer pause option
Don't skip retry logic - use auto-retry
Don't forget notifications - customers expect them

Next Steps

Need help? Contact support@auxvault.com