Recurring Transactions

Recurring transactions automate the creation of regular financial transactions, such as monthly rent payments, subscription fees, or periodic revenue. Crane Ledger provides a comprehensive scheduling system that supports various frequencies, automatic execution, and flexible transaction templates.

Scheduling System

Supported Frequencies

Daily: Every day
Weekly: Every week on specified days
Monthly: Monthly on specific dates or day patterns
Quarterly: Every 3 months
Semi-Annually: Twice per year
Annually: Once per year

Lifecycle Management

Recurring schedules can be:

Active: Automatically executing transactions
Paused: Temporarily suspended
Completed: Finished (end date reached)
Cancelled: Permanently stopped

The Recurring Schedule Object

GET/organizations/:organization_id/recurring/:id

Auth required

{
  "id": "rec_xxxxxxxxxxxxxxxx",
  "organization_id": "org_xxxxxxxxxxxxxxxx",
  "name": "Monthly Rent Payment",
  "description": "Office rent payment - 15th of each month",
  "frequency": "Monthly",
  "frequency_config": {
    "day_of_month": 15
  },
  "start_date": "2024-01-15",
  "end_date": "2024-12-31",
  "next_run_date": "2024-02-15",
  "last_run_date": "2024-01-15",
  "status": "Active",
  "total_executions": 1,
  "max_executions": null,
  "template": {
    "currency": "USD",
    "entries": [
      {
        "account_id": "act_xxxxxxxxxxxxxxxx",
        "amount": "-2500.00",
        "description": "Office Rent Expense"
      },
      {
        "account_id": "act_yyyyyyyyyyyyyyyy",
        "amount": "2500.00",
        "description": "Cash"
      }
    ]
  },
  "created_at": "2024-01-01T10:00:00Z",
  "updated_at": "2024-01-15T08:30:00Z"
}

Attributes

Attribute	Type	Description
`id`	string	Unique identifier with `rec_` prefix
`organization_id`	string	The organization this schedule belongs to
`name`	string	Display name for the recurring schedule
`description`	string	Detailed description of the transaction
`frequency`	enum	Frequency: `Daily`, `Weekly`, `Monthly`, etc.
`frequency_config`	object	Configuration specific to the frequency type
`start_date`	date	When the schedule becomes active
`end_date`	date	Optional end date for the schedule
`next_run_date`	date	Next scheduled execution date
`last_run_date`	date	Date of last successful execution
`status`	enum	`Active`, `Paused`, `Completed`, `Cancelled`
`total_executions`	integer	Number of times executed
`max_executions`	integer	Optional maximum number of executions
`template`	object	Transaction template with entries
`created_at`	datetime	When schedule was created
`updated_at`	datetime	When schedule was last updated

List Recurring Schedules

GET/organizations/:organization_id/recurring

Auth required

Returns a list of recurring transaction schedules for the organization.

Path Parameters

Parameter	Type	Required	Description
`organization_id`	string	Yes	The organization ID

Query Parameters

Parameter	Type	Description
`status`	enum	Filter by status (`Active`, `Paused`, `Completed`, `Cancelled`)
`frequency`	enum	Filter by frequency
`limit`	integer	Number of results (default: 20, max: 100)
`offset`	integer	Pagination offset

Response

{
  "object": "list",
  "data": [
    {
      "id": "rec_xxxxxxxxxxxxxxxx",
      "name": "Monthly Rent Payment",
      "frequency": "Monthly",
      "next_run_date": "2024-02-15",
      "status": "Active",
      "total_executions": 1,
      "created_at": "2024-01-01T10:00:00Z"
    },
    {
      "id": "rec_yyyyyyyyyyyyyyyy",
      "name": "Weekly Payroll",
      "frequency": "Weekly",
      "next_run_date": "2024-01-22",
      "status": "Active",
      "total_executions": 4,
      "created_at": "2024-01-01T10:00:00Z"
    }
  ],
  "has_more": false,
  "total_count": 2
}

Create Recurring Schedule

