Billing & Usage

AS2aaS provides flexible billing models with real-time usage tracking and comprehensive subscription management. The platform integrates with enterprise billing systems and provides detailed usage analytics.

Billing Models

The platform supports multiple billing approaches to accommodate different enterprise requirements:

Base Plus Usage

Monthly base subscription fee plus per-message charges. Provides predictable base costs with usage-based scaling.

Per-Partner Pricing

Fixed monthly fee per active trading partner with unlimited message volume. Ideal for high-volume trading relationships.

Hybrid Billing

Combination of base subscription, per-partner fees, and usage charges. Optimized for complex enterprise scenarios with varied trading patterns.

Enterprise Custom

Tailored pricing models for large enterprise deployments with specific requirements and volume commitments.

Subscription Management

Retrieve Billing Information

curl -X GET https://api.as2aas.com/v1/billing \
  -H "Authorization: Bearer pk_live_your_api_key"

Response:

{
  "customer_id": "cus_enterprise_customer",
  "subscription": {
    "id": "sub_enterprise_plan",
    "status": "active",
    "current_period_start": "2024-01-01T00:00:00Z",
    "current_period_end": "2024-02-01T00:00:00Z",
    "trial_ends_at": null,
    "cancel_at_period_end": false
  },
  "billing_plan": {
    "name": "Enterprise Plan",
    "model": "base_plus_usage",
    "base_fee": 299.00,
    "message_rate": 0.05
  },
  "payment_method": {
    "type": "card",
    "last4": "4242",
    "exp_month": 12,
    "exp_year": 2025
  },
  "has_payment_method": true
}

curl -X POST https://api.as2aas.com/v1/billing/subscribe \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "plan_enterprise",
    "payment_method_id": "pm_card_visa",
    "billing_cycle": "monthly"
  }'

Update Subscription

curl -X PATCH https://api.as2aas.com/v1/billing/subscription \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "plan_enterprise_pro",
    "prorate": true
  }'

Usage Tracking

Retrieve Usage Data

curl -X GET "https://api.as2aas.com/v1/billing/usage?start_date=2024-01-01&end_date=2024-01-31" \
  -H "Authorization: Bearer pk_live_your_api_key"

Response:

{
  "period": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-31T23:59:59Z"
  },
  "usage_summary": {
    "total_messages": 15420,
    "inbound_messages": 7210,
    "outbound_messages": 8210,
    "total_partners": 12,
    "active_partners": 11,
    "total_payload_size": 2147483648,
    "average_message_size": 139264
  },
  "partner_breakdown": [
    {
      "partner_id": "prt_enterprise_001",
      "partner_name": "Enterprise Partner Corp",
      "message_count": 8500,
      "payload_size": 1073741824,
      "success_rate": 99.9
    }
  ],
  "daily_usage": [
    {
      "date": "2024-01-01",
      "messages": 512,
      "payload_size": 67108864
    }
  ]
}

Real-time Usage Metrics

curl -X GET https://api.as2aas.com/v1/billing/usage/current \
  -H "Authorization: Bearer pk_live_your_api_key"

Response:

{
  "current_period": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-02-01T00:00:00Z",
    "days_remaining": 15
  },
  "usage_to_date": {
    "messages": 8420,
    "estimated_charges": 421.00,
    "base_fee": 299.00,
    "usage_charges": 122.00
  },
  "projected_usage": {
    "estimated_monthly_messages": 16840,
    "estimated_monthly_charges": 842.00
  }
}

Payment Methods

Add Payment Method

curl -X POST https://api.as2aas.com/v1/billing/payment-methods \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "card",
    "card": {
      "number": "4242424242424242",
      "exp_month": 12,
      "exp_year": 2025,
      "cvc": "123"
    },
    "billing_details": {
      "name": "Corporation Inc",
      "email": "[email protected]",
      "address": {
        "line1": "123 Business St",
        "city": "Business City",
        "state": "CA",
        "postal_code": "12345",
        "country": "US"
      }
    }
  }'

Set Default Payment Method

curl -X PATCH https://api.as2aas.com/v1/billing/payment-methods/pm_123/default \
  -H "Authorization: Bearer pk_live_your_api_key"

Invoicing and Billing

Retrieve Invoices

curl -X GET https://api.as2aas.com/v1/billing/invoices \
  -H "Authorization: Bearer pk_live_your_api_key"

Response:

{
  "data": [
    {
      "id": "in_invoice_123",
      "number": "AS2-2024-001",
      "status": "paid",
      "amount_due": 421.00,
      "amount_paid": 421.00,
      "currency": "usd",
      "period_start": "2024-01-01T00:00:00Z",
      "period_end": "2024-01-31T23:59:59Z",
      "created": "2024-02-01T00:00:00Z",
      "due_date": "2024-02-15T23:59:59Z",
      "paid_at": "2024-02-01T08:30:00Z"
    }
  ]
}

Download Invoice

curl -X GET https://api.as2aas.com/v1/billing/invoices/in_123/pdf \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -o invoice_2024_001.pdf

Usage Analytics

Partner Usage Analysis

