## Schemas

### GetLearningTrackAuthorizationRequest (object)

| Field | Type | Required | Description |
| - | - | - | - |
| `studentId` | string | Yes | The Timeback student identifier |
| `learningTrackId` | string | Yes | The learning track identifier |

Example:
```json
{
  "studentId": "abc123",
  "learningTrackId": "34a6bd30-a8f0-4c8f-9348-dc736d85c242"
}
```

---

### ListLearningTrackAuthorizationsRequest (object)

| Field | Type | Required | Description |
| - | - | - | - |
| `timebackStudentId` | string | Yes | The Timeback student identifier |
| `providerId` | string | No | Optional provider identifier to filter by |

Example:
```json
{
  "timebackStudentId": "abc123",
  "providerId": "provider-xyz"
}
```

---

### UnifiedLearningTrack (object)

| Field | Type | Required | Description |
| - | - | - | - |
| `learningTrackId` | string | Yes | The learning track identifier |
| `learningTrackName` | string | Yes | The name of the learning track |
| `appId` | string | Yes | The associated app identifier |
| `isLocked` | boolean | Yes | Whether the track is locked (requires payment) |
| `paymentModes` | array[PaymentMode] | Conditional | Available payment options (present when `isLocked` is true) |
| `scheduledChargeDate` | string (date-time) | Conditional | Scheduled charge date for upcoming payment (present for scheduled tracks) |
| `frequency` | string | Conditional | Payment frequency for scheduled payments (present for scheduled tracks) |

Frequency enum values:
- "Monthly"
- "Annually"
- "OneTime"
- "Quarterly"

Example:
```json
{
  "learningTrackId": "34a6bd30-a8f0-4c8f-9348-dc736d85c242",
  "learningTrackName": "Alpha Anywhere",
  "appId": "alpha-anywhere",
  "isLocked": true,
  "paymentModes": [
    {
      "payee": "Parent",
      "amount": 29.0,
      "currency": "USD",
      "frequency": "Monthly"
    }
  ],
  "scheduledChargeDate": "2025-09-29T07:22:53.267Z",
  "frequency": "Monthly"
}
```

---

### PaymentMode (object)

| Field | Type | Required | Description |
| - | - | - | - |
| `payee` | string | Yes | The entity receiving the payment |
| `amount` | number | Yes | The payment amount |
| `currency` | string | Yes | The currency code (e.g., USD) |
| `frequency` | string | Yes | Payment frequency (e.g., Monthly, Annually, OneTime, Quarterly) |

Example:
```json
{
  "payee": "Parent",
  "amount": 29.0,
  "currency": "USD",
  "frequency": "Monthly"
}
```

---

### CaliperEvent (object)
Generic Caliper event payload. Additional properties allowed.

| Field | Type | Required | Description |
| - | - | - | - |
| `type` | string | Yes | Caliper event type |
| `action` | string | Yes | Event action |
| `...additional` | any | No | Additional event-specific fields |

Example:
```json
{
  "type": "AssessmentEvent",
  "action": "Started",
  "actor": { "id": "student-123" },
  "object": { "id": "assessment-456" },
  "edApp": { "id": "alpha-anywhere" },
  "eventTime": "2025-09-29T07:22:53.267Z"
}
```

---

### TokenInput (object)

| Field | Type | Required | Description |
| - | - | - | - |
| `studentId` | string | Yes | Timeback student identifier |
| `timeBackAppId` | string | Yes | App identifier |
| `type` | string | Yes | Token type |
| `data` | string | Yes | JSON string containing `curriculumId` and other token-specific data |
| `evidenceId` | string | Yes | Evidence identifier |

`type` enum values:
- "Mastery"
- "TwoX"

Example:
```json
{
  "studentId": "abc123",
  "timeBackAppId": "alpha-anywhere",
  "type": "Mastery",
  "data": "{\"curriculumId\":\"cur-1\",\"score\":95}",
  "evidenceId": "ev-789"
}
```

---

### SubmitTokenResponse (object)

| Field | Type | Required | Description |
| - | - | - | - |
| `id` | string | Yes | Token submission identifier |

Example:
```json
{ "id": "token-submission-123" }
```

---

### LearningTrackAuthorizationResponse (object)

