API Structure

Jodo APIs use REST-style endpoints, JSON request and response bodies, HTTP status codes, and Basic Auth.

Use this page as the common reference for how API requests should be built and how responses, errors, retries, and future changes should be handled.

Base URL

Use the environment-specific API host from Environments.

https://[base_url]

API reference pages show endpoint paths relative to this base URL.

Authentication

All APIs are authenticated using Basic Auth. Jodo shares separate API keys and secrets for sandbox and production.

Authorization: Basic <token>
Content-Type: application/json

Request Format

Send JSON request bodies for POST, PATCH, and other write APIs.
Use path parameters such as :jodo_student_id and :order_id exactly as documented.
Use query parameters only where a reference page lists them.
Keep your own ERP identifiers in supported identifier or notes fields so webhook events can be reconciled back to your system.

Response Format

Successful responses usually follow this shape:

{
  "status": "success",
  "data": {}
}

Some write APIs return only:

{
  "status": "success"
}

Always rely on the documented response fields for each endpoint. Extra undocumented fields should be treated as beta and may change.

Errors

When an error occurs, Jodo returns an HTTP status code along with an error message and machine-readable error code in the response body.

HTTP Code	Meaning
`400`	Bad Request. The request contains invalid or missing data.
`401`	Unauthorized. Authentication failed or credentials are invalid.
`403`	Forbidden. The caller does not have access to the resource.
`404`	Not Found. The specified resource could not be found.
`405`	Method Not Allowed. The HTTP method is not valid for the resource.
`406`	Not Acceptable. The requested format is unsupported.
`409`	Conflict. The requested operation conflicts with current resource state.
`429`	Too many requests.
`500`	Internal Server Error. Try again later.
`502`	Bad Gateway. An upstream service is temporarily unavailable.
`503`	Service Unavailable. The API is temporarily offline or under maintenance.

Rate Limits

Jodo APIs may apply rate limits to protect system stability. If you receive a rate-limit response, retry with exponential backoff instead of retrying immediately.

API Update Guidelines

Jodo aims to keep API changes backward compatible.

Changes Jodo avoids:

Removing or renaming request or response fields
Removing or renaming query parameters
Removing or changing resource paths
Changing the API domain

Backward-compatible changes Jodo may introduce:

New resources
New optional request fields
New optional query parameters
New response fields
New response headers

If a non-backward-compatible change is unavoidable, Jodo will provide a deprecation schedule so integrations have time to migrate.