curl -X GET "https://api.as2aas.com/v1/billing/analytics/partners?period=last_90_days" \
  -H "Authorization: Bearer pk_live_your_api_key"

Response:

{
  "period": "last_90_days",
  "total_partners": 12,
  "partner_metrics": [
    {
      "partner_id": "prt_high_volume",
      "partner_name": "High Volume Partner",
      "message_count": 25000,
      "success_rate": 99.95,
      "average_size": 145000,
      "cost_contribution": 1250.00,
      "trend": "increasing"
    }
  ],
  "cost_breakdown": {
    "base_fees": 897.00,
    "message_charges": 1875.00,
    "partner_fees": 600.00,
    "total": 3372.00
  }
}

Message Volume Trends

curl -X GET "https://api.as2aas.com/v1/billing/analytics/trends?metric=message_volume&period=last_12_months" \
  -H "Authorization: Bearer pk_live_your_api_key"

Cost Optimization

Usage Optimization Recommendations

curl -X GET https://api.as2aas.com/v1/billing/optimization \
  -H "Authorization: Bearer pk_live_your_api_key"

Response:

{
  "current_plan": "Enterprise Base + Usage",
  "current_monthly_cost": 842.00,
  "recommendations": [
    {
      "type": "plan_change",
      "recommended_plan": "Enterprise Per-Partner",
      "estimated_savings": 180.00,
      "reasoning": "High message volume with consistent partner count"
    },
    {
      "type": "compression_optimization",
      "estimated_savings": 45.00,
      "reasoning": "Enable compression for partners with large message sizes"
    }
  ],
  "usage_patterns": {
    "peak_hours": ["09:00-11:00", "14:00-16:00"],
    "busiest_partners": ["prt_partner_001", "prt_partner_003"],
    "message_size_distribution": {
      "small": 45,
      "medium": 35,
      "large": 20
    }
  }
}

Enterprise Features

Budget Alerts

curl -X POST https://api.as2aas.com/v1/billing/alerts \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "budget_threshold",
    "threshold": 1000.00,
    "notification_email": "[email protected]",
    "webhook_url": "https://corp.com/billing-alerts"
  }'

Department Cost Allocation

curl -X GET "https://api.as2aas.com/v1/billing/allocation?group_by=department" \
  -H "Authorization: Bearer pk_live_your_api_key"

Response:

{
  "allocation_method": "partner_tagging",
  "departments": [
    {
      "department": "Procurement",
      "partners": ["prt_supplier_001", "prt_supplier_002"],
      "message_count": 8500,
      "cost": 425.00
    },
    {
      "department": "Sales",
      "partners": ["prt_customer_001", "prt_customer_002"],
      "message_count": 6920,
      "cost": 346.00
    }
  ]
}

Billing Integration

Webhook Events

The platform sends billing-related webhook notifications:

{
  "type": "billing.usage.threshold_reached",
  "data": {
    "threshold_type": "monthly_budget",
    "threshold_value": 1000.00,
    "current_usage": 1050.00,
    "period": "2024-01"
  }
}

Export for ERP Integration

curl -X GET "https://api.as2aas.com/v1/billing/export?format=csv&period=2024-01" \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -o billing_export_2024_01.csv

Payment Processing

Failed Payment Handling

{
  "type": "billing.payment_failed",
  "data": {
    "invoice_id": "in_123",
    "amount": 842.00,
    "failure_reason": "insufficient_funds",
    "retry_date": "2024-02-05T00:00:00Z"
  }
}

Payment Success Confirmation

{
  "type": "billing.payment_succeeded", 
  "data": {
    "invoice_id": "in_123",
    "amount_paid": 842.00,
    "payment_method": "card_ending_4242",
    "paid_at": "2024-02-01T08:30:00Z"
  }
}

Real-time Billing
Usage is tracked in real-time and reported to billing systems hourly. This ensures accurate billing without end-of-month surprises.

Cost Management

Usage Monitoring

Implement usage monitoring to control costs:

// Monitor daily usage
async function checkDailyUsage(apiKey) {
  const response = await fetch('https://api.as2aas.com/v1/billing/usage/current', {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  });
  
  const usage = await response.json();
  
  if (usage.usage_to_date.estimated_charges > DAILY_BUDGET_LIMIT) {
    await sendBudgetAlert(usage);
  }
  
  return usage;
}

Cost Allocation

def allocate_costs_by_department(usage_data):
    """Allocate AS2 costs to departments based on partner usage"""
    
    department_mapping = {
        'prt_supplier_001': 'Procurement',
        'prt_supplier_002': 'Procurement', 
        'prt_customer_001': 'Sales',
        'prt_customer_002': 'Sales'
    }
    
    allocation = {}
    
    for partner_usage in usage_data['partner_breakdown']:
        partner_id = partner_usage['partner_id']
        department = department_mapping.get(partner_id, 'Unallocated')
        
        if department not in allocation:
            allocation[department] = {
                'message_count': 0,
                'cost': 0.0
            }
        
        allocation[department]['message_count'] += partner_usage['message_count']
        allocation[department]['cost'] += partner_usage['message_count'] * 0.05
    
    return allocation

