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

# Subscriptions

<AccordionGroup>
  <Accordion title="What is a subscription contract in Subotiz and what information does it contain?">
    A subscription contract in Subotiz is the core record that tracks the relationship between a customer and a pricing plan. It is automatically created when a customer subscribes. Each contract contains:

    * Subscription ID
    * pricing name
    * customer information (such as email)
    * subscription start time
    * contract status (such as Active, Trial, Canceled, or Incomplete)
    * billing cycle (Weekly, Monthly, Quarterly, or Yearly)
    * pricing type (Flat pricing, Package pricing, or Based on usage)

    The contract also consolidates all related billing cycles, subscription changes, and refund records in one place. A subscription contract is generated for every subscription pricing plan type — recurring, trial-based, fixed-term, and usage-based.
  </Accordion>

  <Accordion title="What are all the subscription statuses in Subotiz and what does each one mean?">
    Subotiz subscription contracts have seven statuses:

    * **Trial** — the subscription is in a trial phase and has not yet entered regular billing — may be a free or paid trial.
    * **Active** — the subscription is running and generating invoices according to the configured billing rules.
    * **Incomplete** — the customer started checkout but did not complete payment or confirmation, so the contract has not entered an active state.
    * **Past due** — a billing invoice has passed its due date and remains unpaid, requiring follow-up.
    * **Unpaid** — a billing cycle has generated an invoice that has not yet been paid.
    * **Paused** — the subscription has been temporarily stopped and no new invoices will be generated until it is resumed.
    * **Canceled** — the subscription has been terminated and no further billing will occur.
  </Accordion>

  <Accordion title="A customer says they were charged the wrong amount — how do I find their subscription and verify the billing?">
    To investigate an unexpected charge:

    1. Go to Subscriptions > Subscriptions in the Subotiz admin.
    2. Use the search bar and select customer email or invoice ID as the search field to locate the subscription quickly.
    3. Once you open the subscription detail page, review the billing history section which shows each billing cycle's trade order ID, invoice ID, amount, and payment time.
    4. For subscriptions with trial periods or tiered pricing, check the Price column carefully as it displays trial information and staged pricing such as cycle 1–3 at one price and cycle 4 onward at another.
    5. You can click the invoice ID or trade order ID directly to navigate to the related records for a full view.
  </Accordion>

  <Accordion title="Can I upgrade or downgrade a customer's subscription without canceling it?">
    Yes. Subotiz supports subscription changes — upgrades, downgrades, or switches to a different pricing plan — without canceling the existing subscription. The Change subscription option is available in the Actions menu on the subscription detail page. You can:

    * select a new product and pricing plan
    * choose when the change takes effect (immediately or at the end of the current billing cycle)
    * configure proration settings if applicable

    The system automatically updates the subscription contract, records the change time and operator, and generates any required invoices or refund records. Subscription changes are supported for Flat price, Package price, and Based on usage pricing models.
  </Accordion>

  <Accordion title="What is the difference between 'Immediate effect' and 'End of current period' when changing a subscription?">
    When changing a subscription, two timing options are available:

    * **Immediate effect** — applies the new pricing plan right away. Depending on the subscription status, pricing type, and proration settings, the system may charge the new plan price, refund the unused value of the current plan, do both, or apply the change with no billing adjustment. The exact result is shown in the confirmation dialog before you submit.
    * **End of current period** — keeps the existing pricing plan running for the remainder of the current billing cycle. The new pricing plan takes effect at the start of the next cycle with no mid-cycle billing adjustments in most cases. For Package price plans using customer-initiated payment, the new pricing applies the next time the customer initiates payment.
  </Accordion>

  <Accordion title="If I change a subscription while the customer is still in a trial period, what happens to billing?">
    If the subscription is in a trial period when the change is submitted, the billing behavior depends on whether it is a paid or free trial:

    * **For a paid trial** — the system may refund the remaining trial amount and recalculate charges based on the new pricing plan.
    * **For a free trial** — the system may either charge the new plan price immediately or start a new trial period under the new pricing plan.

    The exact billing behavior for the specific scenario is displayed in the confirmation dialog before the change is submitted, so you can review the outcome before confirming.
  </Accordion>

  <Accordion title="What refund options are available when canceling a subscription?">
    When canceling a subscription, three refund options may be available depending on the subscription status and billing stage:

    * No refund
    * Refund the full amount of the latest invoice
    * Prorated refund for unused days from the latest invoice

    For the prorated option, the system calculates the refund automatically using the formula: (Amount paid for the current cycle divided by total days in the billing cycle) multiplied by remaining unused days. For example, a \$31 monthly plan covering July 1–31 canceled on July 10 would result in a \$21 refund (21 unused days remaining). The available refund options may vary depending on the subscription stage, and refund processing may be affected by payment provider rules and settlement cycles.
  </Accordion>

  <Accordion title="Does canceling a subscription delete the billing history and invoice records?">
    No. Canceling a subscription does not delete any historical records. After cancellation, the system stops generating future renewal invoices but preserves the complete subscription history including all billing records, invoices, trade orders, and refund records. Historical invoices that were generated but unpaid before cancellation will continue to follow the configured payment retry or dunning strategy. The subscription contract status updates to Canceled, and all cancellation details are recorded including the scheduled cancellation time, request time, actual cancellation time, canceled by, and cancellation reason.
  </Accordion>

  <Accordion title="If I issue a refund on a subscription invoice, will the subscription automatically pause or cancel?">
    No. In Subotiz, issuing a refund does not automatically pause or cancel a subscription. The subscription remains active and continues running according to its configured billing cycle even after a refund is processed. This is by design for scenarios where merchants want to compensate customers or adjust billing while allowing the subscription to continue. Each refund is linked to the corresponding invoice and subscription contract so you can review complete records in the admin. Both full and partial refunds are supported.
  </Accordion>

  <Accordion title="A subscription renewal payment failed — will the system retry automatically, and how many times?">
    Yes. When a recurring subscription payment fails, Subotiz automatically activates the Smart Retry mechanism. In most cases, the system attempts up to 4 retry attempts after the initial failure. The retry schedule is dynamically adjusted based on several factors:

    * the failure reason
    * the customer's time zone
    * business day adjustments
    * pay cycle optimization in some regions

    If any retry succeeds, the subscription continues running under its original billing cycle. No additional configuration is required — automatic retry is enabled by default for all recurring subscriptions. Merchants can also configure custom retry strategies for specific pricing plans.
  </Accordion>

  <Accordion title="What is the difference between a soft decline and a hard decline in subscription payment retry?">
    When a subscription payment fails, the system classifies the failure type and applies different retry strategies:

    * **Soft declines** — typically temporary issues such as network interruptions, temporary bank system unavailability, or insufficient account balance. For soft declines, the system continues retrying according to the Smart Retry strategy with multiple attempts.
    * **Hard declines** — definitive rejection reasons such as an expired payment card, a closed bank account, or explicit rejection by the issuing bank. For hard declines, the system usually performs only one additional retry attempt.

    If a later retry returns a different error type, the system re-evaluates the retry strategy based on the new failure reason.
  </Accordion>

  <Accordion title="How do I temporarily stop a subscription without canceling it?">
    Subscriptions can be temporarily paused using the Pause subscription option in the Actions menu on the subscription detail page. Once paused, the subscription stops generating new invoices until it is resumed. The subscription status changes to Paused. To restart it, use the Resume subscription option in the same Actions menu to restore the subscription to its normal billing flow. Pausing a subscription is useful when a customer needs a break from the service without ending the subscription permanently.
  </Accordion>

  <Accordion title="A customer wants to update their payment method for a subscription — how do I help them do that?">
    You can generate a payment method update link directly from the subscription detail page. In the Actions menu, select Share payment update link. A popup window appears where you can copy the link and send it to the customer, or send it directly via email from the same window. The customer uses the link to update the payment method associated with their subscription. If the link should no longer be used, it can be disabled from the same popup. This feature is available for active subscriptions.
  </Accordion>

  <Accordion title="When changing a subscription with immediate effect, what is the difference between 'Charge proration amount immediately' and 'Do not charge proration amount'?">
    When changing a subscription with immediate effect, two proration options are available:

    * **Charge proration amount immediately** — the system calculates the price difference based on the remaining time in the current billing cycle and automatically generates an invoice if additional payment is required, or a refund record if the customer should receive money back.
    * **Do not charge proration amount** — the new pricing plan takes effect immediately but no proration calculation is performed. Depending on the subscription state, the system may apply the new plan without any billing changes, or charge the full amount of the new plan directly without adjusting for the current cycle.

    The exact billing result for either option is shown in the confirmation dialog before you submit the change.
  </Accordion>

  <Accordion title="What is the difference between canceling a subscription immediately versus at the end of the current period?">
    When canceling a subscription, two timing options are available:

    * **Cancel immediately** — the subscription contract ends right away and the system stops generating new invoices from that point. This option is typically used by administrators in the admin panel.
    * **At the end of the current period** — the subscription remains active and the customer continues to have access until the current billing cycle ends. No additional renewal invoices will be generated after the cycle ends. This option is commonly used when a customer cancels but wants to continue using the service until their paid period expires.

    The cancellation option is only available when the subscription is still within its active lifecycle — if it has already been canceled or the contract has ended, the option will not appear.
  </Accordion>

  <Accordion title="If all Smart Retry attempts fail, what happens to the subscription?">
    If all automatic retry attempts fail, the system proceeds according to the subscription and billing configuration. Possible outcomes include:

    * waiting for the customer to update their payment method
    * entering the dunning or payment recovery process
    * terminating the subscription according to the subscription rules

    The exact behavior depends on the subscription configuration and system policies — there is no single fixed outcome. Merchants can configure custom retry strategies and dunning rules for specific pricing plans to control what happens after repeated failures. For subscriptions without custom settings, the system follows its default retry and dunning rules.
  </Accordion>

  <Accordion title="What is a fixed-term subscription and how is it different from a recurring subscription?">
    Subotiz supports two subscription models:

    * **Recurring subscriptions** — the default auto-renewal model; billing continues according to the configured billing cycle until the subscription is canceled by the merchant or the customer, with no predefined end date.
    * **Fixed-term subscriptions** — designed for subscriptions with a defined service duration. The system calculates the subscription term based on the configured number of billing periods and automatically stops renewal after the final billing cycle, without requiring manual cancellation. Fixed-term subscriptions may also support conversion to a recurring subscription when configured.

    Fixed-term settings are configured at the subscription contract level, not the product or pricing plan level — meaning different customers purchasing the same pricing plan may have different fixed-term configurations.
  </Accordion>

  <Accordion title="Does a fixed-term subscription end automatically, or do I need to manually cancel it?">
    Fixed-term subscriptions end automatically when the configured number of billing periods is completed. No manual cancellation is required. The system stops generating renewal invoices after the final billing period ends and the contract status updates accordingly. This is different from recurring subscriptions, which continue indefinitely until actively canceled. If a fixed-term subscription is manually canceled before the term is completed, cancellation rules take priority over fixed-term expiration logic. Cancellation at end of period and automatic fixed-term expiration are independent mechanisms.
  </Accordion>

  <Accordion title="How do I set or adjust a fixed term for a subscription contract?">
    Fixed-term settings are managed at the subscription contract level, not the pricing plan level. To set or adjust, open the subscription details page and click More actions > Edit fixed term, or use the edit shortcut beside the fixed-term field. In the dialog you can:

    * enable or disable the fixed term
    * set the number of billing periods (must exceed completed periods)
    * configure Convert to Ongoing Subscription

    When Convert to Ongoing Subscription is enabled, the system sends the Fixed term ending email 3 days before the fixed term expires. The email includes a one-click Convert to Ongoing Subscription button, allowing customers to convert without creating a new subscription. Important: Convert to Ongoing Subscription requires the Fixed term ending transactional email to be enabled at Emails > Transactional emails. If that email is disabled, customers will not receive the conversion button even if the option is enabled on the subscription. After submission, the system updates the contract and recalculates the expiration timeline. The existing product, pricing plan, and billing cycle are not affected.
  </Accordion>

  <Accordion title="Does a trial period count toward the billing periods of a fixed-term subscription?">
    No. For fixed-term subscriptions, trial periods do not count toward the fixed-term billing periods. The fixed-term calculation begins only after the trial ends and regular billing starts. For example, if a fixed-term subscription is configured for 12 billing periods and includes a 7-day free trial, the 12-period countdown starts from the first paid billing cycle, not from the trial start date.
  </Accordion>

  <Accordion title="Can I modify or upgrade a fixed-term subscription, and will it affect the fixed term?">
    Yes. Fixed-term subscriptions support subscription changes including upgrades, downgrades, and switching to a different pricing plan. After the change, the system updates the contract based on the new pricing plan and processes billing adjustments according to the selected effective timing. The existing fixed-term configuration is preserved after the change. If the fixed term also needs to be adjusted, use the Edit fixed term feature separately — subscription changes do not automatically modify fixed-term settings.
  </Accordion>

  <Accordion title="If I enable Convert to Ongoing Subscription on a fixed-term contract, will customers automatically receive a conversion option?">
    Not automatically — two conditions must both be met:

    1. Convert to Ongoing Subscription must be enabled on the subscription contract (via More actions > Edit fixed term).
    2. The Fixed term ending transactional email must be enabled at Emails > Transactional emails.

    When both are active, the system sends the Fixed term ending reminder email 3 days before the fixed term expires. That email includes a one-click Convert to Ongoing Subscription button. If the Fixed term ending email is disabled, customers will not receive the reminder or the conversion button, even if Convert to Ongoing Subscription is enabled on the contract. In that case, customers cannot convert via email.
  </Accordion>
</AccordionGroup>