Skip to main content

​
Frequently Asked Questions

Answers to common questions organized by topic, with real-world scenarios and solutions.

​
Getting Started

  1. Log in to Alguna Dashboard
  2. Navigate to Settings → API Keys
  3. Click Create API Key
  4. Copy and securely store your key
API keys are only shown once. Store them securely in environment variables, never in code.
EnvironmentPurposePaymentsData
SandboxDevelopment & testingSimulated (no real charges)Separate from production
ProductionLive operationsReal paymentsProduction data
Switch between environments using the environment switcher in the top-right corner of the dashboard. Each environment has its own API keys.Sandbox uses completely separate data, so you can experiment freely without affecting production.
We handle migrations for you:
  1. Contact us via Slack or [email protected]
  2. Grant access to your existing billing system (read-only)
  3. We plan the migration based on your data and requirements
  4. We execute with stepped rollout to minimize risk
We support migrations from: Stripe Billing, Chargebee, Recurly, Zuora, and custom billing systems.

​
Subscriptions

Yes! Customers can have multiple active subscriptions. Common scenarios:
  • Different products: Main platform + add-on services
  • Different billing entities: Separate invoicing per department
  • Multiple contracts: Different terms for different services
Navigate to Customers → [Customer] → Subscriptions to view all subscriptions for a customer.
  1. Navigate to Subscriptions
  2. Open the subscription
  3. Click Change Plan or Edit
  4. Select the new plan
  5. Choose proration behavior:
    • Full proration - Calculate exact amounts for time used
    • No proration - Change takes effect, no financial adjustment
  6. Review the prorated amount and confirm
Example calculation (upgrade on day 15 of 30-day month):
  • Credit for unused time on old plan
  • Charge for new plan’s remaining time
  • Net amount billed immediately
See Proration for details.
  1. Navigate to Subscriptions
  2. Find and open the subscription
  3. Click Cancel Subscription
  4. Select Cancel at end of period
  5. Add cancellation reason (optional)
  6. Confirm
Customer Self-Service: Enable cancellation in Settings → Customer Portal → Allow subscription cancellation. Customers can then cancel through their billing portal.The subscription:
  • Remains active until period ends
  • Won’t renew
  • Changes to canceled at period end
  • Triggers subscription.canceled webhook at that time
  1. Navigate to Subscriptions
  2. Open the subscription
  3. Click Pause Subscription
  4. Set pause duration
  5. Confirm
To resume, open the paused subscription and click Resume.Great for seasonal businesses or customers taking a break.
Use subscription versioning to keep existing customers on their current pricing:
  1. Update the plan with new pricing for new customers
  2. Existing subscriptions keep their current version automatically
  3. On renewal, configure whether to update pricing in the subscription’s contract terms
Navigate to the subscription and edit contract terms to control renewal pricing behavior.

​
Invoicing & Payments

Invoices are generated based on your billing configuration:
TypeWhen Generated
Advance billingAt start of period
Arrears billingAt end of period
Usage-basedAt end of period (after usage calculated)
One-timeWhen you create them
Configure in Settings → Invoicing or per-subscription.
  1. Navigate to Invoices
  2. Find the failed invoice (status: Payment Failed)
  3. Click to open invoice details
  4. Click Retry Payment
Before retrying:
  • Send customer a billing portal link to update their payment method
  • Verify the payment amount
  • Check for available credits that could be applied
Automatic retries: Set up payment retry logic using Automations. Create an automation that triggers on payment failure and retries based on your preferred schedule.
  1. Navigate to Invoices
  2. Find and open the paid invoice
  3. Click Issue Refund or Create Credit Note
  4. Enter partial refund amount
  5. Add reason
  6. Choose: Refund to payment method OR Store as credit
  7. Confirm
Credits are applied automatically to invoices when generated.To manually apply credits:
  1. Navigate to Invoices
  2. Open the invoice
  3. Click Apply Credits
  4. Select amount to apply
  5. Confirm
  1. Navigate to Customers → [Customer]
  2. Edit customer details
  3. Set preferred currency
Multi-currency setup:
  1. Configure multi-currency pricing on plans/products
  2. Invoices generate in customer’s currency
  3. Settlement happens in your configured currencies
