Subscription notice

The subscription notice event notification allows vendors to receive overdue or delinquent notices on an existing subscription, as well as receive a notice (SUBSCRIPTION_NOTICE) when the overdue invoice has been resolved. In order to support these subscription notices, Developers define a subscription notice notification URL on the product's Edit integration page.

❗ Important: We strongly recommend that you configure this integration endpoint to get notifications when a subscription is activated, deactivated, and closed.

The general flow for a subscription notice event notification is as follows:

1. A subscription's status changes, such as going overdue or delinquent.
2. AppDirect creates a SUBSCRIPTION_NOTICE event identified by an eventUrl.
3. AppDirect performs a GET operation on the URL defined as the Subscription Notice listener URL, passing the eventUrl identifying this event.
4. The vendor issues a request to read the SUBSCRIPTION_NOTICE event information using the token value. See Authorize inbound API requests for information on how to securely retrieve event details. The Subscription Notice Event contains:
   • type: The type of the event (SUBSCRIPTION_NOTICE in this case)
   • marketplace: Information about the AppDirect-powered marketplace on which the event took place.
   • payload: The event payload, containing the following elements:
     • notice: A type element whose value can be either DEACTIVATED, REACTIVATED, CLOSED or UPCOMING_INVOICE.
     • account: The account identifier provided by the application in the initial Subscription Order Event and its current status (FREE_TRIAL, SUSPENDED, etc.).
5. The vendor returns a result JSON or XML with the following:
   • success: Which should be "true" or "false."
   • errorCode: If "success" is false, this must return a valid error code.
   • message: An optional message containing information about the result of the operation.

For examples, see Subscription notice examples.

Notice types

Notice type	Description
DEACTIVATED	A DEACTIVATED notice means the account has been deactivated and is in a SUSPENDED or FREE_TRIAL_EXPIRED state. It is recommended that all access to the vendor's application be suspended (but not deleted). Account deactivation may occur if, for example, the account holder is overdue in making a payment or if abuse is detected.
REACTIVATED	A REACTIVATED notice means an account should be considered active (ACTIVE or FREE_TRIAL state) and receive its typical access. This status will usually indicate that the account holder has paid an overdue invoice.
CLOSED	A CLOSED notice means that the account is in a CANCELLED, and that it should be deleted by the vendor. In most cases, this event should trigger the same code on the vendor as the SUBSCRIPTION_CANCELLED event.
UPCOMING_INVOICE	An UPCOMING_INVOICE notice informs a vendor that there is an upcoming invoice that will be computed for this account, before it is generated. This notice is issued 21 hours prior to the start of the invoice run that will include the vendor's invoice. (If an invoice is queued and generated, for example, four hours after the invoice generation run starts, the upcoming invoice notice is issued 25 hours before invoice generation.) The intention of this notice is to give a vendor the opportunity to update the AppDirect-powered marketplace with any usage information via the Billing Usage API, which will be included on the upcoming invoice.

Error handling

Since the DEACTIVATED, REACTIVATED and CLOSED notices reflect state changes in the subscription lifecycle, it is important for vendors to process these events successfully. To mitigate temporary errors (downtimes, transport errors ,and so on), the AppDirect marketplace will attempt to redeliver the notice up to 10 times, following an exponential backoff algorithm: the first redelivery will be attempted 30 minutes after the last failure, then one hour after the last failure, then two hours, and so on to a minimum of once a day. The redelivery will happen in a one hour window following the indicated time (so the first redelivery can happen anytime from 30 minutes to 90 minutes after the initial failure).

If the marketplace does not receive a successful response from the vendor to a SUBSCRIPTION_NOTICE event, the behavior is as follows:

• For UPCOMING_INVOICE notices, the invoice is still sent out to the customer. The vendor will be notified again when the next invoice is about to be created.
• For DEACTIVATED, REACTIVATED and CLOSED notices, the marketplace will attempt to redeliver the notice up to 10 times according to an exponential backoff algorithm. The redelivery attempt will occur 30 minutes, one hour, two hours, and so on up to a day after the time of last failure to deliver.