Create a subscription

To create a subscription, you first need to obtain a Billable model instance, which is usually an instance of App\User. Once you have obtained a model instance, you can create a subscription to the model using the newSubscription method:

$user = User::find(1);
$user->newSubscription('main', 'premium')->create($stripeToken);

newSubscription The first parameter to the method should be the name of the subscription. If your application only provides one subscription, you can set it to main or primary. The second parameter is the Stripe/Braintree plan the user is subscribed to. This value should correspond to an identifier in Stripe or Braintree. The

create method accepts a Stripe credit card/source token, which will start the subscription and update the database with the customer ID and other relevant billing information.

Additional details of the user

If you want to specify additional details of the user, you can do so by passing them as the second argument to create Method:

$user->newSubscription('main', 'monthly')->create($stripeToken, [
    'email' => $email,
   ]);

To learn more about the additional fields supported by Stripe or Braintree, check out Stripe's Content Creation Customer Documentation or the corresponding Braintree Documentation .

Coupon

If you want to use a coupon when creating a subscription, you can use the withCoupon method:

$user->newSubscription('main', 'monthly')  
   ->withCoupon('code')     
   ->create($stripeToken);

Checking Subscription Status

Once a user has subscribed in your app, you can easily check their subscription using a variety of convenient methods Subscription status. First, if the user has an active subscription, then the subscribed method will return true even if the subscription is currently in the trial phase:

if ($user->subscribed('main')) {
    //
  }

thissubscribed Method can also be used in routing middleware, allowing you to access routes and controllers based on the user's subscription status:

public function handle($request, Closure $next){
    if ($request->user() && ! $request->user()->subscribed('main')) {
      // This user is not a paying customer...        
      return redirect('billing');   
     }    
    return $next($request);
 }

If you want to determine whether the user is still in the trial phase, you can use onTrial method. This method is useful for showing a warning to the user that they are still in the trial period:

if ($user->subscription('main')->onTrial()) {
    //
   }

Based on a given Stripe/Braintree plan ID, the subscribedToPlan method can be used to determine whether the user is subscribed the plan. In this example, we will determine if the user's main subscription has the monthly plan activated: The

if ($user->subscribedToPlan('monthly', 'main')) {
    //
   }

recurring method can be used to determine if the user is currently Already subscribed and no longer in trial phase:

if ($user->subscription('main')->recurring()) {
    //
   }

Cancelled Subscription Status

To determine if a user was once subscribed, but has canceled their subscription, you can use the cancelled method:

if ($user->subscription('main')->cancelled()) {
    //
   }

You can also determine Whether the user has canceled the subscription, but is still in the "grace period" of the subscription until the subscription completely expires. For example, if a user cancels a subscription on March 5th that was due to expire on March 10th, the user will have a "grace period" until March 10th. Note that the subscribed method still returns true during this time:

if ($user->subscription('main')->onGracePeriod()) {
    //
  }

If you want to determine if the time the user unsubscribed is no longer within their "grace period", you can Use ended method:

if ($user->subscription('main')->ended()) {
    //
  }

Modify Subscription Plan

User in your application After subscribing, they may occasionally want to change to a new subscription plan. To switch a user to a new subscription, pass the subscription plan identifier to the swap method:

$user = App\User::find(1);
$user->subscription('main')->swap('provider-plan-id');

If the user is in a trial period, the duration of the trial period is retained. In addition, if there is a "share" for the number of subscriptions, that share will also be maintained.

If you want to cancel the trial period of the user's current subscription when changing the user's subscription plan, you can use the skipTrial method:

$user->subscription('main')    
    ->skipTrial()        
    ->swap('provider-plan-id');

Subscriptions

{Note} Subscriptions are only supported by Cashier's Stripe. Braintree doesn't have a "quantity" feature that corresponds to Stripe.

Sometimes subscriptions are affected by "quantity". For example, your app might be billed at per account $10/month. You can easily increase or decrease your subscription using the incrementQuantity and decrementQuantity methods:

$user = User::find(1);
$user->subscription('main')->incrementQuantity();
// 对当前的订阅量加5...
$user->subscription('main')->incrementQuantity(5);
$user->subscription('main')->decrementQuantity();
// 对当前的订阅量减5...
$user->subscription('main')->decrementQuantity(5);

