Home → Suggestions →

Proposal: Tracked Item Grants

• Edit

Dan Kamins

13 Jul, 2010 07:23 PM

OVERVIEW

This is a proposal for a new feature / extension to CheddarGetter that would allow individual users to be granted additional tracked items. Comments/feedback welcome.

Currently tracked item limits are hardcoded in the "Plans" to which customers subscribe and cannot be changed without creating totally separate Plans. This is cumbersome and not sufficient for a number of use cases where limits must be altered on an individual customer basis.

The specifics of the proposal are four-fold (see "Technical Details" below):

1. Modification of customer XML format to include item grants.
2. Addition to API to allow setting item grants for customers.
3. Incorporation of grants into invoicing/billing calculations.
4. Admin interface support for adjusting grants.

We believe that this proposal, as described here, should be able to be integrated into CheddarGetter in a straightforward manner. The concepts and approaches are similar to the existing system and would be natural and easy for clients to adopt. Additionally if clients were uninterested in these features, they could easily ignore them.

MOTIVATION

Examples where this would be used:

• rewarding a user for referring a friend.
• rewarding a user for completing a task (e.g. fill out a survey).
• allowing flexible sales without requiring creation of new plans.
• coupons and special promotions.
• and more...

Businesses generally seek to protect profit and revenue, and web-based businesses (your clients) typically have low marginal costs and thus can give "stuff" away more readily than money. The inability of the CheddarGetter billing model to allow for grants as proposed here means that special offers and sales must be done by either creating new plans (which is error-prone and difficult to manage) or by giving monetary discounts (which totally goes against a business's prime goal of profit/revenue maximization).

By supporting this feature, CheddarGetter will allow its clients to grow by leveraging the sales models appropriate for their own businesses. And in the end this means more customers and more revenue for CheddarGetter as well.

TECHNICAL DETAILS

TD:1. Modification of customer XML format to include item grants.

We propose addition of a <grants> element immediately following <quantity> in a customer's subscription's items list. The XML path of the new element is: customers/customer/subscriptions/subscription/items/item/grants.

Example abbreviated customer XML snippet:

<?xml version="1.0" encoding="UTF-8"?>
<customers>
  <customer id="customer-id-123456789abcdef" code="CUST_CODE">
    <subscriptions>
      <subscription id="subscription-id-123456789abcdef">
        <plans>
          <plan id="plan-id-123456789abcdef" code="PLAN_CODE">
            <items>
              <item id="item-id-123456789abcdef" code="ITEM_CODE">
                <name>Tracked Item Name</name>
                <quantityIncluded>10</quantityIncluded>
                <isPeriodic>0</isPeriodic>
                <overageAmount>5</overageAmount>
                <createdDatetime>2010-01-01T00:00:00+00:00</createdDatetime>
              </item>
            </items>
          </plan>
        </plans>
        <items>
          <item id="item-id-123456789abcdef" code="ITEM_CODE">
            <name>Tracked Item Name</name>
            <quantity>8</quantity>

            <grants>5</grants>   <!-- *** THIS IS THE PROPOSED ELEMENT *** -->

            <createdDatetime>2010-01-02T00:00:00+00:00</createdDatetime>
            <modifiedDatetime>2010-01-03T00:00:00+00:00</modifiedDatetime>
          </item>
        </items>
      </subscription>
    </subscriptions>
  </customer>
</customers>

TD:2. Addition to API to allow setting item grants for customers

Similar to the "-item-quantity" methods, we propose "-item-grants" methods.

Existing *-item-quantity methods:

/customers/add-item-quantity/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE/itemCode/MY_ITEM_CODE
/customers/remove-item-quantity/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE/itemCode/MY_ITEM_CODE
/customers/set-item-quantity/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE/itemCode/MY_ITEM_CODE

Proposed *-item-grants methods:

/customers/add-item-grants/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE/itemCode/MY_ITEM_CODE
/customers/remove-item-grants/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE/itemCode/MY_ITEM_CODE
/customers/set-item-grants/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE/itemCode/MY_ITEM_CODE

TD:3. Incorporation of grants into invoicing/billing calculations

Invoices are currently calculated for each tracked item as:

max(0, Sub:quantity - Plan:quantityIncluded) * Plan:overageAmount

With "grants", the calculation for each tracked item would be:

max(0, Sub:quantity - (Plan:quantityIncluded + Sub:grants)) * Plan:overageAmount

TD:4. Admin interface support for adjusting grants

An admin logged into CheddarGetter should be able to adjust grants similar to how they can currently adjust tracked items.

Clicking on the already existing pencil icon pops up the "Set Item Quantity" dialog. Here you should be able to set grants in addition to item quantity.

POSSIBLE EXTENSIONS

In addition to this basic feature set, possible future extensions include:

• Grants that expire (e.g. "get 5 extra Wazoos for the next 3 months")

1. Support Staff 1 Posted by Marc Guyer on 14 Jul, 2010 12:39 PM

   

   Very nice work. This is almost identical to what we have already discussed in preliminary meetings. There may be a few slight differences in the implementation but the effect will be the same. Thanks very much for the spec!

   • Edit

2. 2 Posted by chris on 27 Jul, 2010 06:22 PM

   

   Any idea when this might be implemented? It's our #1 most desired feature by a long shot. I'm actually surprised that other customers haven't been bugging you for this.

   • Edit

3. Support Staff 3 Posted by Marc Guyer on 07 Oct, 2010 05:50 PM

   

   This is the next project on our list after marketing metrics tracking. Promotion/discount codes (which will be able to trigger tracked item grants) will also factor into the metrics tracking. Still no firm ETA, unfortunately.

   • Edit

4. Support Staff 4 Posted by Marc Guyer on 12 Nov, 2010 01:33 PM

   

   Hey guys -- We're curious about how you'd like to handle a couple of scenarios...

   1. Multiple grants for the same item. Is this a requirement for you? We can imagine several scenarios where multiples would be useful.
      
   2. Plan changes -- would you like a customer's grants to continue to be in effect after a plan change?
      
   3. Time limits -- This is related to no. 1. We're considering optional settings for start/end dates on grants. We're considering "matching up" the start/end with the billing period. In other words, the end date would always be the same as the end date of a billing period. Since you prorate your plans, when a customer changes to a different plan, their billing period changes. So, the grant could end in the middle of a billing period. They would then effectively "lose" the period of time since the last bill to then end of the grant period. There's a similar issue with changes between plans with different frequencies (monthly to quarterly, for example). This is fairly hard to explain. Does this make sense?

   We're striving for the optimal simplicity/feature-full tradeoff here.

   • Edit

5. 5 Posted by Dan Kamins on 12 Nov, 2010 06:15 PM

   

   1: "Multiple grants for the same item" seems like a benefit for a) allowing additional grant metadata (e.g. time limits, as in 3), and b) to allow for straightforward line items on a customer's bill with descriptions (e.g. "Refer-a-friend bonus").

   Without it, as in my proposal above, there is a more opaque and vague grant value that is still modifiable to allow for multiple grants, but without clear history or ability to add on additional features like expirations.

   Your idea is a good one and seems more future-proof. It sounds like you would be treating grants more like charges/credits and less like tracked items (as in my proposal). That would be nice.

   2: As a default, plan changes should wipe out grants. You might want to make this an option when the grant is created, similar to how tracked items can be marked as periodic or not.
   

   But for a first version, it would be totally fine to just wipe out grants.

   3: Tracked items without time limits would be a good start. We could make good use of that. But obviously time limits would open up more interesting possibilities, and we would use that as well.

   I'm not 100% following the issue you're describing, but it sounds like there's a fair amount of complexity to getting this right.

   I would say that your idea to do grants as line items (as opposed to how I proposed it) is excellent. Our preference would be for you to take that approach, but try to get a release out without all the bells & whistles first. This would allow you to later add on options for a) durable grants that survive plan changes, b) grants with expiration times, c) other ideas you come up with. Meanwhile we & other customers could start utilizing the basics.

   Thanks for reaching out, and we're always happy to give feedback on upcoming featuers!
   

   • Edit

