# List Subscriptions

GET https://services.leadconnectorhq.com/payments/subscriptions

The "List Subscriptions" API allows to retrieve a paginated list of subscriptions. Customize your results by filtering subscriptions based on name, alt type, subscription status, payment mode, date range, type of source, contact, subscription id, entity id, contact or paginate through the list using the provided query parameters. This endpoint provides a straightforward way to explore and retrieve subscription information.

## Authentication

Send `Authorization: Bearer <token>` using:

- **Sub-Account token: OAuth access token or Private Integration Token.** Scopes: `payments/subscriptions.readonly`

## Parameters

### Header Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `Version` | string | Yes | API Version |

### Query Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `altId` | string | Yes | AltId is the unique identifier e.g: location id. |
| `altType` | string | Yes | AltType is the type of identifier. |
| `entityId` | string | No | Entity id for filtering of subscriptions. |
| `paymentMode` | string | No | Mode of payment. |
| `startAt` | string | No | Starting interval of subscriptions. |
| `endAt` | string | No | Closing interval of subscriptions. |
| `entitySourceType` | string | No | Source of the subscriptions. |
| `search` | string | No | The name of the subscription for searching. |
| `contactId` | string | No | Contact ID for the subscription |
| `id` | string | No | Subscription id for filtering of subscriptions. |
| `limit` | number | No | The maximum number of items to be included in a single page of results |
| `offset` | number | No | The starting index of the page, indicating the position from which the results should be retrieved. |
| `getPaymentsCollectedCount` | boolean | No | Get the total payments collected for the subscription. |

