Fiscal Calendar

The Fiscal Calendar is used both for Reporting and Budget. A fiscal year can start and end at any date as long as the end date is after the start date and does not span more than two years. Fiscal years cannot overlap. Fiscal periods cannot overlap and are limited to 24 per fiscal year.

GET All Fiscal Years

Retrieve a list of all fiscal years

Use the lastModifiedAfter parameter if you wish to only retrieve fiscal years that were changed after a certain date.
Use the includeRemoved parameter if you wish to retrieve all fiscal years, including those that have been deleted. Important: deleted data that is beyond the configured retention period can not be returned.

Scopes

This API call requires one of the following scopes:

budgetitem.read - Refer to Scope Usage for full details.
budgetitem.write - Refer to Scope Usage for full details.
fiscalyear.read - Refer to Scope Usage for full details.
fiscalyear.write - Refer to Scope Usage for full details.

Request

URI

Template

GET  /budget/v4/fiscalYear

Parameters

Name	Type	Format	Description
`lastModifiedAfter`	`datetime`	`YYYY-MM-DDTHH:MM:SS`	Use this field if you only want Fiscal Years that were changed after the supplied date. The supplied date will be interpreted in the UTC time zone. If `lastModifiedAfter` is not supplied, the service will return all Fiscal Years, regardless of modified date. Example: `2016-03-29T16:12:20`
`includeRemoved`	`boolean`	`query`	If `true`, the service will return all Fiscal Years, including those that were previously removed. If not supplied, this field defaults to `false`.

Headers

Response

Status Codes

200 OK Successful call, response is in body.
400 Bad Request The request was determined to be invalid by the server.
403 Forbidden The user does not have the necessary permissions to perform the request.
500 Internal Server Error Error message in response body.
504 Gateway Timeout Error message in response body.

Headers

Response Headers

Payload

Fiscal Year

Example

Request

GET https://us.api.concursolutions.com/budget/v4/fiscalYear?lastModifiedAfter=2017-02-27T12:30:00
Authorization: Bearer {token}
Content-Type: application/json

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 2187
concur-correlationid: ffa4ae0a-f65c-4037-8bfb-8996c3fca28c

[
    {
      "name":"2017",
      "startDate":"2017-01-01",
      "endDate":"2017-12-31",
      "status":"OPEN",
      "id":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
      "lastModified":"2017-03-26 20:53:19",
      "currentYear":false,
      "monthlyFiscalPeriods":[
        {
          "name":"2017 - Aug",
          "fiscalPeriodStatus":"OPEN",
          "id":"a4e94128-c7b7-4561-a57e-1512e59e4896",
          "periodType":"MONTHLY",
          "startDate":"2017-08-01",
          "endDate":"2017-08-31",
          "spendDate":null,
          "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
          "currentPeriod":false
        },
        {
          "name":"2017 - Jan",
          "fiscalPeriodStatus":"CLOSED",
          "id":"ab2810f5-f045-45b0-b2b2-8e84bc978e27",
          "periodType":"MONTHLY",
          "startDate":"2017-01-01",
          "endDate":"2017-01-30",
          "spendDate":null,
          "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
          "currentPeriod":false
        },
        {
          "Additional fiscal periods removed for brevity": "Additional fiscal periods removed for brevity"
        }
      ],
      "quarterlyFiscalPeriods":[
        {"name":"2017 - Q4",
          "fiscalPeriodStatus":"OPEN",
          "id":"655ffe9d-caca-4f2f-a4a1-e04cfb68fd6e",
          "periodType":"QUARTERLY",
          "startDate":"2017-10-01",
          "endDate":"2017-12-31",
          "spendDate":null,
          "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
          "currentPeriod":false
        },
        {
          "Additional fiscal periods removed for brevity": "Additional fiscal periods removed for brevity"
        }
      ],
      "yearlyFiscalPeriods":[
        {
          "name":"2017",
          "fiscalPeriodStatus":"OPEN",
          "id":"2fb8ea93-172a-47a6-9611-44eb75ad547b",
          "periodType":"YEARLY",
          "startDate":"2017-01-01",
          "endDate":"2017-12-31",
          "spendDate":null,
          "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
          "currentPeriod":false
        }
      ],
      "customFiscalPeriods":[]
    }
]

GET a Fiscal Year

Retrieve a single fiscal year by ID.

Scopes

This API call requires one of the following scopes:

budgetitem.read - Refer to Scope Usage for full details.
budgetitem.write - Refer to Scope Usage for full details.
fiscalyear.read - Refer to Scope Usage for full details.
fiscalyear.write - Refer to Scope Usage for full details.