6. adam closed this discussion on 28 Sep, 2011 03:00 PM.

7. Marc Guyer re-opened this discussion on 05 Mar, 2015 04:45 PM

8. Support Staff 6 Posted by Marc Guyer on 05 Mar, 2015 04:45 PM

   

   Hi Dan -- Over 4 years later, are you still interested in using Tracked Item Grants? If so, I have documentation of the beta functionality (API only currently) for you. If not, I hope you've at least had a good laugh about this post.

   • Edit

9. 7 Posted by Dan Kamins on 06 Mar, 2015 12:08 AM

   

   Hi Marc,

   We would definitely like to take advantage of the feature, and I'd be happy
   to review the API docs for now to get a feeling for how it's supposed to
   work.

   But for the most part we would be using it mostly through the admin UI as
   opposed to API. Do you have ETA for a web-based interface?

   dk

   • Edit

10. Support Staff 8 Posted by Marc Guyer on 06 Mar, 2015 03:58 PM

    

    Alrighty.

    Do you have ETA for a web-based interface?

    I'm not entirely sure but it could be relatively soon. Our big GUI project is Almost Done(TM) which will give our UX designer some time to work on the grants UI. I've contacted you in the hopes that you'd want to use the functionality in a beta capacity. I'd ideally like to make sure the functionality is the way we want it before we work too hard on interface design. It's relatively simple functionality so I don't anticipate major changes...

    Here's the preliminary documentation:

    Creating a Customer with Grant(s)

    See current docs: https://cheddargetter.com/developers#add-customer

    This method accepts a new list named 'itemGrants' at the same level as 'items'. Each grant in the list must include the item code of the item that the grant is associated with and the quantity of the grant. Optionally, you may include a param called isPeriodic (set to 0 to override plan config). An example request in json format (note: actual request must be in application/x-www-form-urlencoded format):

    {
      "firstName": "Example",
      "lastName": "Grant",
      "email": "[email blocked]",
      "code": "your_customer_code",
      "subscription": {
        "planCode": "your_customer_code"
      },
      "items": [
        {
          "itemCode": "ITEM_B",
          "quantity": 201
        },
        {
          "itemCode": "ITEM_C",
          "quantity": 11
        }
      ],
      "itemGrants": [
        {
          "itemCode": "ITEM_C",
          "quantity": 1,
          "description": "You get 1 more of these!"
        },
        {
          "itemCode": "ITEM_E",
          "quantity": 500,
          "isPeriodic": 0,
          "description": "You get 500 more of these forever!"
        }
      ]
    }
    

    Grants for an Existing Customer

    Three additional methods are available for manipulating grants. They are modeled after the Item Quantity methods. They take the same parameters and behave the same.

    See current docs for Item Quantities: https://cheddargetter.com/developers#tracked-items

    The new methods are named similarly:

    • customers/set-item-grant: Set a grant quantity for the customer
    • customers/add-item-grant: Increment grant quantity for the customer
    • customers/remove-item-grant: Decrement grant quantity for the customer

    API Response

    A new node in the customer API response includes the grant information. The new node is:

    customers > customer > subscriptions > subscription > items > item > grants
    

    Here's an example:

    ...
    <items>
      <item id="85c31fff-c417-11e4-be75-080027880ca6" code="ITEM_A">
        <name>Item As</name>
        <quantity>0</quantity>
        <grants>
          <grant>
            <quantity>12</quantity>
            <isPeriodic>0</isPeriodic>
            <description>You get 12 more of these!</description>
            <createdDatetime>2015-03-06T15:47:45+00:00</createdDatetime>
            <modifiedDatetime>2015-03-06T15:47:45+00:00</modifiedDatetime>
          </grant>
        </grants>
      </item>
      <item id="85c328d0-c417-11e4-be75-080027880ca6" code="ITEM_B">
        <name>Item Bs</name>
        <quantity>0</quantity>
      </item>
      <item id="85c33074-c417-11e4-be75-080027880ca6" code="ITEM_C">
        <name>Item Cs</name>
        <quantity>12</quantity>
        <createdDatetime>2015-03-06T15:47:45+00:00</createdDatetime>
        <modifiedDatetime>2015-03-06T15:47:45+00:00</modifiedDatetime>
        <grants>
          <grant>
            <quantity>1</quantity>
            <isPeriodic>-1</isPeriodic>
            <description>You get 1 more of these!</description>
            <createdDatetime>2015-03-06T15:47:45+00:00</createdDatetime>
            <modifiedDatetime>2015-03-06T15:47:45+00:00</modifiedDatetime>
          </grant>
        </grants>
      </item>
    ...
    

    How Grants are Applied

    At invoice run time, item usage and grant quantities for the invoice period are calculated. If an item has overage charges on the invoice and there is a grant on that item for that invoice period, a credit is added to the invoice in the amount of the item overage or the amount of the grant, whichever is lower.

    In other words, item overage is charged as usual according to the plan config. Any grants applicable to the item overages charges are added as credits, offsetting the item charges. The credits applied for the grants have the same charge code as the item charges.

    • Edit