## OpenAPI Specification

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "LeadConnector API",
    "version": "v3"
  },
  "servers": [
    {
      "url": "https://services.leadconnectorhq.com"
    }
  ],
  "paths": {
    "/payments/subscriptions": {
      "get": {
        "summary": "List Subscriptions",
        "operationId": "listSubscriptions",
        "description": "The \"List Subscriptions\" API allows to retrieve a paginated list of subscriptions. Customize your results by filtering subscriptions based on name, alt type, subscription status, payment mode, date range, type of source, contact, subscription id, entity id, contact or paginate through the list using the provided query parameters. This endpoint provides a straightforward way to explore and retrieve subscription information.",
        "parameters": [
          {
            "name": "Version",
            "in": "header",
            "description": "API Version",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "v3"
              ]
            }
          },
          {
            "name": "altId",
            "required": true,
            "in": "query",
            "description": "AltId is the unique identifier e.g: location id.",
            "schema": {
              "example": "3SwdhCu3svxI8AKsPJt6",
              "type": "string"
            }
          },
          {
            "name": "altType",
            "required": true,
            "in": "query",
            "description": "AltType is the type of identifier.",
            "schema": {
              "example": "location",
              "enum": [
                "location"
              ],
              "type": "string"
            }
          },
          {
            "name": "entityId",
            "required": false,
            "in": "query",
            "description": "Entity id for filtering of subscriptions.",
            "schema": {
              "example": "61dd0fe9c077f73e67f78803",
              "type": "string"
            }
          },
          {
            "name": "paymentMode",
            "required": false,
            "in": "query",
            "description": "Mode of payment.",
            "schema": {
              "example": "live",
              "type": "string"
            }
          },
          {
            "name": "startAt",
            "required": false,
            "in": "query",
            "description": "Starting interval of subscriptions.",
            "schema": {
              "example": "2024-02-01",
              "type": "string"
            }
          },
          {
            "name": "endAt",
            "required": false,
            "in": "query",
            "description": "Closing interval of subscriptions.",
            "schema": {
              "example": "2024-02-13",
              "type": "string"
            }
          },
          {
            "name": "entitySourceType",
            "required": false,
            "in": "query",
            "description": "Source of the subscriptions.",
            "schema": {
              "example": "funnel",
              "type": "string"
            }
          },
          {
            "name": "search",
            "required": false,
            "in": "query",
            "description": "The name of the subscription for searching.",
            "schema": {
              "example": "Awesome subscription",
              "type": "string"
            }
          },
          {
            "name": "contactId",
            "required": false,
            "in": "query",
            "description": "Contact ID for the subscription",
            "schema": {
              "example": "AmuzcoPBpgKeccNsFlib",
              "type": "string"
            }
          },
          {
            "name": "id",
            "required": false,
            "in": "query",
            "description": "Subscription id for filtering of subscriptions.",
            "schema": {
              "example": "64bf78af39118e4011926cba",
              "type": "string"
            }
          },
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "description": "The maximum number of items to be included in a single page of results",
            "schema": {
              "default": 10,
              "example": 20,
              "type": "number"
            }
          },
          {
            "name": "offset",
            "required": false,
            "in": "query",
            "description": "The starting index of the page, indicating the position from which the results should be retrieved.",
            "schema": {
              "default": 0,
              "example": 0,
              "type": "number"
            }
          },
          {
            "name": "getPaymentsCollectedCount",
            "required": false,
            "in": "query",
            "description": "Get the total payments collected for the subscription.",
            "schema": {
              "example": "true",
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListSubscriptionResponseDto"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestDTO"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedDTO"
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable Entity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnprocessableDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Location-Access": [
              "payments/subscriptions.readonly"
            ]
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "name": "Authorization",
        "in": "header",
        "description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.",
        "type": "http"
      },
      "Location-Access": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "name": "Authorization",
        "in": "header",
        "description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.",
        "type": "http"
      },
      "Location-Access-Only": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "name": "Authorization",
        "in": "header",
        "description": "Use the Access Token generated with user type as Sub-Account.",
        "type": "http"
      },
      "Agency-Access": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "name": "Authorization",
        "in": "header",
        "description": "Use the Access Token generated with user type as Agency (OR) Private Integration Token of Agency.",
        "type": "http"
      },
      "Agency-Access-Only": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "name": "Authorization",
        "in": "header",
        "description": "Use the Access Token generated with user type as Agency.",
        "type": "http"
      }
    },
    "schemas": {
      "ListSubscriptionResponseDto": {
        "type": "object",
        "properties": {
          "data": {
            "description": "An array of subscriptions",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "_id": {
                  "type": "string",
                  "description": "The unique identifier for the subscription.",
                  "example": "64bf78af39118e4011926cba"
                },
                "altId": {
                  "type": "string",
                  "description": "AltId is the unique identifier eg: location id.",
                  "example": "3SwdhCu3svxI8AKsPJt6"
                },
                "altType": {
                  "type": "string",
                  "example": "location",
                  "description": "AltType is the type of identifier.",
                  "enum": [
                    "location"
                  ]
                },
                "contactId": {
                  "type": "string",
                  "example": "XPLSw2SVagl12LMDeTmQ",
                  "description": "Contact id corresponding to the subscription."
                },
                "contactName": {
                  "type": "string",
                  "example": "James Bond",
                  "description": "Contact name corresponding to the subscription."
                },
                "contactEmail": {
                  "type": "string",
                  "example": "james.bond@gohighlevel.com",
                  "description": "Contact email corresponding to the subscription."
                },
                "currency": {
                  "type": "string",
                  "example": "USD",
                  "description": "Currency in which subscription occurred."
                },
                "amount": {
                  "type": "number",
                  "example": "100",
                  "description": "Subscription value."
                },
                "status": {
                  "type": "object",
                  "description": "The status of the subscription (e.g., succeeded).",
                  "example": "active"
                },
                "liveMode": {
                  "type": "boolean",
                  "example": "false",
                  "description": "Subscription is in live / test mode."
                },
                "entityType": {
                  "type": "string",
                  "example": "order",
                  "description": "Entity type of subscription (eg: order)."
                },
                "entityId": {
                  "type": "string",
                  "example": "62f4db0f3059ecee61379012",
                  "description": "Entity id for the subscription. e.g: order id"
                },
                "entitySourceType": {
                  "type": "string",
                  "example": "funnel",
                  "description": "Entity source type of subscription (eg: funnel)."
                },
                "entitySourceName": {
                  "type": "string",
                  "example": "Attribution Funnel",
                  "description": "Entity source name for the subscription."
                },
                "entitySourceId": {
                  "type": "string",
                  "description": "Entity source id for the subscription.",
                  "example": "bevrkPbLaDNXFaqfLKMm"
                },
                "entitySourceMeta": {
                  "type": "object",
                  "description": "Meta content for the entity source of subscription.",
                  "example": "{ domain: \"app.gohighlevel.com\", pageId:  \"sxC4lNhFIavEnLZh5KhC\", pageUrl:  \"/v2/preview/sxC4lNhFIavEnLZh5KhC\", stepId: \"7d303d1f-cb85-403d-b548-bf01de5c7bb0\" }"
                },
                "subscriptionId": {
                  "type": "string",
                  "example": "I-0UE609H8E43P",
                  "description": "Subscription id for subscription."
                },
                "subscriptionSnapshot": {
                  "type": "object",
                  "description": "Snapshot of subscription.",
                  "example": "{ status: \"ACTIVE\", status_update_time: \"2022-08-16T11:06:53Z\", id: \"I-0UE609H8E43P\", plan_id: \"P-82K11750F0313430KMLRGE6Y\", start_time: \"2022-08-16T11:05:31Z\", quantity: 1 }"
                },
                "paymentProviderType": {
                  "type": "string",
                  "example": "stripe",
                  "description": "Payment provider for subscription."
                },
                "paymentProviderConnectedAccount": {
                  "type": "string",
                  "example": "ATn0CqrzrWS5ak185Bsb1xCpyzBDOZ8WdRxyFotppLYePTDhiuQ49H5QXO_L-4HKk1GBn7f9_QhbNK2s",
                  "description": "Payment provider connected account id for subscription."
                },
                "ipAddress": {
                  "type": "string",
                  "example": "103.100.16.82",
                  "description": "Ip address from where subscription was initiated."
                },
                "createdAt": {
                  "format": "date-time",
                  "type": "string",
                  "description": "The creation timestamp of the subscription.",
                  "example": "2023-11-20T10:23:36.515Z"
                },
                "updatedAt": {
                  "format": "date-time",
                  "type": "string",
                  "description": "The update timestamp of the subscription.",
                  "example": "2023-11-20T10:23:36.515Z"
                },
                "createdBy": {
                  "type": "string",
                  "example": "user123",
                  "description": "User ID who created the subscription."
                }
              },
              "required": [
                "_id",
                "altId",
                "altType",
                "status",
                "entitySourceType",
                "createdAt",
                "updatedAt"
              ],
              "title": "SubscriptionResponseSchema"
            }
          },
          "totalCount": {
            "type": "number",
            "description": "total subscriptions count"
          }
        },
        "required": [
          "data",
          "totalCount"
        ],
        "title": "ListSubscriptionResponseDto"
      },
      "BadRequestDTO": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "number",
            "example": 400
          },
          "message": {
            "type": "string",
            "example": "Bad Request"
          }
        },
        "title": "BadRequestDTO"
      },
      "UnauthorizedDTO": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "number",
            "example": 401
          },
          "message": {
            "type": "string",
            "example": "Invalid token: access token is invalid"
          },
          "error": {
            "type": "string",
            "example": "Unauthorized"
          }
        },
        "title": "UnauthorizedDTO"
      },
      "UnprocessableDTO": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "number",
            "example": 422
          },
          "message": {
            "example": [
              "Unprocessable Entity"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "error": {
            "type": "string",
            "example": "Unprocessable Entity"
          }
        },
        "title": "UnprocessableDTO"
      }
    }
  }
}
```

## Code Examples

**cURL**

```bash
curl -L -X GET 'https://services.leadconnectorhq.com/payments/subscriptions?altId=<ALTID>&altType=<ALTTYPE>' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Version: v3'
```

**Node.js**

```javascript
const options = {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <TOKEN>',
    Version: 'v3'
  }
};

