# Get Subscription by Id

> GET `/subscriptions/{subscriptionId}`
> Part of the One API reference. Source: https://hub.ozow.com/api-reference/one-api/get-subscriptions-subscription-id/

Server: `https://one.ozow.com/v1` (Production)

Other environments: `https://stagingone.ozow.com/v1` (Staging)

Retrieve the details of a single subscription.

## Authentication

- `Authentication` (oauth2)
  - Scopes: `subscriptions`

## Path parameters

- `subscriptionId` (string, required) - The unique identifier of the subscription.

## Header parameters

- `X-Correlation-ID` (string) - Optional correlation id for the request, if not supplied a new one will be generated and passed onto all underlying requests and returned as a header.

## Responses

### 200 OK

- Header `X-Correlation-ID`: The correlation id for the request that was processed.

- `subscriptionId` (string, required) - The unique identifier of the subscription.
- `status` (string, required, one of "PendingAuthorization", "Active", "Canceled", "Completed", "Expired", "Failed", "Unknown") - The lifecycle status of a subscription: * `PendingAuthorization` - created, awaiting customer authorisation via `redirectUrl`. * `Active` - authorised; scheduled charges are being taken. * `Canceled` - cancelled; no further charges. * `Completed` - all scheduled occurrences have been taken. * `Expired` - the authorisation lapsed before activation. * `Failed` - the subscription could not be established or sustained. * `Unknown` - the status could not be determined.
- `siteCode` (string, required) - The site code the subscription belongs to.
- `amount` (object, required) - The recurring charge amount.
- `amountConstraints` (object) - The authorised per-payment band. Returned on create and get.
- `payableNow` (object) - The once-off sign-up charge. Returned on create only.
- `description` (string) - The subscription description.
- `merchantReference` (string, required) - Your reference for the subscription.
- `bankReference` (string) - The reference that appears on the merchant's bank statement for each payment in the subscription.
- `frequency` (string, one of "Daily", "Weekly", "Fortnightly", "Monthly", "Biannually", "Annually") - The billing cadence of a subscription.
- `firstPaymentDate` (string, date, required) - The date of the first scheduled charge.
- `occurrences` (integer, required) - The total number of scheduled charges.
- `redirectUrl` (string, uri) - The hosted authorisation page the customer must be redirected to in order to approve the subscription. Present while authorisation is pending.
- `authorization` (object) - The customer's authorisation (consent) status. Populated once the customer has authorised via `redirectUrl`.
  - `status` (string) - The provider-mirrored authorisation status.
- `links` (object, required) - Related resource links for the subscription.
  - `self` (string, uri) - The URI of this subscription.
  - `cancel` (string, uri) - The URI to cancel this subscription.
  - `transactions` (string, uri) - The URI to create an ad-hoc charge against this subscription.

### 401 Unauthorised.

- Header `X-Correlation-ID`: The correlation id for the request that was processed.

- `id` (string, uuid, required) - a unique identifier for this particular occurrence of the problem.
- `links` (object, nullable) - Present on an authentication or authorisation failure, and null otherwise.
  - `about` (string, uri) - A link that leads to further details about this particular occurrence of the problem. When derefenced, this URI SHOULD return a human-readable description of the error.
  - `type` (string, uri) - A link that identifies the type of error that this particular error is an instance of. This URI SHOULD be dereferencable to a human-readable explanation of the general error.
- `code` (string, required) - An application-specific error code, expressed as a string value. Key on this rather than on `title` or `detail`, which are written for a person. A rejection at the transport level uses the status name, one of `BadRequest`, `Unauthorized`, `Forbidden`, `NotFound`, `NotAllowed`, `Conflict`, `UnsupportedMediaType`, `BadGateway` or `InternalServerError`. An operation refusing a request on its own rules returns a code of its own.
- `title` (string, required) - A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
- `detail` (string, required) - A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
- `source` (object, nullable) - Where in the request the problem was found. All three keys are present whenever `source` is, with the ones that do not apply set to null. `source` itself is null where the failure is not about a part of the request.
  - `pointer` (string, json-pointer, nullable) - a JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901) to the value in the request document that caused the error [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. This MUST point to a value in the request document that exists; if it doesn’t, the client SHOULD simply ignore the pointer.
  - `parameter` (string, nullable) - A string indicating which URI query parameter caused the error.
  - `header` (string, nullable) - A string indicating the name of a single request header which caused the error.
- `meta` (object, nullable) - A [meta object](https://jsonapi.org/format/#document-meta) containing non-standard meta-information about the error. Null where the request carried no `X-Correlation-ID`, and on an authentication failure, which does not echo it.
  - `correlationId` (string) - The `X-Correlation-ID` sent with the request, echoed back so it can be quoted to support. Absent when the request carried no correlation header.

Example (No usable access token on the request):

```json
{
  "id": "1cecc2b7-1c29-418a-b26a-bf7546926083",
  "links": {
    "about": "https://ozow.stoplight.io/docs/one-api/zi18vomr0jm8c-generate-authentication-token",
    "type": "https://tools.ietf.org/html/rfc7235#section-3.1"
  },
  "code": "Unauthorized",
  "title": "Unauthorized Request",
  "detail": "Authorization header is missing or invalid.",
  "source": {
    "pointer": null,
    "parameter": null,
    "header": "Authorization"
  },
  "meta": null
}
```

### 404 Not found.  The item with the specified identifier could not be found, or this resource is not allowed for the resource identifier.

- Header `X-Correlation-ID`: The correlation id for the request that was processed.

`Error`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/one-api/schemas/error.md

Example (No resource with that identifier):

```json
{
  "id": "5b9e3c17-4a8d-42f0-9e61-3c7b0f2a8d15",
  "links": null,
  "code": "NotFound",
  "title": "Not Found",
  "detail": "The requested resource was not found.",
  "source": {
    "pointer": "/data",
    "parameter": "/v1/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "header": null
  },
  "meta": {
    "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}
```

### 502 Bad Gateway. An upstream payment service was unreachable or returned an error; the request was not completed. Safe to retry shortly.

- Header `X-Correlation-ID`: The correlation id for the request that was processed.

`Error`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/one-api/schemas/error.md

Example (An upstream payment service could not be reached):

```json
{
  "id": "6c3a1f95-8d07-4e2b-a94c-5f0b7d2e8134",
  "links": null,
  "code": "BadGateway",
  "title": "Bad Gateway",
  "detail": "The upstream service is currently unavailable. Please try again shortly.",
  "source": null,
  "meta": {
    "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}
```