Overview

Koteshen is Everything you need to bill like a pro. Stop wrestling spreadsheets. Koteshen bundles quotes, invoicing, and recurring payments into one clean workflow. Our API provides the flexibility to integrate these features seamlessly into your applications.

This API follows RESTful conventions and uses JSON for request and response bodies. All endpoints are under the /api/v1 namespace.

Quick Start

Base URL

All API requests should be made to:

https://koteshen.com/api/v1

Authentication

Koteshen uses OAuth 2.0 for secure authentication. To access protected endpoints:

1. Register your application in the Koteshen dashboard to obtain your client_id and client_secret.
2. Authorize your app by redirecting users to the authorization endpoint:

   GET https://koteshen.com/oauth/authorize?client_id={client_id}&redirect_uri={redirect_uri}&scope=read write&response_type=code

1. Exchange the authorization code for an access token:

   POST https://koteshen.com/oauth/token

• Body (form-encoded): grant_type=authorization_code&code={code}&redirect_uri={redirect_uri}&client_id={client_id}&client_secret={client_secret}

The access token should be included in the Authorization header as a Bearer token:

Authorization: Bearer {access_token}

• Scopes: read (for GET requests) and write (for POST/PATCH/DELETE).
• Token Refresh: Use the refresh token endpoint at POST https://koteshen.com/oauth/token with grant_type=refresh_token.
• Rate Limits: 100 requests per minute per token (subject to change).

For testing, import our Postman collection which includes pre-configured OAuth2 authentication.

Error Handling

API responses use standard HTTP status codes. Errors return a JSON body like:

{
  "error": "Invalid token",
  "message": "The provided token is expired or invalid"
}

Common codes:

• 200 OK: Success.
• 201 Created: Resource created.
• 401 Unauthorized: Authentication required or failed.
• 422 Unprocessable Entity: Validation errors (details in response body).
• 404 Not Found: Resource not found.
• 429 Too Many Requests: Rate limit exceeded.

Resources

Koteshen API exposes the following core resources. Each supports standard CRUD operations unless noted.

Customers

Manage clients and contacts (individuals/businesses with addresses).

Example Response (List):

{
  "data": [
    {
      "id": 13,
      "name": "Texas Ins",
      "company": "Texas Ins",
      "customer_type": "business",
      "email": "procurement@texas.com",
      "phone": "+27675711214",
      "currency": "ZAR",
      "address": {
        "line": "1 Mahem Pl",
        "city": "East London",
        "country": "South Africa"
      },
      "url": "https://koteshen.com/api/v1/customers/13"
    }
  ],
  "meta": {
    "pagination": {
      "current_page": 1,
      "total_count": 5
    }
  }
}

Invoices

Create, send, and track invoices (with items, taxes, discounts, payments, reminders, recurring).

Quotes

Generate and manage estimates (convertible to invoices).

Payments

Track payments (standalone or invoice-linked).

Account

Basic introspection.

Webhooks

Subscribe to events (e.g., invoice.overdue).

Example Payload:

{
  "url": "https://your-webhook-url.com/events",
  "enabled_events": ["invoice.overdue", "payment.received"]
}

Pagination

List endpoints use cursor-based pagination via query params:

• ?page=1&per_page=20 Responses include meta.pagination with current_page, total_count, etc.

Versioning

We use URL-based versioning (/api/v1). Check the changelog for updates.

Support

• API Reference: Detailed endpoint docs coming soon.
• Contact: Reach out at support@koteshen.com or via the dashboard.

Happy invoicing!