try {
  const response = await fetch('https://services.leadconnectorhq.com/payments/subscriptions?altId=<ALTID>&altType=<ALTTYPE>', options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

**Python**

```python
import requests

url = "https://services.leadconnectorhq.com/payments/subscriptions"

headers = {
    "Authorization": "Bearer <TOKEN>",
    "Version": "v3"
}

params = {
    "altId": "<ALTID>",
    "altType": "<ALTTYPE>"
}

response = requests.get(url, params=params, headers=headers)
print(response.json())
```

**PHP**

```php
<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://services.leadconnectorhq.com/payments/subscriptions?altId=<ALTID>&altType=<ALTTYPE>',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <TOKEN>',
    'Version: v3',
  ],
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;
```

**Java**

```java
HttpResponse<String> response = Unirest
  .get("https://services.leadconnectorhq.com/payments/subscriptions?altId=<ALTID>&altType=<ALTTYPE>")
  .header("Authorization", "Bearer <TOKEN>")
  .header("Version", "v3")
  .asString();
```

**Go**

```go
package main

import (
  "fmt"
  "net/http"
  "io"
)

func main() {
  url := "https://services.leadconnectorhq.com/payments/subscriptions?altId=<ALTID>&altType=<ALTTYPE>"
  req, _ := http.NewRequest("GET", url, nil)
  req.Header.Add("Authorization", "Bearer <TOKEN>")
  req.Header.Add("Version", "v3")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)
  fmt.Println(string(body))
}
```

**Ruby**

```ruby
require 'uri'
require 'net/http'

url = URI("https://services.leadconnectorhq.com/payments/subscriptions?altId=<ALTID>&altType=<ALTTYPE>")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = "Bearer <TOKEN>"
request["Version"] = "v3"

response = http.request(request)
puts response.read_body
```

**PowerShell**

```powershell
$headers = @{
  "Authorization" = "Bearer <TOKEN>"
  "Version" = "v3"
}

$response = Invoke-RestMethod -Uri 'https://services.leadconnectorhq.com/payments/subscriptions?altId=<ALTID>&altType=<ALTTYPE>' -Method 'GET' -Headers $headers
$response | ConvertTo-Json
```