Skip to main content

Update a Subscription Balance Entry (Tags)

Overview​

Update the tags associated with an existing Subscription Balance Entry. Note that only tags can be modified; the amount, type, and description cannot be changed after creation.

Resource Access​

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

Arguments​

ParameterTypeRequiredDescription
subscription_idstringYes (path)The unique ID of the Subscription
subscription_balance_entry_idstringYes (path)The unique ID of the Balance Entry
tagsobjectYesUpdated custom metadata tags

Example Request​

curl -X PUT \
  'https://api.ahrvo.network/payments/na/subscriptions/SUBsubscription123/subscription_balance_entries/SBEbalanceEntry001' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "tags": {
      "reason": "upgrade_proration",
      "original_plan": "basic",
      "new_plan": "pro",
      "approved_by": "support_manager",
      "ticket_id": "TICKET-12345"
    }
  }'

Example Response​

{
  "id": "SBEbalanceEntry001",
  "created_at": "2023-12-01T10:00:00Z",
  "updated_at": "2023-12-10T20: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",
    "approved_by": "support_manager",
    "ticket_id": "TICKET-12345"
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/subscriptions/SUBsubscription123/subscription_balance_entries/SBEbalanceEntry001"
    },
    "subscription": {
      "href": "https://api.ahrvo.network/payments/na/subscriptions/SUBsubscription123"
    }
  }
}

Additional Information​

  • Tags Only: Limited update scope
    • ✅ tags: Can be updated
    • ❌ amount: Cannot be changed
    • ❌ type: Cannot be changed
    • ❌ description: Cannot be changed
    • ❌ currency: Cannot be changed
  • Why Tags Only: Balance entries are financial records
    • Immutable for audit/compliance
    • Changing amount would affect billing
    • To correct amount: Create new entry with opposite amount
    • Tags for metadata/categorization only
  • Use Cases:
    • Add Tracking Information:
      • Link to support ticket
      • Add approval information
      • Reference incident ID
    • Categorization:
      • Update reason codes
      • Add campaign tracking
      • Organizational metadata
    • Audit Enhancement:
      • Add approver information
      • Link to related records
      • Compliance documentation
  • Common Tag Updates:
    • Add Support Reference: 
      {
        "tags": {
          "reason": "service_outage",
          "ticket_id": "SUP-2023-5678",
          "approved_by": "manager@company.com"
        }
      }
    • Track Campaign: 
      {
        "tags": {
          "reason": "promotional",
          "campaign_id": "summer_sale_2023",
          "promotion_code": "SUMMER20"
        }
      }
    • Link to Incident: 
      {
        "tags": {
          "reason": "service_outage",
          "incident_id": "INC-2023-1201",
          "downtime_hours": "6",
          "compensation_approved": "true"
        }
      }
  • Correcting Amount Mistakes: Cannot update amount
    • If wrong amount entered:
      1. Create offsetting entry (negative of wrong amount)
      2. Create new entry with correct amount
    • Example: Applied $50 instead of $5
      1. Cannot update original $50 entry
      2. Create -$50 entry (reversal)
      3. Create +$5 entry (correct amount)
      4. Net result: $5 credit as intended
  • Best Practices:
    • Use tags for all trackable metadata
    • Standard tag keys across all entries
    • Document tag schema internally
    • Update tags as processes evolve
    • Link to external systems (CRM, ticketing)
  • Updated At: Timestamp changes
    • Reflects when tags were updated
    • Compare to created_at
    • Track modification history
  • Related Endpoints:
    • GET /subscriptions/{id}/subscription_balance_entries: List all credits
    • POST /subscriptions/{id}/subscription_balance_entries: Create new credit
    • GET /subscriptions/{id}: View subscription details