Convert to Recurring Invoice

PATCH /api/v1/invoices/:id/recurring

/api/v1/invoices/:id/recurring

Convert a one-time invoice to a recurring invoice by attaching a subscription schedule. The original invoice remains unchanged; a new recurring series is created.

Path Parameters

Request Body

Request Example

{
  "invoices_subscription": {
    "schedule": "every month",
    "ends_at": "2025-11-30"
  }
}

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

{request_body}

Response

Status Codes:

• 201 Created - Recurring subscription created.
• 401 Unauthorized - Invalid or missing token.
• 404 Not Found - Source invoice not found.
• 422 Unprocessable Entity - Invalid schedule.

Success Response (201)

{
  "data": {
    "id": 151,
    "number": "INV-3B1F-2555",
    "customer_id": 13,
    "business_id": 1,
    "currency": "USD",
    "due_at": "2025-10-30T09:00:00.000Z",
    "issued_at": "2025-10-21T00:00:00.000Z",
    "notes": "",
    "discount_type": "percent",
    "discount_value": "5.0",
    "status": "unpaid",
    "paid": false,
    "payment_term_id": 89,
    "emailed_at": null,
    "created_at": "2025-10-21T03:58:04.983Z",
    "updated_at": "2025-10-21T03:58:04.983Z",
    "subtotal": {
      "cents": 400,
      "currency_iso": "USD"
    },
    "discount": {
      "cents": 20,
      "currency_iso": "USD"
    },
    "tax_total": 0,
    "total": {
      "cents": 380,
      "currency_iso": "USD"
    },
    "balance": {
      "cents": 380,
      "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"
    },
    "recurring_invoice": {
      "id": 11,
      "starts_at": "2025-10-21T00:00:00.000Z",
      "ends_at": null,
      "schedule": "every month",
      "last_ran_at": null,
      "next_run_at": null,
      "invoice_id": 151,
      "created_at": "2025-10-21T03:58:10.548Z",
      "updated_at": "2025-10-21T03:58:10.548Z"
    },
    "url": "http://localhost:3000/api/v1/invoices/151.json",
    "items": [
      {
        "id": 182,
        "name": "Items Consulting",
        "unit_price": "400.0",
        "quantity": 1,
        "total": "400.0",
        "created_at": "2025-10-21T03:58:05.033Z",
        "updated_at": "2025-10-21T03:58:05.033Z"
      }
    ],
    "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": []
  }
}