Get the Subscription Post Body

The subscription proposal is a new workflow that Stax Bill has introduced which allows you to get a mock subscription, or invoice without creating any entities in the Stax Bill system. This can be leveraged for many things such as to create quotes or registration flows.

This workflow starts assuming that you have the Plan Id of the plan in question you would like to get a proposal for, if you do not have your Plan Id at this point follow these steps before continuing.

Now with plan Id you can get your subscription proposal:

This request will return you the object needed to post the subscription proposal including the query string view=subscription causes this endpoint to return us a post subscription object rather than a plan object.

GET https://secure.fusebill.com/v1/plans/PlanId?view=subscription

However, if your plan has more than one frequency you will see an error returned that looks like this “Unable to find the specific plan frequency with the provided information: interval N/A, number of intervals: N/A”
You can further filter down which frequency should be chosen by including two query strings to the call

GET https://secure.fusebill.com/v1/plans/PlanId?view=subscription&interval=monthly&numberOfIntervals=1

This will cause the GET plans to filter out all plan frequencies that do not have that same frequency values.

After successfully fetching the subscription view from the GET plans endpoint you will be armed with everything that you need to see your subscription proposal. The response body from the call above should look like this:

Subscription post body (this is a minimalistic view of the returned information)

{
    "reference": "reference",
    "subscriptionProducts": [
        {
            "planProductUniqueId": 2309,
            "name": "Product Name",
            "description": "Product Description",
            "quantity": 1,
            "isIncluded": true,
            "pricingModelType": "Standard",
            "price": 10,
            "subscriptionProductDiscounts": [
            ]
        }
    ]
}

Post the Subscription Proposal

You now have the body of the Post subscription call from above, take the return of the last request and make another:

This request will return you what a subscription would look like on a customer without creating a customer in Stax Bill

POST https://secure.fusebill.com/v1/subscriptions?preview=true

However, at this point you still don’t have an invoice or a quote from the plan in question, this can easily be solved by adding another query to the POST subscription call.

POST https://secure.fusebill.com/v1/subscriptions?preview=true&view=sideeffects

Including the query string view=sideeffects will cause this endpoint to return a new object in the body called sideEffects. The sideEffects will have a draftInvoice object inside it if any invoice would have been created from this call.
The invoice returned will have the total amount of the invoice, all the charges, and any applicable discounts.

You have now gotten a Subscription proposal out of Stax Bill without creating any entities in Stax Bill’s system. But this is just the beginning, we will now go into optional customization of the subscription proposal.

Subscription proposal response (this is a minimalistic view of the returned information)

{
    "planCode": "invoiceinadvance",
    "subscriptionProducts": [
        {
            "subscriptionId": 0,
            "quantity": 1,
            "isIncluded": true,
            "subscriptionProductDiscounts": [
            ],
            "amount": 10,
            "status": "Active"
        }
    ],
    "sideEffects": {
        "draftInvoice": {
            "subtotal": 10,
            "totalDiscount": 0,
            "total": 10,
            "terms": "0"
        }
    }
}

Subscription Proposal Advanced Customization

You may be thinking, “This subscription proposal is great, but this customer wants 3 quantity of that product not the default 1.”, well good news, this functionality is also supported. If you look at the body of the GET plans?view=subscription call from above, you will be able to see that there is a list of subscriptionProduct objects within the body.
You can modify specific products before submitting the subscription proposal, the workflow would then look like this:

First let’s fetch the body of the subscription we want to post

GET https://secure.fusebill.com/v1/plans/PlanId?view=subscription&interval=monthly&numberOfIntervals=1

Now we have the body of our post, but I would like to add 2 extra quantity to a product. All you need to do is modify the quantity field on a subscriptionProduct to be 3 rather than 1.
Now that we have changed the quantity field, we are ready to post our subscription proposal once again

POST https://secure.fusebill.com/v1/subscriptions?preview=true&view=sideeffects

Now that we have our subscription proposal we can check both the subscriptionProducts object returned to see its quantity, or view the created invoice inside the sideEffects object and we will be able to see that the invoice value is larger than our previous proposal.

This was only a small slice of the new power our subscription proposal can provide, any of the returned (non id) fields from the GET Plans?view=subscription call are modifiable and will be reflected in the returned subscription object and any returned invoices as well.

Subscription post body change quantity (this is a minimalistic view of the returned information)

{
    "reference": "reference",
    "subscriptionProducts": [
        {
            "planProductUniqueId": 2309,
            "name": "Product Name",
            "description": "Product Description",
            "quantity": 1,
            "isIncluded": true,
            "pricingModelType": "Standard",
            "price": 10,
            "subscriptionProductDiscounts": [
            ]
        }
    ]
}

Getting Your Plan Id

To see every one of your plans in Stax Bill you can query this endpoint:

GET https://secure.fusebill.com/v1/plans

This endpoint supports Stax Bill’s query strings, if you have knowledge about the plan you would like to see you can filter down the results with queries such as this:

If you have prior knowledge as to what the Plan Code value of your plan is you can find the specific plan with a query like this:

GET https://secure.fusebill.com/v1/plans?query=code:PlanCode

This is an example of searching for two different queries in one, this is done by splitting the query with a ‘;’ symbol

GET https://secure.fusebill.com/v1/plans?query=status:Active;code:PlanCode

At this point after returning a specific plan or your list of Plans, we would suggest that you store this data on your end, by storing the plan data (specifically the Plan Id) you will not need to query us for this information in the future, allowing your processes to run more quickly by not needing to query Stax Bill. It is not likely that your plan information will change very often so this is something that could be synced every so often, or specifically when changes are made to your catalog in Stax Bill. The “Plan Id” field can be found on the object below highlighted in yellow.
Plan Object (this is a minimalistic view of the returned information)

[{
        "code": "Plan Code",
        "name": "Plan Name",
        "reference": "Plan Reference",
        "description": "Plan Description",
        "status": "Active",
        "id": 4465
}]

GET https://secure.fusebill.com/v1/plans?query=status:Active;code:PlanCode

[{
        "code": "Plan Code",
        "name": "Plan Name",
        "reference": "Plan Reference",
        "description": "Plan Description",
        "status": "Active",
        "id": 4465
}]