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

You are viewing an old version of the API
Search subscriptions BETA

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
Name Description
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.

limit
integer

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

Default: 200

Min 1
query
SearchSubscriptionsQuery

Query subscriptions based on the given conditions and sort order. Calling SearchSubscriptions without an explicit query parameter will return all subscriptions.

Response Fields

Name Description
errors
Error [ ]

Information about errors encountered during the request.

subscriptions
Subscription [ ]

The search result.

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.

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: 2021-01-21' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "location_ids": [
          "S8GWD5R9QB376"
        ],
        "customer_ids": [
          "CHFGVKYY8RSV93M5KCYTG4PN0G"
        ]
      }
    }
  }'
Response JSON
{
  "subscriptions": [
    {
      "id": "de86fc96-8664-474b-af1a-abbe59cacf0e",
      "location_id": "S8GWD5R9QB376",
      "plan_id": "L3TJVDHVBEQEGQDEZL2JJM7R",
      "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G",
      "start_date": "2020-04-14",
      "canceled_date": "2020-04-14",
      "charged_through_date": "2020-05-14",
      "status": "CANCELED",
      "created_at": "2020-08-03T21:53:10Z",
      "card_id": "ccof:mueUsvgajChmjEbp4GB",
      "paid_until_date": "2020-05-14",
      "timezone": "UTC"
    },
    {
      "id": "56214fb2-cc85-47a1-93bc-44f3766bb56f",
      "location_id": "S8GWD5R9QB376",
      "plan_id": "6JHXF3B2CW3YKHDV4XEM674H",
      "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G",
      "start_date": "2020-08-01",
      "status": "PENDING",
      "tax_percentage": "5",
      "price_override_money": {
        "amount": 100,
        "currency": "USD"
      },
      "version": 1594155459464,
      "created_at": "2020-08-03T21:53:10Z",
      "timezone": "America/Los_Angeles"
    },
    {
      "id": "8151fc89-da15-4eb9-a685-1a70883cebfc",
      "location_id": "S8GWD5R9QB376",
      "plan_id": "6JHXF3B2CW3YKHDV4XEM674H",
      "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G",
      "start_date": "2020-05-11",
      "charged_through_date": "2020-06-11",
      "status": "ACTIVE",
      "invoice_ids": [
        "grebK0Q_l8H4fqoMMVvt-Q",
        "rcX_i3sNmHTGKhI4W2mceA"
      ],
      "price_override_money": {
        "amount": 1000,
        "currency": "USD"
      },
      "created_at": "2020-08-03T21:53:10Z",
      "paid_until_date": "2020-06-11",
      "timezone": "America/Los_Angeles"
    }
  ]
}

Share Feedback

Thanks for visiting the Square API documentation. What's on your mind?