Covenant Agreement Models Guide

Route: /gateway/covenants-agreement

Authentication: Bearer token (JWT) and tenant context — see Combined Login

Overview

Covenant Agreement Models are pre-configured recurring billing templates. They define everything needed to automatically generate periodic documents for Entities — from the document type and billing series to the items/services, pricing rules, and periodicity.

Once a template is created, it can be assigned to one or more Entities, each with their own start date, end date, and payment mode. The system uses these assignments to automatically generate invoices or other documents at the configured intervals.

When to Use

• ✅ Monthly or annual service contracts (e.g., IT support contracts)
• ✅ Recurring maintenance agreements
• ✅ Subscription-based billing for software or hardware
• ✅ Fixed-fee periodic invoicing with predefined items
• ✅ Bulk assignment of the same contract model to multiple Entities

---

Model Characteristics

Property	Type	Description
id	string (GUID)	Unique identifier
name	string	Template name (e.g., "Monthly IT Support")
description	string	Detailed description
documentType	int	Document type to generate (e.g., Invoice)
documentSerie	int	Document series to use
documentTypeToConvert	int	Document type to convert/finalise into
periodicityType	int	Periodicity unit (e.g., Monthly, Annual)
periodicityValue	int	Periodicity interval value
isGlobal	bool	If true, applies to all Entities
priceType	int?	Price list type to apply
withTax	bool?	Whether prices include tax
descriptionInDocument	bool	Include model description in generated document
ignoreCustomerDiscount	bool?	Ignore the customer's existing discount
items	array	Line items included in the agreement

Item Properties

Property	Type	Description
reference	string (int)	Numeric ID of the item/service, sent as string (e.g., "42"). Must exist in the system.
description	string	Line description
quantity	decimal	Quantity (min: 1)
unitPrice	decimal	Unit price (min: 0)
discount	decimal?	Discount (optional, min: 0)
netPrice	decimal	Net price after discount (min: 0)
taxIncludedPrice	decimal	Price with tax (min: 0)
itemAttributeCode	string?	Item attribute code (optional)

note

The reference field holds the numeric ID of the item registered in the system. Although the type is string, the value must always be an integer number (e.g., "1", "42", "150").

---

Create Covenant Agreement

POST /gateway/covenants-agreement
Content-Type: application/json
Authorization: Bearer {token}

Basic Example — Monthly Support

{
  "name": "Monthly IT Support",
  "description": "Monthly technical support and maintenance contract",
  "documentType": 5,
  "documentSerie": 1,
  "documentTypeToConvert": 5,
  "periodicityType": 3,
  "periodicityValue": 1,
  "isGlobal": false,
  "priceType": 1,
  "withTax": false,
  "descriptionInDocument": true,
  "ignoreCustomerDiscount": false,
  "items": [
    {
      "reference": "1",
      "description": "Monthly IT Support Service",
      "quantity": 1,
      "unitPrice": 150.00,
      "discount": null,
      "netPrice": 150.00,
      "taxIncludedPrice": 184.50,
      "itemAttributeCode": null
    }
  ]
}

Response: 200 OK — returns the generated GUID of the created agreement.

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

Example with Multiple Items and Discount — Annual

{
  "name": "Annual IT Maintenance Package",
  "description": "Annual hardware and software maintenance package",
  "documentType": 5,
  "documentSerie": 2,
  "documentTypeToConvert": 5,
  "periodicityType": 4,
  "periodicityValue": 1,
  "isGlobal": false,
  "priceType": 1,
  "withTax": false,
  "descriptionInDocument": true,
  "ignoreCustomerDiscount": true,
  "items": [
    {
      "reference": "2",
      "description": "Hardware Maintenance",
      "quantity": 1,
      "unitPrice": 500.00,
      "discount": 10.00,
      "netPrice": 450.00,
      "taxIncludedPrice": 553.50,
      "itemAttributeCode": null
    },
    {
      "reference": "3",
      "description": "Software Maintenance & Licensing",
      "quantity": 1,
      "unitPrice": 300.00,
      "discount": null,
      "netPrice": 300.00,
      "taxIncludedPrice": 369.00,
      "itemAttributeCode": null
    }
  ]
}

