Introduction
An Agreement represents a recurring donation, membership, service, or a recurring purchase of a product, and so answers what is being paid for, for how much, when and how often.
Changes committed to an Agreement can be retrieved via the ChangeLog entity.
Endpoints
GET /agreements?pageNumber={x}&pageSize={y}&state={z}
Get a list of Shared Agreements at a given size by a given offset and availability type. Use "state" (see list of states below) to focus your query. All parameters are optional.
Response
HTTP |
Description |
---|---|
200 |
OK |
HTTP 200 Example
{
"pageNumber": {x},
"pageSize": {y},
"list": [
{
"agreementGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"...": "..."
},
{
"agreementGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"...": "..."
}
]
}
GET /agreement/{guid}
Get a single Agreement.
Response
HTTP |
Description |
---|---|
200 |
OK |
404 |
Agreement not found |
HTTP 200 Example
{
"agreementGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"createdTs": "2019-01-01 00:00:00 +0100",
"merchantId": "your-organisation",
"name": "Youth Membership",
"description": "",
"agreementType": "Shared",
"contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"communicationCollectionGuid": "",
"defaultQuantity": 1,
"unit": "pcs",
"unitPrice": 100.0,
"amount": 100.0,
"amountVat": 25.0,
"amountTotal": 125.0,
"taxDeductable": false,
"vatPercentage": 25.0,
"currencyCode": "DKK",
"state": "",
"paymentRequired": true,
"scheduleType": "Monthly",
"scheduleBaseTier": 1,
"scheduleFixedDay": 1,
"scheduleEveryOther": 1,
"scheduleCalendarUnit": "Month",
"scheduleSelectedSet": "[1,2,3,4,5,6]",
"purposeAccountingCode": "",
"dataSetGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx"
}
POST /agreement
Insert a single Agreement.
Request
The following must be provided as the request body:
{
"name": "Youth Membership",
"description": "",
"agreementType": "Shared/Personal",
"contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"defaultQuantity": 1,
"unit": "pcs",
"unitPrice": 100.0,
"amount": 100.0,
"amountVat": 25.0,
"amountTotal": 125.0,
"taxDeductable": false,
"vatPercentage": 25.0,
"currencyCode": "DKK",
"paymentRequired": true,
"scheduleType": "Monthly",
"scheduleBaseTier": 1,
"scheduleFixedDay": 1,
"scheduleEveryOther": 1,
"scheduleCalendarUnit": "Month",
"scheduleSelectedSet": "[1,2,3,4,5,6]",
"purposeAccountingCode": "",
"dataSetGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx"
}
Response
HTTP |
Description |
---|---|
201 |
Created |
400 |
Something's wrong with request body. |
HTTP 200 Example
{
"agreementGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"...": "..."
}
PUT /agreement/{guid}
Replace a single Agreement.
Request
The following must be provided as the request body:
{
"name": "Youth Membership",
"description": "",
"agreementType": "Shared/Personal",
"contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"defaultQuantity": 1,
"unit": "pcs",
"unitPrice": 100.0,
"amount": 100.0,
"amountVat": 25.0,
"amountTotal": 125.0,
"taxDeductable": false,
"vatPercentage": 25.0,
"currencyCode": "DKK",
"paymentRequired": true,
"scheduleType": "Monthly",
"scheduleBaseTier": 1,
"scheduleFixedDay": 1,
"scheduleEveryOther": 1,
"scheduleCalendarUnit": "Month",
"scheduleSelectedSet": "[1,2,3,4,5,6]",
"purposeAccountingCode": "",
"dataSetGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx"
}
Response
HTTP |
Description |
---|---|
200 |
OK |
400 |
Something's wrong with request body. |
404 |
Agreement not found |
HTTP 200 Example
{
"agreementGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"...": "..."
}
PATCH /agreement/{guid}
Update a single Agreement. The following fields are patchable: name, description, defaultQuantity, unit, taxDeductable, paymentRequired, externalId, purposeAccountingCode and communicationCollectionGuid
Request
The following must be provided as the request body:
[
{
"op": "replace",
"path": "/name",
"value": "New agreement name"
}
]
Response
HTTP |
Description |
---|---|
200 |
OK |
400 |
Something's wrong with request body. |
404 |
Agreement was not found |
POST /agreement/{guid}/ChangeAmount
Change amount of a single Agreement.
Request
The following must be provided as the request body:
{
"unitPrice": 100.0,
"quantity": 1,
"amount": 100.0,
"amountVat": 25.0,
"amountTotal": 125.0,
"vatPercentage": 25.0
}
Response
HTTP |
Description |
---|---|
200 |
OK |
400 |
Something's wrong with request body. |
404 |
Agreement was not found |
POST /agreement/{guid}/ChangeFrequency
Change frequency of a single Agreement.
Request
The following must be provided as the request body:
{
"scheduleType": "Monthly",
"scheduleBaseTier": 1,
"scheduleFixedDay": 1,
"scheduleEveryOther": 1,
"scheduleCalendarUnit": "Month",
"scheduleSelectedSet": "[1,2,3,4,5,6]"
}
Response
HTTP |
Description |
---|---|
200 |
OK |
400 |
Something's wrong with request body. |
404 |
Agreement was not found |
POST /agreement/{guid}/Archive
Archives a single Agreement.
Response
HTTP |
Description |
---|---|
200 |
OK |
404 |
Agreement was not found |
GET /agreement/{guid}/payments?pageNumber={x}&pageSize={y}
Get a list of Payments at a given size by a given offset.
Response
HTTP |
Description |
---|---|
200 |
OK |
HTTP 200 Example
{
"pageNumber": {x},
"pageSize": {y},
"list": [
{
"paymentGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"...": "..."
},
{
"paymentGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"...": "..."
}
]
}
GET /agreement/{guid}/subscriptions?pageNumber={x}&pageSize={y}
Get a list of Agreements at a given size by a given offset.
Response
HTTP |
Description |
---|---|
200 |
OK |
HTTP 200 Example
{
"pageNumber": {x},
"pageSize": {y},
"list": [
{
"subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"...": "..."
},
{
"subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"...": "..."
}
]
}
GET /agreement/{guid}/log?limit={limit}
Get a list of changes to an Agreement.
Response
HTTP |
Description |
---|---|
200 |
OK |
HTTP 200 Example
[
{
"changeGuid": "242bf0de-5ed3-48a1-bb3a-xxxxxxxxxxxx",
"createdTs": "2021-01-01 00:00:00 +0100",
"entityType": "Agreement",
"entityGuid": "9a7c3665-5be0-4a5c-9641-xxxxxxxxxxxx",
"changeTs": "2021-01-01 00:00:00 +0100",
"oldEntityJson": "{ .. }",
"changeDescription": "Updated by PUT request",
"requester": "",
"systemRequest": false,
"changes": [
{
"newValue": "Membership",
"oldValue": "Donation",
"fieldName": "name"
}
]
}
]
Schema
Name |
Type |
Mandatory |
Default |
Example |
Description |
---|---|---|---|---|---|
agreementGuid |
STRING(64) |
- |
|
a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx |
Unique GUID |
createdTs |
TIMESTAMP |
- |
|
|
Timestamp of Agreement creation |
merchantId |
STRING |
- |
|
|
Readable ID of the merchant |
name |
STRING(30) |
YES |
|
|
Name of Agreement |
description |
STRING(60) |
NO |
|
|
Invoice description |
agreementType |
STRING |
YES |
|
Personal / Shared |
Agreements can either be Personal or Shared. Shared agreements are used by many Contacts, such as memberships with a certain frequency and amount, whereas personal agreements are unique to each individual Contact, such as a recurring donation of a specific frequency and amount. |
contactGuid |
STRING(64) |
NO |
|
a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx |
GUID of Contact |
communicationCollectionGuid |
STRING(64) |
NO |
|
a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx |
GUID of Communication Collection |
defaultQuantity |
INTEGER |
NO |
1 |
|
Default quantity |
unit |
STRING |
YES |
|
pcs |
Unit |
unitPrice |
DOUBLE |
YES |
|
100.0 |
The price of a single unit |
amount |
DOUBLE |
YES |
|
100.0 |
Summarized amount excluding VAT |
amountVat |
DOUBLE |
YES |
|
25.0 |
Amount VAT |
amountTotal |
DOUBLE |
YES |
|
125.0 |
Total amount including VAT used when charging |
taxDeductable |
BOOLEAN |
YES |
|
true |
Defines basis for tax deductibility |
vatPercentage |
DOUBLE |
YES |
|
25.0 |
VAT percentage |
currencyCode |
STRING |
YES |
|
DKK |
ISO formatted Currency Code (wiki) |
state |
STRING |
- |
|
|
Please see list of Agreement States below. |
paymentRequired |
BOOLEAN |
YES |
|
true |
Are Payments required for the Agreement's Subscriptions to be valid? |
scheduleType |
STRING |
YES |
|
Monthly |
Please see list of Agreement Schedule Types below. |
scheduleBaseTier |
INTEGER |
YES |
|
|
The offset in relation to the chosen calendarUnit. |
scheduleFixedDay |
INTEGER |
YES |
|
1-28 |
A fixed day of the chosen calendarUnit. |
scheduleEveryOther |
INTEGER |
YES |
|
|
Please see description below. |
scheduleCalendarUnit |
STRING |
NO |
Month |
Month |
Calculate due date based on the chosen calendarUnit. Please see list of Schedule Calendar Units below. |
scheduleSelectedSet |
STRING |
NO |
|
"[1,2,3,4,5,6]" |
Only calculate due dates when due date based on calendarUnit is in provided set of integers. |
archivedTs |
TIMESTAMP |
- |
|
|
Timestamp of archivation |
externalId |
STRING |
NO |
|
|
An external ID |
originTs |
TIMESTAMP |
NO |
|
|
Timestamp of origin, useful when importing data |
purposeAccountingCode |
STRING(32) |
NO |
|
|
Accounting Code defined by Merchant used to identify the receiving part of transactions |
dataSetGuid |
STRING(64) |
NO |
|
a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx |
A DataSet GUID containing metadata |
Schedule Types
Following is a list of allowed schedule types:
scheduleType |
Description |
---|---|
Manual |
Payment occurs only when manually initiated |
Custom |
Uses provided baseTier, fixedDay, everyOther, calendarUnit and selectedSet to calculate next dueDate |
Daily |
Daily occurrence |
Weekly |
Weekly occurrence (~52 per year) |
Monthly |
Monthly occurrence (12 per year) |
Quarterly |
Quarterly occurrence (4 per year) |
Halfyearly |
Biannual occurrence (2 per year) |
Yearly |
Annual occurrence (1 per year) |
MonthlyFirst |
Monthly occurrence on the 1st of given month |
QuarterlyFirst |
Quarterly occurrence on the 1st of given month |
HalfyearlyFirst |
Biannual occurrence on the 1st of given month |
YearlyFirst |
Annual occurrence on the 1st of given month |
Schedule Calendar Units
Following is a list of allowed schedule calendar units:
scheduleCalendarUnit |
Description |
---|---|
Day |
One day |
Week |
One week |
Month |
One month |
Examples of schedules
All the following examples, assumes that the start date of the related subscription is the 1st of January.
Example 1 The following will calculate due dates the 7th of every month. When scheduleEveryOther is 1, scheduleBaseTier does not have any effect.
- scheduleType: Monthly
- scheduleBaseTier: 1
- scheduleFixedDay: 7
- scheduleEveryOther: 1
- scheduleCalendarUnit: Month
Calculated dates are: 7/1, 7/2, 7/3, ...
Example 2 The following will calculate due dates at the 14th of every other month, starting in February.
- scheduleType: Custom
- scheduleBaseTier: 2
- scheduleFixedDay: 14
- scheduleEveryOther: 2
- scheduleCalendarUnit: Month
Calculated dates are: 14/2, 14/4, 14/6, ...
Example 3 The following will calculate due dates the 10th of every quarter, starting in March.
- scheduleType: Quarterly
- scheduleBaseTier: 3
- scheduleFixedDay: 10
- scheduleEveryOther: 3
- scheduleCalendarUnit: Month
Calculated dates are: 10/3, 10/6, 10/9, ...
Example 4 The following will calculate due dates the 28th of every December.
- scheduleType: Yearly
- scheduleBaseTier: 12
- scheduleFixedDay: 28
- scheduleEveryOther: 12
- scheduleCalendarUnit: Month
Calculated dates are: 28/12-2018, 28/12-2019, 28/12-2020, ...
Example 5 The following will calculate due dates the 2nd of the selected months.
- scheduleType: Custom
- scheduleBaseTier: 1
- scheduleFixedDay: 2
- scheduleEveryOther: 1
- scheduleCalendarUnit: Month
- scheduleSelectedSet: 1, 4, 5, 11
Calculated dates are: 2/1, 2/4, 2/5, 2/11, ...
Example 6 The following will calculate due dates every week, start from the 1. of May 2020.
Since the 1. of May 2020 is a friday, scheduleFixedDay should be set to 5.
- scheduleType: Weekly
- scheduleBaseTier: 1
- scheduleFixedDay: 5
- scheduleEveryOther: 1
- scheduleCalendarUnit: Week
Calculated dates are: 1/5-2020, 8/5-2020, 15/5-2020, 22/5-2020, 29/5-2020, ...
Agreement States
Following is a list of Agreement states:
State |
Description |
---|---|
Available |
Agreement is available for Subscriptions. |
Archived |
Agreement was archived and is hidden from queries. |