Subscriptions

In DEUNA, Subscriptions are a relationship between a customer and a product or service plan.

The Subscriptions API manages user subscriptions to plans offered by your system.

Use this API to control subscription and plan states. Ensures that the billing, activation, cancellation, and expiration process is performed correctly.

The Subscriptions API includes an intelligent retry mechanism to handle temporary failures in communication with payment processors.

Subscriptions are structured as follows:

Subscription States

The subscription states are:

• pending: The subscription has been created in our system, but the charge has not yet been made. This state is maintained until the system confirms that the charge has been made or fails.
• active: The subscription is active when the payment process has been completed successfully, confirming the validity of the subscription. This state is reached when the system receives a successful response and the subscription has been validated.
• canceled: The subscription has been canceled, either by the customer or by the merchant. This state is the result of an explicit action by the customer or the system to terminate the subscription before its expiration.
• expired: The subscription has ended, either because it has reached its expiration date or has been manually terminated by the customer or merchant. This state is activated when the subscription reaches its expiration date or is canceled by either party.

Plan States

The plan states are:

• active: The plan is active and available for new subscriptions.
• Pending: The plan has been attempted to be created but due to an internal system failure, it is not completed.

Managing Subscriptions

Manage your subscriptions through the Subscriptions API.

Use this API to control subscription and plan states. Ensures that the billing, activation, cancellation, and expiration process is performed correctly.

Create a Subscription

Use the Create a subscription endpoint to create a subscription.

📘

If you receive a timeout error when creating a subscription, retrieve the suscription_ID from the response details.

Cancel a Subscription

Changes the status to canceled and can specify:

• Cancellation at the end of the current billing cycle.
• Cancellation at the end of the renewal cycle.
  • A monthly subscription renewed for 1 year is canceled upon completing that time.
• term_end indicates the end of the current cycle and generates a refund.
• bill_date indicates the start of the next cycle (24 hours difference with term_end) and generates a refund.

Terminate a Subscription

Immediately changes the status to expired. This allows:

• Performing refunds (total or partial).
• Not performing refunds, charging only for the time the subscription was active.

📘

Use the Get subscription list endpoint to receive a list of all subscriptions for a user.

📘

The subscription_end_date parameter represents the date on which the charge is made for a subscription.

Overdue Invoices

If after 24 hours the charge is not made:

• The invoice goes to past_due status.
• We will notify the merchant about the failures and status change.

Card Update

If the customer updates their card, you can:

• Call Update subscription to update the subscription.
• Retry the charge for the overdue invoice.

Retries

The intelligent retry mechanism is designed to handle temporary failures during subscription creation or validation.

This mechanism ensures that payment and activation processes are completed without requiring manual intervention, even in case of intermittent failures.

Key Features:

• Automatic retry: If subscription charging or activation fails, the system attempts to perform the process again after a brief delay.
• Failure control: The system establishes a maximum number of attempts to avoid infinite retry loops and ensures the system is not overloaded.

Intelligent Retry Sequence

1. Initial Failure: In case of a temporary error, such as a problem with the payment service, the system automatically retries at a predetermined interval.

2. Retries: Each retry progressively increases the wait time between attempts, based on an "exponential backoff" policy to avoid overloading the system.

3. Retry Limit: If the number of retries reaches a configurable maximum (for example, 6 attempts), the system will mark the subscription as failed and notify the user or administrator.

4. Notification: After several failed attempts, the system can send notifications to the customer or administrator, informing about the subscription status and failures that occurred.

Escalated Retries