Recurring Schedules API

Clientary provides programmatic access to recurring schedules which can be used to periodically generate new invoices.

Get All Recurring Schedules

GET /api/v2/recurring/

{
  "page_size": 10,
  "page_count": 1,
  "total_count": 2,
  "recurring": [
    {
      "action":0,
      "client_id":4,
      "compound_tax":false,
      "currency_code":"USD",
      "due_period":10,
      "id":2,
      "next_date":"2014-03-16",
      "note":"",
      "number":"1000001",
      "occurrences_remaining":10,
      "payment_profile_id":null,
      "po":null,
      "status":0,
      "summary":null,
      "tax":8.25,
      "tax2":2.0,
      "tax2_label":"",
      "tax_label":"",
      "tax3_label": "",
      "tax3": 0,
      "time_interval":3,
      "title":"Monthly Retainer",
      "unlimited":false,
      "updated_at":"2013-02-06T21:23:21-08:00",
      "subtotal":49.99,
      "total_cost":49.99,
      "client":
      {
        ...
      },
      "recurring_schedule_items": [
        {
          "id":3,
          "item_type":1,
          "price":"49.99",
          "quantity":1.0,
          "recurring_schedule_id":2,
          "title":"Subscription",
          "taxable?":false,
          "secondary_tax?":false,
          "tertiary_tax?":false,
          "total_tax":0
        },
        ...
      ]
    },
    ...
  ]
}

Recurring Schedule Status Values:

0: Active
1: Paused
2: Stopped

Recurring Schedule Item Type Values:

0: Section Header
3: Regular Invoice Line Item

Recurring Schedule Action Values:

0: Send
1: Draft
2: Autobill. payment_profile_id must be set to a valid ID.

Recurring Schedule Time Interval Values:

1: Weekly
2: Every 2 Weeks
3: Semimonthly
4: Every 4 Weeks
5: Monthly
6: Every 2 Months
7: Quarterly
8: Every 6 Months
9: Annually
10: Every 2 Years
11: Every 4 Months

GET /api/v2/recurring?page=2

On a bulk GET Clientary will return 30 results at once. To paginate through more results, you can use the page parameter.

Get A Recurring Schedule

GET /api/v2/recurring/:id

{
  "action":0,
  "client_id":4,
  "compound_tax":false,
  "currency_code":"USD",
  "due_period":10,
  "id":2,
  "next_date":"2014-03-16",
  "note":"",
  "number":"1000001",
  "occurrences_remaining":10,
  "payment_profile_id":null,
  "po":null,
  "status":0,
  "summary":null,
  "tax":8.25,
  "tax2":2.0,
  "tax2_label":"",
  "tax_label":"",
  "tax3_label": "",
  "tax3": 0,
  "time_interval":3,
  "title":"Monthly Retainer",
  "unlimited":false,
  "updated_at":"2013-02-06T21:23:21-08:00",
  "subtotal":49.99,
  "total_cost":49.99,
  "client":
  {
    ...
  },
  "recurring_schedule_items": [
    {
      "id":3,
      "item_type":1,
      "price":"49.99",
      "quantity":1.0,
      "recurring_schedule_id":2,
      "title":"Subscription",
      "taxable?":false,
      "secondary_tax?":false,
      "tertiary_tax?":false,
      "total_tax":0
    },
    ...
  ]
}

Create A New Recurring Schedule

POST /api/v2/recurring

{
  "recurring_schedule": {
    "number": 185,
    "next_date": "2015-07-29",
    "due_period": 30,
    "currency_code": "USD",
    "time_interval": 4,
    "client_id": 123,
    "recurring_schedule_items_attributes": [
      {
        "title": "foo",
        "quantity": 1,
        "price": 100
      },
      {
        "title": "bar",
        "quantity": 2,
        "price": 200
      }
    ]
  }
}

Required Fields: due_period (in days), currency_code, next_date, time_interval, client_id (HTTP 422 on failure)
Optional Fields: number will be autoincremented from previous invoice numbers if not provided
Conditional Fields: invoice_item_attributes.title, invoice_item_attributes.quantity, invoice_item_attributes.price must be provided if any items are added (HTTP 422 on failure)
Unique Fields: number (HTTP 422 on failure)

Update A Recurring Schedule

PUT /api/v2/recurring/:id

You may provide a partial list of fields to update

  {
    "recurring_schedule": {
      "number": 185,
      "recurring_schedule_items_attributes": [
        {
          "id": 501,
          "_destroy": true
        },
        {
          "id": 502
          "title": "bar",
          "quantity": 2,
          "price": 200
        },
        {
          "title": "bar",
          "quantity": 2,
          "price": 200
        }
      ]
    }
  }

In recurring_schedule_items_attributes, provide id to edit an existing recurring_schedule_items or omit id to create new recurring schedule items. Provide _destroy attribute along with id to delete the recurring schedule item.

Unique Fields: number (HTTP 422 on failure)

Delete A Recurring Schedule

DELETE /api/v2/recurring/:id