Agreement – OnlineFundraising

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.

Properties

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

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"
      }
    ]
  }
]

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.

How may we help?

Payment API

Introduction

Properties

Endpoints

GET /agreements?pageNumber={x}&pageSize={y}&state={z}

Response

GET /agreement/{guid}

Response

POST /agreement

Request

Response

PUT /agreement/{guid}

Request

Response

PATCH /agreement/{guid}

Request

Response

POST /agreement/{guid}/ChangeAmount

Request

Response

POST /agreement/{guid}/ChangeFrequency

Request

Response

POST /agreement/{guid}/Archive

Response

GET /agreement/{guid}/payments?pageNumber={x}&pageSize={y}

Response

GET /agreement/{guid}/subscriptions?pageNumber={x}&pageSize={y}

Response

GET /agreement/{guid}/log?limit={limit}

Response

Schedule Types

Schedule Calendar Units

Examples of schedules

Agreement States