GuidesAPI ReferenceSupport
Guides

Setting up a New Customer and Subscription for recurring billing

One of the most common tasks a developer will perform using the Stax Bill API is creating a completely new billing entity in the Stax Bill system so that it can be properly charged for services.

At a high level this requires input of the following 3 pieces of information:

  • Who the customer is
  • What they want to buy
  • How they want to Pay

The following tutorial identifies the inventory of API calls that may be required to get this information properly captured in the Stax Bill system.

Step 1: Get plans

Assuming you have (active) plans in your Stax Bill account, you will need to retrieve them. This request will return a list of plan objects

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

Step 2: Get a subscription preview

Once your customer has selected the specific plan, this request will return an object which can later be used to create a subscription. The query string view=subscription causes the endpoint to return a post subscription object and not a plan object. The post subscription object would specify the price of each subscription product before any taxes are applied.

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

This may produce errors if the plan has multiple frequencies. If that is the case more query strings will be required as shown in this request:

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

Step 3: Get a mock subscription

Once you have the post subscription object from step 2, you can use it in the body of this request to receive a side effects object. The side effects object may contain a draft invoice object if any invoice would be generated from the creation of an active subscription. From this you can get the total amount of the invoice, the charges that would be present, and any discounts. You can display the relevant details to the customer before requesting payment information.

Since there is no customer, remove the customerId and populate the taxationAddress to get an invoice preview after tax. You can also provide coupon codes, control the inclusion/exclusion of subscription products, and provide overrides. For full details on what can be done during subscription creation consult the developer reference. The countryId and stateId can be found with the Read Country call.

POST https://secure.fusebill.com/v1/subscriptions?preview=true&view=sideeffects 
{
    "taxationAddress": {
        "line1": "10 Main St",
        "line2": "Unit B",
        "countryId": 123,
        "stateId": 2,
        "city": "Ottawa",
        "postalZip": "V9V9V9"
    },
    "planFrequencyId": 22104,
    "couponCodes": [
        "coupon_12",
        "coupon_43"
    ]
}

You now have all the information needed to create a confirmation page, and no draft customers or draft subscriptions have been made. This means that if the customer aborts no changes occur in your Stax Bill account.

Step 4: Create a (draft) customer

This request creates a customer based on the fields in the body. This customer will be in draft status by default

POST https://secure.fusebill.com/v1/customers
{
  "firstName": "John",
  "lastName": "Smith",
  "companyName": "Google",
  "primaryEmail": "[email protected]",
  "currency": "CAD",
  "billing": {
    "companyName": "Billing Company",
    "line1": "109 Old House Street",
    "line2": "Suite 17",
    "city": "ExampleTown",
    "postalZip": 12345,
    "country": "US",
    "state": "NY"
  }
}

It is possible when using that request to provide much more information, and even overwrite account defaults. For full details on what can be provided and overwritten, see the documentation for this call in the developer reference.

Step 5: Add a payment method

Credit Card:

Follow the instructions from AJAX Redirect to get and add a credit card to a customer's account.

ACH:

For ACH, create a payment method through the regular API.

POST https://secure.fusebill.com/v1/paymentMethods/achCard
{
  "accountNumber": "123457832156",
  "transitNumber": "12345",
  "bankAccountType": "CHQ",
  "firstName":"James",
  "lastName":"McHenry",
  "address1": "98 Roberts St",
  "address2": "",
  "city": "Chicago",
  "stateId": 1,
  "countryId": 124,
  "postalZip": "V9V 9V9",
  "makeDefault": true,
  "customerId": 669521,
  "source": "Manual"
}
Note, while there is an endpoint for credit cards similar to the ACH one, use one of the redirect methods instead.

Step 6: Create a (draft) subscription

You can use the customer id returned in step 4 to override the customerId field in the post subscription object from step 2. Remove the taxationAddress. Using this altered post subscription object as the body, this request will create a (draft) subscription associated with the draft customer created in step 4.

POST https://secure.fusebill.com/v1/subscriptions?view=sideeffects 
{
    "customerId": {customer ID},
    "planFrequencyId": 22104,
    "couponCodes": [
        "coupon_12",
        "coupon_43"
    ]
}

Step 7: Activate the customer

This request will activate the customer, but not their subscriptions. By changing the value of activateAllSubscriptions to true, this request would also change the status of the customer’s subscriptions to active. The option rollBackOnFail, when true, if there's a problem with collection while trying to activate, will roll the customer and their subscription and purchases back to a draft state.

POST https://secure.fusebill.com/v1/customerActivation
{ 
    "customerId": {customerId}, 
    "activateAllSubscriptions": true, 
    "activateAllDraftPurchases": true, 
    "temporarilyDisableAutoPost": false,
  	"rollBackOnFail": true
}

Updated 7 months ago

What’s Next