Global Agreement Example — Monthly

{
  "name": "Standard Support — All Entities",
  "description": "Standard support fee applicable to all Entities",
  "documentType": 5,
  "documentSerie": 1,
  "documentTypeToConvert": 5,
  "periodicityType": 3,
  "periodicityValue": 1,
  "isGlobal": true,
  "withTax": false,
  "descriptionInDocument": false,
  "ignoreCustomerDiscount": false,
  "items": [
    {
      "reference": "1",
      "description": "Standard Monthly Support Fee",
      "quantity": 1,
      "unitPrice": 50.00,
      "discount": null,
      "netPrice": 50.00,
      "taxIncludedPrice": 61.50
    }
  ]
}

---

Get Covenant Agreement

By ID

GET /gateway/covenants-agreement/{id}
Authorization: Bearer {token}

GET /gateway/covenants-agreement/3fa85f64-5717-4562-b3fc-2c963f66afa6

Response 200 OK:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Monthly IT Support",
  "description": "Monthly technical support and maintenance contract",
  "documentType": 5,
  "documentSerie": 1,
  "documentTypeToConvert": 5,
  "periodicityType": 3,
  "periodicityValue": 1,
  "isGlobal": false,
  "priceType": 1,
  "withTax": false,
  "descriptionInDocument": true,
  "ignoreCustomerDiscount": false,
  "items": [...]
}

Example response with expanded items:

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "name": "Annual IT Maintenance Package",
  "description": "Annual hardware and software maintenance package",
  "documentType": 5,
  "documentSerie": 2,
  "documentTypeToConvert": 5,
  "periodicityType": 4,
  "periodicityValue": 1,
  "isGlobal": false,
  "priceType": 1,
  "withTax": false,
  "descriptionInDocument": true,
  "ignoreCustomerDiscount": true,
  "items": [
    {
      "reference": "2",
      "description": "Hardware Maintenance",
      "quantity": 1,
      "unitPrice": 500.00,
      "discount": 10.00,
      "netPrice": 450.00,
      "taxIncludedPrice": 553.50,
      "itemAttributeCode": null,
      "lineOrder": 1
    },
    {
      "reference": "3",
      "description": "Software Maintenance & Licensing",
      "quantity": 1,
      "unitPrice": 300.00,
      "discount": null,
      "netPrice": 300.00,
      "taxIncludedPrice": 369.00,
      "itemAttributeCode": null,
      "lineOrder": 2
    }
  ]
}

info

lineOrder represents the display order of each item in the generated document. It is assigned automatically by the server based on the position of each item in the items array — the first item receives lineOrder = 1, the second lineOrder = 2, and so on.

---

List Covenant Agreements

GET /gateway/covenants-agreement
Authorization: Bearer {token}

With Pagination

GET /gateway/covenants-agreement?page=1&pageSize=20
Authorization: Bearer {token}

Response 200 OK:

{
  "totalCount": 12,
  "pageSize": 20,
  "currentPage": 1,
  "totalPages": 1,
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Monthly IT Support",
      "description": "Monthly technical support and maintenance contract",
      "documentType": 5,
      "documentTypeDescription": "Invoice",
      "documentSerie": 1,
      "documentSerieDescription": "FT 2026",
      "documentTypeToConvert": 5,
      "documentTypeToConvertDescription": "Invoice",
      "periodicityType": 3,
      "periodicityValue": 1,
      "isGlobal": false,
      "priceType": 1,
      "withTax": false,
      "descriptionInDocument": true,
      "ignoreCustomerDiscount": false
    }
  ]
}

---

Update Covenant Agreement

PUT /gateway/covenants-agreement/{id}
Content-Type: application/json
Authorization: Bearer {token}

PUT /gateway/covenants-agreement/3fa85f64-5717-4562-b3fc-2c963f66afa6

Full item replacement

The items array replaces all existing items on the agreement. Send the complete desired list — any item omitted will be deleted.