POST/organizations/:organization_id/recurring

Auth required

10 credits

Creates a new recurring transaction schedule with a transaction template.

Path Parameters

Parameter	Type	Required	Description
`organization_id`	string	Yes	The organization ID

Request Body

Parameter	Type	Required	Description
`name`	string	Yes	Schedule name
`description`	string	No	Schedule description
`frequency`	enum	Yes	Frequency type
`frequency_config`	object	Yes	Frequency-specific configuration
`start_date`	date	Yes	When schedule becomes active
`end_date`	date	No	Optional end date
`max_executions`	integer	No	Maximum number of executions
`template`	object	Yes	Transaction template

Frequency Configurations

Daily:

{
  "frequency": "Daily",
  "frequency_config": {}
}

Weekly:

{
  "frequency": "Weekly",
  "frequency_config": {
    "days_of_week": ["Monday", "Wednesday", "Friday"]
  }
}

Monthly:

{
  "frequency": "Monthly",
  "frequency_config": {
    "day_of_month": 15
  }
}

Annually:

{
  "frequency": "Annually",
  "frequency_config": {
    "month": 12,
    "day_of_month": 31
  }
}

Transaction Template

{
  "currency": "USD",
  "entries": [
    {
      "account_id": "act_xxxxxxxxxxxxxxxx",
      "amount": "-1000.00",
      "description": "Monthly Subscription"
    },
    {
      "account_id": "act_yyyyyyyyyyyyyyyy",
      "amount": "1000.00",
      "description": "Credit Card"
    }
  ]
}

Response

{
  "id": "rec_xxxxxxxxxxxxxxxx",
  "organization_id": "org_xxxxxxxxxxxxxxxx",
  "name": "Monthly Rent Payment",
  "description": "Office rent - 15th of each month",
  "frequency": "Monthly",
  "frequency_config": {
    "day_of_month": 15
  },
  "start_date": "2024-02-15",
  "end_date": "2024-12-31",
  "next_run_date": "2024-02-15",
  "status": "Active",
  "total_executions": 0,
  "template": {
    "currency": "USD",
    "entries": [
      {
        "account_id": "act_xxxxxxxxxxxxxxxx",
        "amount": "-2500.00",
        "description": "Office Rent Expense"
      },
      {
        "account_id": "act_yyyyyyyyyyyyyyyy",
        "amount": "2500.00",
        "description": "Checking Account"
      }
    ]
  },
  "created_at": "2024-01-10T14:30:00Z",
  "updated_at": "2024-01-10T14:30:00Z"
}

Get Recurring Schedule

GET/organizations/:organization_id/recurring/:id

Auth required

Retrieves the details of a specific recurring schedule.

Path Parameters

Parameter	Type	Required	Description
`organization_id`	string	Yes	The organization ID
`id`	string	Yes	The recurring schedule ID

Response

{
  "id": "rec_xxxxxxxxxxxxxxxx",
  "organization_id": "org_xxxxxxxxxxxxxxxx",
  "name": "Monthly Rent Payment",
  "description": "Office rent - 15th of each month",
  "frequency": "Monthly",
  "frequency_config": {
    "day_of_month": 15
  },
  "start_date": "2024-01-15",
  "end_date": "2024-12-31",
  "next_run_date": "2024-02-15",
  "last_run_date": "2024-01-15",
  "status": "Active",
  "total_executions": 1,
  "template": {
    "currency": "USD",
    "entries": [
      {
        "account_id": "act_xxxxxxxxxxxxxxxx",
        "amount": "-2500.00",
        "description": "Office Rent Expense"
      },
      {
        "account_id": "act_yyyyyyyyyyyyyyyy",
        "amount": "2500.00",
        "description": "Checking Account"
      }
    ]
  },
  "created_at": "2024-01-01T10:00:00Z",
  "updated_at": "2024-01-15T08:30:00Z"
}

Update Recurring Schedule

PUT/organizations/:organization_id/recurring/:id

Auth required

5 credits