Request

URI

Template

GET  /budget/v4/fiscalYear/{id}

Parameters

Name	Type	Format	Description
`id`	`string`	`uuid`	The fiscal year’s key field.

Headers

Response

Status Codes

200 OK Successful call, response is in body.
400 Bad Request The request was determined to be invalid by the server.
403 Forbidden The user does not have the necessary permissions to perform the request.
404 Not Found The resource could not be found or does not exist.
500 Internal Server Error Error message in response body.
504 Gateway Timeout Error message in response body.

Headers

Response Headers

Payload

Fiscal Year

Example

Request

GET https://us.api.concursolutions.com/budget/v4/fiscalYear/5e58b9b1-fed6-4d36-a5a1-a1ed325931d4
Authorization: Bearer {token}

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: 39216840-2808-4c49-8874-e9862d96fdb6

{
  "name":"2017",
  "startDate":"2017-01-01",
  "endDate":"2017-12-31",
  "status":"OPEN",
  "id":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
  "lastModified":"2017-03-26 20:53:19",
  "currentYear":false,
  "monthlyFiscalPeriods":[
    {
      "name":"2017 - Aug",
      "fiscalPeriodStatus":"OPEN",
      "id":"a4e94128-c7b7-4561-a57e-1512e59e4896",
      "periodType":"MONTHLY",
      "startDate":"2017-08-01",
      "endDate":"2017-08-31",
      "spendDate":null,
      "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
      "currentPeriod":false
    },
    {
      "name":"2017 - Jan",
      "fiscalPeriodStatus":"CLOSED",
      "id":"ab2810f5-f045-45b0-b2b2-8e84bc978e27",
      "periodType":"MONTHLY",
      "startDate":"2017-01-01",
      "endDate":"2017-01-30",
      "spendDate":null,
      "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
      "currentPeriod":false
    },
    {
      "Additional fiscal periods removed for brevity": "Additional fiscal periods removed for brevity"
    }
  ],
  "quarterlyFiscalPeriods":[
    {"name":"2017 - Q4",
      "fiscalPeriodStatus":"OPEN",
      "id":"655ffe9d-caca-4f2f-a4a1-e04cfb68fd6e",
      "periodType":"QUARTERLY",
      "startDate":"2017-10-01",
      "endDate":"2017-12-31",
      "spendDate":null,
      "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
      "currentPeriod":false
    },
    {
      "Additional fiscal periods removed for brevity": "Additional fiscal periods removed for brevity"
    }
  ],
  "yearlyFiscalPeriods":[
    {
      "name":"2017",
      "fiscalPeriodStatus":"OPEN",
      "id":"2fb8ea93-172a-47a6-9611-44eb75ad547b",
      "periodType":"YEARLY",
      "startDate":"2017-01-01",
      "endDate":"2017-12-31",
      "spendDate":null,
      "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
      "currentPeriod":false
    }
  ],
  "customFiscalPeriods":[],
  "displayName":"2017-Special"
}

POST Fiscal Year(s)

Create or update a list of one or more fiscal years.

Fiscal years may be created for the future or the past
Unless there is a need to do so, the client should only specify monthly fiscal periods when creating/updating a fiscal year. The system will auto-generate the quarterly and yearly fiscal periods.

Scopes

This API call requires one of the following scopes:

budgetitem.write - Refer to Scope Usage for full details.
fiscalyear.write - Refer to Scope Usage for full details.

Request

URI

Template

POST  /budget/v4/budgetCategory

Parameters

N/A

Headers

Payload

Fiscal Year

Response

Status Codes

200 OK Successful call, response is in body.
400 Bad Request The request was determined to be invalid by the server. Possibly a validation failed on the data that was sent in the payload. The response will have a list of validation errors in the body. See below for an example 400 response.
403 Forbidden The user does not have the necessary permissions to perform the request.
404 Not Found The resource could not be found or does not exist.
500 Internal Server Error Error message in response body.
504 Gateway Timeout Error message in response body.

Headers

Response Headers

Payload

Fiscal Year or Error Response

Example

Request

POST https://us.api.concursolutions.com/budget/v4/fiscalYear
Authorization: Bearer {token}