Enterprise Reporting

Monthly Reports

curl -X GET "https://api.as2aas.com/v1/billing/reports/monthly?year=2024&month=1" \
  -H "Authorization: Bearer pk_live_your_api_key"

Annual Summary

curl -X GET "https://api.as2aas.com/v1/billing/reports/annual?year=2024" \
  -H "Authorization: Bearer pk_live_your_api_key"

Custom Reports

curl -X POST https://api.as2aas.com/v1/billing/reports/custom \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "report_type": "partner_utilization",
    "date_range": {
      "start": "2024-01-01",
      "end": "2024-03-31"
    },
    "group_by": ["partner", "month"],
    "include_metrics": ["message_count", "success_rate", "cost"]
  }'

Budget Management

Set Budget Limits

curl -X POST https://api.as2aas.com/v1/billing/budgets \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly AS2 Budget",
    "amount": 2000.00,
    "period": "monthly",
    "alert_thresholds": [50, 75, 90],
    "hard_limit": true
  }'

Budget Alerts

{
  "type": "billing.budget_alert",
  "data": {
    "budget_name": "Monthly AS2 Budget",
    "threshold_percentage": 75,
    "current_usage": 1500.00,
    "budget_limit": 2000.00,
    "period_remaining_days": 8
  }
}

Enterprise Integration

ERP System Integration

class ERPBillingIntegration:
    def __init__(self, as2_api_key, erp_config):
        self.as2_client = AS2Client(as2_api_key)
        self.erp_config = erp_config
    
    def sync_monthly_billing(self, year, month):
        """Sync AS2 billing data with ERP system"""
        
        # Get AS2 usage data
        usage_data = self.as2_client.get_monthly_usage(year, month)
        
        # Transform for ERP format
        erp_entries = self.transform_usage_for_erp(usage_data)
        
        # Post to ERP system
        for entry in erp_entries:
            self.post_to_erp(entry)
    
    def transform_usage_for_erp(self, usage_data):
        """Transform AS2 usage data to ERP journal entries"""
        entries = []
        
        for partner_usage in usage_data['partner_breakdown']:
            entries.append({
                'account': '6100-AS2-MESSAGING',
                'department': self.get_partner_department(partner_usage['partner_id']),
                'amount': partner_usage['cost'],
                'description': f"AS2 messaging - {partner_usage['partner_name']}",
                'reference': f"AS2-{usage_data['period']['start'][:7]}"
            })
        
        return entries

Compliance and Auditing

Billing Audit Trail

curl -X GET "https://api.as2aas.com/v1/billing/audit?start_date=2024-01-01" \
  -H "Authorization: Bearer pk_live_your_api_key"

Tax Reporting

curl -X GET "https://api.as2aas.com/v1/billing/tax-summary?year=2024" \
  -H "Authorization: Bearer pk_live_your_api_key"

Response:

{
  "tax_year": 2024,
  "total_charges": 10104.00,
  "tax_breakdown": {
    "base_subscription": 3588.00,
    "usage_charges": 6516.00,
    "applicable_tax": 808.32,
    "tax_rate": 0.08
  },
  "quarterly_summary": [
    {
      "quarter": "Q1",
      "charges": 2526.00,
      "tax": 202.08
    }
  ]
}

Compliance Support
AS2aaS provides detailed billing records and audit trails to support financial compliance requirements and internal cost allocation processes.

Best Practices

Cost Control

Monitor usage patterns and trends regularly
Set up budget alerts for proactive cost management
Review partner utilization for optimization opportunities
Implement department-level cost allocation

Financial Planning

Use historical data for accurate budget forecasting
Consider annual plans for cost savings
Plan for seasonal usage variations
Factor in business growth when selecting plans

Integration

Integrate billing data with enterprise financial systems
Automate monthly reconciliation processes
Implement approval workflows for plan changes
Maintain audit trails for compliance requirements

Billing & Usage

Billing Models

Base Plus Usage

Per-Partner Pricing

Hybrid Billing

Enterprise Custom

Subscription Management

Retrieve Billing Information

Subscribe to Plan

Update Subscription

Usage Tracking

Retrieve Usage Data

Real-time Usage Metrics

Payment Methods

Add Payment Method

Set Default Payment Method

Invoicing and Billing

Retrieve Invoices

Download Invoice

Usage Analytics

Partner Usage Analysis

Message Volume Trends

Cost Optimization

Usage Optimization Recommendations

Enterprise Features

Budget Alerts

Department Cost Allocation

Billing Integration

Webhook Events

Export for ERP Integration

Payment Processing

Failed Payment Handling

Payment Success Confirmation

Cost Management

Usage Monitoring

Cost Allocation

Enterprise Reporting

Monthly Reports

Annual Summary

Custom Reports

Budget Management

Set Budget Limits

Budget Alerts

Enterprise Integration

ERP System Integration

Compliance and Auditing

Billing Audit Trail

Tax Reporting

Best Practices

Cost Control

Financial Planning

Integration