GuidesAPI ReferenceSupport
Guides

Managing Quantity and Usage

How can I update my subscription product quantities at scale via the API?

We recommend latching subscription products to their related resource in your system with the subscription ID and/or subscription product ID.

If latching is not being used, then to get the information needed to modify quantities you would need to loop through the subscriptions with GET https://secure.fusebill.com/v1/subscriptions/getAll?pageNumber=0&pageSize=50&query=status:active and increasing pageNumber as you go. For each subscription found you would need to iterate through the subscriptionProducts list to find the desired subscription product.

Here are a few quantity management use cases:

Case 1: Adding quantity on a subscription product knowing the subscription product ID

This request will update the quantity based on two body fields subscriptionProductId and deltaQuantity. There are optional URL parameters showZeroDollarCharges and temporarilyDisableAutoPost of type Boolean which specify whether to include $0 charges on the invoice and whether the invoice posts.

POST https://secure.fusebill.com/v1/SubscriptionProductQuantityChange

{ 
 "subscriptionProductId": 12341234, 
 "deltaQuantity": 1 
}

Case 2: Adding quantity on a subscription product knowing only the customer ID and the product name

Step 1: fetch the customer’s subscription data

This request will return a list of the customer’s (active) subscriptions.

GET https://secure.fusebill.com/v1/customers/593500/subscriptions?query=status:Active

Each subscription in the list will have a field called subscriptionProducts which itself is also a list. Here is a (simplified) example of what is contained in subscriptionProducts:

"subscriptionProducts": [
    {
      "subscriptionId": 85452,
      "planProduct": {
        "status": "Active",
        "productName": "phone line",
        "id": 258585
      }
    },
    {
      "subscriptionId": 87655,
      "planProduct": {
        "status": "Active",
        "productName": "hydro",
        "id": 74147
      }
    }
  ]

Each element of the list is a subscription product. Since you are looking for the subscription product ID, the value you need is in the id field selected from the subscription product with a matching planProduct.productName. In this example, if the product name is “phone line” then the value needed is 258585.

Step 2: update the subscription product quantity

This request will update the quantity based on two body fields subscriptionProductId and the deltaQuantity. As in the first case, there are optional query parameters showZeroDollarCharges and temporarilyDisableAutoPost of type Boolean which specify whether to include $0 charges on the invoice and whether to invoice posts.

POST https://secure.fusebill.com/v1/SubscriptionProductQuantityChange

{ 
 "subscriptionProductId": 258585, 
 "deltaQuantity": 1 
}

Case 3: Given a subscription id, modify the minutes of a customer to represent usage fees, deferring the posting of the invoice until the end of the month.

Step 1: verify plan product settings (done through the UI)

When editing a plan product in the UI, there are advanced price settings that need to be configured. In this case, "Automatic Quantity Reset" should be "At end of Period", under "Timing" the option "When quantity is changed" should be set to "Charge at end of period" and "Rollup charges" should be set to "Group Quantity Change Charges". The effect of this is that multiple increases over the course of the month will be grouped together as one line item on the invoice posted at the end of the month. The amount of minutes would then be reset to 0 after the posting of the invoice. Setting up the plan product cannot be done through API calls. Catalog setup is done exclusively through the UI. Further, this can’t be changed for a specific customer.

Step 2: fetch the subscription data

This request will get all the data on the subscription with the specified ID:

GET https://secure.fusebill.com/v1/subscriptions/{ID}

Step 3: modify and update the subscription data

The body of the response from step 2 will be the body of this PUT request. The only thing that needs to be done is for the quantity field(s) to be set to the new value for the object(s) in the subscriptionProducts list. This is assuming there are no discounts on any of the subscription products. If there are, then each subscriptionProductDiscount must be set to null for each element of the subscriptionProducts list (see Case 5).

PUT https://secure.fusebill.com/v1/subscriptions/{ID}?temporarilyDisableAutoPost=true

Case 4: Change the number of user licences for a specific subscription product. The invoice will be posted at the start of the next month. Proration will be used. The subscription product ID is known

Step 1: verify plan product settings (done through the UI)

When editing a plan product in the UI, there are advanced price settings that toggle proration, proration granularity (i.e daily), and whether the response to a change in quantity is “charge immediately”, “do not charge”, or “charge at end of period”. To be charged at the start of the next month, “do not charge” should be selected for when the quantity changes, and proration should be toggled. This cannot be done through API calls. Catalog setup is done exclusively through the UI. Further, this can’t be changed for a specific customer.

Step 2: use the subscription product ID to update the license number if the delta value is known

If you only have the value to set to, then skip to step 3. Otherwise, this step is the last step.

Like in the other cases, this request will update the quantity based on a delta value.

POST https://secure.fusebill.com/v1/SubscriptionProductQuantityChange?temporarilyDisableAutoPost=true

{ 
 "subscriptionProductId": 12341234, 
 "deltaQuantity": 1 
}

Step 3: fetch the subscription product data

This request will return all the information on the specific subscription product associated with the ID.

GET https://secure.fusebill.com/v1/SubscriptionProducts/{ID}

Step 4: update the subscription product data

Take a copy of the response body from step 3 and modify the quantity field (NOT planProduct.quantity) to its new value. If the product had one or more discounts applied, then it is necessary to change subscriptionProductDiscount to null (see case 5).

Use the modified data as the body to this request. This request will return all the information on the specific subscription product associated with the ID. In this case, set temporarilyDisableAutoPost to true.

PUT https://secure.fusebill.com/v1/SubscriptionProducts?temporarilyDisableAutoPost=true

Case 5: modify the quantity of a discounted subscription product, given the subscription id and the name of the product to change.

Step 1: retrieve the subscription data

Using the subscription ID, this request will return all the data on that subscription.

GET https://secure.fusebill.com/v1/subscriptions/{ID}

Step 2: modify the data

Copy the body of the response from step 1. In this copied body there will be a field called subscriptionProducts which is a list. In the subscription object to be changed (the one matching the product name), there is a field called quantity which can be set to the desired amount.

Since the subscription products in question have discount(s) applied, more fields need to be modified.

Specifically, subscriptionProductDiscount needs to be set to null. The subscriptionProductDiscounts list should not be altered. subscriptionProductDiscount must be set to null for all the elements of the subscriptionProducts list even if quantity is not being modified.
####Step 3: push the updated data to the subscription
This request will use the modified data from step 2 as the body. This request will change the modified quantities. The effect of this is that the discounted rate is preserved even for additional products. In this case, set temporarilyDisableAutoPost to true.

PUT https://secure.fusebill.com/v1/subscriptions/{id}?temporarilyDisableAutoPost=true

Updated about 1 year ago