# Get Subscription

`GET /v1/subscriptions/{subscription_id}`

Endpoints: `https://{tenant}.core.server.test.neobits.ai/v1/subscriptions/{subscription_id}`, `https://{tenant}.core.server.prod.neobits.ai/v1/subscriptions/{subscription_id}`
OpenAPI document: https://docs.neobits.ai/openapi/core-authz.json

Authentication: `bearer` (Bearer token authentication using OAuth 2.0 client credentials flow.)

Retrieves one of your tenant's subscriptions, with its plan. Your client's `subscription_id` (see [Get Client](https://docs.neobits.ai/api-reference/operation/getClient/method/get.md)) is the subscription Fuse serves it under. Your token must carry `subscription:read`, which the `owner` and `admin` roles grant.

## Parameters

| Name | In | Required | Schema | Description |
| --- | --- | --- | --- | --- |
| `subscription_id` | path | yes | string (uuid); example `0197a1b2-0000-7000-8000-000000000001` | The subscription ID |

Full schemas:

- `subscription_id` (path): `{"type":"string","format":"uuid"}`

## Example request

```bash
curl --request GET \
  --url https://your-tenant.core.server.test.neobits.ai/v1/subscriptions/0197a1b2-0000-7000-8000-000000000001 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
```

## Responses

### 200 Subscription details

Content type: `application/json`

Schema (JSON Schema):

```json
{"title":"Subscription","type":"object","required":["id","description","starts_at","ends_at","plan","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Subscription ID. Set it as a client's `subscription_id` to let Fuse serve the client.","example":"0197a1b2-0000-7000-8000-000000000001"},"description":{"type":"string","description":"What the subscription is for","example":"Fuse for loan applications"},"starts_at":{"type":"string","format":"date-time","example":"2019-09-16T22:14:45.624Z","description":"When the subscription starts"},"ends_at":{"type":["string","null"],"format":"date-time","description":"When the subscription ends. Null when it has no end.","example":null},"plan":{"title":"Plan","type":"object","required":["id","name","billing","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Plan ID","example":"0197a1b2-0000-7000-8000-000000000101"},"name":{"type":"string","description":"The plan's name","example":"Fuse Standard"},"description":{"type":"string","description":"What the plan includes. Present only when the plan has a description.","example":"Income, tax and debt data for loan applications"},"billing":{"type":"object","required":["frequency","terms"],"properties":{"frequency":{"type":"string","enum":["MONTHLY","QUARTERLY","YEARLY"],"description":"How often the plan is invoiced","example":"MONTHLY"},"terms":{"type":"string","enum":["NET_30","NET_14","NET_7"],"description":"Days to pay an invoice","example":"NET_30"}}},"created_at":{"type":"string","format":"date-time","example":"2019-09-16T22:14:45.624Z","description":"When the plan was created"},"updated_at":{"type":"string","format":"date-time","example":"2019-09-16T22:14:45.624Z","description":"When the plan was last changed"}}},"created_at":{"type":"string","format":"date-time","example":"2019-09-16T22:14:45.624Z","description":"When the subscription was created"},"updated_at":{"type":"string","format":"date-time","example":"2019-09-16T22:14:45.624Z","description":"When the subscription was last changed"}}}
```

Example:

```json
{
  "id": "0197a1b2-0000-7000-8000-000000000001",
  "description": "Fuse for loan applications",
  "starts_at": "2019-09-16T22:14:45.624Z",
  "ends_at": null,
  "plan": {
    "id": "0197a1b2-0000-7000-8000-000000000101",
    "name": "Fuse Standard",
    "description": "Income, tax and debt data for loan applications",
    "billing": {
      "frequency": "MONTHLY",
      "terms": "NET_30"
    },
    "created_at": "2019-09-16T22:14:45.624Z",
    "updated_at": "2019-09-16T22:14:45.624Z"
  },
  "created_at": "2019-09-16T22:14:45.624Z",
  "updated_at": "2019-09-16T22:14:45.624Z"
}
```

## Error responses

Error bodies follow the format in the [error reference](https://docs.neobits.ai/api-reference/errors.md), which lists every error code.

| Status | Meaning | Example body |
| --- | --- | --- |
| 400 | OAuth 2.0 Bad Request | `{"error":"invalid_request","error_code":"400-000","error_uri":"https://docs.neobits.ai/api-reference/errors","error_description":"The request is missing a required parameter.","error_timestamp":"2025-06-25T15:29:49.992Z"}` |
| 401 | OAuth 2.0 Unauthorized | `{"error":"invalid_client","error_code":"401-000","error_uri":"https://docs.neobits.ai/api-reference/errors","error_description":"Client authentication failed.","error_timestamp":"2025-06-25T15:29:49.992Z"}` |
| 403 | OAuth 2.0 Forbidden. The token doesn't carry the scope this endpoint needs, or it was issued for another host. Request a token from your tenant's Core host with `resource` set to that host and `scope` including the endpoint's scope, or with a `role` that grants it. | `{"error":"access_denied","error_code":"403-000","error_uri":"https://docs.neobits.ai/api-reference/errors","error_description":"An unknown forbidden error occurred.","error_timestamp":"2026-11-06T19:42:10.512Z"}` |
| 404 | OAuth 2.0 Not Found. Your tenant has no subscription with this ID: it doesn't exist, or it belongs to another tenant. Both cases answer the same. | `{"error":"not_found","error_code":"404-001","error_uri":"https://docs.neobits.ai/api-reference/errors","error_description":"Subscription with id '0197a1b2-0000-7000-8000-000000000001' does not exist.","error_timestamp":"2026-11-08T12:00:00.000Z"}` |
| 429 | OAuth 2.0 Too Many Requests. When the rate limit rejects a request, the response carries `Retry-After` and no `error_timestamp` or `X-Request-ID`, as the request never reached the API. | `{"error":"too_many_requests","error_code":"429-000","error_uri":"https://docs.neobits.ai/api-reference/errors","error_description":"Too many requests. Please try again later."}` |
| 500 | OAuth 2.0 Internal Server Error | `{"error":"server_error","error_code":"500-000","error_uri":"https://docs.neobits.ai/api-reference/errors","error_description":"The authorization server encountered an unexpected condition.","error_timestamp":"2025-06-25T15:29:49.992Z"}` |
| 504 | OAuth 2.0 Gateway Timeout | `{"error":"gateway_timeout","error_code":"504-000","error_uri":"https://docs.neobits.ai/api-reference/errors","error_description":"Timeout of 29s reached. Closing connection.","error_timestamp":"2025-06-25T15:29:49.992Z"}` |