11. 9 Posted by Dan Kamins on 25 Mar, 2015 03:17 AM

    

    Marc,

    That looks like a reasonable approach. A couple comments:

    - I assume (hope) the grants would disappear in the case of a plan change.

    - It's important for the invoices to be sensible, so it should be clear what the usage was, how much the grant allowed for, etc.

    dk

    • Edit

12. Support Staff 10 Posted by Marc Guyer on 25 Mar, 2015 03:48 PM

    

    I assume (hope) the grants would disappear in the case of a plan change.

    Grants persist just like their corresponding item quantities. So, no, they don't disappear. Perhaps this should be a per-grant option? Alternatively, a listener for the plan change hook could be used to strip any grants -- of course that would only work for simple (not prorated) plan changes.

    On a similar topic: a grant inherits or overrides the parent item's isPeriodic settings. In other words, a grant may reset at the beginning of the next period, persist to the next period, or defer to the parent item's isPeriodic setting.

    It's important for the invoices to be sensible, so it should be clear what the usage was, how much the grant allowed for, etc.

    Absolutely. Item overages are charged as usual. Then the grants are considered and applied as credits on the invoice if applicable:

    HOW GRANTS ARE APPLIED

    At invoice run time, item usage and grant quantities for the invoice period are calculated. If an item has overage charges on the invoice and there is a grant on that item for that invoice period, a credit is added to the invoice in the amount of the item overage or the amount of the grant, whichever is lower.

    In other words, item overage is charged as usual according to the plan config. Any grants applicable to the item overages charges are added as credits, offsetting the item charges. The credits applied for the grants have the same charge code as the item charges.

    Each item overage charge has a line item on the invoice. If a grant is applicable there will be a corresponding line item indicating the grant credit.

    • Edit

