> ## Documentation Index
> Fetch the complete documentation index at: https://alguna.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Frequently Asked Questions

> Common questions and real-world scenarios

# Frequently Asked Questions

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

***

## Getting Started

<AccordionGroup>
  <Accordion title="How do I get my API keys?">
    1. Log in to [Alguna Dashboard](https://app.alguna.io)
    2. Navigate to **Settings → API Keys**
    3. Click **Create API Key**
    4. Copy and securely store your key

    <Warning>
      API keys are only shown once. Store them securely in environment variables, never in code.
    </Warning>
  </Accordion>

  <Accordion title="What's the difference between sandbox and production?">
    | Environment    | Purpose               | Payments                    | Data                     |
    | -------------- | --------------------- | --------------------------- | ------------------------ |
    | **Sandbox**    | Development & testing | Simulated (no real charges) | Separate from production |
    | **Production** | Live operations       | Real payments               | Production 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.
  </Accordion>

  <Accordion title="How do I migrate from another billing system?">
    We handle migrations for you:

    1. **Contact us** via Slack or [support@alguna.io](mailto: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.
  </Accordion>
</AccordionGroup>

***

## Subscriptions

<AccordionGroup>
  <Accordion title="Can a customer have multiple 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.
  </Accordion>

  <Accordion title="How do I handle upgrades mid-billing cycle?">
    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](/subscriptions/proration) for details.
  </Accordion>

  <Accordion title="How do I cancel a subscription but let them use until period end?">
    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
  </Accordion>

  <Accordion title="How do I pause a subscription instead of canceling?">
    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.
  </Accordion>

  <Accordion title="How do I grandfather customers on old pricing?">
    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.
  </Accordion>
</AccordionGroup>

***

## Invoicing & Payments

<AccordionGroup>
  <Accordion title="When are invoices generated?">
    Invoices are generated based on your billing configuration:

    | Type                | When Generated                            |
    | ------------------- | ----------------------------------------- |
    | **Advance billing** | At start of period                        |
    | **Arrears billing** | At end of period                          |
    | **Usage-based**     | At end of period (after usage calculated) |
    | **One-time**        | When you create them                      |

    Configure in **Settings → Invoicing** or per-subscription.
  </Accordion>

  <Accordion title="How do I retry a failed payment?">
    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.
  </Accordion>

  <Accordion title="How do I issue a partial refund?">
    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
  </Accordion>

  <Accordion title="How do I apply credits to an invoice?">
    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
  </Accordion>

  <Accordion title="How do I handle international payments and currencies?">
    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](/currencies/multi-currency) for details.
  </Accordion>

  <Accordion title="What payment methods are supported?">
    * **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**.
  </Accordion>
</AccordionGroup>

***

## Usage-Based Billing

<AccordionGroup>
  <Accordion title="How often should usage events be sent?">
    **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](/api-reference/events/ingest) for technical details.
  </Accordion>

  <Accordion title="How do I prevent duplicate usage events?">
    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](/api-reference/events/ingest) for details.
  </Accordion>

  <Accordion title="Can I backfill historical usage data?">
    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.
  </Accordion>

  <Accordion title="How do I show customers their current usage?">
    **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
  </Accordion>

  <Accordion title="How do I set up usage alerts/thresholds?">
    1. Navigate to **Automations**
    2. Create new automation
    3. Set trigger based on usage conditions
    4. Configure actions (email notification, webhook, etc.)
  </Accordion>
</AccordionGroup>

***

## Webhooks & Integration

<AccordionGroup>
  <Accordion title="Which webhooks should I listen to?">
    **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](/api-reference/events-reference) for full list.
  </Accordion>

  <Accordion title="How do I verify webhook signatures?">
    Webhooks are delivered via Svix. Use the Svix SDK for verification in your application.

    See the [Webhooks Setup Guide](/guides/webhooks-quickstart) for configuration details.
  </Accordion>

  <Accordion title="What if my webhook endpoint is down?">
    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
  </Accordion>

  <Accordion title="How do I sync with my CRM (Salesforce/HubSpot)?">
    1. Go to **Settings → Integrations**
    2. Connect your CRM
    3. Configure field mappings
    4. Enable bi-directional sync

    See [Salesforce](/integrations/crm/salesforce) and [HubSpot](/integrations/crm/hubspot) docs.
  </Accordion>
</AccordionGroup>

***

## Credits & Wallets

<AccordionGroup>
  <Accordion title="What's the difference between credits and wallets?">
    | Feature        | Credits                    | Wallets               |
    | -------------- | -------------------------- | --------------------- |
    | **Purpose**    | Promotional/compensation   | Prepaid balance       |
    | **Source**     | Granted by you             | Topped up by customer |
    | **Expiration** | Usually expires            | Typically doesn't     |
    | **Use case**   | Referrals, service credits | Prepaid accounts      |

    Use **credits** for promotions and **wallets** for prepaid billing.
  </Accordion>

  <Accordion title="How do I grant credits to a customer?">
    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](/guides/credits-quickstart) for more details.
  </Accordion>

  <Accordion title="How do credits apply to invoices?">
    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.
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="API returns 401 Unauthorized">
    * 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
  </Accordion>

  <Accordion title="Webhooks not being received">
    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
  </Accordion>

  <Accordion title="Invoice shows wrong amount">
    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.
  </Accordion>

  <Accordion title="Subscription requires approval">
    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](/approvals/overview) for configuration.
  </Accordion>
</AccordionGroup>

***

## Still Have Questions?

<CardGroup cols={2}>
  <Card title="Contact Support" icon="headset" href="mailto:support@alguna.io">
    Our team is here to help with any questions.
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/overview">
    Detailed API documentation.
  </Card>
</CardGroup>