Update a Subscription

Overview

Update an existing Subscription's amount, payment method, notification preferences, or metadata. Use this for subscription upgrades, downgrades, or payment method changes.

Resource Access

User Permissions: Admin users only
Endpoint: PUT /subscriptions/\{subscription_id}

Arguments

Parameter	Type	Required	Description
subscription_id	string	Yes (path)	The unique ID of the Subscription
amount	integer	No	New recurring amount in cents
nickname	string	No	Updated display name
buyer_details	object	No	Update payment instrument or delivery methods
subscription_details	object	No	Update billing preferences
tags	object	No	Updated custom metadata

Example Request

curl -X PUT \
  'https://api.ahrvo.network/payments/na/subscriptions/SUBsubscription123' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 49900,
    "nickname": "Pro Plan - Customer Name",
    "buyer_details": {
      "instrument_id": "PInewCreditCard999",
      "requested_delivery_methods": [
        {
          "type": "EMAIL",
          "destinations": ["newemail@example.com"]
        }
      ]
    },
    "tags": {
      "customer_tier": "pro",
      "upgrade_date": "2023-12-10"
    }
  }'

Example Response

{
  "id": "SUBsubscription123",
  "created_at": "2023-11-10T10:00:00Z",
  "updated_at": "2023-12-10T18:00:00Z",
  "amount": 49900,
  "currency": "USD",
  "linked_to": "MUmerchant123",
  "linked_type": "MERCHANT",
  "billing_interval": "MONTHLY",
  "nickname": "Pro Plan - Customer Name",
  "first_charge_at": "2023-11-24T10:00:00Z",
  "next_billing_date": {
    "year": 2024,
    "month": 1,
    "day": 24
  },
  "subscription_phase": "EVERGREEN",
  "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": null,
    "discount_phase_details": null
  },
  "buyer_details": {
    "identity_id": "IDidentityBuyer456",
    "instrument_id": "PInewCreditCard999",
    "requested_delivery_methods": [
      {
        "type": "EMAIL",
        "destinations": ["newemail@example.com"]
      }
    ],
    "shipping_address": null
  },
  "tags": {
    "customer_tier": "pro",
    "upgrade_date": "2023-12-10"
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/subscriptions/SUBsubscription123"
    }
  }
}

Additional Information

Amount Updates: Change pricing (upgrade/downgrade)
- New amount applied on next billing cycle
- Immediate proration not automatic
- Consider applying credit for partial periods
Payment Instrument Update: Change payment method
- Update buyer_details.instrument_id
- New card/account must be verified
- Prevents future payment failures
- Good for expired/lost cards
Delivery Methods: Update notification preferences
- Change email addresses
- Add SMS notifications
- Update buyer contact info
What Can Be Updated:
- ✅ amount: Pricing changes
- ✅ nickname: Display name
- ✅ buyer_details: Payment method, notifications
- ✅ subscription_details: Collection method, receipt preferences
- ✅ tags: Metadata
- ❌ billing_interval: Cannot change (create new subscription)
- ❌ linked_to: Cannot change merchant
- ❌ subscription_plan_id: Cannot change plan
- ❌ state: Use DELETE to cancel

Use Cases:

Upgrade Plan:
```
{"amount": 49900, "nickname": "Pro Plan"}
```
- Customer upgrades from Basic to Pro
- New price on next billing
Update Payment Method:
```
{"buyer_details": {"instrument_id": "PInewCard123"}}
```
- Card expired or lost
- Customer adds new payment method

Change Email:

{
  "buyer_details": {
    "requested_delivery_methods": [
      {"type": "EMAIL", "destinations": ["new@example.com"]}
    ]
  }
}

Downgrade Plan:
```
{"amount": 9900}
```
- Customer downgrades to lower tier
- Reduced price on next billing

Proration Best Practices:
- Calculate partial period credit
- Apply via POST /subscriptions/{id}/subscription_balance_entries
- Example: Upgrade mid-month
  - Used 15 days of $19 plan = $9.50
  - Has 15 days remaining = $9.50 credit
  - Apply $9.50 credit
  - Next bill: $49 - $9.50 = $39.50
Common Workflows:
- Self-Service Upgrade:
  1. Customer selects Pro plan
  2. Update amount to Pro pricing
  3. Calculate proration credit
  4. Apply credit via balance entry
  5. Send confirmation email
- Failed Payment Recovery:
  1. Subscription goes PAST_DUE
  2. Customer updates payment method
  3. Update buyer_details.instrument_id
  4. Retry failed charge
  5. Subscription returns to ACTIVE
Related Endpoints:
- GET /subscriptions/{id}: View current details
- DELETE /subscriptions/{id}: Cancel subscription
- POST /subscriptions/{id}/subscription_balance_entries: Apply proration credit

Overview​

Resource Access​

Arguments​

Example Request​

Example Response​

Additional Information​