Skip to main content
Contracts API

createContractPaymentSchedules

createContractPaymentSchedules

Overview

This method adds payment lines to a contract's existing payment arrangements, inside existing payment periods. It replicates the Insert function on the Contracts / Payments tab.

You can add between 1 and 25 payment lines in one request. Every line is checked before anything is saved: if any line fails, nothing is written and the response lists each failing line and the reason.

To create new payment arrangements with their full schedule, use createContractPaymentStructures.

This method requires the ContractPaymentSchedules:Create permission to be associated with your role.

Permissions

The permission for this API is stored in [gb_api_permissions]permission as 'ContractPaymentSchedules:Create'.

Only roles with a stored link to this permission in [gb_role_api_permissions] can run this API.

This permission is not granted to any role by default. A client administrator must grant it in System / Roles / APIs before the API can be used; until then it returns 403.

HTTP Method

Use the HTTP Method 'POST' for consuming this web service.

URL Examples

https://api.demo.catch-e.com/fm/contract/payment-schedules https://api.{environment}.catch-e.com/fm/contract/payment-schedules https://api.test.catch-e.com/fm/contract/payment-schedules 

Input Fields (Header)

Key

Format

Notes

Mandatory

Delegated-Locking-Session-Id

string

(Optional) Locking responsibility is delegated to the specified Session Id. The API only verifies that the required lock exists for this session id and does not obtain it itself. Requires the DelegatedLocking permission.

No

Audit-User-Id

string

(Optional) User Id to use for audit purposes. Up to 5 digits. Requires the Audit:UserIdOverride permission.

No

Input Fields (JSON)

Send an array of 1 to 25 payment lines.

Identifiers (contract, payment arrangement, supplier, payee, bank account) are treated as the same value whether sent as a number or as text, including with leading zeros. Values that are not whole numbers, such as 5.0, 5abc or +5, are rejected.

Locking

  • Adding a line takes the contract's payments lock, as Insert on the screen does. It does not need the contract record lock.

  • The request is refused with 423 if the contract's payments are being edited on the Contracts / Payments tab, through Edit, Vary or Insert. Retry once the form has been saved or cancelled.

  • Editing only the Contracts / Finance tab does not block this API.

Response Details

Success

201 - Created

The payment lines were added.

Error Response Details

Validation Message

Comments

401 - Unauthorized

1. You have not authenticated before running this API or 2. The token_timeout of the current session has passed. You need to authenticate again.

403 - Forbidden

You do not have permission for this request, or the lock for a delegated session belongs to another user. Go to System Roles and enter 'web_services'. Navigate to the Roles / APIs tab to make sure the permission you need to run this API is checked.

422 - Unprocessable Entity

One or more payment lines failed validation. Messages are keyed by the line's position in the request. Field checks are reported for every line together; business checks stop at the first failing line.

422 - tooManyItems

More than 25 payment lines were sent.

422 - gst_rate.notConfigured

The system GST rate is missing or not a number. Contact Catch-e Support.

423 - Locked

The contract's payments are being edited by another session, for example Edit, Vary or Insert is open on the Contracts / Payments tab. Nothing was added. Retry once the form is saved or cancelled.

424 - Failed Dependency

Lock expected: a Delegated-Locking-Session-Id was sent but that session does not hold the required lock.

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized" } 
{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "Forbidden" } 
{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Locked", "status": 423, "detail": "locked_by" } 
{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "string", "status": 599, "detail": "string" }