| Field | Type | Required | Description |
| - | - | - | - |
| `track` | object (UnifiedLearningTrack) | Yes | Learning track details and payment info |
| `defaulted` | boolean | Yes | Whether the authorization has defaulted (expired payments) |
| `status` | string | Yes | Explicit authorization status for the requested learning track |

`track` object fields:
| Field | Type | Required | Description |
| - | - | - | - |
| `learningTrackId` | string | Yes | The learning track identifier |
| `learningTrackName` | string | Yes | The name of the learning track |
| `appId` | string | Yes | The associated app identifier |
| `isLocked` | boolean | Yes | Whether the track is locked (requires payment) |
| `paymentModes` | array[PaymentMode] | Conditional | Present when `isLocked` is true |
| `scheduledChargeDate` | string (date-time) | Conditional | Present for scheduled tracks |
| `frequency` | string | Conditional | Present for scheduled tracks |

`status` enum values:
- "unlocked"
- "locked"
- "scheduled"
- "defaulted"

`frequency` enum values:
- "Monthly"
- "Annually"
- "OneTime"
- "Quarterly"

Example:
```json
{
  "track": {
    "learningTrackId": "34a6bd30-a8f0-4c8f-9348-dc736d85c242",
    "learningTrackName": "Alpha Anywhere",
    "appId": "alpha-anywhere",
    "isLocked": true,
    "paymentModes": [
      {
        "payee": "Parent",
        "amount": 29.0,
        "currency": "USD",
        "frequency": "Monthly"
      }
    ],
    "scheduledChargeDate": "2025-09-29T07:22:53.264Z",
    "frequency": "Monthly"
  },
  "defaulted": false,
  "status": "locked"
}
```

---

### ListLearningTrackAuthorizationsResponse (object)

| Field | Type | Required | Description |
| - | - | - | - |
| `lockedTracks` | array[UnifiedLearningTrack] | Yes | Learning tracks that require payment (`isLocked = true`, with `paymentModes`) |
| `unlockedTracks` | array[UnifiedLearningTrack] | Yes | Learning tracks that are accessible (`isLocked = false`) |
| `scheduledTracks` | array[UnifiedLearningTrack] | Yes | Tracks with scheduled payments (`isLocked = true`, with `paymentModes`, `scheduledChargeDate`, and `frequency`) |
| `defaultedTracks` | array[UnifiedLearningTrack] | Yes | Tracks for which payments have expired (`isLocked = false`) |

UnifiedLearningTrack items (see above):
- `learningTrackId: string` – The learning track identifier
- `learningTrackName: string` – The name of the learning track
- `appId: string` – The associated app identifier
- `isLocked: boolean` – Whether the track is locked (requires payment)
- `paymentModes: PaymentMode[]` – Present when `isLocked` is true
- `scheduledChargeDate: string (date-time)` – Present for scheduled tracks
- `frequency: string` – Present for scheduled tracks

`frequency` enum values:
- "Monthly"
- "Annually"
- "OneTime"
- "Quarterly"

Example:
```json
{
  "lockedTracks": [
    {
      "learningTrackId": "lt-1",
      "learningTrackName": "Alpha Anywhere",
      "appId": "alpha-anywhere",
      "isLocked": true,
      "paymentModes": [
        { "payee": "Parent", "amount": 29.0, "currency": "USD", "frequency": "Monthly" }
      ]
    }
  ],
  "unlockedTracks": [
    {
      "learningTrackId": "lt-2",
      "learningTrackName": "Alpha Math",
      "appId": "alpha-math",
      "isLocked": false
    }
  ],
  "scheduledTracks": [
    {
      "learningTrackId": "lt-3",
      "learningTrackName": "Alpha Science",
      "appId": "alpha-science",
      "isLocked": true,
      "paymentModes": [
        { "payee": "Parent", "amount": 99.0, "currency": "USD", "frequency": "Annually" }
      ],
      "scheduledChargeDate": "2025-09-29T07:22:53.267Z",
      "frequency": "Monthly"
    }
  ],
  "defaultedTracks": [
    {
      "learningTrackId": "lt-4",
      "learningTrackName": "Alpha Reading",
      "appId": "alpha-reading",
      "isLocked": false
    }
  ]
}
```


---

### BatchLearningTrackAuthorizationResult (object)

