Skip to main content

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​

ParameterTypeRequiredDescription
subscription_idstringYes (path)The unique ID of the Subscription
typestringYesType of balance entry (currently only "CREDIT")
amountintegerYesCredit amount in cents
currencystringYesCurrency code (e.g., "USD")
descriptionstringNoDescription of the credit
tagsobjectNoCustom 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