api: support free trials (#203)

This commit adds a Trial field to the Phase object accepted by the API
for creating and updating subscriptions and schedules. The new Trial
field tell Stripe to count the Phase as a trial phase, which Stripe will
honor by counting all features as free during the lifetime of the Phase.

This also adds the --trial=<days> flag to the CLI subscribe subcommand
for specifying trial periods. If days is negative, then a single phase
is scheduled as a trial that never ends. If days is zero, a single
non-trial phase is scheduled with the features/plans provided. If days
is positive, a trial phase is scheduled ending after the number of days
provided, followed by a phase that never ends for the features/plans
provided.

api/api.go

@@ -160,6 +160,7 @@ func (h *Handler) serveSubscribe(w http.ResponseWriter, r *http.Request) error {
 				return err
 			}
 			phases = append(phases, control.Phase{
+				Trial:     p.Trial,
 				Effective: p.Effective,
 				Features:  fs,
 			})

api/apitypes/apitypes.go

@@ -19,6 +19,7 @@ func (e *Error) Error() string {
 }
 
 type Phase struct {
+	Trial     bool
 	Effective time.Time
 	Features  []string
 }

cmd/tier/help.go

@@ -124,15 +124,23 @@ The output is in the format:
 `,
 	"subscribe": `Usage:
 
-	tier [--live] subscribe [--email=<email>] <org> [plan|featurePlan]...
+	tier [--live] subscribe [flags] <org> [plan|featurePlan]...
 
 Tier subscribe creates or updates a subscription for the provided org, applying
 the features in the plan.
 
-If the --live flag is provided, your accounts live mode will be used.
+Flags:
+
+	--email
+		set the org's email address
+	--trial days
+		set the org's trial period to the provided number of days. If
+		negative, the tial period will last indefinitely, and no other
+		phase will come after it.
 
-If the --email flag is provided, the org's email address will be set to the
-provided email address.
+Global Flags:
+
+If the --live flag is provided, your accounts live mode will be used.
 `,
 	"limits": `Usage:
 

cmd/tier/tier.go

@@ -255,6 +255,7 @@ func runTier(cmd string, args []string) (err error) {
 	case "subscribe":
 		fs := flag.NewFlagSet(cmd, flag.ExitOnError)
 		email := fs.String("email", "", "sets the customer email address")
+		trial := fs.Int("trial", 0, "sets the trial period in days")
 		if err := fs.Parse(args); err != nil {
 			return err
 		}
@@ -270,7 +271,24 @@ func runTier(cmd string, args []string) (err error) {
 		var refs []string
 		if fs.NArg() > 1 {
 			refs = fs.Args()[1:]
-			p.Phases = []tier.Phase{{Features: refs}}
+			switch {
+			case *trial > 0:
+				p.Phases = []tier.Phase{{
+					Trial:    true,
+					Features: refs,
+				}, {
+					Effective: time.Now().AddDate(0, 0, *trial),
+					Features:  refs,
+				}}
+			case *trial < 0:
+				// Indefinite trial, effective immediately.
+				p.Phases = []tier.Phase{{
+					Trial:    true,
+					Features: refs,
+				}}
+			default:
+				p.Phases = []tier.Phase{{Features: refs}}
+			}
 		}
 		vlogf("subscribing %s to %v", org, refs)
 		return tc().Schedule(ctx, org, p)

control/client.go

@@ -321,7 +321,6 @@ type stripePrice struct {
 	stripe.ID
 	LookupKey string `json:"lookup_key"`
 	Metadata  struct {
-		Plan      string           `json:"tier.plan"`
 		PlanTitle string           `json:"tier.plan_title"`
 		Feature   refs.FeaturePlan `json:"tier.feature"`
 		Limit     string           `json:"tier.limit"`