Subscriptions
Create, update, delete, and query the available Subscriptions in Stripe.
Table Specific Information
Select
Server-Side Query Support
The driver will use the Stripe API to filter the results by the following columns and operators while the rest of the filter is executed client side within the driver.
- Id, CustomerId, CreatedAt, PlanId, and Status support the following operators: <,>>=,<,<=,=.
The provider supports all columns to be used as criteria in the WHERE clause of Select statement, as long as SupportEnhancedSQL is set to True. If SupportEnhancedSQL property is set to False, you still can retrieve:
-a Subscription by specifying its Id:
SELECT * FROM Subscriptions WHERE Id = 'mySubscriptionId'
-Subscriptions created after a specific date (Created may be used with the >, >=, <, <=, or = conditions and may be used twice to specify a range):
SELECT * FROM Subscriptions WHERE CreatedAt > '2016-01-03'
-Subscriptions that belong to a Customer:
SELECT * FROM Subscriptions WHERE CustomerId = 'cus_12345678'
-Subscriptions that belong to a Plan:
SELECT * FROM Subscriptions WHERE PlanId = 'myPlanId'
-Subscriptions with a specific Status:
SELECT * FROM Subscriptions WHERE Status = 'active'
Insert
CustomerId and PlanId columns are required to create a new subscription .
INSERT INTO Subscriptions (CustomerId,PlanId,ApplicationFeePercent,Quantity,TaxPercent,TrialEnd) VALUES ('cus_A8PXYRQoPlrgpR','123-z72a0xda9',1,100,10,'2017-12-12')
To apply a discount to a new subscription, set the CouponId field:
INSERT INTO Subscriptions (CustomerId,PlanId,ApplicationFeePercent,Quantity,TaxPercent,TrialEnd,CouponId) VALUES ('cus_A8PXYRQoPlrgpR','123-z72a0xda9',1,100,10,'2017-12-12','cup_123456')
Update
To update a subscription, specify Id column.
UPDATE Subscriptions SET ApplicationFeePercent=0, Quantity=500, TaxPercent=10, IsProrate = true WHERE Id = 'sub_A9WZGVTbvgBJ4t'
To apply a discount to an existing subscription, set the CouponId field:
UPDATE Subscriptions SET CouponId = 'cup_123456' WHERE Id = 'sub_A9WZGVTbvgBJ4t'
Delete
To delete a subscription specify the Id of the subscription.
DELETE FROM Subscriptions WHERE Id = 'sub_A9WZGVTbvgBJ4t'
Columns
| Name | Type | ReadOnly | References | Description |
| Id [KEY] | String | True |
The Id of the subscription. | |
| CustomerId | String | False |
Customers.Id |
The Id of the customer who owns the subscription. |
| PlanId | String | False |
Plans.Id |
The Id of the plan. |
| ApplicationFeePercent | Decimal | False |
A positive decimal that represents the fee percentage of the subscription invoice amount that will be transferred to the application of the Stripe account owner each billing period. | |
| CancelAtPeriodEnd | Boolean | True |
If the subscription has been canceled with the at_period_end flag set to true, cancel_at_period_end on the subscription will be true. You can use this attribute to determine whether a subscription that has a status of active is scheduled to be canceled at the end of the current period. | |
| CanceledAt | Datetime | True |
If the subscription has been canceled, the date of that cancellation. If the subscription was canceled with cancel_at_period_end, canceled_at will still reflect the date of the initial cancellation request, not the end of the subscription period when the subscription is automatically moved to a canceled state. | |
| CreatedAt | Datetime | True |
The creation date. | |
| CurrentPeriodEnd | Datetime | True |
End of the current period that the subscription has been invoiced for. At the end of this period, a new invoice will be created. | |
| CurrentPeriodStart | Datetime | True |
Start of the current period that the subscription has been invoiced for. | |
| CouponId | String | False |
SubscriptionDiscounts.CouponId |
The id of the discount. |
| EndedAt | Datetime | True |
If the subscription has ended (either because it was canceled or because the customer was switched to a subscription to a new plan), the date the subscription ended. | |
| Quantity | Double | False |
The quantity of the plan to which the customer should be subscribed. For example, if your plan is $10/user/month, and your customer has 5 users, you could pass 5 as the quantity to have the customer charged $50 (5 x $10) monthly. | |
| Start | Datetime | True |
Date the most recent update to this subscription started. | |
| Status | String | True |
The status of the subscription The allowed values are active, past_due, unpaid, canceled, incomplete, incomplete_expired, trialing, all, ended. | |
| TaxPercent | Decimal | False |
If provided, each invoice created by this subscription will apply the tax rate, increasing the amount billed to the customer. | |
| TrialEnd | Datetime | False |
If the subscription has a trial, the end of that trial. | |
| TrialStart | Datetime | True |
If the subscription has a trial, the beginning of that trial. | |
| MetadataAggregate | String | False |
The set of key/value pairs that you can attach to a subscription object. | |
| BillingCycleAnchor | Datetime | True |
Determines the date of the first full invoice, and, for plans with month or year intervals, the day of the month for subsequent invoices. | |
| DefaultPaymentMethod | String | False |
ID of the default payment method for the subscription | |
| ItemsAggregate | String | False |
List of subscription items, each with an attached price. | |
| LatestInvoice | String | False |
The ID of the most recent invoice this subscription has generated. | |
| PendingSetupIntent | String | False |
You can use this SetupIntent to collect user authentication when creating a subscription without immediate payment or updating a subscription's payment method, allowing you to optimize for off-session payments. | |
| PendingUpdate | String | False |
If specified, pending updates that will be applied to the subscription once the latest_invoice has been paid. | |
| BillingThresholds | String | False |
Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period | |
| AutomaticTaxEnabled | Boolean | False |
Automatic tax settings for this subscription. | |
| AutomaticTaxStatus | String | False |
The status of the most recent automated tax calculation for this subscription. | |
| CollectionMethod | String | False |
Either charge_automatically, or send_invoice. When charging automatically, Stripe will attempt to pay this subscription at the end of the cycle using the default source attached to the customer. | |
| DaysUntilDue | Integer | False |
Number of days a customer has to pay invoices generated by this subscription. This value will be null for subscriptions where collection_method=charge_automatically | |
| DefaultSource | String | False |
ID of the default payment source for the subscription. | |
| DefaultTaxRates | String | False |
The tax rates that will apply to any subscription item that does not have tax_rates set. Invoices created will have their default_tax_rates populated from the subscription. | |
| LiveMode | Integer | False |
Has the value true if the object exists in live mode or the value false if the object exists in test mode. | |
| NextPendingInvoiceItemInvoice | Datetime | False |
Specifies the approximate timestamp on which any pending invoice items will be billed according to the schedule provided at pending_invoice_item_interval | |
| PauseCollection | String | False |
If specified, payment collection for this subscription will be paused. | |
| PaymentSettings | String | False |
Payment settings passed on to invoices created by the subscription. | |
| PendingInvoiceItemInterval | String | False |
Specifies an interval for how often to bill for any pending invoice items. It is analogous to calling Create an invoice for the given subscription at the specified interval. | |
| Schedule | String | False |
The schedule attached to the subscription | |
| TestClock | String | False |
ID of the test clock this customer belongs to. | |
| TransferData | String | False |
The account (if any) the subscription's payments will be attributed to for tax reporting, and where funds from each payment will be transferred to for each of the subscription's invoices. | |
| CancelAt | Datetime | False |
A date in the future at which the subscription will automatically get canceled. | |
| Description | String | False |
The subscription's description. |
Pseudo-Columns
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
| Name | Type | Description |
| IsProrate | Boolean |
Flag indicating whether to prorate switching plans during a billing cycle. |
| ProrationDate | Date |
If set, the proration will be calculated as though the subscription was updated at the given time. It can also be used to implement custom proration logic, such as prorating by day instead of by second, by providing the time that you wish to use for proration calculations. |
| TrialPeriodDays | Integer |
The number of trial period days before the customer is charged for the first time. If set, trial_period_days overrides the default trial period days of the plan the customer is being subscribed to. |
| AccountId | String |
The Id of the connected account to get subscriptions for. |