Sign in

v1

latestOpenAPI 3.1.02026-08-0670151364.9 KB
Recurring invoices

Create a recurring invoice

The recurring invoice is created as a draft. Nothing is generated or sent to the customer until it is activated, either via PUT /schedules/invoices/{id}:activate or from the console.

post/schedules/invoices

Request body

Example request

{
  "cadence": {
    "type": "INTERVAL",
    "timeUnit": "MONTH",
    "frequency": 1,
    "startDate": "2025-01-01T00:00:00.000Z"
  },
  "invoiceDetails": {
    "customer": {
      "id": "80349480-490b-4234-92e7-fad697e3d446"
    },
    "paymentTerm": {
      "timeUnit": "DAY",
      "value": 30
    },
    "distribution": {
      "collectionMethod": "AUTO_COLLECT",
      "customMessage": "Please find your invoice attached. Thank you for your business!",
      "approvedForSending": true
    },
    "description": "Monthly subscription for January",
    "currencyCode": "GBP",
    "itemsTaxType": "INCLUSIVE",
    "items": [
      {
        "description": "Pro Plan Subscription",
        "unitAmount": 5000,
        "quantity": 1
      }
    ]
  }
}

Response

The request was successful and the recurring invoice was created

idstring

The Adfin ID of the recurring invoice.

recurringInvoiceNostring

A system-generated, unique identifier for the recurring invoice. Automatically created using the prefix SCH followed by a numeric sequence (e.g., SCH-1, SCH-2, ...).

nextIssueDatestring date-time

The next date a new invoice will be automatically generated.

statusstring

Indicates the current status of the recurring invoice. Possible values might include:

  • DRAFT – currently not generating new invoices
  • ACTIVE – currently generating new invoices
  • FINISHED – has finished all planned occurrences
  • CANCELLED – has been cancelled before finishing all planned occurrences
creationTimestring date-time

The date and time when the recurring invoice was created.

lastUpdatedTimestring date-time

The date and time when the recurring invoice was last updated.

totalInvoicesinteger

The total number of invoices this recurring invoice is expected to generate based on cadence, start date, and end date.

amountnumber

The total amount of the recurring invoice. Calculated based on the sum of all invoice line items across all occurrences.

Example response

{
  "recurringInvoiceNo": "SCH-42",
  "nextIssueDate": "2025-10-15T00:00:00Z",
  "status": "ACTIVE",
  "cadence": {
    "timeUnit": "WEEK",
    "frequency": 2,
    "startDate": "2025-01-01T00:00:00.000Z",
    "endDate": "2025-12-31T23:59:59.000Z"
  },
  "invoiceDetails": {
    "customer": {
      "id": "80349480-490b-4234-92e7-fad697e3d446"
    },
    "paymentTerm": {
      "timeUnit": "DAY",
      "value": 30
    },
    "distribution": {
      "collectionMethod": "AUTO_COLLECT",
      "customMessage": "Please find your invoice attached. Thank you for your business!",
      "approvedForSending": true
    },
    "description": "Monthly subscription for January",
    "currencyCode": "GBP",
    "itemsTaxType": "INCLUSIVE",
    "items": [
      {
        "description": "Pro Plan Subscription",
        "unitAmount": 5000,
        "quantity": 1,
        "taxRate": 0.1
      }
    ]
  },
  "creationTime": "2025-09-27T12:00:00Z",
  "lastUpdatedTime": "2025-10-01T08:30:00Z",
  "totalInvoices": 10,
  "amount": 1234.5,
  "nextInvoices": [
    {
      "index": 3,
      "issueDate": "2025-11-01T00:00:00Z",
      "dueDate": "2025-11-08T00:00:00Z"
    }
  ]
}