{
  "name": "Monthly IT Support — Updated",
  "description": "Updated monthly technical support contract",
  "documentType": 5,
  "documentSerie": 1,
  "documentTypeToConvert": 5,
  "periodicityType": 3,
  "periodicityValue": 1,
  "isGlobal": false,
  "priceType": 1,
  "withTax": false,
  "descriptionInDocument": true,
  "ignoreCustomerDiscount": false,
  "items": [
    {
      "reference": "1",
      "description": "Monthly IT Support Service",
      "quantity": 1,
      "unitPrice": 175.00,
      "discount": null,
      "netPrice": 175.00,
      "taxIncludedPrice": 215.25,
      "itemAttributeCode": null
    }
  ]
}

Response: 204 No Content

---

Delete Covenant Agreement

DELETE /gateway/covenants-agreement/{id}
Authorization: Bearer {token}

DELETE /gateway/covenants-agreement/3fa85f64-5717-4562-b3fc-2c963f66afa6

Response: 204 No Content

danger

Deletion is permanent. Ensure the agreement has no active entity assignments before deleting.

---

Entity Assignment

Once a covenant agreement model is created, it must be assigned to the Entities it applies to.

Get Assigned Entities

Retrieve all Entities currently assigned to a covenant agreement.

GET /gateway/covenants-agreement/{covenantId}/entities
Authorization: Bearer {token}

GET /gateway/covenants-agreement/3fa85f64-5717-4562-b3fc-2c963f66afa6/entities

Response 200 OK:

{
  "hasAssignedEntities": true,
  "assignedEntities": [
    {
      "entityKeyId": "1",
      "entityName": "Acme Technologies, Ltd"
    },
    {
      "entityKeyId": "2",
      "entityName": "TechVision Solutions"
    }
  ]
}

Assign to Entities

Assign a covenant agreement to one or multiple Entities at once.

POST /gateway/covenants-agreement/{covenantId}/assign-entities
Content-Type: application/json
Authorization: Bearer {token}

POST /gateway/covenants-agreement/3fa85f64-5717-4562-b3fc-2c963f66afa6/assign-entities

{
  "entityKeyIds": ["1", "2", "3"],
  "assignment": {
    "initialDate": "2026-01-01T00:00:00",
    "finalDate": "2026-12-31T00:00:00",
    "nextDate": "2026-02-01T00:00:00",
    "paymentMode": 1
  }
}

Response 200 OK:

{
  "totalSuccess": 2,
  "totalFailed": 1,
  "logLines": [
    {
      "entityKeyId": "1",
      "entityName": "Acme Technologies, Ltd",
      "status": "Success",
      "errorMessage": null
    },
    {
      "entityKeyId": "2",
      "entityName": "TechVision Solutions",
      "status": "Success",
      "errorMessage": null
    },
    {
      "entityKeyId": "3",
      "entityName": "Unknown Customer",
      "status": "Failed",
      "errorMessage": "Entity not found."
    }
  ]
}

Bulk Assignment

The assign-entities endpoint processes All Entities and returns a detailed log of successes and failures. Even if some assignments fail, the successful ones are committed.

---

Lifecycle

1. Create: Define the template with document type, series, items, and periodicity
2. Assign: Link the template to one or more Entities with assignment dates
3. Execute: The system automatically generates documents at each nextDate
4. Advance: nextDate advances by periodicityValue after each generation
5. End: Billing stops when finalDate is reached (or the assignment is removed)

---

Important Validations

Required Fields (Create)

• ✅ name — Template name (max 150 characters)
• ✅ description — Description (max 250 characters)
• ✅ documentType — Valid document type ID (> 0)
• ✅ periodicityType — Periodicity unit. Allowed values: 1 (Daily), 2 (Weekly), 3 (Monthly), 4 (Yearly)
• ✅ periodicityValue — Interval value — see rules below
• ✅ items — At least one line item

The id field

On Create, do not send id — it is generated by the server and returned in the response.
On Update, the id goes in the URL path (PUT /gateway/covenants-agreement/{id}), not in the request body.

PeriodicityValue Rules

The meaning of periodicityValue depends on periodicityType:

periodicityType	Meaning	periodicityValue rule
1 — Daily	Days of the week to issue	Weekday bitmask, range 1–127 (Sun=1, Mon=2, Tue=4, Wed=8, Thu=16, Fri=32, Sat=64)
2 — Weekly	Number of weeks between issuances	Any integer ≥ 1
3 — Monthly	Number of months between issuances	Any integer ≥ 1
4 — Yearly	Number of years between issuances	Any integer ≥ 1

