---
title: "SearchSubscriptions"
method: POST
path: "/v2/subscriptions/search"
tags: ["Subscriptions"]
---

# SearchSubscriptions

`POST /v2/subscriptions/search`

Searches for subscriptions.
Results are ordered chronologically by subscription creation date. If
the request specifies more than one location ID,
the endpoint orders the result
by location ID, and then by creation date within each location. If no locations are given
in the query, all locations are searched.

You can also optionally specify `customer_ids` to search by customer.
If left unset, all customers
associated with the specified locations are returned.
If the request specifies customer IDs, the endpoint orders results
first by location, within location by customer ID, and within
customer by subscription creation date.

For more information, see
[Retrieve subscriptions](https://developer.squareup.com/docs/subscriptions-api/overview#retrieve-subscriptions).

## Request body

- SearchSubscriptionsRequest — Defines parameters in a [SearchSubscriptions](https://developer.squareup.com/reference/square_2021-08-18/subscriptions-api/search-subscriptions) endpoint request.
  - `cursor` string — A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
  - `limit` integer — The upper limit on the number of subscriptions to return in the response. Default: `200`
  - `query` SearchSubscriptionsQuery — Represents a query (including filtering criteria) used to search for subscriptions.
    - `filter` SearchSubscriptionsFilter — Represents a set of SearchSubscriptionsQuery filters used to limit the set of Subscriptions returned by SearchSubscriptions.
      - `customer_ids` string[] — A filter to select subscriptions based on the customer.
      - `location_ids` string[] — A filter to select subscriptions based the location.

## Response `200`

Success

- SearchSubscriptionsResponse — Defines the fields that are included in the response from the [SearchSubscriptions](https://developer.squareup.com/reference/square_2021-08-18/subscriptions-api/search-subscriptions) endpoint.
  - `cursor` string — When a response is truncated, it includes a cursor that you can use in a subsequent request to fetch the next set of subscriptions. If empty, this is the final response. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
  - `errors` Error[] — Information about errors encountered during the request.
    - `category` string, required — The high-level category for the error.
    - `code` string, required — The specific code of the error.
    - `detail` string — A human-readable description of the error for debugging purposes.
    - `field` string — The name of the field provided in the original request (if any) that the error pertains to.
  - `subscriptions` Subscription[] — The search result.
    - `canceled_date` string — The subscription cancellation date, in YYYY-MM-DD format (for example, 2013-01-15). On this date, the subscription status changes to `CANCELED` and the subscription billing stops. If you don't set this field, the subscription plan dictates if and when subscription ends. You cannot update this field, you can only clear it.
    - `card_id` string — The ID of the [customer](https://developer.squareup.com/reference/square_2021-08-18/objects/Customer) [card](https://developer.squareup.com/reference/square_2021-08-18/objects/Card) that is charged for the subscription.
    - `charged_through_date` string — The date up to which the customer is invoiced for the subscription, in YYYY-MM-DD format (for example, 2013-01-15). After the invoice is sent for a given billing period, this date will be the last day of the billing period. For example, suppose for the month of May a customer gets an invoice (or charged the card) on May 1. For the monthly billing scenario, this date is then set to May 31.
    - `created_at` string — The timestamp when the subscription was created, in RFC 3339 format.
    - `customer_id` string — The ID of the associated [customer](https://developer.squareup.com/reference/square_2021-08-18/objects/Customer) profile.
    - `id` string — The Square-assigned ID of the subscription.
    - `invoice_ids` string[] — The IDs of the [invoices](https://developer.squareup.com/reference/square_2021-08-18/objects/Invoice) created for the subscription, listed in order when the invoices were created (oldest invoices appear first).
    - `location_id` string — The ID of the location associated with the subscription.
    - `plan_id` string — The ID of the associated [subscription plan](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogSubscriptionPlan).
    - `price_override_money` Money — Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information.
      - `amount` integer — The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case.
      - `currency` string — The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values.
    - `start_date` string — The start date of the subscription, in YYYY-MM-DD format (for example, 2013-01-15).
    - `status` string — The current status of the subscription.
    - `tax_percentage` string — The tax amount applied when billing the subscription. The percentage is expressed in decimal form, using a `'.'` as the decimal separator and without a `'%'` sign. For example, a value of `7.5` corresponds to 7.5%.
    - `timezone` string — Timezone that will be used in date calculations for the subscription. Defaults to the timezone of the location based on `location_id`. Format: the IANA Timezone Database identifier for the location timezone (for example, `America/Los_Angeles`).
    - `version` integer — The version of the object. When updating an object, the version supplied must match the version in the database, otherwise the write will be rejected as conflicting.

---

[API](https://skmtc.net/square/apis/squareup.md) · [All operations](https://skmtc.net/square/apis/squareup/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/square/squareup/versions/8d95e3639487/schema)