Alternatively, you can use the updateQuantity method to set Set a specific quantity:

$user->subscription('main')->updateQuantity(10);

noProrate method can be used to update the quantity of the subscription without pricing the charge:

$user->subscription('main')->noProrate()->updateQuantity(10);

To get more information about the subscription quantity For information, please refer to the Stripe documentation.

Subscription tax amount

In billing mode Implement the taxPercentage method and return a number from 0 to 100 with no more than 2 decimal places, used to specify the tax rate percentage paid by the user in the subscription.

public function taxPercentage() {
    return 20;
   }

taxPercentage method enables you to apply tax rates on a model basis, which may be helpful for a user base that spans multiple countries and tax rates.

{Note} taxPercentage method is only applicable to paid subscription model. If you use charges to make "one-time" charges, you need to manually specify the tax rate at the same time.

Synchronize Tax Percentage

When changing the hardcoded value returned by the taxPercentage method, the tax rate settings for any existing subscriptions of the user will remain unchanged. If you want to update the tax rate for an existing subscription with the returned taxPercentage value, you should call the syncTaxPercentage method on the user's subscription instance:

$user->subscription('main')->syncTaxPercentage();

Subscription anchor date

{Note} Only Stripe in Cashier supports modifying the subscription anchor date.

By default, the billing cycle is anchored to the date the subscription was created, or if using a trial period, the date the trial ends. If you want to modify the billing anchor date, you can use the anchorBillingCycleOn method:

use App\User;use Carbon\Carbon;
$user = User::find(1);
$anchor = Carbon::parse('first day of next month');
$user->newSubscription('main', 'premium')      
      ->anchorBillingCycleOn($anchor->startOfDay())            
      ->create($stripeToken);

For more information about managing subscription billing cycles, see the Stripe Billing Cycle Documentation

Cancel subscription

Call the cancel method on the user subscription to cancel the subscription:

$user->subscription('main')->cancel();

When a subscription is canceled, Cashier will automatically set the ends_at column in your database. This column is often used to know when a subscribed field should start returning false. For example, if the customer cancels their subscription on March 1st, but the subscription plan does not end until March 5th, the subscribed method will continue to return true until March 5th.

You can use the onGracePeriod method to determine whether the user is sure to subscribe, but there is still a "grace period":

if ($user->subscription('main')->onGracePeriod()) {
    //
   }

If you want to cancel the subscription immediately, please cancel the subscription in the user's Call cancelNow method in subscription:

$user->subscription('main')->cancelNow();

Resume subscription

If a user has been canceled Subscription, you can use the resume method when you wish to resume it. The user must still be within their grace period before they can resume their subscription:

$user->subscription('main')->resume();

If a user has canceled their subscription and then resumes it before the subscription grace period, they will not be immediately counted fee. Instead, their subscription will be reactivated and they will need to pay again according to the original payment process.

Trial Subscription

Subscribe by credit card

If you want to offer your customers a trial period while collecting payment method information, then you should use the trialDays method when creating the subscription:

$user = User::find(1);$user->newSubscription('main', 'monthly')    
        ->trialDays(10)            
        ->create($stripeToken);

This method will set the end time of the subscription period on the database subscription record to tell Sripe/Braintree not to calculate the user's billing information before then.

{Note} Subscriptions are automatically billed if the customer does not cancel before the trial ends, so you should make sure to inform your users of the end of their trial. The

trialUntil method allows specifying the trial end period by providing a DateTime instance:

use Carbon\Carbon;$user->newSubscription('main', 'monthly')        
    ->trialUntil(Carbon::now()->addDays(10))            
    ->create($stripeToken);

You can use onTrial# of the user instance ## method or the onTrial method of the subscription instance determines whether the user is in the trial period. The following two examples are equivalent:

if ($user->onTrial('main')) { 
   //
  }
if ($user->subscription('main')->onTrial()) {  
  //
 }

trial_ends_at column of the user record to the desired trial end date, which is usually done during user registration:

$user = User::create([ 
   // Populate other user properties...    
   'trial_ends_at' => now()->addDays(10),
 ]);

{Note } Make sure you have added the

trial_ends_at date modifier to the model definition.

