Subscription Billing

in this guide we are going to show you how to programmatically setup subscription billing https //docs invoiced com/billing/subscription billing through the invoiced api quickstart guide in this example we are going to walk you through setting up a basic subscription billing scenario from scratch create a customer in order to bill our customer, we must first create an account for them on invoiced for this example we are going to use autopay https //docs invoiced com/payments/autopay , which will charge your customer's payment source automatically when invoices are issued on the account, including each billing cycle when the subscription renews curl "https //api invoiced com/customers" \\ u {api key} \\ d name="acme" \\ d email="billing\@acmecorp com" \\ d number="1234" \\ d autopay=1import com invoiced entity connection; import com invoiced entity customer; connection invoiced = new connection("{your api key}", false); customer customer = invoiced newcustomer(); customer name = "acme"; customer email = "billing\@acmecorp com"; customer autopay = true; customer create();\<?php $invoiced = new invoiced\client("{your api key}"); $customer = $invoiced >customer >create(\[ 'name' => "acme", 'email' => "billing\@acmecorp com", 'number' => "1234", 'autopay' => true ]);import invoiced client = invoiced client("{your api key}") customer = client customer create( name="acme", email="billing\@acmecorp com", number="1234", autopay=true )require "invoiced" invoiced = invoiced client new("{your api key}") customer = invoiced customer create( \ name => "acme", \ email => "billing\@acmecorp com", \ number => "1234", \ autopay => true ) since our customer does not have payment information yet, they will be sent the first invoice when they pay that invoice their payment information will be automatically saved because autopay is turned on subscribe the customer to a plan in this example we are going to bill for charges that happen during our customer's billing cycle, in addition to the base subscription price the plan we are using was created through the dashboard in settings → plans with the id starter for example, the plan could be $30/month curl "https //api invoiced com/subscriptions" \\ u {api key} \\ d customer={customer id} \\ d plan="starter"import com invoiced entity subscription; subscription subscription = invoiced newsubscription(); subscription customer = customer id; subscription plan = "starter"; subscription create();\<?php $invoiced >subscription >create(\[ &#x9;'customer' => $customer >id, &#x9;'plan' => "starter" ]);client subscription create( &#x9;customer=customer id, &#x9;plan="starter" )invoiced subscription create( &#x9;\ customer => customer id, &#x9;\ plan => "starter" ) subscriptions with addons subscription addons allow you to bill for multiple line items in the same billing cycle addons can represent a fixed recurring cost on top of the base price, such as extra user seats or more capacity than the base plan includes or addons can represent a usage based component that is added to the base price, where the amount varies each month depending on usage (see metered billing https //docs invoiced com/dev/metered billing for more information) underneath the hood an addon is just another plan added to a subscription in this example we are using a plan with the id ipad license that is $20/month curl "https //api invoiced com/subscriptions" \\ u {api key} \\ d customer={customer id} \\ d plan="starter" \\ d addons\[0]\[plan]="ipad license" \\ d addons\[0]\[quantity]=11 import com invoiced entity subscription; import com invoiced entity subscriptionaddon; subscription subscription = invoiced newsubscription(); subscription customer = customer id; subscription plan = "starter"; subscription addons = new subscriptionaddon\[1]; subscription addons\[0] = new subscriptionaddon(); subscription addons\[0] plan = "ipad license"; subscription addons\[0] quantity = 11; subscription create();\<?php $invoiced >subscription >create(\[ &#x9;'customer' => $customer >id, &#x9;'plan' => "starter", &#x9;'addons' => \[ &#x9; \[ &#x9; 'plan' => "ipad license", &#x9; 'quantity' => 11 &#x9; ] &#x9;] ]);client subscription create( &#x9;customer=customer id, &#x9;plan="starter", &#x9;addons=\[ &#x9; { &#x9; 'plan' "ipad license", &#x9; 'quantity' 11 &#x9; } &#x9;] )invoiced subscription create( &#x9;\ customer => customer id, &#x9;\ plan => "starter", &#x9;\ addons => \[ &#x9; { &#x9; \ plan => "ipad license", &#x9; \ quantity => 11 &#x9; } &#x9;] ) note an addon must use a plan that matches the billing interval of the subscription's primary plan (i e you cannot mix monthly and yearly plans on the same subscription) upgrades and downgrades occassionally a subscriber will need to modify their subscription for various reasons, which can result in an increased price (upgrade) or a decreased price (downgrade) subscription changes that affect the price include changing the billing interval (i e going from monthly to yearly billing), changing the base plan, adding or removing addons, and quantity adjustments of the subscription or addons invoiced handles subscription changes easily out of the box and will even perform proration calculations for you, up to the second changing a plan the easiest subscription change is to change the plan and/or quantity curl "https //api invoiced com/subscriptions/\ id" \\ u {api key} \\ d plan="pro" \\ x patchsubscription plan = "pro"; subscription save();\<?php $subscription >plan = "pro"; $subscription >save();subscription plan = "pro" subscription save()subscription plan = "pro" subscription save note if you change the base plan to a new billing interval (i e monthly to yearly) then any addons must match the billing interval of the new plan adding an addon addons can be added or removed, just as easily as changing the base plan curl "https //api invoiced com/subscriptions/\ id" \\ u {api key} \\ d addons\[0]\[plan]="extra users" \\ d addons\[0]\[quantity]=25 \\ x patchimport com invoiced entity subscriptionaddon; subscription addons = new subscriptionaddon\[1]; subscription addons\[0] = new subscriptionaddon(); subscription addons\[0] plan = "extra users"; subscription addons\[0] quantity = 25; subscription save();\<?php $subscription >addons = \[ \[ 'plan' => "extra users", 'quantity' => 25 ] ]; $subscription >save();subscription addons = \[ { 'plan' "extra users", 'quantity' 25 } ] subscription save()subscription addons = \[ { \ plan => "extra users", \ quantity => 25 } ] subscription save prorations when you make a change to a subscription that affects the price during the middle of the billing period, invoiced will by default generate a proration for the time remaining in the billing period the prorated amount will be added to the next bill, unless the billing interval is changing, in which case a new invoice will be generated immediately when modifying the subscription you can pass in prorate set to false in order to disable prorations if you are allowing prorations and want to change the timestamp used to generate the proration you can use the proration date parameter (defaults to current timestamp) note taxes and discounts are excluded from the proration calculations cancellations not all billing arrangements last forever when a customer is ready to cancel their subscription and stop billing this can be handled with a simple api call cancel immediately when canceling a subscription the cancellation will take effect immediately if you wish to return funds to your customer then you have to perform this calculation yourself curl "https //api invoiced com/subscriptions/\ id" \\ u {api key} \\ x deletesubscription cancel();\<?php $subscription >cancel();subscription cancel()subscription cancel note cancellations do not produce a proration cancel at end of period instead of canceling immediately, you can cancel the subscription at the end of the current billing period, or at the end of the current contract term if the subscription has a contract you might decide to use this because the customer has already paid for the month and they should continue to have access to your service for the full period the procedure for canceling at the end of the period is slightly different you will modify the subscription to set the cancel at period end property to true when the subscription is billed next (or up for contract renewal) then the subscription will be canceled instead of being billed curl "https //api invoiced com/subscriptions/\ id" \\ u {api key} \\ d cancel at period end=1 \\ x patchsubscription cancelatperiodend = true; subscription save();\<?php $subscription >cancel at period end = true; $subscription >save();subscription cancel at period end = true subscription save()subscription cancel at period end = true subscription save what's next? we have gone through several subscription billing workflows of course, business is not always that simple the subscription billing https //invoiced com/docs/api/#subscription billing section of the api reference details all of the subscription billing endpoints available to you