Getting StartedReference Documentation

Subscription Add-ons

Suggest Edits

Add-ons are additional products that can be attached to a subscription and billed for in each billing cycle. Add-ons can be used to solve a wide range of use-cases. E.g. variable number of "user licenses" or "extended support", in addition to a base subscription product.

Below a use case.

Use case: Computer leasing

In this use-case the base subscription product is computer leasing. In addition to the base subscription product, a customer can have a number of leased computers. The computers leased are represented by subscription add-ons referenced by computer serial number.

Manage add-ons

Add-ons are generic additional products that can be seen as templates for subscription add-ons. Subscription add-ons link an add-on to a subscription, together with parameters like quantity and possible custom amount.

Add-ons can be managed in the administration or through the API using the add-on resource. To create an add-on through the API.

curl -X POST "https://api.reepay.com/v1/add_on" -u "priv_dbd002cf1313cb4213efcfb3afebfb66:" \
  -H  "Accept: application/json" -H  "Content-Type: application/json" -d \
  '{
    "name": "Super Laptop X2",
    "handle": "super_laptop_x2",
    "description": "Additional specs",
    "type": "on_off",
    "amount": 12900,
    "eligible_plans": [
      "leasing_gold"
    ]
  }'

The add-on represents the generic class of the "Super laptop X2" product. The type of the add-on is on_off as a subscription add-on will represent a single laptop by serial number so quantity does not make sense. The base product is represented by the subscription plan with handle leasing_gold. The subscription plan might have some base price, or a zero amount if all costs are induced by the leased computers.

Add-ons can be limited to specific subscription plans in the case that add-ons only makes sense, or are limited to, specific plans. This could for example be the case if pricing for add-ons differs based on the subscription plan. It is also possible to allow for all plans.

In addition to the laptop add-on we also create an add-on representing "extended support". This add-on has type quantity as it is per laptop.

curl -X POST "https://api.reepay.com/v1/add_on" -u "priv_dbd002cf1313cb4213efcfb3afebfb66:" \
  -H  "Accept: application/json" -H  "Content-Type: application/json" -d \
  '{
    "name": "Extended laptop support",
    "handle": "extended_laptop_support",
    "type": "quantity",
    "amount": 50000,
    "all_plans": true
  }'

Create subscription with add-ons

A subscription can optionally be created with a number of subscription add-ons. For more information on subscription handling see here. In this case we create a subscription for an existing customer by using the parameter customer. A subscription and customer can also be created in one atomic call by using the parameter create_customer.

To create subscription add-ons for a subscription a number of CreateSubscriptionAddOn objects must be provided. Below an example.

curl -X POST "https://api.reepay.com/v1/subscription" -u "priv_dbd002cf1313cb4213efcfb3afebfb66:" \
  -H  "Accept: application/json" -H  "Content-Type: application/json" -d \
  '{
    "handle": "leasing_00425",
    "plan": "leasing_gold",
    "signup_method": "email",
    "customer": "cust-0059",
    "add_ons": [
      {      
        "add_on": "super_laptop_x2",
        "handle": "sn764654216"   
      },
      {
        "add_on": "extended_laptop_support",
        "quantity": 1
      }
    ]
}'

{
  "handle": "leasing_00425",
  "customer": "cust-0059",
  "plan": "leasing_gold",
  "state": "active",
  ...,
  "subscription_add_ons": [
    "sn764654216",
    "extended_laptop_support"
  ]
}

When creating a subscription add-on the following can be defined

  • add_on - The add-on for this subscription add-on.
  • handle - This is an optional reference that can be provided if a reference to the specific subscription add-on is required. In this use-case the laptop serial number is used as this allows to lookup subscriptions involving the specific laptop. If no handle is provided, the add-on handle is used. As handle must be unique this means that only one instance of each add-on can be attached to a subscription in the case a custom handle is not provided.
  • quantity - For quantity type add-ons it is possible to define a quantity of the add-on for the subscription. The default is one.
  • fixed_amount - By default the subscription add-on is with a fixed amount. This means that amount is defined for the subscription add-on at creation, either by the add-on amount or using the amount parameter to define a custom fixed amount. If the amount on the add-on is later changed, it does not affect the subscription add-ons tied to this add-on. If fixed_amount is set to false, the pricing for the subscription add-on follows the add-on amount. This can be used in a consumable scenario where the price for subscription add-on is the price of the add-on at billing time.