See Multi-Currency for details.
  • Cards: Visa, Mastercard, Amex, Discover
  • ACH/Bank Transfer: US bank accounts
  • SEPA: European bank accounts
  • Wire Transfer: Manual wire payments
  • Wallets: Apple Pay, Google Pay (via Stripe)
Configure in Settings → Payments → Payment Methods.

​
Usage-Based Billing

Best practice: Send events as they happen, or batch every few seconds.Events are processed in near real-time. Batching improves performance at scale. Work with your development team to set up event ingestion via the Events API.See Events API Reference for technical details.
Use idempotency keys when sending events. If you send the same idempotency key twice, only one event is recorded.Work with your development team to implement idempotency keys in your event ingestion. See the Events API Reference for details.
Yes! Send events with past timestamps. Events are associated with the correct billing period based on their timestamp.Use idempotency keys to prevent duplicates during backfills.
For Customers (Billing Portal): Enable usage display in Settings → Customer Portal → Show usage. Customers can view their usage directly in the billing portal.In Dashboard:
  1. Navigate to Customers
  2. Open the customer account
  3. View Usage tab for current period
  1. Navigate to Automations
  2. Create new automation
  3. Set trigger based on usage conditions
  4. Configure actions (email notification, webhook, etc.)

​
Webhooks & Integration

Essential (start with these):
  • subscription.activated - Grant access
  • subscription.canceled - Revoke access
  • invoice.paid - Confirm payment
  • payment.updated - Handle payment status changes
  • checkout.session.completed - Provision from checkout
Recommended:
  • invoice.issued - Custom receipts
  • subscription.cancelation_scheduled - Retention offers
  • account.credits.balance_depleted - Upsell opportunities
See Events Reference for full list.
Webhooks are delivered via Svix. Use the Svix SDK for verification in your application.See the Webhooks Setup Guide for configuration details.
Alguna retries with exponential backoff:
  • Immediate → 5 min → 30 min → 2 hr → 8 hr → 24 hr
After 6 failed attempts, the event is marked failed. You can:
  1. Fix your endpoint
  2. Manually retry from Settings → Webhooks → [Endpoint] → Failed Events
  3. Use the API to fetch missed events
  1. Go to Settings → Integrations
  2. Connect your CRM
  3. Configure field mappings
  4. Enable bi-directional sync
See Salesforce and HubSpot docs.

​
Credits & Wallets

FeatureCreditsWallets
PurposePromotional/compensationPrepaid balance
SourceGranted by youTopped up by customer
ExpirationUsually expiresTypically doesn’t
Use caseReferrals, service creditsPrepaid accounts
Use credits for promotions and wallets for prepaid billing.
  1. Navigate to Customers → [Customer] → Credits
  2. Click Grant Credits
  3. Enter the amount and type (monetary or units)
  4. Set expiration (optional)
  5. Add a reason for the grant
  6. Click Grant
See Credits Guide for more details.
Credits are automatically applied when invoices are generated:
  1. Invoice generated for $100
  2. Customer has $30 in credits
  3. Credits applied: $30
  4. Remaining due: $70
  5. $70 charged to payment method
Credits expiring soonest are used first.

​
Troubleshooting

  • Verify API key is correct
  • Check you’re using the right environment (sandbox vs production keys)
  • Ensure API key hasn’t been revoked
  • Check Authorization: Bearer <key> header format
  1. Verify endpoint URL in Settings → Webhooks
  2. Check endpoint is publicly accessible (not localhost)
  3. Ensure firewall allows requests from webhook IPs
  4. Check webhook logs in dashboard
  5. Verify your endpoint returns 200 status
Check these common causes:
  • Proration calculations (mid-cycle changes)
  • Tax configuration
  • Credit applications
  • Currency conversion
View invoice details in dashboard to see the full breakdown.
If your organization has approval flows configured, subscriptions may require approval before activation:
  1. Navigate to Approvals in the sidebar
  2. Find the pending subscription
  3. Review the details
  4. Click Approve or Reject
See Approval Flows for configuration.

​
Still Have Questions?

Contact Support

Our team is here to help with any questions.

API Reference

Detailed API documentation.