API Documentation

API Endpoint

Automatic Invoicing Rules

Automatic Invoicing Rules

The automatic invoicing rule object defines when draft invoices will be automatically created based on predefined schedules and conditions. The rule is linked to one recurring budget.

You can find out more about automatic invoicing in our Help documentation: Automatic Invoicing

Following diagram shows automatic invoicing rules in our data hierarchy:

Automatic Invoicing Rules diagram

How Automatic Invoicing Works

Automatic invoicing rules are processed daily at 8 AM in the organization’s local timezone. When a rule’s next_invoice_date matches the current date, the system generates a draft invoice using the invoice template. It also creates invoice attributions, line items and updates the rule’s processed_at.

Supported filter params

  • budget_id (array)

  • creator_id (array)

  • id (array)

Supported sort params

  • created_at

  • id

Filter operations are supported on this endpoint.

Rule Configuration

Reference Date Options

The reference_date determines which budget date is used as the baseline for calculating when to create invoices:

  • start_date: Uses the budget’s start date as reference

  • end_date: Uses the budget’s end date as reference

Creation Offset

The creation_offset and creation_offset_unit work together to determine when the invoice should be created relative to the reference date:

  • creation_offset: A positive or negative integer representing the number of units

  • creation_offset_unit: The time unit for the offset

    • day: Creates invoice X days relative to reference date
    • week: Creates invoice X weeks relative to reference date
    • month: Creates invoice X months relative to reference date

Weekend Handling

The skip_weekends boolean option determines how the system handles invoice creation dates that fall on weekends:

  • true: Automatically moves Saturday and Sunday dates to Monday

  • false: Creates invoices on the calculated date regardless of whether it’s a weekend

Automatic Invoicing & Invoice Templates

Automatic invoicing rules work exclusively with invoice templates. Each rule:

  1. Requires a Budget: Must be linked to a recurring budget that has an associated invoice template

  2. Uses Template Configuration: The invoice template defines all invoice details (document type, subsidiary, issuer, etc.)

  3. Generates Line Items and Invoice Attribution: Uses the template’s invoice_creation_options to determine how to create line items and attributions

  4. Prevents Duplicates: Will not create a new invoice if an active invoice already exists for the template

Workflow Example

Here’s a typical workflow for setting up automatic invoicing:

  1. Create Budget: Set up a recurring project budget with defined start and end dates

  2. Create Invoice Template: Configure template with document type, subsidiary, and line item generation rules

  3. Create Automatic Invoicing Rule: Define when invoices should be created relative to budget dates

  4. Automatic Processing: System creates draft invoices automatically based on the rule schedule

GET /api/v2/automatic_invoicing_rules
Requestsreturns automatic invoicing rules

GET  /api/v2/automatic_invoicing_rules

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": [
    {
      "id": "1",
      "type": "automatic_invoicing_rules",
      "attributes": {
        "creation_offset": 5,
        "creation_offset_unit": "day",
        "reference_date": "end_date",
        "skip_weekends": false,
        "next_invoice_date": null
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organizations",
            "id": "2375"
          }
        },
        "budget": {
          "meta": {
            "included": false
          }
        },
        "creator": {
          "meta": {
            "included": false
          }
        }
      }
    }
  ],
  "links": {
    "first": "http://api-test.productive.io/api/v2/automatic_invoicing_rules?page%5Bnumber%5D=1&page%5Bsize%5D=30",
    "last": "http://api-test.productive.io/api/v2/automatic_invoicing_rules?page%5Bnumber%5D=1&page%5Bsize%5D=30"
  },
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 1,
    "page_size": 30,
    "max_page_size": 200
  }
}

Get automatic invoicing rules
GET/api/v2/automatic_invoicing_rules

GET /api/v2/automatic_invoicing_rules/1
Requestsreturns automatic invoicing rule

GET  /api/v2/automatic_invoicing_rules/2

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "2",
    "type": "automatic_invoicing_rules",
    "attributes": {
      "creation_offset": 5,
      "creation_offset_unit": "day",
      "reference_date": "end_date",
      "skip_weekends": false,
      "next_invoice_date": null
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "2377"
        }
      },
      "budget": {
        "meta": {
          "included": false
        }
      },
      "creator": {
        "meta": {
          "included": false
        }
      }
    }
  },
  "meta": {}
}

