Skip to main content
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.
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. See Testing and sandbox.
Alguna is not the payment processor, so the test cards come from yours. Connect your processor’s test mode to sandbox, then use its published test numbers — with Stripe, Stripe’s test cards, including the numbers that force a decline or a 3-D Secure challenge.See Testing and sandbox for what to run through before going live.
POST /customers always creates — there is no upsert. Look up first with GET /customers/lookup?alias=<your ID>, create only on a 404, and send an Idempotency-Key on the create so a retry replays instead of duplicating.Set your own ID in aliases at creation time; that is what makes the lookup work next time. See Create or look up?
We handle migrations for you:
  1. Contact us via Slack or support@alguna.io
  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. Set when the change takes effect
  6. Review the prorated amount in the preview 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.
Not with effective: immediate — “immediate” means now, which is before the subscription begins.
  • Still a draft subscription: add the item to its draft version and publish.
  • Activated with a future start date: create a new version with effective_at set to the subscription’s start date and the complete item set. A published version already sits at that date, so you get a 409 naming it — delete that version, then retry.
  • From a later date instead: use POST /subscriptions/{id}/changes with that explicit date.
See Subscriptions that have not started yet.

​
Pricing & Packaging

A bundle is a group of priced products that travel together as one item. A plan is a complete sellable offer: products and the commercial terms around them — contract length, renewal, trial, discounts, entitlements, invoice behaviour.A plan can contain bundles, so they compose rather than compete. A bundle cannot be sold on its own; a plan can. See Bundles.
No. A subscription holds its own copy of the priced items from the moment it was created, so editing a bundle changes the template only. To change what an active customer pays, amend the subscription — see Amendments.

​
Emails

Yes. Custom sender addresses are configured per organization by our team rather than in the dashboard — email support@alguna.io with the address you want.Internal emails (team invitations, approval notifications) keep their Alguna addresses either way. See Custom Domains and Addresses.
Not for the default setup: Alguna sends from its own authenticated domain, so there is nothing to publish on your side.Sending from an address at your domain does require DNS records authorizing Alguna as a sender — but wait for the exact records from us as part of setting it up. Do not add records copied from another vendor’s guide, and note that a DMARC policy that rejects unauthenticated mail will silently drop your own invoices if the sending identity is not configured first. See Custom Domains and Addresses.The CNAME that serves hosted checkout and the portal from your own domain is separate and does not affect email.
Two places, in order:
  1. The customer’s contacts. A customer with no contact email receives nothing, and the invoice still progresses. See Customer contacts.
  2. Settings → Logs → Emails, which shows what was sent and to which address — that separates a missing contact from a deliverability problem.
Replies go to the billing support address on your business details, not to Alguna.
Both, under Settings → Organization → Customizations → Email Templates: subject, body and call-to-action per email type, plus per-type CC/BCC and the Global CC Recipients / Global BCC Recipients lists that apply to every customer-facing email. See Emails.

​
Invoicing & Payments

Invoices are generated based on your billing configuration:Configure in Settings → Invoicing or per-subscription.
  1. Navigate to Invoices
  2. Find the invoice — it will be Issued or Overdue, with the payment showing as 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, Diners, JCB, UnionPay, eftpos Australia
  • Bank transfer: including ACH for US bank accounts
  • Stripe Link: saved details through Stripe
  • Alguna wallet: pay down an invoice from a prepaid wallet balance
  • Offline payment: record a payment taken outside Alguna, such as a wire
Which of these are available depends on your payment provider. Configure them in Settings → Workflows → Payments → Payment methods.
Turn it off under Settings → Workflows → Payments → Payment methods. It is an organization-level setting — a checkout session has no field for restricting payment methods, so the same set applies to hosted and embedded checkout. Sessions already open keep what they were rendered with. See Embedded Checkout.
Because that is correct. There is no refunded invoice status: the invoice records what was billed and that it was settled at the time, and the reversal is recorded against the payment as a refund.Which record you create matters. A bare refund returns money without changing what was billed — right for a duplicate charge. A credit note applied with a refund reverses the charge itself and flows into revenue and tax — right for an overcharge or a cancelled service. Voiding is not available once an invoice is paid. See What happens to a paid invoice.
Yes. Every mutating endpoint — POST, PUT, PATCH, DELETE — accepts Idempotency-Key, credit notes included. The only exception is POST /events, which deduplicates on each event’s own unique_id. See Idempotency.

​
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 Webhooks for the full list of events.
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.
No. An account sync carries the company name, external ID, contacts, currency, billing address, website and a link back to the CRM record. The record’s owner is not among them, and Alguna has no owner or Account Executive field of its own — ownership stays a CRM concept. Follow the link back to the CRM record, where the current owner is always right. See What an account sync carries.
The session reaching successful with a subscription_id means the subscription exists, not that it is active. Read it with GET /subscriptions/{id} and check its own status — with approval flows configured it can land in pending_approval. Fulfilment is asynchronous, so poll the session or use the checkout.session.completed webhook rather than the browser redirect. See Hosted Checkout.

​
Credits & Wallets

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.