13. 11 Posted by Dan Kamins on 25 Mar, 2015 09:13 PM

    

    Grants persist just like their corresponding item quantities.

    Don't item quantities get reset on plan changes too?

    • Edit

14. Support Staff 12 Posted by Marc Guyer on 25 Mar, 2015 09:50 PM

    

    Grants persist just like their corresponding item quantities.

    Don't item quantities get reset on plan changes too?

    Only under certain circumstances. The relevant config options are the item isPeriodic config on each plan and also the plan's config setting for plan change to that plan.

    Your PLAN_BASIC plan, for example, has the KEYWORDS_STANDARD item configured to reset at the beginning of each invoice period. Since the plan change setting for this plan is Bill immediately for a prorated amount and start new billing period, a new period begins upon change to that plan so that item would be reset to 0.

    TL;DR > Yes.

    • Edit

15. 13 Posted by Dan Kamins on 07 Aug, 2015 02:19 AM

    

    Wondering if this might show up in the web admin UI in the near future?

    • Edit

16. Support Staff 14 Posted by Marc Guyer on 12 Aug, 2015 12:35 PM

    

    Hi Dan -- It's not on the current short list. We're working on another big project right now that you'll probably be interested in: External Payments. That feature will enable you to have customers that pay via some method other than CC within CheddarGetter but maintain accurate authorization, usage, and revenue information within CheddarGetter. I know that you have a lot of that going on in your current setup and I think you use large credits currently as a workaround for the current limitation. Coincidentally, I think this is related to your other question over here. I'll comment further in that thread.

    • Edit