| Field | Type | Required | Description |
| - | - | - | - |
| `studentId` | string | Yes | The Timeback student identifier from the request |
| `track` | object (UnifiedLearningTrack) | Conditional | Learning track authorization data (present when no error) |
| `defaulted` | boolean | Conditional | Whether the authorization has defaulted (present when no error) |
| `error` | string | Conditional | Error message if student not found or other issues occurred |
| `status` | string | Conditional | Explicit authorization status when `track` is present |

`track` object fields (when present):
- `learningTrackId: string` – The learning track identifier
- `learningTrackName: string` – The name of the learning track
- `appId: string` – The associated app identifier
- `isLocked: boolean` – Whether the track is locked (requires payment)
- `paymentModes: PaymentMode[]` – Available payment options (present when `isLocked` is true)
- `scheduledChargeDate: string (date-time)` – Scheduled charge date (present for scheduled tracks)
- `frequency: string` – Payment frequency (present for scheduled tracks)

`status` enum values:
- "unlocked"
- "locked"
- "scheduled"
- "defaulted"

`frequency` enum values:
- "Monthly"
- "Annually"
- "OneTime"
- "Quarterly"

Example (success):
```json
{
  "studentId": "stu-1",
  "track": {
    "learningTrackId": "34a6bd30-a8f0-4c8f-9348-dc736d85c242",
    "learningTrackName": "Alpha Anywhere",
    "appId": "alpha-anywhere",
    "isLocked": false
  },
  "defaulted": false,
  "status": "unlocked"
}
```

---

### BatchGetLearningTrackAuthorizationResponse (object)

| Field | Type | Required | Description |
| - | - | - | - |
| `learningTrackId` | string | Yes | The learning track identifier from the request |
| `results` | array[BatchLearningTrackAuthorizationResult] | Yes | Authorization results for each student in the batch |

Each `results` item has the following fields:
- `studentId: string` – The Timeback student identifier from the request
- `track: UnifiedLearningTrack` – Learning track authorization data (only present when no error)
- `defaulted: boolean` – Present when no error
- `error: string` – Error message if student not found or other issues occurred
- `status: string` – Explicit authorization status when `track` is present

`status` enum values:
- "unlocked"
- "locked"
- "scheduled"
- "defaulted"

`frequency` enum values (within `track`):
- "Monthly"
- "Annually"
- "OneTime"
- "Quarterly"

Example:
```json
{
  "learningTrackId": "34a6bd30-a8f0-4c8f-9348-dc736d85c242",
  "results": [
    {
      "studentId": "stu-1",
      "track": {
        "learningTrackId": "34a6bd30-a8f0-4c8f-9348-dc736d85c242",
        "learningTrackName": "Alpha Anywhere",
        "appId": "alpha-anywhere",
        "isLocked": false
      },
      "defaulted": false,
      "status": "unlocked"
    },
    {
      "studentId": "stu-missing",
      "error": "Student not found"
    }
  ]
}
```

Example (error):
```json
{
  "studentId": "stu-missing",
  "error": "Student not found"
}
```




---

### GenerateParentTokenRequest (object)

| Field | Type | Required | Description |
| - | - | - | - |
| `parentTimebackId` | string | Yes | The Timeback identifier for the parent |
| `expiryMinutes` | number | No | Optional expiration time in minutes for the token (default 60) |

Example:
```json
{
  "parentTimebackId": "parent-abc-123",
  "expiryMinutes": 60
}
```

---

### GenerateParentTokenResponse (object)

| Field | Type | Required | Description |
| - | - | - | - |
| `url` | string | Yes | The URL to the Students app subscription portal with embedded token |

Example:
```json
{ "url": "https://students.example.com/subscribe?token=..." }
```

---

### BatchGetLearningTrackAuthorizationRequest (object)

| Field | Type | Required | Constraints | Description |
| - | - | - | - | - |
| `learningTrackId` | string | Yes |  | The learning track identifier |
| `studentIds` | array[string] | Yes | 1–100 items | Array of Timeback student identifiers (maximum 100 per batch) |

Example:
```json
{
  "learningTrackId": "34a6bd30-a8f0-4c8f-9348-dc736d85c242",
  "studentIds": [
    "stu-1",
    "stu-2"
  ]
}
```
