> ## Documentation Index
> Fetch the complete documentation index at: https://dvaultdocs.dukka.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscription API

> Manage recurring payments and subscriptions

# Subscription API Documentation

## Overview

The Subscription API provides endpoints for managing recurring payments and subscriptions between accounts in the wallet service.

## Base URL

`/api/v1/subscriptions`

## Authentication

All endpoints require authentication using an API key in the request headers:

* `X-API-KEY`: Your API key

## Endpoints

### Create Subscription

Create a new subscription for recurring payments.

**Endpoint:** `POST /register`

**Headers:**

* `X-API-KEY` (optional): API key for authentication

**Request Body:**

```json theme={null}
{
  "debitAccountId": "string",
  "creditAccountId": "string",
  "amount": "number",
  "currency": "string",
  "frequency": "DAILY|WEEKLY|BI_WEEKLY|MONTHLY|YEARLY",
  "description": "string",
  "tenantId": "string",
  "userId": "string",
  "startTime": "string",
  "endTime": "string",
  "notificationUrl": "string"
}
```

**Response:**

```json theme={null}
{
  "statusCode": 201,
  "message": "string",
  "data": {
    "subscriptionReference": "string",
    "debitAccount": {
      "accountId": "string",
      "accountNumber": "string",
      "accountName": "string",
      "currency": "string",
      "status": "string"
    },
    "creditAccount": {
      "accountId": "string",
      "accountNumber": "string",
      "accountName": "string",
      "currency": "string",
      "status": "string"
    },
    "amount": "number",
    "currency": "string",
    "frequency": "string",
    "status": "ACTIVE|PAUSED|COMPLETED|CANCELLED|FAILED|EXPIRED",
    "webhookUrl": "string",
    "startTime": "string",
    "nextDueTime": "string",
    "endTime": "string",
    "narration": "string",
    "count": "number"
  }
}
```

### Update Subscription

Update an existing subscription.

**Endpoint:** `POST /update/{reference}`

**Headers:**

* `X-API-KEY` (optional): API key for authentication

**Path Parameters:**

* `reference`: Subscription reference ID

**Request Body:**

```json theme={null}
{
  "debitAccountId": "string",
  "creditAccountId": "string",
  "amount": "number",
  "currency": "string",
  "frequency": "DAILY|WEEKLY|BI_WEEKLY|MONTHLY|YEARLY",
  "description": "string",
  "tenantId": "string",
  "userId": "string",
  "startTime": "string",
  "endTime": "string",
  "notificationUrl": "string"
}
```

**Response:**

```json theme={null}
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "subscriptionReference": "string",
    "debitAccount": {
      "accountId": "string",
      "accountNumber": "string",
      "accountName": "string",
      "currency": "string",
      "status": "string"
    },
    "creditAccount": {
      "accountId": "string",
      "accountNumber": "string",
      "accountName": "string",
      "currency": "string",
      "status": "string"
    },
    "amount": "number",
    "currency": "string",
    "frequency": "string",
    "status": "string",
    "webhookUrl": "string",
    "startTime": "string",
    "nextDueTime": "string",
    "endTime": "string",
    "narration": "string",
    "count": "number"
  }
}
```

### Get Subscriptions

Retrieve subscriptions with filtering and pagination.

**Endpoint:** `GET /`

**Headers:**

* `X-API-KEY` (optional): API key for authentication

**Query Parameters:**

* `debitAccountId`: Filter by debit account ID
* `creditAccountId`: Filter by credit account ID
* `status`: Filter by subscription status
* `frequency`: Filter by frequency
* `tenantId`: Filter by tenant ID
* `startDateFrom`: Filter by start date from
* `startDateTo`: Filter by start date to
* `endDateFrom`: Filter by end date from
* `endDateTo`: Filter by end date to
* `currency`: Filter by currency
* `page`: Page number (default: 0)
* `size`: Page size (default: 20)
* `sort`: Sort field and direction (e.g., "createdAt,desc")

**Response:**

```json theme={null}
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "content": [
      {
        "subscriptionReference": "string",
        "debitAccount": {
          "accountId": "string",
          "accountNumber": "string",
          "accountName": "string",
          "currency": "string",
          "status": "string"
        },
        "creditAccount": {
          "accountId": "string",
          "accountNumber": "string",
          "accountName": "string",
          "currency": "string",
          "status": "string"
        },
        "amount": "number",
        "currency": "string",
        "frequency": "string",
        "status": "string",
        "webhookUrl": "string",
        "startTime": "string",
        "nextDueTime": "string",
        "endTime": "string",
        "narration": "string",
        "count": "number"
      }
    ],
    "totalElements": "number",
    "totalPages": "number",
    "size": "number",
    "number": "number"
  }
}
```

### Get Subscription Transactions

Retrieve transactions associated with a subscription.

**Endpoint:** `GET /transactions`

**Headers:**

* `X-API-KEY` (optional): API key for authentication

**Query Parameters:**

* `status`: Filter by transaction status
* `subscriptionReference`: Filter by subscription reference
* `tenantId`: Filter by tenant ID
* `type`: Filter by transaction type
* `startDateFrom`: Filter by start date from
* `startDateTo`: Filter by start date to
* `endDateFrom`: Filter by end date from
* `endDateTo`: Filter by end date to
* `currency`: Filter by currency
* `page`: Page number (default: 0)
* `size`: Page size (default: 20)
* `sort`: Sort field and direction (e.g., "createdAt,desc")

**Response:**

```json theme={null}
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "content": [
      {
        "transactionId": "string",
        "requestId": "string",
        "amount": "number",
        "currency": "string",
        "status": "string",
        "type": "string",
        "narration": "string",
        "createdAt": "string"
      }
    ],
    "totalElements": "number",
    "totalPages": "number",
    "size": "number",
    "number": "number"
  }
}
```

## Error Responses

All endpoints may return the following error responses:

**401 Unauthorized**

```json theme={null}
{
  "statusCode": 401,
  "message": "Unauthorized",
  "data": null
}
```

**404 Not Found**

```json theme={null}
{
  "statusCode": 404,
  "message": "Resource not found",
  "data": null
}
```

**409 Conflict**

```json theme={null}
{
  "statusCode": 409,
  "message": "Duplicate subscription",
  "data": null
}
```

## Notes

* All timestamps are in ISO-8601 format
* Minimum subscription amount is 100 units of the specified currency
* Subscription frequencies:
  * DAILY: Daily recurring payment
  * WEEKLY: Weekly recurring payment
  * BI\_WEEKLY: Bi-weekly recurring payment
  * MONTHLY: Monthly recurring payment
  * YEARLY: Yearly recurring payment
* Subscription statuses:
  * ACTIVE: Currently running
  * PAUSED: Temporarily halted
  * COMPLETED: Finished after reaching end time
  * CANCELLED: Manually cancelled
  * FAILED: Last execution failed
  * EXPIRED: Reached end time
* Platform admins can create subscriptions for any tenant
* Tenant admins can create subscriptions for their tenant
* Regular users can only create subscriptions for themselves
* Subscriptions are processed automatically based on their frequency
* Failed subscriptions can be retried manually
* Webhook notifications are sent for subscription events
* Subscription history is maintained for audit purposes
* Account currency must match the subscription currency
* Subscriptions are unique per debit account, credit account, amount, currency, and frequency