Updates an existing recurring schedule. Note that some fields cannot be changed after creation.

Path Parameters

Parameter	Type	Required	Description
`organization_id`	string	Yes	The organization ID
`id`	string	Yes	The recurring schedule ID

Request Body

Parameter	Type	Description
`name`	string	Updated schedule name
`description`	string	Updated description
`end_date`	date	Updated end date
`max_executions`	integer	Updated maximum executions
`template`	object	Updated transaction template

Response

{
  "id": "rec_xxxxxxxxxxxxxxxx",
  "name": "Updated Monthly Rent",
  "description": "Office rent increased to $2600",
  "updated_at": "2024-01-20T11:15:00Z",
  "next_run_date": "2024-02-15"
}

Pause Recurring Schedule

POST/organizations/:organization_id/recurring/:id/pause

Auth required

1 credits

Temporarily pauses a recurring schedule. No transactions will be created until resumed.

Path Parameters

Parameter	Type	Required	Description
`organization_id`	string	Yes	The organization ID
`id`	string	Yes	The recurring schedule ID

Response

{
  "id": "rec_xxxxxxxxxxxxxxxx",
  "status": "Paused",
  "next_run_date": null,
  "updated_at": "2024-01-25T09:30:00Z"
}

Resume Recurring Schedule

POST/organizations/:organization_id/recurring/:id/resume

Auth required

1 credits

Resumes a paused recurring schedule. The next run date will be recalculated.

Path Parameters

Parameter	Type	Required	Description
`organization_id`	string	Yes	The organization ID
`id`	string	Yes	The recurring schedule ID

Response

{
  "id": "rec_xxxxxxxxxxxxxxxx",
  "status": "Active",
  "next_run_date": "2024-02-15",
  "updated_at": "2024-01-26T10:00:00Z"
}

Delete Recurring Schedule

DELETE/organizations/:organization_id/recurring/:id

Auth required

5 credits

Permanently deletes a recurring schedule. Only paused or completed schedules can be deleted.

Path Parameters

Parameter	Type	Required	Description
`organization_id`	string	Yes	The organization ID
`id`	string	Yes	The recurring schedule ID

Response

{
  "id": "rec_xxxxxxxxxxxxxxxx",
  "deleted": true
}

Recurring Transaction Best Practices

Schedule Planning

Start Dates: Set appropriate start dates (avoid scheduling for past dates)
End Dates: Use end dates for fixed-term obligations (leases, subscriptions)
Business Days: Consider business day scheduling for payment processing
Time Zones: Account for time zone differences in international operations

Transaction Templates

Balanced Entries: Ensure all transaction templates are properly balanced
Account Validation: Verify account IDs exist and are active
Currency Consistency: Use consistent currencies across entries
Descriptive Entries: Include clear, specific descriptions

Frequency Selection

Daily: For frequent small transactions (interest accrual, petty cash)
Weekly: For payroll, regular service fees
Monthly: For rent, utilities, subscriptions
Quarterly: For tax payments, insurance premiums
Annually: For annual fees, license renewals

Monitoring & Maintenance

Execution Tracking: Monitor successful executions and failures
Schedule Reviews: Regularly review and update schedules
Status Management: Pause schedules during account changes
Audit Trails: Maintain records of all schedule changes

Common Use Cases

Recurring Revenue: Subscription services, membership fees
Expense Management: Rent, utilities, insurance payments
Payroll Processing: Regular salary and benefit payments
Loan Servicing: Interest and principal payments
Depreciation: Periodic asset depreciation entries

Automatic Execution

Recurring transactions are executed automatically by background workers. Ensure your worker system is running to process scheduled transactions.

Schedule Changes

Changes to frequency, amounts, or accounts only affect future transactions. Past transactions remain unchanged for audit purposes.

Need help?

Create a free account to access our support portal. Once signed in, use the Support tab in your dashboard to submit a support ticket — our team typically responds within 24 hours.

✨ For LLMs/AI assistants: Read our structured API reference