openapi: 3.2.0
info:
  title: Jodo ERP Integrations Students API
  version: v1
  summary: Fee collection, flexible instalment plans and education credit for Indian educational institutes.
  description: 'Jodo''s ERP Integrations API lets an institute''s ERP, finance or student-information system

    connect to Jodo fee collection. It covers user registration and hosted-flow access tokens,

    student master data and fee structures, manual/direct payment reconciliation, Flex instalment

    plans, Pay checkout orders and shareable payment links, and webhook subscription management.


    PROVENANCE: Jodo publishes no OpenAPI document. This description was assembled from Jodo''s own

    public API reference at https://docs.jodo.in/ (Astro Starlight, server-rendered HTML), one

    documented operation per reference page. Every path, method, path/query parameter, request-body

    field, response field and error code below is transcribed from the corresponding docs page named

    in the operation''s `x-source` extension. No operation, parameter or field has been invented.

    Field types are the ones the docs state. Where the docs do not state a constraint, none is asserted.

    '
  contact:
    name: Jodo
    url: https://docs.jodo.in/
  x-provenance:
    method: generated
    generated_by: API Evangelist enrichment pipeline
    generated: '2026-08-23'
    source_docs: https://docs.jodo.in/
    note: Endpoint paths, methods, parameters, request/response fields and error codes are grounded in docs.jodo.in as fetched 2026-08-23 (all reference pages HTTP 200). This is a third-party rendering of Jodo's published reference, not a Jodo-published artifact. Reconcile against the live API reference before relying on it.
servers:
- url: https://ext.jodo.in
  description: Production API host. Jodo documents this as base_url on https://docs.jodo.in/getting-started/environments/. https://api.jodo.in is documented as jodo_auth_host and issues an HTTP 301 to https://ext.jodo.in.
- url: https://ext.devtest1.jodopay.com
  description: UAT / sandbox API host, documented on https://docs.jodo.in/getting-started/environments/. jodopay.com is Jodo's own non-production domain (the company also operates @Jodopay social handles).
security:
- basicAuth: []
tags:
- name: Students
  description: Student master data, fee structures and manual payment reconciliation.
