Home → Dev Review →

Improve Documentation for prorations

• Edit

Brandon Elliott

Jul 25, 2013 @ 08:59 PM

After six long months of coding our integration, we just suffered a major setback.

We have learned that there is no workaround for free->paid charge behavior and that the best we can do is go back to the drawing board to issue credits before we upgrade subscriptions.

Had this been explained in the documentation, it would have saved the last three(3) months of unnecessary coding and hundreds of tests to try to issue credits to one-time invoices and get it working that way --only to find out that it's impossible. You simply charge the full subscription price, no matter what, and there is no way to credit that subscription.

So end of rant there. I am thoroughly frustrated at this point.

1. 1 Posted by Brandon Elliott on Jul 25, 2013 @ 10:04 PM

   

   It should be optional to charge the plan subscription on free->paid. There is no reason to force it to charge only on free->paid and not paid->paid.

   • Edit

2. Support Staff 2 Posted by Marc Guyer on Jul 26, 2013 @ 11:52 AM

   

   It appears that what you're attempting is not what we discussed. Our suggestion on the call was this:

   1. Issue one-time invoice for plan change according to your prorating style.
      
      • invoices/new
      • POST data: charges according to the prorated amount due
      • https://cheddargetter.com/developers#one-time-invoice
   2. Upon successful one-time invoice transaction, issue simple plan change
      
      • customers/edit-subscription
      • POST data: planCode=your_plan_code&changeBillDate=your_reset_date
      • Next invoice will be set to your reset date.
      • https://cheddargetter.com/developers#update-subscription

   This process enables you to have full control of your prorate method and also enables you to maintain the billing period according to your reset date. It's my understanding that these are your requirements.

   hundreds of tests to try to issue credits to one-time invoices and get it working that way --only to find out that it's impossible.

   I'm confused here. What's impossible? While it's certainly possible to add credits to one-time invoices, I think it's cleaner to just add the prorated charge amount for each line item. In the less likely event of a downgrade where the prorate would result in a total credit, you can add the resulting credit amount (or individual line item credits) to the subscription invoice after plan change instead of running the one-time invoice.

   You simply charge the full subscription price, no matter what, and there is no way to credit that subscription.

   Do you mean on plan change? Are you using the changeBillDate param?

   It should be optional to charge the plan subscription on free->paid. There is no reason to force it to charge only on free->paid and not paid->paid.

   Using the changeBillDate param on plan change effectively overrides the default behavior, forcing the next transaction to occur on that date instead of at the time of plan change.

   • Edit

3. 3 Posted by Brandon Elliott on Jul 27, 2013 @ 03:43 AM

   

   This morning, I reverted to our prior code and simply passed changeBillDate but it did not seem to work as intended. It did not bill immediately (good) but the changes to the account also did not take place immediately. (deal-breaker)

   Since I had already gone through the trouble of modifying the credit behavior so that we credit the subscription invoice first and then make the subscription changes, it worked such that the free->paid change would take into account the credit proration for the account level and apply it to the immediate invoice. So it is effectively prorating now and appears to be working. So no reason to troubleshoot why it fails to apply account changes immediately using changeBillDate but it may have been an issue with my implementation.

   • Edit

4. Support Staff 4 Posted by Marc Guyer on Jul 29, 2013 @ 04:45 PM

   

   Per the title of this thread, we have improved the plan change documentation. Specifically we added a bit about ways of accomplishing custom prorating:

   http://support.cheddargetter.com/kb/pricing-plans/pricing-plan-chan...

   This morning, I reverted to our prior code and simply passed changeBillDate but it did not seem to work as intended. It did not bill immediately (good) but the changes to the account also did not take place immediately. (deal-breaker)

   Confused about this. All actions are performed prior to API response and the latest information is contained within that response. Can you provide more detail? I can look at some detailed logs on our end if you have a timestamp/customer code handy for an instance of this behavior.

   So it is effectively prorating now and appears to be working. So no reason to troubleshoot why it fails to apply account changes immediately using changeBillDate but it may have been an issue with my implementation.

   I see. Either option should work for you. In my opinion, the full override (one-time invoice, then plan change with changeBillDate=your_reset_date) is cleanest. It remains, of course, up to you.

   • Edit

