Create a Subscription Balance Entry (Credit)

Overview

Apply a credit to a Subscription to reduce the next charge amount. Use this for proration adjustments, customer goodwill credits, refunds, or promotional offers.

Resource Access

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

Arguments

Parameter	Type	Required	Description
subscription_id	string	Yes (path)	The unique ID of the Subscription
type	string	Yes	Type of balance entry (currently only "CREDIT")
amount	integer	Yes	Credit amount in cents
currency	string	Yes	Currency code (e.g., "USD")
description	string	No	Description of the credit
tags	object	No	Custom metadata

Example Request

curl -X POST \
  'https://api.ahrvo.network/payments/na/subscriptions/SUBsubscription123/subscription_balance_entries' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "CREDIT",
    "amount": 1000,
    "currency": "USD",
    "description": "Proration credit for mid-cycle upgrade",
    "tags": {
      "reason": "upgrade_proration",
      "original_plan": "basic",
      "new_plan": "pro"
    }
  }'

Example Response

{
  "id": "SBEbalanceEntry123",
  "created_at": "2023-12-10T19:00:00Z",
  "updated_at": "2023-12-10T19:00:00Z",
  "type": "CREDIT",
  "subscription_id": "SUBsubscription123",
  "amount": 1000,
  "currency": "USD",
  "description": "Proration credit for mid-cycle upgrade",
  "tags": {
    "reason": "upgrade_proration",
    "original_plan": "basic",
    "new_plan": "pro"
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/subscriptions/SUBsubscription123/subscription_balance_entries/SBEbalanceEntry123"
    },
    "subscription": {
      "href": "https://api.ahrvo.network/payments/na/subscriptions/SUBsubscription123"
    }
  }
}

Additional Information

Credit Application: Reduces next charge
- Applied automatically on next billing cycle
- Amount deducted from subscription amount
- If credit > charge, rolls over to next cycle
- Example: $49 charge - $10 credit = $39 charged
Type: Currently only CREDIT supported
- Positive amounts reduce charges
- Cannot create DEBIT entries (use amount updates instead)
Amount: Credit value in cents
- Example: 1000 = $10.00 credit
- Must be positive integer
- Can be greater than subscription amount (rolls over)
Use Cases:
- Upgrade Proration:
  - Customer upgrades mid-cycle
  - Calculate unused portion of old plan
  - Apply as credit
  - Example: 15 days unused on $19 plan = $9.50 credit
- Downgrade Proration:
  - Customer downgrades mid-cycle
  - Calculate overpayment
  - Credit the difference
  - Applied to next (lower) charge
- Service Outage Compensation:
  - Service down for period
  - Calculate downtime value
  - Apply goodwill credit
  - Example: 2 days outage on $30/month = $2 credit
- Customer Retention:
  - Customer threatens to cancel
  - Offer retention credit
  - "Here's $20 off next month"
- Refund Alternative:
  - Instead of cash refund
  - Apply credit to account
  - Used on future charges
- Promotional Credit:
  - Marketing promotion
  - "$10 off your next bill"
  - Limited time offer

Proration Calculations:

Mid-Month Upgrade:

Old plan: $19/month
New plan: $49/month
Upgrade on day 15 of 30-day month

Days used at old price: 15
Days remaining: 15
Daily rate old: $19 / 30 = $0.633/day
Credit: 15 days × $0.633 = $9.50

Next charge: $49 - $9.50 = $39.50

Mid-Month Downgrade:

Old plan: $49/month (already paid)
New plan: $19/month
Downgrade on day 15 of 30-day month

Overpaid: $49 - $19 = $30
Days into cycle: 15
Daily rate diff: $30 / 30 = $1/day
Days remaining: 15
Credit: 15 days × $1 = $15

Next charge: $19 - $15 = $4

Credit Balance Tracking:
- Credits accumulate if not fully used
- Example:
  - Apply $20 credit
  - Next charge $15
  - Charged $0, $5 credit remains
  - Following charge $30
  - Charged $25 ($30 - $5 remaining credit)
Multiple Credits: Can apply multiple
- Credits stack/accumulate
- All applied to next charge
- Example:
  - Credit 1: $10
  - Credit 2: $5
  - Next charge: $49 - $15 = $34
Description: Explain the credit
- Shows on customer invoices
- Helps with support questions
- Internal tracking
- Examples:
  - "Proration credit for plan upgrade"
  - "Apology for service outage on 12/5"
  - "Promotional credit - Holiday offer"
  - "Refund for overcharge"
Tags: Track credit reasons
- Internal categorization
- Not visible to customer
- Useful for reporting
- Examples:
  - reason: "upgrade_proration", "retention", "outage"
  - campaign_id: For promotional credits
  - support_ticket_id: Link to support case
Common Workflows:
- Upgrade with Proration:
  1. Customer upgrades to higher plan
  2. Update subscription amount (PUT /subscriptions/{id})
  3. Calculate unused days on old plan
  4. Create balance entry with credit
  5. Next bill shows reduced amount
  6. Send email explaining new pricing
- Service Outage Compensation:
  1. Service down for 6 hours
  2. Calculate outage percentage (6hrs/720hrs = 0.83%)
  3. Apply credit: $49 × 0.83% = $0.41
  4. Round up for goodwill: $5 credit
  5. Create balance entry
  6. Email apology with credit notice
- Retention Offer:
  1. Customer attempts to cancel
  2. Offer: "Stay and get $20 off next month"
  3. Customer accepts
  4. Create $20 credit balance entry
  5. Don't cancel subscription
  6. Send confirmation
Best Practices:
- Document reason in description field
- Use tags for internal tracking
- Round in customer's favor for goodwill
- Communicate credits to customers
- Track credit usage in analytics
- Set policies for when to apply credits
Related Endpoints:
- GET /subscriptions/{id}/subscription_balance_entries: List all credits
- PUT /subscriptions/{id}/subscription_balance_entries/{entry_id}: Update tags
- GET /subscriptions/{id}: View subscription and next charge
- PUT /subscriptions/{id}: Update subscription amount

Overview​

Resource Access​

Arguments​

Example Request​

Example Response​

Additional Information​