paths:
  /api/v1/integrations/erp/users/{registration_id}/students:
    post:
      operationId: registerStudent
      summary: Register Student
      description: Register a new student for a given user, uniquely identified by registration_id. Creates student profiles associated with specific users within the Jodo system.
      tags:
      - Students
      x-source: https://docs.jodo.in/student/api/register-student/
      parameters:
      - $ref: '#/components/parameters/RegistrationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterStudentRequest'
      responses:
        '200':
          description: Student registered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusOnlyResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/integrations/erp/students/{jodo_student_id}:
    get:
      operationId: getStudent
      summary: Get Student
      description: Returns student details identified by jodo_student_id.
      tags:
      - Students
      x-source: https://docs.jodo.in/student/api/get-student/
      parameters:
      - $ref: '#/components/parameters/JodoStudentId'
      responses:
        '200':
          description: Student record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudentResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateStudent
      summary: Update Student
      description: Update the profile details of a student identified by jodo_student_id.
      tags:
      - Students
      x-source: https://docs.jodo.in/student/api/update-student/
      parameters:
      - $ref: '#/components/parameters/JodoStudentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Student'
      responses:
        '200':
          description: Student updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/integrations/erp/students/{jodo_student_id}/fee:
    patch:
      operationId: updateStudentFee
      summary: Update Fee
      description: Update the fee components and discounts configured for a student.
      tags:
      - Students
      x-source: https://docs.jodo.in/student/api/update-fee/
      parameters:
      - $ref: '#/components/parameters/JodoStudentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFeeRequest'
      responses:
        '200':
          description: Fee updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusOnlyResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/integrations/erp/students/{jodo_student_id}/products:
    get:
      operationId: listStudentProducts
      summary: List Products
      description: Retrieve Jodo products associated with a student, optionally filtered by product type.
      tags:
      - Students
      x-source: https://docs.jodo.in/student/api/list-products/
      parameters:
      - $ref: '#/components/parameters/JodoStudentId'
      - name: product_type
        in: query
        required: false
        description: 'Optional product filter. Possible values: flex, pay, cred.'
        schema:
          type: string
          enum:
          - flex
          - pay
          - cred
      responses:
        '200':
          description: Products for the student.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductListResponse'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/integrations/erp/students/{jodo_student_id}/payments:
    get:
      operationId: listStudentPayments
      summary: List Payments
      description: Retrieve the payment list for a student identified by jodo_student_id.
      tags:
      - Students
      x-source: https://docs.jodo.in/student/api/list-payments/
      parameters:
      - $ref: '#/components/parameters/JodoStudentId'
      responses:
        '200':
          description: Payments recorded for the student.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentListResponse'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: addStudentPayment
      summary: Add Payment
      description: Record a manual (direct) payment for a student identified by jodo_student_id.
      tags:
      - Students
      x-source: https://docs.jodo.in/student/api/add-payment/
      parameters:
      - $ref: '#/components/parameters/JodoStudentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddPaymentRequest'
      responses:
        '200':
          description: Payment recorded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusOnlyResponse'
        '400':
          $ref: '#/components/responses/BadRequestMAE'
        '404':
          $ref: '#/components/responses/StudentNotFound'
  /api/v1/integrations/erp/students/{jodo_student_id}/payments/{transaction_id}:
    delete:
      operationId: cancelStudentPayment
      summary: Cancel Payment
      description: Cancel a payment for a student identified by jodo_student_id and transaction_id. Use only for payments recorded through the direct/manual payment API, with the same transaction_id that was sent when the payment was added.
      tags:
      - Students
      x-source: https://docs.jodo.in/student/api/cancel-payment/
      parameters:
      - $ref: '#/components/parameters/JodoStudentId'
      - name: transaction_id
        in: path
        required: true
        description: Transaction ID of the payment to cancel.
        schema:
          type: string
      responses:
        '200':
          description: Payment cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusOnlyResponse'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Student:
      type: object
      required:
      - fullname
      - identifier
      - grade
      - new_admission
      - academic_year_start
      - academic_year_end
      - date_of_birth
      - primary_contact_name
      - primary_contact_number
      - primary_contact_email
      properties:
        fullname:
          type: string
          description: The full name of the student.
        identifier:
          type: string
          description: An identifier for the student assigned by the school (enrolment number).
        custom_identifier:
          type: string
          description: Student custom identifier.
        grade:
          type: string
          description: Unique grade identifier as shared between Jodo and the ERP provider.
        new_admission:
          type: boolean
          description: Indicates if it is a new admission.
        academic_year_start:
          type:
          - string
          - integer
          description: The start year of the academic year.
        academic_year_end:
          type:
          - string
          - integer
          description: The end year of the academic year.
        date_of_birth:
          type: string
          description: Date of birth in YYYY-MM-DD format.
        primary_contact_name:
          type: string
          description: The name of the primary contact for the student.
        primary_contact_number:
          type: string
          description: The primary contact number.
        primary_contact_email:
          type: string
          format: email
          description: The primary contact email.
    RegisterStudentRequest:
      type: object
      required:
      - student
      properties:
        student:
          $ref: '#/components/schemas/Student'
        fee_components:
          type: array
          items:
            $ref: '#/components/schemas/FeeComponent'
        payments:
          type: array
          items:
            $ref: '#/components/schemas/HistoricPayment'
    PaymentListResponse:
      type: object
      properties:
        status:
          type: string
          examples:
          - success
        data:
          type: array
          items:
            type: object
    FeeComponent:
      type: object
      required:
      - component_type
      - fee_amount
      properties:
        component_type:
          type: string
          description: The type of fee component, e.g. TUITION_FEE, TRANSPORT_FEE.
        fee_amount:
          type: number
          description: The fee amount for the component.
        discounts:
          type: array
          description: Discounts applied to this component.
          items:
            $ref: '#/components/schemas/Discount'
    Discount:
      type: object
      required:
      - discount_type
      - value
      properties:
        discount_type:
          type: string
          description: One of the discount types as shared between Jodo and the ERP.
        value:
          type: integer
          description: Discount amount in INR.
    StudentResponse:
      type: object
      properties:
        status:
          type: string
          examples:
          - success
        data:
          type: object
          properties:
            fullname:
              type: string
            identifier:
              type: string
              description: Student identifier assigned by the school (enrolment number).
            custom_identifier:
              type: string
            grade:
              type: string
              description: Unique grade identifier as shared between Jodo and the ERP provider.
            new_admission:
              type: boolean
            academic_year_start:
              type: integer
            academic_year_end:
              type: integer
            date_of_birth:
              type: string
              description: Date of birth in YYYY-MM-DD format.
            collector_code:
              type: string
              description: Institute code.
            joining_year:
              type: integer
              description: Joining year; present if the student is a new admission.
            primary_contact_name:
              type: string
            primary_contact_number:
              type: string
            primary_contact_email:
              type: string
              format: email
            fee_summary:
              type: object
              properties:
                total_fee:
                  type: number
                  description: Total fee for the student.
                total_discount:
                  type: number
                  description: Total discount for the student.
    AddPaymentRequest:
      type: object
      required:
      - amount
      - paid_at
      - fee_components
      properties:
        amount:
          type: number
          description: Total amount paid.
        paid_at:
          type: string
          format: date-time
          description: Paid date and time in ISO 8601 format.
        mode:
          type: string
          description: Mode of payment. Defaults to others if not provided.
        transaction_id:
          type: string
          description: Unique transaction ID from your system. Reused as the path key when cancelling the payment.
        settlement_utr:
          type: string
          description: Settlement UTR
          if already available.: null
        notes:
          type: string
          description: Payment notes.
        fee_components:
          type: array
          description: Fee component level payment allocation.
          items:
            $ref: '#/components/schemas/PaymentAllocation'
    Error:
      type: object
      description: Jodo returns an HTTP status code with a user-facing message and a machine-readable error code.
      properties:
        status:
          type: string
          examples:
          - error
        code:
          type: string
          description: Machine-readable Jodo error code, e.g. HUE00000, HUE00001, MAE00000, MAE00001.
        message:
          type: string
          description: User-friendly explanation of the error.
    PaymentAllocation:
      type: object
      required:
      - component_type
      - amount
      properties:
        component_type:
          type: string
          description: Fee component for which payment is made.
        amount:
          type: number
          description: Amount paid for this fee component.
    HistoricPayment:
      type: object
      required:
      - amount
      - paid_at
      - mode
      - transaction_id
      - fee_components
      properties:
        amount:
          type: number
          description: The payment amount.
        paid_at:
          type: string
          format: date-time
          description: The date and time of the payment in ISO 8601 format.
        mode:
          type: string
          description: The payment mode, e.g. cash, credit card.
        transaction_id:
          type: string
          description: The unique transaction ID for the student.
        settlement_utr:
          type: string
          description: The settlement UTR (Unique Transaction Reference)
          if applicable.: null
        notes:
          type: string
          description: Additional notes or comments regarding the payment.
        fee_components:
          type: array
          description: Fee components included in this payment.
          items:
            $ref: '#/components/schemas/PaymentAllocation'
    UpdateFeeRequest:
      type: object
      required:
      - fee_components
      properties:
        fee_components:
          type: array
          items:
            $ref: '#/components/schemas/FeeComponent'
    ProductListResponse:
      type: object
      properties:
        status:
          type: string
          examples:
          - success
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              product_type:
                type: string
                enum:
                - flex
                - pay
                - cred
              status:
                type: string
                examples:
                - pending
    StatusOnlyResponse:
      type: object
      description: Some write APIs return only a status envelope.
      properties:
        status:
          type: string
          examples:
          - success
  parameters:
    RegistrationId:
      name: registration_id
      in: path
      required: true
      description: Unique registration ID for the user, returned by Register User.
      schema:
        type: string
    JodoStudentId:
      name: jodo_student_id
      in: path
      required: true
      description: Jodo student ID.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Unauthorized. Authentication failed or credentials are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    StudentNotFound:
      description: MAE00001 — Student not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: HUE00000 — Bad request. The request contains invalid or missing data.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequestMAE:
      description: MAE00000 — Bad request error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: HUE00001 — Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: All Jodo APIs are authenticated using HTTP Basic Auth. Jodo shares separate API keys and secrets for the UAT and production environments. Documented at https://docs.jodo.in/getting-started/authentication/ — keys and secrets must never be exposed in browsers, mobile apps or client-side code.