Skip to main content

List Subscription Balance Entries

Overview​

Retrieve a list of all balance entries (credits) applied to a Subscription. Use this to view the credit history and track proration adjustments, goodwill credits, and promotional offers.

Resource Access​

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

Arguments​

ParameterTypeRequiredDescription
subscription_idstringYes (path)The unique ID of the Subscription
limitintegerNoMaximum number of records to return

Example Request​

curl -X GET \
  'https://api.ahrvo.network/payments/na/subscriptions/SUBsubscription123/subscription_balance_entries' \
  -u username:password \
  -H 'Content-Type: application/json'

Example Response​

{
  "_embedded": {
    "subscription_balance_entries": [
      {
        "id": "SBEbalanceEntry001",
        "created_at": "2023-12-01T10:00:00Z",
        "updated_at": "2023-12-01T10:00:00Z",
        "type": "CREDIT",
        "subscription_id": "SUBsubscription123",
        "amount": 950,
        "currency": "USD",
        "description": "Proration credit for mid-cycle upgrade from Basic to Pro",
        "tags": {
          "reason": "upgrade_proration",
          "original_plan": "basic",
          "new_plan": "pro"
        },
        "_links": {
          "self": {
            "href": "https://api.ahrvo.network/payments/na/subscriptions/SUBsubscription123/subscription_balance_entries/SBEbalanceEntry001"
          }
        }
      },
      {
        "id": "SBEbalanceEntry002",
        "created_at": "2023-11-15T14:00:00Z",
        "updated_at": "2023-11-15T14:00:00Z",
        "type": "CREDIT",
        "subscription_id": "SUBsubscription123",
        "amount": 500,
        "currency": "USD",
        "description": "Apology credit for service outage on 11/14",
        "tags": {
          "reason": "service_outage",
          "incident_id": "INC-2023-1114"
        },
        "_links": {
          "self": {
            "href": "https://api.ahrvo.network/payments/na/subscriptions/SUBsubscription123/subscription_balance_entries/SBEbalanceEntry002"
          }
        }
      },
      {
        "id": "SBEbalanceEntry003",
        "created_at": "2023-11-01T09:00:00Z",
        "updated_at": "2023-11-01T09:00:00Z",
        "type": "CREDIT",
        "subscription_id": "SUBsubscription123",
        "amount": 2000,
        "currency": "USD",
        "description": "Black Friday promotional credit",
        "tags": {
          "reason": "promotional",
          "campaign_id": "black_friday_2023"
        },
        "_links": {
          "self": {
            "href": "https://api.ahrvo.network/payments/na/subscriptions/SUBsubscription123/subscription_balance_entries/SBEbalanceEntry003"
          }
        }
      }
    ]
  },
  "page": {
    "offset": 0,
    "limit": 10,
    "count": 3
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/subscriptions/SUBsubscription123/subscription_balance_entries"
    },
    "subscription": {
      "href": "https://api.ahrvo.network/payments/na/subscriptions/SUBsubscription123"
    }
  }
}

Additional Information​

  • Balance Entries: Credits applied to subscription
    • Reduce future charges
    • Track credit history
    • Audit trail for adjustments
  • Type: All entries are CREDIT
    • Positive amounts reduce charges
    • Applied to next billing cycle
    • Multiple credits accumulate
  • Use Cases:
    • Customer Support: Explain account credits
    • Billing Questions: Show why charge was reduced
    • Audit Trail: Track all credits applied
    • Credit Balance: Calculate total unused credits
    • Reporting: Analyze credit usage patterns
  • Credit Application: How credits are used
    • Oldest credits applied first (FIFO)
    • Deducted from subscription amount
    • Unused credits roll over
    • Example with 3 credits:
      • Credit 1: $20 (Nov 1)
      • Credit 2: $5 (Nov 15)
      • Credit 3: $10 (Dec 1)
      • Next charge: $49
      • Applied: $20 + $5 + $10 = $35
      • Actual charge: $49 - $35 = $14
  • Total Credit Calculation: 
    Total Credits = Sum of all entry amounts
    Example:
    - Entry 1: $9.50
    - Entry 2: $5.00
    - Entry 3: $20.00
    - Total: $34.50 in credits

    Next bill: $49 - $34.50 = $14.50 charged
  • Tags for Categorization:
    • reason: upgrade_proration, downgrade_proration, service_outage, retention, promotional
    • campaign_id: For promotional credits
    • support_ticket_id: Link to support case
    • incident_id: For outage compensations
  • Related Endpoints:
    • POST /subscriptions/{id}/subscription_balance_entries: Create new credit
    • PUT /subscriptions/{id}/subscription_balance_entries/{entry_id}: Update tags
    • GET /subscriptions/{id}: View subscription details