[
  {
    "name":"2017-Special",
    "startDate":"2017-01-01",
    "endDate":"2017-03-31",
    "status":"OPEN",
    "monthlyFiscalPeriods":[
      {
        "name":"2017-Special - Jan",
        "fiscalPeriodStatus":"OPEN",
        "periodType":"MONTHLY",
        "startDate":"2017-01-01",
        "endDate":"2017-01-31"
      },
      {
        "name":"2017-Special - Feb",
        "fiscalPeriodStatus":"OPEN",
        "periodType":"MONTHLY",
        "startDate":"2017-02-01",
        "endDate":"2017-02-28"
      },
      {
        "name":"2017-Special - Mar",
        "fiscalPeriodStatus":"OPEN",
        "periodType":"MONTHLY",
        "startDate":"2017-03-01",
        "endDate":"2017-03-31"
      }
    ],
    "displayName":"2017-Special"
  }
]

Response

Success Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: 5c00e59f-d00c-4019-8d3d-47130d8e37b4

[
    {
      "name":"2017-Special",
      "startDate":"2017-01-01",
      "endDate":"2017-03-31",
      "status":"OPEN",
      "id":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
      "lastModified":"2018-03-26 20:54:11",
      "currentYear":false,
      "monthlyFiscalPeriods":[
        {
          "name":"2017-Special - Jan",
          "fiscalPeriodStatus":"OPEN",
          "periodType":"MONTHLY",
          "startDate":"2017-01-01",
          "endDate":"2017-01-31",
          "id":"1929d1d9-6c99-4635-9272-508364193f8f",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        },
        {
          "name":"2017-Special - Feb",
          "fiscalPeriodStatus":"OPEN",
          "periodType":"MONTHLY",
          "startDate":"2017-02-01",
          "endDate":"2017-02-28",
          "id":"41aa7452-e52a-4fd6-9c8a-5b199edeadaf",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        },
        {
          "name":"2017-Special - Mar",
          "fiscalPeriodStatus":"OPEN",
          "periodType":"MONTHLY",
          "startDate":"2017-03-01",
          "endDate":"2017-03-31",
          "id":"6c7d0b13-96b9-4d76-a083-4d38c96144e2",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        }
      ],
      "quarterlyFiscalPeriods":[
        {
          "name":"2017-Special - Q1",
          "fiscalPeriodStatus":"OPEN",
          "id":"5ce25dfd-8b2b-4fea-91eb-f8f9ad0bb896 ",
          "periodType":"QUARTERLY",
          "startDate":"2017-01-01",
          "endDate":"2017-03-31",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        }
      ],
      "yearlyFiscalPeriods":[
        {
          "name":"2017-Special",
          "fiscalPeriodStatus":"OPEN",
          "id":"a6bede66-4f3d-412f-a620-2a073013cb2a",
          "periodType":"YEARLY",
          "startDate":"2017-01-01",
          "endDate":"2017-03-31",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        }
      ],
      "customFiscalPeriods":[],
      "displayName":"2017-Special"
    }
]

Failure Response

HTTP/1.1 400 Bad Request
Cache-Control: no-store
Connection: close
Content-Length: 338
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:27:05 GMT
Expires: Thu, 20 Sep 2018 15:27:05 GMT
Pragma: no-cache
concur-correlationid: cb061832-82eb-418e-a968-de6b4ce370ae

{
  "status" : false,
  "errorMessageList" : [
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.FISCAL_YEAR_SDATE_ERROR",
      "errorMessage" : "Fiscal year should have a start date"
    },
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.FISCAL_YEARS_HAVE_GAP",
      "errorMessage" : "Fiscal years should not have gaps between them"
    }
  ]
}

DELETE a Fiscal Year

Delete a fiscal year. Fiscal years that are in use may not be deleted.

Scopes

This API call requires one of the following scopes:

budgetitem.write - Refer to Scope Usage for full details.
fiscalyear.write - Refer to Scope Usage for full details.

Request

URI

Template

DELETE  /budget/v4/fiscalYear/{id}

Parameters

Name	Type	Format	Description
`id`	`string`	`uuid`	The fiscal years’s key field.

Headers

Response

Status Codes

200 OK Successful call, response is in body.
400 Bad Request The request was determined to be invalid by the server.
403 Forbidden The user does not have the necessary permissions to perform the request.
404 Not Found The resource could not be found or does not exist.
500 Internal Server Error Error message in response body.
504 Gateway Timeout Error message in response body.

Headers

Response Headers

Example

Request

DELETE https://us.api.concursolutions.com/budget/v4/fiscalYear/a11cfc7c-967f-415f-9b30-23f8ce2dbf69
Authorization: Bearer {token}

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: eb7cf20a-3481-45a5-808c-98b8ef7fe805

Schema

FiscalYear

