We are using cookies to improve your experience!

By clicking "Allow all", you agree to use of all cookies. Visit our Privacy Policy to learn more.

Start

Create an Invoice

POST /api/v1/invoices

Create a new invoice for a customer. Optionally include line items, discounts, and taxes. The invoice starts in draft status.

Request Body

Field Type Required Description
invoice[issued_at] string (ISO 8601) No Issue date (default: now).
invoice[due_at] string (ISO 8601) No Due date.
invoice[payment_term_id] integer No ID of the payment term.
invoice[currency] string Yes Currency code (e.g., USD, ZAR).
invoice[customer_id] integer Yes ID of the customer.
invoice[notes] string No Additional notes.
invoice[discount_type] string No fixed or percent (default: none).
invoice[discount_value] decimal No Discount amount or percentage.
invoice[items_attributes][][name] string Yes (per item) Item description.
invoice[items_attributes][][quantity] integer Yes (per item) Quantity.
invoice[items_attributes][][unit_price] decimal Yes (per item) Unit price.
invoice[invoice_taxes_attributes][][tax_id] integer No ID of the tax rate.

Request Example

{
  "invoice": {
    "issued_at": "2025-10-12T00:00:00.000Z",
    "payment_term_id": 89,
    "currency": "USD",
    "customer_id": 13,
    "items_attributes": [
      {
        "name": "Items Consulting",
        "quantity": 1,
        "unit_price": "400.0"
      }
    ],
    "discount_type": "percent",
    "discount_value": "5",
    "invoice_taxes_attributes": [
      {
        "tax_id": "1"
      }
    ],
    "notes": ""
  }
}

POST /api/v1/invoices HTTP/1.1
Host: koteshen.com
Authorization: Bearer {access_token}
Content-Type: application/json
Accept: application/json

{request_body}

Response

Status Codes:

  • 201 Created - Invoice created successfully.
  • 401 Unauthorized - Invalid or missing token.
  • 422 Unprocessable Entity - Validation errors (e.g., missing required fields).

Success Response (201)

{
  "data": {
    "id": 150,
    "number": "INV-8E5E-2268",
    "customer_id": 13,
    "business_id": 1,
    "currency": "USD",
    "due_at": "2025-10-12T00:00:00.000Z",
    "issued_at": "2025-10-12T00:00:00.000Z",
    "notes": "",
    "discount_type": "percent",
    "discount_value": "5.0",
    "status": "created",
    "paid": false,
    "payment_term_id": 89,
    "emailed_at": null,
    "created_at": "2025-10-21T03:39:57.825Z",
    "updated_at": "2025-10-21T03:39:57.913Z",
    "subtotal": {
      "cents": 400,
      "currency_iso": "USD"
    },
    "discount": {
      "cents": 20,
      "currency_iso": "USD"
    },
    "tax_total": {
      "cents": 5700,
      "currency_iso": "USD"
    },
    "total": {
      "cents": 437,
      "currency_iso": "USD"
    },
    "balance": {
      "cents": 437,
      "currency_iso": "USD"
    },
    "payment_term": {
      "id": 89,
      "name": "Due on Receipt",
      "value": 0,
      "created_at": "2025-09-20T12:04:28.089Z",
      "updated_at": "2025-09-20T12:04:28.089Z"
    },
    "url": "http://localhost:3000/api/v1/invoices/150.json",
    "items": [
      {
        "id": 181,
        "name": "Items Consulting",
        "unit_price": "400.0",
        "quantity": 1,
        "total": "400.0",
        "created_at": "2025-10-21T03:39:57.893Z",
        "updated_at": "2025-10-21T03:39:57.893Z"
      }
    ],
    "business": {
      "id": 1,
      "user_id": 1,
      "name": "Flixtechs",
      "slug": "flixtechs",
      "phone": "+27675711214",
      "phone_country": null,
      "discarded_at": null,
      "created_at": "2025-08-17T09:26:59.612Z",
      "updated_at": "2025-08-29T13:30:08.427Z",
      "address": {
        "id": 9,
        "line": "1 Mahem Place",
        "line2": "",
        "post_code": "5256",
        "city": "East London",
        "country": "ZA",
        "created_at": "2025-08-29T13:30:08.441Z",
        "updated_at": "2025-08-29T13:30:08.441Z"
      },
      "logo": "<logo_url>"
    },
    "customer": {
      "id": 13,
      "name": "Texas Ins",
      "company": "Texas Ins",
      "customer_type": "business",
      "phone": "+27675711214",
      "phone_country": "za",
      "currency": "zar",
      "email": "procurement@texas.com",
      "website": "https://texas.com",
      "business_id": 1,
      "notes": "notesy",
      "created_at": "2025-10-12T19:00:37.057Z",
      "updated_at": "2025-10-12T19:09:27.293Z",
      "address": {
        "id": 26,
        "line": "1 Mahem Pl",
        "line2": "Unit 23",
        "post_code": "5256",
        "city": "East London",
        "country": "South Africa",
        "created_at": "2025-10-12T19:09:27.300Z",
        "updated_at": "2025-10-12T19:09:27.300Z"
      },
      "url": "http://localhost:3000/api/v1/customers/13.json"
    },
    "taxes": [
      {
        "id": 18,
        "tax_name": "VAT",
        "tax_amount": {
          "cents": 5700,
          "currency_iso": "USD"
        },
        "tax_rate": "15.0",
        "created_at": "2025-10-21T03:39:57.946Z",
        "updated_at": "2025-10-21T03:39:57.946Z",
        "tax": {
          "id": 1,
          "name": "VAT",
          "rate": "15.0"
        }
      }
    ]
  }
}

Error Response Example (422)

{
  "errors": []
}