How may we help?

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. Please see examples below.
scheduleFixedDay	INTEGER	YES		1-28	A fixed day of the chosen calendarUnit. Please note we do not accept the 29-31 of any month. Please see examples below.
scheduleEveryOther	INTEGER	YES			Please see description below. Skip every other due date.
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.