Name	Type	Format	Description
`currentYear`	`boolean`	-	READ ONLY `True` if this the current fiscal year based on the current date and time, `False` otherwise.
`startDate`	`date`	`YYYY-MM-DD`	Required The start date for this fiscal year. The distance between start date and end date may not be more than two years.
`endDate`	`date`	`YYYY-MM-DD`	Required The end date for this fiscal year. The distance between start date and end date may not be more than two years.
`name`	`datetime`	-	Required The name of this fiscal year. Must be unique for this entity.
`status`	`string`	-	Required The status of this fiscal year. Supported values: `OPEN`, `CLOSED`, `REMOVED`
`id`	`string`	-	The budget service’s key for this object.
`lastModified`	`datetime`	-	READ ONLY The UTC date and time when this object was last changed.
`monthlyFiscalPeriods`	`array`	`fiscalPeriod`	Required The list of monthly fiscal periods in this fiscal year. Fiscal periods must complete fill the parent fiscal year with no overlaps.
`quarterlyFiscalPeriods`	`array`	`fiscalPeriod`	READ ONLY The list of quarterly fiscal periods in this fiscal year. If this parameter is not specified, quarterly fiscal periods are automatically generated based on the monthly fiscal periods supplied.
`yearlyFiscalPeriods`	`array`	`fiscalPeriod`	READ ONLY The list of yearly fiscal periods in this fiscal year. If this parameter is not specified, one period is created that fills the fiscal year.
`customFiscalPeriods`	`array`	`fiscalPeriod`	READ ONLY The list of custom fiscal periods in this fiscal year. Custom fiscal periods are API-only and will not display on user budget dashboards.
`openAndClosedFiscalPeriods`	`array`	`fiscalPeriod`	READ ONLY The list of all fiscal periods in this fiscal year, sorted by status.
`fiscalPeriods`	`array`	`fiscalPeriod`	READ ONLY The list of all fiscal periods in this fiscal year.
`displayName`	`string`	-	READ ONLY Display name for fiscal year. For date range budget item we use this field to display.

FiscalPeriod

Name	Type	Format	Description
`currentPeriod`	`boolean`	-	READ ONLY `True` if this the current fiscal period based on the current date and time, `False` otherwise.
`startDate`	`date`	`YYYY-MM-DD`	Required The start date for this fiscal period. Must be within the parent fiscal year.
`endDate`	`date`	`YYYY-MM-DD`	Required The end date for this fiscal year. Must be within the parent fiscal year.
`name`	`string`	-	Required The name of this fiscal period. Must be unique for this entity.
`fiscalPeriodStatus`	`string`	-	Required The status of this fiscal period. Supported values: `OPEN`, `CLOSED`, `REMOVED`
`periodType`	`string`	-	Required The type of fiscal period. Supported values: `MONTHLY`, `QUARTERLY`, `YEARLY`, `CUSTOM`
`fiscalYearId`	`string`	-	The key of the parent fiscal year for this fiscal period.
`id`	`string`	-	The budget service’s key for this object.
`spendDate`	`date`	-	READ ONLY If the current date is after this fiscal period’s start date, this field shows the current date.

Error Response

Name	Type	Format	Description
`status`	`boolean`	-	`False` if there was an error.
`errorMessageList`	`array`	`errorMessage`	List of all errors detected.

Error Message

Name	Type	Format	Description
`errorType`	`String`	-	WARNING or ERROR.
`errorCode`	`String`	-	Text code for this error.
`errorMessage`	`String`	-	Plain language error message.

Response Headers

concur-correlationid is a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
RFC 7231 Allow
RFC 7234 Cache-Control
RFC 7230 Content-Length
RFC 7231 Content-Type
RFC 7231 Date
RFC 7234 Expires
RFC 7232 ETag
RFC 7234 Pragma
RFC 7231 Server
RFC 7231 Vary

Fiscal Calendar

GET All Fiscal Years

Scopes

Request

URI

Template

Parameters

Headers

Response

Status Codes

Headers

Payload

Example

Request

Response

GET a Fiscal Year

Scopes

Request

URI

Template

Parameters

Headers

Response

Status Codes

Headers

Payload

Example

Request

Response

POST Fiscal Year(s)

Scopes

Request

URI

Template

Parameters

Headers

Payload

Response

Status Codes

Headers

Payload

Example

Request

Response

Success Response

Failure Response

DELETE a Fiscal Year

Scopes

Request

URI

Template

Parameters

Headers

Response

Status Codes

Headers

Example

Request

Response

Schema

FiscalYear

FiscalPeriod

Error Response

Error Message

Response Headers

On this page