# List subscriptions By default, returns a list of subscriptions that have not been canceled. In order to list canceled subscriptions, specify `status=canceled`. ## Returns Returns a list of subscriptions. ## Parameters - `automatic_tax` (object, optional) Filter subscriptions by their automatic tax settings. - `automatic_tax.enabled` (boolean, required) Enabled automatic tax calculation which will automatically compute tax rates on all invoices generated by the subscription. - `collection_method` (enum, optional) The collection method of the subscriptions to retrieve. Either `charge_automatically` or `send_invoice`. Possible enum values: - `charge_automatically` - `send_invoice` - `created` (object, optional) Only return subscriptions that were created during the given date interval. - `created.gt` (integer, optional) Minimum value to filter by (exclusive) - `created.gte` (integer, optional) Minimum value to filter by (inclusive) - `created.lt` (integer, optional) Maximum value to filter by (exclusive) - `created.lte` (integer, optional) Maximum value to filter by (inclusive) - `current_period_end` (object, optional) Only return subscriptions whose minimum item current_period_end falls within the given date interval. - `current_period_end.gt` (integer, optional) Minimum value to filter by (exclusive) - `current_period_end.gte` (integer, optional) Minimum value to filter by (inclusive) - `current_period_end.lt` (integer, optional) Maximum value to filter by (exclusive) - `current_period_end.lte` (integer, optional) Maximum value to filter by (inclusive) - `current_period_start` (object, optional) Only return subscriptions whose maximum item current_period_start falls within the given date interval. - `current_period_start.gt` (integer, optional) Minimum value to filter by (exclusive) - `current_period_start.gte` (integer, optional) Minimum value to filter by (inclusive) - `current_period_start.lt` (integer, optional) Maximum value to filter by (exclusive) - `current_period_start.lte` (integer, optional) Maximum value to filter by (inclusive) - `customer` (string, optional) The ID of the customer whose subscriptions you’re retrieving. - `customer_account` (string, optional) The ID of the account representing the customer whose subscriptions you’re retrieving. - `ending_before` (string, optional) A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list. - `limit` (integer, optional) A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. - `price` (string, optional) Filter for subscriptions that contain this recurring price ID. - `starting_after` (string, optional) A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list. - `status` (enum, optional) The status of the subscriptions to retrieve. Passing in a value of `canceled` will return all canceled subscriptions, including those belonging to deleted customers. Pass `ended` to find subscriptions that are canceled and subscriptions that are expired due to [incomplete payment](https://docs.stripe.com/docs/billing/subscriptions/overview.md#subscription-statuses). Passing in a value of `all` will return subscriptions of all statuses. If no value is supplied, all subscriptions that have not been canceled are returned. - `test_clock` (string, optional) Filter for subscriptions that are associated with the specified test clock. The response will not include subscriptions with test clocks if this and the customer parameter is not set. ```php $stripe = new \Stripe\StripeClient('<>'); $subscriptions = $stripe->subscriptions->all(['limit' => 3]); ``` ### Response ```json { "object": "list", "url": "/v1/subscriptions", "has_more": false, "data": [ { "id": "sub_1MowQVLkdIwHu7ixeRlqHVzs", "object": "subscription", "application": null, "application_fee_percent": null, "automatic_tax": { "enabled": false, "liability": null }, "billing_cycle_anchor": 1679609767, "cancel_at": null, "cancel_at_period_end": false, "canceled_at": null, "cancellation_details": { "comment": null, "feedback": null, "reason": null }, "collection_method": "charge_automatically", "created": 1679609767, "currency": "usd", "customer": "cus_Na6dX7aXxi11N4", "days_until_due": null, "default_payment_method": null, "default_source": null, "default_tax_rates": [], "description": null, "discounts": null, "ended_at": null, "invoice_settings": { "issuer": { "type": "self" } }, "items": { "object": "list", "data": [ { "id": "si_Na6dzxczY5fwHx", "object": "subscription_item", "created": 1679609768, "current_period_end": 1682288167, "current_period_start": 1679609767, "metadata": {}, "plan": { "id": "price_1MowQULkdIwHu7ixraBm864M", "object": "plan", "active": true, "amount": 1000, "amount_decimal": "1000", "billing_scheme": "per_unit", "created": 1679609766, "currency": "usd", "discounts": null, "interval": "month", "interval_count": 1, "livemode": false, "metadata": {}, "nickname": null, "product": "prod_Na6dGcTsmU0I4R", "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "price": { "id": "price_1MowQULkdIwHu7ixraBm864M", "object": "price", "active": true, "billing_scheme": "per_unit", "created": 1679609766, "currency": "usd", "custom_unit_amount": null, "livemode": false, "lookup_key": null, "metadata": {}, "nickname": null, "product": "prod_Na6dGcTsmU0I4R", "recurring": { "interval": "month", "interval_count": 1, "trial_period_days": null, "usage_type": "licensed" }, "tax_behavior": "unspecified", "tiers_mode": null, "transform_quantity": null, "type": "recurring", "unit_amount": 1000, "unit_amount_decimal": "1000" }, "quantity": 1, "subscription": "sub_1MowQVLkdIwHu7ixeRlqHVzs", "tax_rates": [] } ], "has_more": false, "total_count": 1, "url": "/v1/subscription_items?subscription=sub_1MowQVLkdIwHu7ixeRlqHVzs" }, "latest_invoice": "in_1MowQWLkdIwHu7ixuzkSPfKd", "livemode": false, "metadata": {}, "next_pending_invoice_item_invoice": null, "on_behalf_of": null, "pause_collection": null, "payment_settings": { "payment_method_options": null, "payment_method_types": null, "save_default_payment_method": "off" }, "pending_invoice_item_interval": null, "pending_setup_intent": null, "pending_update": null, "schedule": null, "start_date": 1679609767, "status": "active", "test_clock": null, "transfer_data": null, "trial_end": null, "trial_settings": { "end_behavior": { "missing_payment_method": "create_invoice" } }, "trial_start": null } ] } ```