Bitmask examples for Daily:

Days	Calculation	periodicityValue
Monday–Friday	2+4+8+16+32	62
Monday only	2	2
All days	1+2+4+8+16+32+64	127
Saturday & Sunday	1+64	65

Item Validations

• ✅ reference — Required, must exist in the system
• ✅ description — Required (max 250 characters)
• ✅ quantity — Minimum 1
• ✅ unitPrice, netPrice, taxIncludedPrice — Cannot be negative
• ✅ discount — Cannot be negative (optional)

Assignment Validations

• ✅ paymentMode — Required, cannot be 0
• ✅ initialDate — Required, must be a valid date
• ✅ nextDate — Must be between initialDate and finalDate
• ✅ finalDate — If provided, must be >= initialDate

Date Rule

nextDate must be within the range [initialDate, finalDate]. If finalDate is null, the assignment runs indefinitely.

Error Responses

HTTP Code	Error Code	Meaning
400	CovenantAgreement.PeriodicityValueInvalidForDaily	periodicityValue is not a valid weekday bitmask (1–127) for Daily type
400	CovenantAgreement.ItemReferenceNotFound	One or more item references do not exist in the system
400	CovenantAgreement.PaymentModeRequired	paymentMode is 0 or missing in assignment
400	CovenantAgreement.InvalidDateRange	Date range invalid in assignment
400	CovenantAgreement.AssignmentOptionsInvalid	Invalid assignment options
404	CovenantsAgreement.NotFound	Agreement ID not found
500	CovenantAgreement.AssignmentDatabaseError	Database error during assignment

---

Best Practices

✅ Recommended

• Omit the id field on Create — it is server-generated and returned in the response
• Always set finalDate for time-limited contracts
• Verify documentType and documentSerie are active before creating
• Use the logLines from the assign response to detect and retry failed assignments
• Set descriptionInDocument: true for contracts where the customer should see the agreement description
• On Update, send the complete desired item list — items omitted from the array will be deleted

❌ Avoid

• Sending id in the Create request body (it is ignored and assigned by the server)
• Setting paymentMode to 0 in assignments (blocked by validation)
• Setting nextDate outside the [initialDate, finalDate] range
• Deleting an agreement that has active assignments
• Setting periodicityValue to 0 or negative
• For Daily (periodicityType=1), using periodicityValue outside the range 1–127

---

Common Use Cases

Monthly Flat-Rate IT Support

A fixed monthly fee for unlimited support hours.

{
  "periodicityType": 3,
  "periodicityValue": 1,
  "items": [{ "reference": "1", "unitPrice": 200.00, ... }]
}

Annual Maintenance Contract

A single annual document generated once per year.

{
  "periodicityType": 4,
  "periodicityValue": 1,
  "items": [{ "reference": "2", "unitPrice": 1200.00, ... }]
}

Quarterly Billing for Multiple Entities

Assign the same quarterly template (every 3 months) to a customer segment.

{
  "periodicityType": 3,
  "periodicityValue": 3
}

Assign in bulk:

{
  "entityKeyIds": ["1", "2", "10", "11"],
  "assignment": {
    "initialDate": "2026-01-01T00:00:00",
    "nextDate": "2026-04-01T00:00:00",
    "paymentMode": 2
  }
}

Daily Issuance — Monday to Friday

Issue a document every working day using the weekday bitmask.
Mon(2) + Tue(4) + Wed(8) + Thu(16) + Fri(32) = 62

{
  "periodicityType": 1,
  "periodicityValue": 62,
  "items": [{ "reference": "5", "unitPrice": 10.00, ... }]
}

---

Integration with Other Modules

Generated Documents

The covenant agreement generates documents according to documentType and documentTypeToConvert. These follow the same rules as manually created documents in the Invoice API.

Assistance Contracts

Covenant agreements work alongside the SAT contracts module. A contract may reference an avença model as the billing vehicle for the services defined in the contract.

---

Next Steps

• Debit Agreement Guide — Process and bill covenant agreements
• General Usage Guide — Authentication and common patterns

---

Last Updated: June 2, 2026