Include a past due status on user-facing subscription page

or finding a way to do this using their SDK.

I haven't been able to find a way to do this via the SDK. Oddly when getting a list of subscriptions like this:

  $subscription_list = Recurly_SubscriptionList::getForAccount($account->account_code, array('per_page' => $per_page));

All the subscriptions all just have state == 'active', no mention of the fact that they're past due at all. Seems like a pretty big oversight on the part of the API. :(

Any public discussions that you've seen about this topic?

Ohhh, I get it now. In their API page on subscription the "past_due" state is only a *query* option, it's not actually in the returned $subscription object at all. http://docs.recurly.com/api/subscriptions

The subscription object will always be in only one of the following: "active", "canceled", "future", "expired", "modified". However you may query for specifically "past_due" subscriptions if desired, though these subscriptions will still have state "active" when you examine the subscription object.

So one way we could handle this is by querying for "past_due" subscriptions or optionally for a "past_due" account, since there's only one billing address per account they're really equivalent for the most part.

Finally we could also query for past_due invoices, which may be the most helpful indicator since we could actually link to the invoices that are currently unpaid. Invoices (unlike accounts or subscriptions) actually reflect the "past_due" state in the invoice object.

Even though it's not documented that you can pass "state" into the list of parameters, both of these queries work:

  // Get past due subscriptions.
  $subscriptions = Recurly_SubscriptionList::getForAccount('1', array('state' => 'past_due'));

  // Get past due invoices.
  $invoices = Recurly_InvoiceList::getForAccount('1', array('state' => 'past_due'));

Likewise the PHP SDK also includes a method for getPastDue invoices, which also can take an account code, so this is equivalent to the second query above, though it makes more sense to me personally (though internally it's doing the exact same GET query):

  // Get past due invoices.
  $invoices = Recurly_InvoiceList::getPastDue(array('account_code' => '1'));

So looks like we've got lots of options for discovering closed/trial/past_due subscriptions, though it will require separate requests.

The separate requests are a bit of a drag, I wonder if we could suggest to them, like I was mentioning, when querying an account or subscription that is actually past_due (but returning as active), to include some additional/helpful information.

Yes I think we should definitely pursue asking Recurly to improve the API in this regard. In the mean time, we might make a wrapper function (similar to recurly_get_subscriptions()) that retrieves all the states of all subscriptions for a Recurly account. I think that would come down to the following requests:

  $past_due = Recurly_SubscriptionList::getForAccount('1', array('state' => 'past_due'));
  $in_trial = Recurly_SubscriptionList::getForAccount('1', array('state' => 'in_trial'));
  $canceled = Recurly_SubscriptionList::getForAccount('1', array('state' => 'canceled'));
  // Getting live subscriptions seems like a waste. We already know if it's "active".
  $live = Recurly_SubscriptionList::getForAccount('1', array('state' => 'live'));

We can then compare the returned lists against the full list of accounts to determine the states of all of them. A few remaining states are already given to us directly in the normal subscription object. These are: "active", "expired", and "future". The SDK also includes a "non_renewing" state that is not mentioned in the API, it seems as though it's the same as "canceled" for auto-renewing subscriptions, but perhaps it's also set for any subscription that is a fixed time period. It doesn't seem like something worthwhile to retrieve IMO, since I think sites are likely to either use all auto-renewing or fixed-length plans, rather than a mix of both.

So this means that when we show the main subscriptions listing page, we can get all the information we need with 3 additional API requests. We're currently only doing 2 (one for the account and one for the subscription list), so this is a bit of unfortunate overhead just to get subscription states.

Actually if the "expires_at" property exists as advertised (I mentioned it in #1632284-3: How to handle subscription total_billing_cycles and first_renewal_date subscription params), we don't need to check for canceled or non_renewing. Actually continuing that thought process, you can use "trial_starts_at" and "trial_ends_at" to determine if the user is in a trial state. So in fact it seems that the *only* state you can't get derive directly from the subscription object is "past_due".

In the PHP SDK, "expires_at" does not seems to exist. :(

However we have other information (again not mentioned in the API) for total and remaining billing cycles:

        'activated_at' => 
        DateTime::__set_state(array(
           'date' => '2012-06-13 23:15:49',
           'timezone_type' => 2,
           'timezone' => 'Z',
        )),
        'total_billing_cycles' => 12,
        'remaining_billing_cycles' => 12,
        'current_period_started_at' => 
        DateTime::__set_state(array(
           'date' => '2012-06-13 23:15:49',
           'timezone_type' => 2,
           'timezone' => 'Z',
        )),
        'current_period_ends_at' => 
        DateTime::__set_state(array(
           'date' => '2012-06-16 23:15:49',
           'timezone_type' => 2,
           'timezone' => 'Z',
        )),
        'trial_started_at' => 
        DateTime::__set_state(array(
           'date' => '2012-06-13 23:15:49',
           'timezone_type' => 2,
           'timezone' => 'Z',
        )),
        'trial_ends_at' => 
        DateTime::__set_state(array(
           'date' => '2012-06-16 23:15:49',
           'timezone_type' => 2,
           'timezone' => 'Z',
        )),

So I would think that "remaining_billing_cycles" would be exactly what you would be interested in as far as warning users whose subscription is nearing its end (when remaining_billing_cycles is 0, you should start the pestering).

This patch gets the basics handled for this problem. It adds a class to each invoice row in the invoice list and it shows a message on each subscription to reflect subscriptions that are past due or in a trial. Bunch of minor fixes included also.

for a subscription which is not in a trial. I seem to recall that these properties may linger, but I could be wrong!

Yes that's true, they stick around. I calculated if the subscription is in-trial by comparing the current date against the start and end dates of the trial, so when the trial ends the status properly reflects that.