​
Life cycles

Unibee supports changing existing subscriptions without having to cancel and recreate them. Some of the most significant changes you might make are:

  • Changing to a plan with a different base cost
  • Changing the quantity
  • Append or remove to different addon or it’s quantity
  • Canceling an active subscription
  • By Default, use the pending updates feature with these changes so that the updates are only applied if the new invoice is successfully paid.
  • Adding a trial period to an active subscription

Proration ensures that customers are billed accurately, but a proration can result in different payment amounts than you expect, which may be confusing. Also keep in mind that prorations are never automatically refunded to a customer nor immediately billed, although you can do both manually. When applying changes to existing subscriptions, discounts don’t affect the resulting proration line items.

UniBee has multi apis for subscription creation and update

  • You can preview a invoice of subscription create to view the amount before create it by Create Preview Api, And submit it by Create Api
  • You can preview a proration of subscription change to view the amount before applying the changes by Update Preview Api, And submit by Update Api Submit

This is common subscription flow looks like:

  1. You create the subscription. The status of the subscription is create .
  • UniBee sends a subscription.created event webhook event.
  1. An invoice is created for the subscription. The status of the invoice is process.
  2. The customer pays the first invoice.
  3. If the payment succeeds:
  • The subscription status changed to active
  • The invoice status is set to paid
  • UniBee sends an subscription.updated event webhook event.
  1. You provision access to your product. You can confirm whether the invoice has been paid by:
  • Setting up a webhook endpoint and listening for the subscription.updated event.
  • Manually checking the subscription object and looking for subscription.status=active. The status becomes active when the invoice has been paid either through an automatic charge or having the customer pay manually.

The status can also become trialing if you offer trials that don’t require payments. When the trial is over, the subscription moves to active and the subscribed customer starts to be charged.

​
Status

  • The Pending status indicates the initial state of a subscription when it is created before its payment is successful or if it does not require payment. This status does not grant access to plan features until it changes to Active or Incomplete.

    • Next Step 1: If the customer successfully pays the latest_invoice, the status will change to Active.
    • Next Step 2: An admin can temporarily mark the subscription as valid on the admin portal, changing the status to Incomplete.
    • Next Step 3: An admin can mark the latest_invoice as paid (only applicable for wire transfers), which will change the status to Active.
    • Next Step 4: An admin can cancel the subscription immediately, changing the status to Cancelled.
    • Next Step 5: If the latest_invoice payment is not successful within 2 days, the status will change to Expired.

  • An Active subscription is in good standing, with the invoice for the current billing cycle paid. It is safe to provision your product for the customer.

    • Next Step 1: The status will change to Incomplete at the end of the current period if the next billing cycle invoice is not paid. An Incomplete subscription is also safe for provisioning your product to the customer.
    • Next Step 2: The status will automatically change to Cancelled at the end of the current period if CancelAtPeriodEnd is set to true.
    • Next Step 3: An admin can cancel the subscription immediately, changing the status to Cancelled.

  • The Cancelled status is always caused by the customer or admin.

    • Next Action : Call the renew subscription action or API to start the renewal process. The status will change to Active if the latest_invoice payment is successful.

  • The Expired status means the automatic payment has failed and the subscription is out of time.

    • Next Action: Call the renew subscription action or API to start the renewal process. The status will change to Active if the latest_invoice payment is successful.

  • An Incomplete subscription means the latest_invoice needs to be paid within a certain timeframe (default is 24 hours) to activate the subscription. Alternatively, the payment may require customer action, such as authentication.

    • Next Step 1: The status will change to Expired if the latest_invoice is not paid within the specified timeframe.
    • Next Step 2 : The status will change to Active if the latest_invoice is paid on time.

  • Processing is available for wire transfers. The subscription status changes from Pending to Processing after the customer clicks “I Finished Payment.” Admins can filter Processing subscriptions to verify if the wire transfer payment was successful. If verified offline, the admin can mark the invoice as paid.

    • Next Step 1: An admin can temporarily mark the subscription as valid on the admin portal, changing the status to Incomplete.
    • Next Step 2: An admin can mark the latest_invoice as paid, changing the status to Active (only applicable for wire transfers).
    • Next Step 3: An admin can cancel the subscription immediately, changing the status to Cancelled.
    • Next Step 4: The status will change to Expired after 2 days if the latest_invoice payment is not successful.

  • Subscription will turn to Failed if its first payment expired or failed.

​
Status flow

​
Wire transfer status flow