5. Support Staff 5 Posted by Marc Guyer on Jul 29, 2013 @ 05:10 PM

   

   Incidentally, we've been seeing 500 errors on attempts to run the customers/import call on your dev account. The dev team has just released a patch to address this issue. In case you're curious, it was related to importing customers without a payment method when the account has more than one billing solution simulator configured.

   • Edit

6. 6 Posted by Brandon Elliott on Jul 29, 2013 @ 05:13 PM

   

   Incidentally, we've been seeing 500 errors on attempts to run the customers/import call on your dev account. The dev team has just released a patch to address this issue. In case you're curious, it was related to importing customers without a payment method when the account has more than one billing solution simulator configured.

   Ah! I assumed it was a problem with my code and was waiting on my lead dev to assist me with it. Glad it was something you saw and addressed quickly. Thanks!

   • Edit

7. 7 Posted by Brandon Elliott on Jul 29, 2013 @ 05:17 PM

   

   Now I'm getting this:
   [err_code] => 404 [err_msg] => Item not found (id=1)

   Is that something on our end? Here is the array that I am trying to import:

   Array
   ( [cust_0] => Array ( [code] => gizmo [firstName] => Gizmo [lastName] => Tester [email] => [email blocked] [remoteAddress] => [subscription] => Array ( [planCode] => ACC_PLUS_MO [initialBillDate] => 1375934400 )

           [items] => Array
               (
                   [allpro] => 1
                   [permspec] => 
                   [permcust] => 
                   [permfull] => 
                   [permerrors] => 
                   [permnative] => 
                   [permpdf] => 
                   [maxbw] => 10
                   [maxquota] => 50000
               )
   
       )
   

   • Edit

8. Support Staff 8 Posted by Marc Guyer on Jul 29, 2013 @ 05:30 PM

   

   Your items array is not understood. It also is a nested array of arrays. For example (untested):

   $arr = array(
       array(
           'code' => 'gizmo',
           'firstName' => 'Gizmo',
           'lastName' => 'Tester',
           'email' => '[email blocked]',
           'subscription' => array(
               'planCode' => 'ACC_PLUS_MO',
               'initialBillDate' => date('c', strtotime('+5 days'))
           ),
           'items' => array(
               array(
                   'itemCode' => 'allpro',
                   'quantity' => 1
               ),
               array(
                   'itemCode' => 'maxbw',
                   'quantity' => 10
               ),
               array(
                   'itemCode' => 'maxquota',
                   'quantity' => 50000
               )
           )
       )
   );
   

   • Edit

9. 9 Posted by Brandon Elliott on Jul 29, 2013 @ 06:01 PM

   

   I got that fixed but now it's acting like I'm not nesting the customers, which I am. I am just sending through a single one as a test (cust_0).

   [err_code] => 400 [err_msg] => POST data must be a nested list of customer data

   • Edit

10. Support Staff 10 Posted by Marc Guyer on Jul 29, 2013 @ 08:05 PM

    

    The remoteAddress param is being added at the end:

    [cust_0] => stdClass Object
        (
            [code] => gizmo
            [firstName] => Gizmo
            [lastName] => Tester
            [email] => [email blocked]
            [subscription] => stdClass Object
                (
                    [planCode] => ACC_PLUS_MO
                    [initialBillDate] => 1375934400
                )
    
            [items] => Array
                (
                    [0] => stdClass Object
                        (
                            [itemCode] => allpro
                            [quantity] => 1
                        )
    
                    [1] => stdClass Object
                        (
                            [itemCode] => permspec
                        )
    
                    [2] => stdClass Object
                        (
                            [itemCode] => permcust
                        )
    
                    [3] => stdClass Object
                        (
                            [itemCode] => permfull
                        )
    
                    [4] => stdClass Object
                        (
                            [itemCode] => permerrors
                        )
    
                    [5] => stdClass Object
                        (
                            [itemCode] => permnative
                        )
    
                    [6] => stdClass Object
                        (
                            [itemCode] => permpdf
                        )
    
                    [7] => stdClass Object
                        (
                            [itemCode] => maxbw
                            [quantity] => 10
                        )
    
                    [8] => stdClass Object
                        (
                            [itemCode] => maxquota
                            [quantity] => 50000
                        )
    
                )
    
        )
    
    [remoteAddress] => 69.180.63.193
    

    • Edit

11. 11 Posted by Brandon Elliott on Jul 29, 2013 @ 08:31 PM

    

    That's odd. The remoteAddress is just below email, on the same level, so it
    should definitely not be outside the entire customer array itself. I
    suppose that I will just omit it.

    • Edit

12. 12 Posted by Brandon Elliott on Jul 29, 2013 @ 08:39 PM

    

    Didn't work. I removed remoateAddress from the array and it still fails
    with the same error. Any hints in the logs?

    • Edit

13. Support Staff 13 Posted by Marc Guyer on Jul 29, 2013 @ 08:50 PM

    

    Possible bug in the request method?

    https://github.com/marcguyer/cheddargetter-client-php/blob/master/C...

    • Edit

14. 14 Posted by Brandon Elliott on Jul 30, 2013 @ 06:00 PM

    

    On the import, I have no idea. It does not work. However, that is a separate issue and we still cannot get a working integration, so we need to address first things first.

    Back to the prorations: We ended up having to pass the changeBillDate anyway, BUT when we do; we credit the current subscription, which then gets pulled into the subscription auto invoice (as intended for proration), but then we see that the credit is duplicated (pulled forward or duplicated). The credit is not pulled forward or duplicated, if we do not send changeBillDate.

    SO... as a test, I have reverted back to a prior version of our integration (before my free->paid fixes) and merely sent changeBillDate to deal with the free->paid override issue. However, the system still generates a subscription invoice for the full amount. The new recurring invoice does get the new billing date (as intended) but the user is still charged separately for the full amount. Since we use one-time invoices to charge a prorated amount for the subscription, the user ends up paying in full AND then prorated. Advise us on how to properly bypass this behavior so that nothing posts except for our one-time invoice.

    • Edit

15. Support Staff 15 Posted by Marc Guyer on Jul 30, 2013 @ 07:09 PM

    

    Please isolate this behavior, note the exact timestamp when you began the replication and provide a link to the customer record affected. We'll take a look at the logs and see what's happening.

    • Edit

16. 16 Posted by Brandon Elliott on Jul 30, 2013 @ 11:02 PM

    

    We have run numerous tests and can no longer reproduce this behavior. It appears to have started working. I went to a doctor's appointment, came back, and now it works.

    Did your team make any changes to your side???

    • Edit

17. Support Staff 17 Posted by Marc Guyer on Jul 30, 2013 @ 11:08 PM

    

    No deployments today.

    On Tuesday, July 30, 2013, be wrote:

    • Edit

18. 18 Posted by Brandon Elliott on Aug 12, 2013 @ 02:01 PM

    

    This problem may have reared its ugly head again.

    Please see account "techtom"

    They upgraded to basic and the nextreset was sent as Aug 22nd. Our code prorated a one-time invoice (Invoice 11875) correctly BUT they were also charged the full amount (Invoice 4394).

    I need you to tell us why this occurs in some cases. Otherwise, it will result in quite a few refunds.

    • Edit

19. Support Staff 19 Posted by Marc Guyer on Aug 14, 2013 @ 03:00 PM

    

    This is ticketed for replication. We'll update you here when we know more.

    • Edit

20. Marc Guyer closed this discussion on May 08, 2015 @ 02:29 PM.