# GET /api/public/subscriptions/{subscriptionId}

> Get a subscription by id

- Surface: `/api/public` · operationId `getSubscription` · Group: Subscription
- Authorisation: Token with scope `public:subscriptions:read`
- Organisation key: needs the capabilities `orders:read` + `customers:read` on the clinic, all together
- The spec: https://developers.rivr.io/openapi/api-public.json
- The spec's introduction: https://developers.rivr.io/reference/api-public.md
- Page in the portal: https://developers.rivr.io/reference/api-public/getSubscription

The examples target the sandbox (`https://api.test.rivr.io`) and need test credentials.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `subscriptionId` | path | string (uuid) | yes |  |

## Responses

### 200

OK

`application/json`

**Response fields**

| Field | Type | Description |
| --- | --- | --- |
| `id` | string (uuid) |  |
| `createdDate` | string (date-time) |  |
| `modifiedDate` | string (date-time) |  |
| `version` | integer (int32) | (nullable) |
| `erasedAt` | string (date-time) | (nullable) |
| `merchantId` | string (uuid) |  |
| `merchantName` | string | (nullable) |
| `activatedDate` | string (date-time) | (nullable) |
| `firstPaymentDate` | string (date-time) | (nullable) |
| `lastPaymentDate` | string (date-time) | (nullable) |
| `isActive` | boolean |  |
| `customer` | DomainCommonCustomer |  |
| `customer.id` | string (uuid) |  |
| `customer.createdDate` | string (date-time) |  |
| `customer.modifiedDate` | string (date-time) |  |
| `customer.version` | integer (int32) | (nullable) |
| `customer.erasedAt` | string (date-time) | (nullable) |
| `customer.personalNumber` | string | (nullable) |
| `customer.firstName` | string | (nullable) |
| `customer.lastName` | string | (nullable) |
| `customer.name` | string | (nullable) |
| `customer.email` | string | (nullable) |
| `customer.phone` | string | (nullable) |
| `customer.address` | DomainAddress |  |
| `customer.address.street` | string | (nullable) |
| `customer.address.street2` | string | (nullable) |
| `customer.address.postalCode` | string | (nullable) |
| `customer.address.city` | string | (nullable) |
| `customer.address.country` | string | (nullable) |
| `customer.blockedInfo` | BlockedInfo |  |
| `customer.blockedInfo.blockedAt` | string (date-time) |  |
| `customer.blockedInfo.blockedBy` | string | (nullable) |
| `customer.blockedInfo.reason` | string | (nullable) |
| `customer.isBlocked` | boolean |  |
| `customer.isConfidential` | boolean |  |
| `customer.registryError` | CommonCustomerRegistryError |  |
| `customer.registryError.comment` | string | (nullable) |
| `customer.registryError.blockedState` | string | (nullable) |
| `customer.nationalIdentity` | NationalIdentity |  |
| `customer.nationalIdentity.personalIdentityNumber` | string | (nullable) |
| `customer.nationalIdentity.countryCode` | CountryCode | (Values: 0 = Unknown, 1 = SE, 2 = DK, 3 = NO) |
| `customer.personalDataFetchedAt` | string (date-time) | (nullable) |
| `customer.hasVerifiedIdentity` | boolean | (nullable) |
| `subscriptionNumber` | string | (nullable) |
| `shortId` | string | (nullable) |
| `totalAmount` | Amount |  |
| `totalAmount.currencyCode` | string |  |
| `totalAmount.currency` | string | ISO 4217 currency code |
| `totalAmount.decimals` | integer (int32) |  |
| `totalAmount.value` | integer (int64) |  |
| `totalAmount.valueForView` | number (double) |  |
| `totalAmount.money` | Money |  |
| `totalAmount.money.decimals` | integer (int32) |  |
| `totalAmount.money.value` | integer (int64) |  |
| `totalAmount.money.valueForView` | number (double) |  |
| `nextPayment` | DomainSubscriptionPayment |  |
| `nextPayment.id` | string (uuid) |  |
| `nextPayment.paymentDate` | string (date-time) |  |
| `nextPayment.amount` | Amount |  |
| `nextPayment.amount.currencyCode` | string |  |
| `nextPayment.amount.currency` | string | ISO 4217 currency code |
| `nextPayment.amount.decimals` | integer (int32) |  |
| `nextPayment.amount.value` | integer (int64) |  |
| `nextPayment.amount.valueForView` | number (double) |  |
| `nextPayment.amount.money` | Money |  |
| `nextPayment.description` | string | (nullable) |
| `nextPayment.externalReference` | string | (nullable) |
| `nextPayment.isPaid` | boolean |  |
| `nextPayment.isDue` | boolean |  |
| `nextPayment.isFuture` | boolean |  |
| `nextPayment.paymentInfo` | PaymentInfo |  |
| `nextPayment.paymentInfo.paymentDate` | string (date-time) | (nullable) |
| `nextPayment.paymentInfo.isPaid` | boolean |  |
| `nextPayment.paymentInfo.paymentMethod` | PaymentMethod | (Values: 0 = NotPaid, 1 = Giro, 2 = InstalmentDefault, 4 = InstalmentInterestFree, 8 = InstalmentFullKyc, 14 = Instalment, 16 = Direct, 64 = Swish, 128 = Invoice, 256 = Card, 512 = DigitalWallet, 1024 = AvardaInvoice, … and 10 more) Full list: the schema [PaymentMethod](https://developers.rivr.io/openapi/api-public.json#/components/schemas/PaymentMethod) |
| `nextPayment.paymentInfo.amount` | Amount |  |
| `nextPayment.paymentInfo.reference` | string | (nullable) |
| `unpaidDuePayments` | DomainSubscriptionPayment[] |  |
| `unpaidDuePayments[].id` | string (uuid) |  |
| `unpaidDuePayments[].paymentDate` | string (date-time) |  |
| `unpaidDuePayments[].amount` | Amount |  |
| `unpaidDuePayments[].amount.currencyCode` | string |  |
| `unpaidDuePayments[].amount.currency` | string | ISO 4217 currency code |
| `unpaidDuePayments[].amount.decimals` | integer (int32) |  |
| `unpaidDuePayments[].amount.value` | integer (int64) |  |
| `unpaidDuePayments[].amount.valueForView` | number (double) |  |
| `unpaidDuePayments[].amount.money` | Money |  |
| `unpaidDuePayments[].description` | string | (nullable) |
| `unpaidDuePayments[].externalReference` | string | (nullable) |
| `unpaidDuePayments[].isPaid` | boolean |  |
| `unpaidDuePayments[].isDue` | boolean |  |
| `unpaidDuePayments[].isFuture` | boolean |  |
| `unpaidDuePayments[].paymentInfo` | PaymentInfo |  |
| `unpaidDuePayments[].paymentInfo.paymentDate` | string (date-time) | (nullable) |
| `unpaidDuePayments[].paymentInfo.isPaid` | boolean |  |
| `unpaidDuePayments[].paymentInfo.paymentMethod` | PaymentMethod | (Values: 0 = NotPaid, 1 = Giro, 2 = InstalmentDefault, 4 = InstalmentInterestFree, 8 = InstalmentFullKyc, 14 = Instalment, 16 = Direct, 64 = Swish, 128 = Invoice, 256 = Card, 512 = DigitalWallet, 1024 = AvardaInvoice, … and 10 more) Full list: the schema [PaymentMethod](https://developers.rivr.io/openapi/api-public.json#/components/schemas/PaymentMethod) |
| `unpaidDuePayments[].paymentInfo.amount` | Amount |  |
| `unpaidDuePayments[].paymentInfo.reference` | string | (nullable) |
| `unpaidFuturePayments` | DomainSubscriptionPayment[] |  |
| `unpaidFuturePayments[].id` | string (uuid) |  |
| `unpaidFuturePayments[].paymentDate` | string (date-time) |  |
| `unpaidFuturePayments[].amount` | Amount |  |
| `unpaidFuturePayments[].amount.currencyCode` | string |  |
| `unpaidFuturePayments[].amount.currency` | string | ISO 4217 currency code |
| `unpaidFuturePayments[].amount.decimals` | integer (int32) |  |
| `unpaidFuturePayments[].amount.value` | integer (int64) |  |
| `unpaidFuturePayments[].amount.valueForView` | number (double) |  |
| `unpaidFuturePayments[].amount.money` | Money |  |
| `unpaidFuturePayments[].description` | string | (nullable) |
| `unpaidFuturePayments[].externalReference` | string | (nullable) |
| `unpaidFuturePayments[].isPaid` | boolean |  |
| `unpaidFuturePayments[].isDue` | boolean |  |
| `unpaidFuturePayments[].isFuture` | boolean |  |
| `unpaidFuturePayments[].paymentInfo` | PaymentInfo |  |
| `unpaidFuturePayments[].paymentInfo.paymentDate` | string (date-time) | (nullable) |
| `unpaidFuturePayments[].paymentInfo.isPaid` | boolean |  |
| `unpaidFuturePayments[].paymentInfo.paymentMethod` | PaymentMethod | (Values: 0 = NotPaid, 1 = Giro, 2 = InstalmentDefault, 4 = InstalmentInterestFree, 8 = InstalmentFullKyc, 14 = Instalment, 16 = Direct, 64 = Swish, 128 = Invoice, 256 = Card, 512 = DigitalWallet, 1024 = AvardaInvoice, … and 10 more) Full list: the schema [PaymentMethod](https://developers.rivr.io/openapi/api-public.json#/components/schemas/PaymentMethod) |
| `unpaidFuturePayments[].paymentInfo.amount` | Amount |  |
| `unpaidFuturePayments[].paymentInfo.reference` | string | (nullable) |
| `payments` | DomainSubscriptionPayment[] |  |
| `payments[].id` | string (uuid) |  |
| `payments[].paymentDate` | string (date-time) |  |
| `payments[].amount` | Amount |  |
| `payments[].amount.currencyCode` | string |  |
| `payments[].amount.currency` | string | ISO 4217 currency code |
| `payments[].amount.decimals` | integer (int32) |  |
| `payments[].amount.value` | integer (int64) |  |
| `payments[].amount.valueForView` | number (double) |  |
| `payments[].amount.money` | Money |  |
| `payments[].description` | string | (nullable) |
| `payments[].externalReference` | string | (nullable) |
| `payments[].isPaid` | boolean |  |
| `payments[].isDue` | boolean |  |
| `payments[].isFuture` | boolean |  |
| `payments[].paymentInfo` | PaymentInfo |  |
| `payments[].paymentInfo.paymentDate` | string (date-time) | (nullable) |
| `payments[].paymentInfo.isPaid` | boolean |  |
| `payments[].paymentInfo.paymentMethod` | PaymentMethod | (Values: 0 = NotPaid, 1 = Giro, 2 = InstalmentDefault, 4 = InstalmentInterestFree, 8 = InstalmentFullKyc, 14 = Instalment, 16 = Direct, 64 = Swish, 128 = Invoice, 256 = Card, 512 = DigitalWallet, 1024 = AvardaInvoice, … and 10 more) Full list: the schema [PaymentMethod](https://developers.rivr.io/openapi/api-public.json#/components/schemas/PaymentMethod) |
| `payments[].paymentInfo.amount` | Amount |  |
| `payments[].paymentInfo.reference` | string | (nullable) |
| `notifications` | Notification[] |  |
| `notifications[].id` | string (uuid) |  |
| `notifications[].createdDate` | string (date-time) |  |
| `notifications[].type` | SubscriptionNotificationType | (Values: 0 = Created, 1 = PaymentPaid) |
| `notifications[].message` | string | (nullable) |
| `notifications[].isRead` | boolean |  |
| `events` | SubscriptionEvent[] |  |
| `events[].eventId` | string (uuid) |  |
| `events[].title` | string | (nullable) |
| `events[].content` | string | (nullable) |
| `events[].eventDate` | string (date-time) |  |
| `events[].eventBy` | string | (nullable) |
| `events[].eventType` | SubscriptionEventType | (Values: 0 = Created, 1 = Activated, 2 = VisitedEntryPoint, 3 = PaymentSucceded, 4 = PaymentFailed) |
| `events[].isPublic` | boolean |  |
| `events[].hasOccurred` | boolean |  |
| `events[].user` | User |  |
| `events[].user.userId` | string (uuid) |  |
| `events[].user.name` | string | (nullable) |
| `events[].messageKey` | string | (nullable) |
| `events[].messageArgs` | map<string, string> | (nullable) |
| `canActivate` | boolean |  |
| `references` | Reference[] |  |
| `references[].value` | string (uuid) |  |
| `references[].type` | ReferenceType | (Values: 0 = Empty, 1 = Client, 2 = Customer, 4 = Merchant, 8 = Invoice, 16 = Instalment, 32 = InvoicePayment, 64 = OutgoingPayment, 128 = Settlement, 256 = CreditCommitment, 512 = Platform, 1024 = Overpayment, … and 32 more) Full list: the schema [ReferenceType](https://developers.rivr.io/openapi/api-public.json#/components/schemas/ReferenceType) |

**Example**

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "createdDate": "2026-10-18T09:00:00Z",
  "modifiedDate": "2026-10-18T09:00:00Z",
  "version": 0,
  "erasedAt": "2026-10-18T09:00:00Z",
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "merchantName": "string",
  "activatedDate": "2026-10-18T09:00:00Z",
  "firstPaymentDate": "2026-10-18T09:00:00Z",
  "lastPaymentDate": "2026-10-18T09:00:00Z",
  "isActive": false,
  "customer": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "createdDate": "2026-10-18T09:00:00Z",
    "modifiedDate": "2026-10-18T09:00:00Z",
    "version": 0,
    "erasedAt": "2026-10-18T09:00:00Z",
    "personalNumber": "string",
    "firstName": "string",
    "lastName": "string",
    "name": "string",
    "email": "string",
    "phone": "string",
    "address": {
      "street": "string",
      "street2": "string",
      "postalCode": "string",
      "city": "string",
      "country": "string"
    },
    "blockedInfo": {
      "blockedAt": "2026-10-18T09:00:00Z",
      "blockedBy": "string",
      "reason": "string"
    },
    "isBlocked": false,
    "isConfidential": false,
    "registryError": {
      "comment": "string",
      "blockedState": "string"
    },
    "nationalIdentity": {
      "personalIdentityNumber": "string",
      "countryCode": 1
    },
    "personalDataFetchedAt": "2026-10-18T09:00:00Z",
    "hasVerifiedIdentity": false
  },
  "subscriptionNumber": "string",
  "shortId": "string",
  "totalAmount": {
    "currencyCode": "string",
    "currency": "SEK",
    "decimals": 0,
    "value": 0,
    "valueForView": 0,
    "money": {
      "decimals": 0,
      "value": 0,
      "valueForView": 0
    }
  },
  "nextPayment": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "paymentDate": "2026-10-18T09:00:00Z",
    "amount": {
      "currencyCode": "string",
      "currency": "SEK",
      "decimals": 0,
      "value": 0,
      "valueForView": 0,
      "money": {
        "decimals": 0,
        "value": 0,
        "valueForView": 0
      }
    },
    "description": "string",
    "externalReference": "string",
    "isPaid": false,
    "isDue": false,
    "isFuture": false,
    "paymentInfo": {
      "paymentDate": "2026-10-18T09:00:00Z",
      "isPaid": false,
      "paymentMethod": 1,
      "amount": {
        "currencyCode": "string",
        "currency": "SEK",
        "decimals": 0,
        "value": 0,
        "valueForView": 0,
        "money": {
          "decimals": 0,
          "value": 0,
          "valueForView": 0
        }
      },
      "reference": "string"
    }
  },
  "unpaidDuePayments": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "paymentDate": "2026-10-18T09:00:00Z",
      "amount": {
        "currencyCode": "string",
        "currency": "SEK",
        "decimals": 0,
        "value": 0,
        "valueForView": 0,
        "money": {
          "decimals": 0,
          "value": 0,
          "valueForView": 0
        }
      },
      "description": "string",
      "externalReference": "string",
      "isPaid": false,
      "isDue": false,
      "isFuture": false,
      "paymentInfo": {
        "paymentDate": "2026-10-18T09:00:00Z",
        "isPaid": false,
        "paymentMethod": 1,
        "amount": {
          "currencyCode": "string",
          "currency": "SEK",
          "decimals": 0,
          "value": 0,
          "valueForView": 0,
          "money": {
            "decimals": 0,
            "value": 0,
            "valueForView": 0
          }
        },
        "reference": "string"
      }
    }
  ],
  "unpaidFuturePayments": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "paymentDate": "2026-10-18T09:00:00Z",
      "amount": {
        "currencyCode": "string",
        "currency": "SEK",
        "decimals": 0,
        "value": 0,
        "valueForView": 0,
        "money": {
          "decimals": 0,
          "value": 0,
          "valueForView": 0
        }
      },
      "description": "string",
      "externalReference": "string",
      "isPaid": false,
      "isDue": false,
      "isFuture": false,
      "paymentInfo": {
        "paymentDate": "2026-10-18T09:00:00Z",
        "isPaid": false,
        "paymentMethod": 1,
        "amount": {
          "currencyCode": "string",
          "currency": "SEK",
          "decimals": 0,
          "value": 0,
          "valueForView": 0,
          "money": {
            "decimals": 0,
            "value": 0,
            "valueForView": 0
          }
        },
        "reference": "string"
      }
    }
  ],
  "payments": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "paymentDate": "2026-10-18T09:00:00Z",
      "amount": {
        "currencyCode": "string",
        "currency": "SEK",
        "decimals": 0,
        "value": 0,
        "valueForView": 0,
        "money": {
          "decimals": 0,
          "value": 0,
          "valueForView": 0
        }
      },
      "description": "string",
      "externalReference": "string",
      "isPaid": false,
      "isDue": false,
      "isFuture": false,
      "paymentInfo": {
        "paymentDate": "2026-10-18T09:00:00Z",
        "isPaid": false,
        "paymentMethod": 1,
        "amount": {
          "currencyCode": "string",
          "currency": "SEK",
          "decimals": 0,
          "value": 0,
          "valueForView": 0,
          "money": {
            "decimals": 0,
            "value": 0,
            "valueForView": 0
          }
        },
        "reference": "string"
      }
    }
  ],
  "notifications": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "createdDate": "2026-10-18T09:00:00Z",
      "type": 1,
      "message": "string",
      "isRead": false
    }
  ],
  "events": [
    {
      "eventId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "title": "string",
      "content": "string",
      "eventDate": "2026-10-18T09:00:00Z",
      "eventBy": "string",
      "eventType": 1,
      "isPublic": false,
      "hasOccurred": false,
      "user": {
        "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "string"
      },
      "messageKey": "string",
      "messageArgs": {
        "key": "string"
      }
    }
  ],
  "canActivate": false,
  "references": [
    {
      "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "type": 1
    }
  ]
}
```

### 400

The id is not a UUID: the validation problem, with `code` `request_invalid`.

Error codes: [request_invalid](https://developers.rivr.io/errors/request_invalid.md)

`application/json`

```json
{
  "type": "string",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "string",
  "errors": {
    "key": [
      "string"
    ]
  },
  "code": "string",
  "message": "string"
}
```

### 401

The token is missing (`token_missing`), not valid (`token_invalid`), expired (`token_expired`) or could not be
checked (`authentication_unavailable`), or it is not issued for a merchant (`merchant_token_required`).

Error codes: [token_missing](https://developers.rivr.io/errors/token_missing.md), [token_invalid](https://developers.rivr.io/errors/token_invalid.md), [token_expired](https://developers.rivr.io/errors/token_expired.md), [authentication_unavailable](https://developers.rivr.io/errors/authentication_unavailable.md), [merchant_token_required](https://developers.rivr.io/errors/merchant_token_required.md)

`application/json`

```json
{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid Authorization Header",
  "propertyName": null,
  "message": "The request has no valid Authorization header. Send the token in the Authorization header, after Bearer.",
  "errorCode": "token_missing",
  "code": "token_missing",
  "type": "https://developers.rivr.io/errors/token_missing"
}
```

### 403

The token lacks the scope (`invalid_scope`), is a rivr-auth token that is not a clinic token
(`clinic_token_required`), or the subscription belongs to another merchant on the same platform
(`merchant_mismatch`). The body also carries `error` and `error_description`, as before.

Error codes: [invalid_scope](https://developers.rivr.io/errors/invalid_scope.md), [clinic_token_required](https://developers.rivr.io/errors/clinic_token_required.md), [merchant_mismatch](https://developers.rivr.io/errors/merchant_mismatch.md)

`application/json`

```json
{
  "error": "invalid_scope",
  "error_description": "The scope(s) 'public:subscriptions:read' is required.",
  "propertyName": null,
  "message": "The scope(s) 'public:subscriptions:read' is required.",
  "errorCode": "invalid_scope",
  "code": "invalid_scope",
  "type": "https://developers.rivr.io/errors/invalid_scope"
}
```

### 404

There is no subscription with the id that the token reaches: `subscription_not_found`. A subscription of a merchant on
another platform gets the same answer.

Error codes: [subscription_not_found](https://developers.rivr.io/errors/subscription_not_found.md)

`application/json`

```json
{
  "propertyName": "subscriptionId",
  "message": "The subscription was not found",
  "errorCode": "subscription_not_found",
  "code": "subscription_not_found",
  "type": "https://developers.rivr.io/errors/subscription_not_found"
}
```

### 500

Something unexpected failed: `internal_error`.

Error codes: [internal_error](https://developers.rivr.io/errors/internal_error.md)

`application/json`

```json
{
  "propertyName": null,
  "message": "Something unexpected failed at Rivr, and whether the request was carried out is not known. Check the order or what the request was about before you retry.",
  "errorCode": "internal_error",
  "code": "internal_error",
  "type": "https://developers.rivr.io/errors/internal_error"
}
```

## Example request

```bash
curl -X GET https://api.test.rivr.io/api/public/subscriptions/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```