Gets an automatic invoicing rule
GET/api/v2/automatic_invoicing_rules/{id}

URI Parameters
HideShow
id
number (required) Example: 1

automatic invoicing rule id

POST /api/v2/automatic_invoicing_rules
Requestscreates automatic invoicing rule when valid paramsreturns error when invalid params

POST  /api/v2/automatic_invoicing_rules

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "automatic_invoicing_rules",
    "attributes": {
      "creation_offset": 5,
      "creation_offset_unit": "day",
      "reference_date": "end_date"
    },
    "relationships": {
      "budget": {
        "data": {
          "type": "quotes",
          "id": "1941"
        }
      }
    }
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "3",
    "type": "automatic_invoicing_rules",
    "attributes": {
      "creation_offset": 5,
      "creation_offset_unit": "day",
      "reference_date": "end_date",
      "skip_weekends": false,
      "next_invoice_date": "2025-09-13"
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "2379"
        }
      },
      "budget": {
        "meta": {
          "included": false
        }
      },
      "creator": {
        "meta": {
          "included": false
        }
      }
    }
  },
  "meta": {}
}

POST  /api/v2/automatic_invoicing_rules

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "automatic_invoicing_rules",
    "attributes": {
      "creation_offset": 5,
      "creation_offset_unit": "day",
      "reference_date": "end_date"
    }
  }
}
Responses422
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "status": "422",
      "code": "invalid_attribute",
      "title": "Invalid Attribute",
      "detail": "can't be blank",
      "source": {
        "pointer": "data/attributes/budget"
      }
    }
  ]
}

Create an automatic invoicing rule
POST/api/v2/automatic_invoicing_rules

URI Parameters
HideShow
creation_offset
number (required) Example: -5

Number of units to offset from reference date (can be negative)

creation_offset_unit
string (required) Example: day

Unit of time for offset (day, week, month)

reference_date: `end_date`
string (required) 

Reference date to calculate offset from budget (start_date, end_date)

budget_id
number (required) Example: 1

Budget id that this rule is linked to

skip_weekends
boolean (optional) Example: true

Option to skip weekends when creating invoices

PATCH /api/v2/automatic_invoicing_rules/1
Requestsupdates automatic invoicing rule when valid paramsreturns error when invalid params

PATCH  /api/v2/automatic_invoicing_rules/4

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "automatic_invoicing_rules",
    "attributes": {
      "creation_offset": 10
    }
  }
}
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "4",
    "type": "automatic_invoicing_rules",
    "attributes": {
      "creation_offset": 10,
      "creation_offset_unit": "day",
      "reference_date": "end_date",
      "skip_weekends": false,
      "next_invoice_date": null
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "2381"
        }
      },
      "budget": {
        "meta": {
          "included": false
        }
      },
      "creator": {
        "meta": {
          "included": false
        }
      }
    }
  },
  "meta": {}
}

PATCH  /api/v2/automatic_invoicing_rules/5

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "automatic_invoicing_rules",
    "attributes": {
      "creation_offset": null
    }
  }
}
Responses422
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "status": "422",
      "code": "invalid_attribute",
      "title": "Invalid Attribute",
      "detail": "can't be blank",
      "source": {
        "pointer": "data/attributes/creation_offset"
      }
    }
  ]
}

Update an automatic invoicing rule
PATCH/api/v2/automatic_invoicing_rules/{id}

URI Parameters
HideShow
id
number (required) Example: 1

automatic invoicing rule id

DELETE /api/v2/automatic_invoicing_rules/1
Requestsdeletes automatic invoicing rule

DELETE  /api/v2/automatic_invoicing_rules/6

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Responses204
This response has no content.

Deletes an automatic invoicing rule
DELETE/api/v2/automatic_invoicing_rules/{id}

URI Parameters
HideShow
id
number (required) Example: 1

automatic invoicing rule id

Generated by aglio on 13 Sep 2025