Adding Purchases and Subscriptions to existing customers

This tutorial is not for registering new customers. For a tutorial on registering a new customer with a new subscription, use the Creating a Registration/Checkout Page tutorial.

For the purposes of this tutorial, it is assumed that the Stax Bill generated customer id is known at the start of this workflow. That customer should already have a status of active and whose address information and payment method information has been captured. To capture a payment method, see the transparent redirect options or the direct credit card or ACH options.

Get purchasable products (optional)

If you do already not have a list of prices for your purchasable products, fetch them with List Products:

GET https://secure.fusebill.com/v1/Products/?includePricing=true&query=availableForPurchase:true

A list will be returned in response. Note eachid and name value found. Additionally, orderToCashCycle.pricingModel.quantityRanges contains display pricing information. Note that this pricing information will not include tax. The post-tax value can be found after the customer has selected the product.

Get available plans (optional)

If do not already have a list of plan, plan frequency, and plan product pricing information, they can be retrieved with List Plans:

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

For each plan, iterate through the planFrequencies list. For each plan frequency with a status of Active, copy the id. Note these frequency IDs in a separate data structure so as not to confuse them with purchasable product IDs.

For each plan frequency, a subscription create preview can be used to get an example of a subscription:

POST https://secure.fusebill.com/v1/subscriptions?preview=true
{
  "planFrequencyId":{Plan Frequency ID},
  "customerId":{Customer ID}
}

The value needed is invoicepreview.subtotal. This is the cost before tax.

Add purchases to customer (make a draft purchase)

For one-time line items, separate from a billing schedule, create purchases on the customer. When a customer selects a purchasable product, the related id can be used to create a draft purchase using Create Single Purchase:

POST https://secure.fusebill.com/v1/Purchases  
{
  "customerId": {Customer ID},
  "name": "Product Name",
  "productid": {Product ID},
  "quantity": {quantity},
  "couponCodes": [
    "codeAsString1",
    "codeAsString2"
  ]
}

📘

Coupons

Observe that coupon codes can be provided at this time if you've determined the customer is eligible. Coupon codes can be found via:

GET https://secure.fusebill.com/v1/Coupons?query=status:Active

Note that if a coupon has a limited number of usages you may get a 400 error "Coupon is not Valid".

Hold onto the resulting id of the purchase for the activation step later. The purchase will have a status of draft.

If the customer changes their mind and removes the item from their cart, this draft purchase can be deleted with a call to Delete Draft Purchase:

DELETE https://secure.fusebill.com/v1/Purchases/{PurchaseID}

Check that a 204 No Content response is returned, which indicates successful deletion.

Add subscription to customer

If the customer selects a plan and frequency, then a draft subscription can be created using Create Subscription:

POST https://secure.fusebill.com/v1/subscriptions
  "planFrequencyId":{Plan Frequency ID},
  "customerId":{Customer ID},
  "couponCodes":[
     "code1",
     "code2"
  ]

📘

Coupons

Observe that coupon codes can be provided at this time if you've determined the customer is eligible. Coupon codes can be found via:

GET https://secure.fusebill.com/v1/Coupons?query=status:Active

Note that if a coupon has a limited number of usages you may get a 400 error "Coupon is not Valid".

Take note of the id of the resulting subscription, it will have a status of draft.

To remove that draft subscription, delete it with Delete Subscription:

DELETE https://secure.fusebill.com/v1/subscriptions/{subscriptionID}

Check that a 204 No Content response is returned, which indicates successful deletion.

Preview activation of new purchases and new subscriptions

At this stage the customer may have selected multiple purchases and subscriptions. To get the post-tax amount the customer will have to pay, use Activate Customer's Specific Subscriptions and Purchases using all of the IDs from all the customer's selected purchases/subscriptions. Make sure to include preview as true:

POST https://secure.fusebill.com/v1/customers/Purchase/{CustomerID}
{
    "preview": true,
    "specificSubscriptionIds": [
        {Subscription ID 1},
        {Subscription ID 2}
    ],
    "specificPurchaseIds": [
        {Purchase ID 3},
        {Purchase ID 4}
    ]
}

At the end of this step nothing has been taken out of draft status and no invoices have been generated or posted. Now would be the time to get confirmation from the customer.

Activate subscriptions and purchases

Once confirmation is received, activate the customer’s subscriptions and purchases using the same call as the preview, but removing or setting preview to false:

POST https://secure.fusebill.com/v1/customers/Purchase/{CustomerID}
{
    "preview": false,
    "specificSubscriptionIds": [
        {Sub ID 1},
        {Sub ID 2}
    ],
    "specificPurchaseIds": [
        {ID 3},
        {ID 4}
    ]
}

📘

Providing no JSON body

This call can be made with no JSON body. Doing this has the effect of activating all the draft subscriptions for the customer and finalizing all draft purchases for the customer. Providing the specificPurchaseIds or specificSubscriptionIds tells Stax Bill to activate/finalize a subset of the customer's draft subscriptions/purchases.

Optionally, the call can be made with invoice collect options that would allow the transaction to roll back to a draft state upon payment failure. Make sure to include the invoiceCollectOptions object and at least rollbackOnFailedPayment with a value of true:

POST https://secure.fusebill.com/v1/customers/Purchase/{CustomerID}
{
    "specificSubscriptionIds": [
        {Sub ID 1},
        {Sub ID 2}
    ],
    "specificPurchaseIds": [
        {ID 3},
        {ID 4}
    ],
    "invoiceCollectOptions": {
        "paymentMethod": " UseDefaultPaymentMethod",
        "rollbackOnFailedPayment": true,
    }
}

For more details on how the invoice collect options work, consult the Invoice Collect Options tutorial.