• Example searches: “transaction”, “CreateOrder”, “/v2/locations”, “inventory”, “delete customer”

You are viewing an old version of the API
Search subscriptions

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.

Permissions
SUBSCRIPTIONS_READ
Guide
Subscriptions Guide Try in API Explorer

Request Body

Example code
Name Description
cursor
string

When the total number of resulting subscriptions exceeds the limit of a paged response, specify the cursor returned from a preceding response here to fetch the next set of results. If the cursor is unset, the response contains the last page of the results.

For more information, see Pagination.
limit
integer (32-bit)

The upper limit on the number of subscriptions to return in a paged response.

Min 1
query
SearchSubscriptionsQuery

A subscription query consisting of specified filtering conditions.

If this query field is unspecified, the SearchSubscriptions call will return all subscriptions.
include
string [ ]
Beta

An option to include related information in the response.

The supported values are:

  • actions: to include scheduled actions on the targeted subscriptions.

Response Fields
Name Description
errors
Error [ ]

Errors encountered during the request.
subscriptions
Subscription [ ]

The subscriptions matching the specified query expressions.
cursor
string

When the total number of resulting subscription exceeds the limit of a paged response, the response includes a cursor for you to use in a subsequent request to fetch the next set of results. If the cursor is unset, the response contains the last page of the results.

For more information, see Pagination.

Examples

You are viewing an old version of the API
POST /v2/subscriptions/search
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js 
curl https://connect.squareup.com/v2/subscriptions/search \
  -X POST \
  -H 'Square-Version: 2022-11-16' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "location_ids": [
          "S8GWD5R9QB376"
        ],
        "customer_ids": [
          "CHFGVKYY8RSV93M5KCYTG4PN0G"
        ],
        "source_names": [
          "My App"
        ]
      }
    }
  }'
Response JSON 
{
  "subscriptions": [
    {
      "id": "de86fc96-8664-474b-af1a-abbe59cacf0e",
      "location_id": "S8GWD5R9QB376",
      "plan_id": "L3TJVDHVBEQEGQDEZL2JJM7R",
      "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G",
      "start_date": "2021-10-20",
      "canceled_date": "2021-10-20",
      "charged_through_date": "2021-11-20",
      "status": "CANCELED",
      "created_at": "2021-10-20T21:53:10Z",
      "card_id": "ccof:mueUsvgajChmjEbp4GB",
      "paid_until_date": "2021-11-20",
      "timezone": "UTC",
      "source": {
        "name": "My Application"
      }
    },
    {
      "id": "56214fb2-cc85-47a1-93bc-44f3766bb56f",
      "location_id": "S8GWD5R9QB376",
      "plan_id": "6JHXF3B2CW3YKHDV4XEM674H",
      "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G",
      "start_date": "2021-10-20",
      "status": "PENDING",
      "tax_percentage": "5",
      "price_override_money": {
        "amount": 100,
        "currency": "USD"
      },
      "version": 1594155459464,
      "created_at": "2021-10-20T21:53:10Z",
      "timezone": "America/Los_Angeles",
      "source": {
        "name": "My Application"
      }
    },
    {
      "id": "8151fc89-da15-4eb9-a685-1a70883cebfc",
      "location_id": "S8GWD5R9QB376",
      "plan_id": "6JHXF3B2CW3YKHDV4XEM674H",
      "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G",
      "start_date": "2021-10-20",
      "charged_through_date": "2021-11-20",
      "status": "ACTIVE",
      "invoice_ids": [
        "grebK0Q_l8H4fqoMMVvt-Q",
        "rcX_i3sNmHTGKhI4W2mceA"
      ],
      "price_override_money": {
        "amount": 1000,
        "currency": "USD"
      },
      "created_at": "2021-10-20T21:53:10Z",
      "paid_until_date": "2021-11-20",
      "timezone": "America/Los_Angeles",
      "source": {
        "name": "My Application"
      }
    }
  ]
}

Error Descriptions
400 Bad request CUSTOMER_NOT_FOUND

The provided customer id can't be found in the merchant's customers list.

 >
400 Bad request 
{
  "errors": [
    {
      "code": "CUSTOMER_NOT_FOUND",
      "category": "INVALID_REQUEST_ERROR"
    }
  ]
}