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

Property	Format and Description
agreementGuid	string<uuid> Unique Guid
agreementType required	string 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. Enum: "Personal", "Shared"
contactGuid	string<uuid> Unique Guid
communicationCollectionGuid	string<uuid> Unique Guid
dataSetGuid	string<uuid> Unique Guid
default_quantity	integer Default quantity = 1.
createdTs	string<yyyy-MM-dd HH:mm:ss zzzz> Timestamp of creation
updatedTs	string<yyyy-MM-dd HH:mm:ss zzzz> Timestamp of update
archivedTs	string<yyyy-MM-dd HH:mm:ss zzzz> Timestamp of archivation
merchantId	string Unique ID of merchant
name required	string The name of the record
description	string Description of the record
unit required	string Type of unit
unitPrice required	number Unit price of a single AddOn
amount required	number Summarized amount excluding VAT
amountVat required	number Amount VAT
amountTotal required	number Total amount including VAT
vatPercentage required	number VAT percentage
currencyCode required	string ISO formatted Currency Code
state	string Enum: "Available", "Archived"
taxDeductible	boolean Defines basis for tax deductibility. Default: true
paymentRequired required	boolean Default: false Is payment required for the purpose of the Agreement (i.e. purchase of a product, membership access)?
scheduleType required	itring Allowed schedule types Enum: "Manual", "Custom", "Daily", "Weekly", "Monthly", "Quarterly", "Halfyearly", "Yearly", "MonthlyFirst", "HalfyearlyFirst", "YearlyFirst"
scheduleBaseTier required	integer The offset in relation to the chosen calendarUnit. A Yearly subscription in March has baseTier: 3
scheduleFixedDay required	integer The offset day of the chosen calendarUnit. A subscription the 15th has fixedDay: 15 Please note we do not accept the 29-31 of any month.
scheduleEveryOther required	integer The interval of the chosen calendarUnit. Yearly : everyOther = 12 Monthly : everyOther = 1
scheduleCalendarUnit	string Default: "Month" Due date is calculated by the chosen calendarUnit. Enum: "Day", "Week", "Month"
scheduleSelectedSet	string Only relevant for Custom scheduleType. A subscription in March, August and September has selectedSet: [3,8,9]
externalId	string An external ID as provided by merchant
originTs	string<yyyy-MM-dd HH:mm:ss zzzz> Timestamp of origin, useful when importing data (e.g. if originated in external system)
purposeAccountingCode	string Accounting code provided by Merchant

 

Example

{
"agreementGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"communicationCollectionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"dataSetGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"createdTs": "2019-12-31 15:59:59 +0100",
"updatedTs": "2019-12-31 15:59:59 +0100",
"archivedTs": "2019-12-31 15:59:59 +0100",
"merchantId": "your-merchant",
"name": "Recurring donation",
"description": "Custom regular donation",
"agreementType": "Personal",
"default_quantity": 1,
"unit": "pcs",
"unitPrice": 100,
"amount": 100,
"amountVat": 0,
"amountTotal": 100,
"vatPercentage": 0,
"currencyCode": "DKK",
"state": "Available",
"paymentRequired": false,
"scheduleType": "Custom",
"scheduleBaseTier": 1,
"scheduleFixedDay": 2,
"scheduleEveryOther": 1,
"scheduleCalendarUnit": "Day",
"scheduleSelectedSet": "[1,4,5,11]",
"externalId": "some-id",
"originTs": "2019-12-31 15:59:59 +0100",
"purposeAccountingCode": "donation"
}

 

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.