trail_ends_at value, the User instance's onTrial method will return true:

if ($user->onTrial()) { 
   // 用户在他们的试用期内...
  }

onGenericTrial method:

if ($user->onGenericTrial()) {
    // 用户在他们「一般」试用期...
   }

newSubsription method:

$user = User::find(1);
$user->newSubscription('main', 'monthly')->create($stripeToken);

createAsStripeCustomer method:

$user->createAsStripeCustomer();

{Tip} To create a customer in Braintree, use the

createAsBraintreeCustomer method.

cards method on a billable model instance returns a collection of Laravel\Cashier\Card instances:

$cards = $user->cards();

defaultCard method;

$card = $user->defaultCard();

if ($user->hasCardOnFile()) {
    //
   }

$user->updateCard($stripeToken);

$user->updateCardFromStripe();

foreach ($user->cards() as $card) {
    $card->delete();
  }

$user->deleteCards();

Route::post( 
   'stripe/webhook',    
   '\Laravel\Cashier\Http\Controllers\WebhookController@handleWebhook'
   );

protected $except = [
    'stripe/*',
   ];

<?php
    namespace App\Http\Controllers;
    use Laravel\Cashier\Http\Controllers\WebhookController as CashierController;
    class WebhookController extends CashierController{  
      /**
     * Handle invoice payment succeeded.
     *
     * @param  array  $payload
     * @return \Symfony\Component\HttpFoundation\Response
     */   
      public function handleInvoicePaymentSucceeded($payload)  
        {     
           // 此处处理事件   
         }
      }

Route::post( 
   'stripe/webhook',    
   '\App\Http\Controllers\WebhookController@handleWebhook'
  );

Route::post( 
   'stripe/webhook',    
   '\Laravel\Cashier\Http\Controllers\WebhookController@handleWebhook'
  );

Route::post(
    'braintree/webhook',    
    '\Laravel\Cashier\Http\Controllers\WebhookController@handleWebhook'
    );

protected $except = [ 
   'braintree/*',
  ];

<?php
    namespace App\Http\Controllers;
    use Braintree\WebhookNotification;
    use Laravel\Cashier\Http\Controllers\WebhookController as CashierController;
    class WebhookController extends CashierController{ 
       /**
     * Handle a new dispute.
     *
     * @param  \Braintree\WebhookNotification  $webhook
     * @return \Symfony\Component\HttpFoundation\Responses
     */  
      public function handleDisputeOpened(WebhookNotification $webhook)  
        {    
            // 此处处理时事件... 
         }
     }

Route::post(
    'braintree/webhook',    
    '\Laravel\Cashier\Http\Controllers\WebhookController@handleWebhook'
  );

// Stripe 接收分为单位的费用...
$stripeCharge = $user->charge(100);
// Braintree 接收美元为单位的费用...
$user->charge(1);

$user->charge(100, [ 
   'custom_option' => $value,
  ]);

try { 
   $response = $user->charge(100);
   } 
catch (Exception $e) {
    //
    }

// Stripe 接收分为单位的费用...
$user->invoiceFor('One Time Fee', 500);
// Braintree 接收美元为单位的费用...
$user->invoiceFor('One Time Fee', 5);

$user->invoiceFor('Stickers', 500,
 [
    'quantity' => 50,
 ], 
 [  
      'tax_percent' => 21,
 ]);

$user->invoiceFor('One Time Fee', 500,
 [
     'description' => 'your invoice description here',
 ]);

$stripeCharge = $user->charge(100);
$user->refund($stripeCharge->id);

$invoices = $user->invoices();
// 结果包含处理中的发票...
$invoices = $user->invoicesIncludingPending();

<table>
    @foreach ($invoices as $invoice) 
    <tr>
       <td>{{ $invoice->date()->toFormattedDateString() }}</td>            
       <td>{{ $invoice->total() }}</td>            
       <td><a href="/user/invoice/{{ $invoice->id }}">Download</a></td>        
     </tr>
    @endforeach
</table>

use Illuminate\Http\Request;
Route::get('user/invoice/{invoice}', function (Request $request, $invoiceId) {
    return $request->user()->downloadInvoice($invoiceId, [ 
           'vendor'  => 'Your Company',        
           'product' => 'Your Product',    
         ]);
     });