Get all subscription add-ons for subscription

All subscription add-ons for a subscription can be fetched with the following call.

curl "https://api.reepay.com/v1/subscription/leasing_00425/add_on" \
  -u "priv_dbd002cf1313cb4213efcfb3afebfb66:" -H  "Accept: application/json"

[
  {
    "handle": "sn764654216",    
    "amount": 12900,
    "add_on": {
      "name": "Super Laptop X2",
      ...
    }
  },
  {
    "handle": "extended_laptop_support",
    "quantity": 1,
    "amount": 50000,
    "add_on": {
      "name": "Extended laptop support",
      ...
    }
  }
]

Querying for subscriptions with subscription add-on

Subscriptions can be fetched based on different filtering options. To get active subscriptions with a specific subscription add-on the following can be used.

curl "https://api.reepay.com/v1/list/subscription?subscription_add_on_handle=sn764654216&state=active" \
  -u "priv_dbd002cf1313cb4213efcfb3afebfb66:" -H  "Accept: application/json"

{
  "size": 20,
  "count": 1,
  "content": [
    {
      "handle": "leasing_00425",
      "customer": "cust-0059",
      "plan": "leasing_gold",
      "state": "active",
      ...
    }
  ],
  ...
}

In our use case this can be used to determine to whom a specific laptop is leased, and to determine under which terms the leasing is done by looking at the subscription plan.

To get subscriptions with subscription add-ons based on a specific add-on, the search parameter add_on.handle can be used.

Changing subscription add-ons

Changing subscription add-ons are done using the subscription change operation. A subscription change can either be scheduled for next subscription renewal, or it can be performed immediately. For an immediate change it can be controlled whether compensation should be done by a prorated refund, and it can be controlled how billing should be done for the remaining part of the period. Whether prorated refunding and billing should be done for immediate subscription add-on change depends on the type of add-ons and the terms for the subscription.

To change add-ons at renewal the following call can be performed. The changes will take effect just before billing for the next billing period. The change removes the current extended support, adds an additional laptop and adds extended support for two laptops.

curl -X PUT "https://api.reepay.com/v1/subscription/leasing_00425" -u "priv_dbd002cf1313cb4213efcfb3afebfb66:" \
  -H  "Accept: application/json" -H  "Content-Type: application/json" -d \
  '{
  "timing": "renewal",
  "remove_add_ons": [
    "extended_laptop_support"
  ],
  "add_ons": [
    {      
      "add_on": "super_laptop_x2",
      "handle": "sn643674219"   
    },
    {
      "add_on": "extended_laptop_support",
      "quantity": 2
    }
  ]
  }'

{
  "handle": "leasing_00425",
  "customer": "cust-0059",
  "plan": "leasing_gold",
  "state": "active",
  "pending_change": {
    "pending": true,
    "subscription_add_ons": [
      {
        "handle": "sn643674219",
        ...
      },
      {
        "handle": "extended_laptop_support",
        "quantity": 2,
        ...        
      }
    ],
    "remove_add_ons": [
      "extended_laptop_support"
    ]
  },
  "subscription_add_ons": [
    "sn764654216",
    "extended_laptop_support"
  ]
}

To perform an immediate prorated change the following call can be used. This removes extended support.

curl -X PUT "https://api.reepay.com/v1/subscription/leasing_00425" -u "priv_dbd002cf1313cb4213efcfb3afebfb66:" \
  -H  "Accept: application/json" -H  "Content-Type: application/json" -d \
  '{
  "timing": "immediate",
  "remove_add_ons": [
    "extended_laptop_support"
  ]
  }'

Proration is default. An immediate change without any compensation and billing can be performed using the following call that adds another laptop.

curl -X PUT "https://api.reepay.com/v1/subscription/leasing_00425" -u "priv_dbd002cf1313cb4213efcfb3afebfb66:" \
  -H  "Accept: application/json" -H  "Content-Type: application/json" -d \
  '{
  "timing": "immediate",
  "compensation_method": "none",
  "billing": "none",
  "add_ons": [
    {      
      "add_on": "super_laptop_x2",
      "handle": "sn643624219"   
    }
  ]
  }'

The difference between a change at renewal and an immediate change without compensation and new billing, is the fact that the subscription add-ons will be added immediately. The customer will also receive a subscription changed email if this is enabled.

Updated 12 months ago