How may we help?

Introduction

A Subscription represents the Contact's unique Subscription of a given Agreement (i.e. membership or recurring donation) and so is the engagement of an Agreement. It connects possible upgrades to the chosen Agreement and defines which Payment Method the Agreement and upgrade should be charged by.

Changes committed to a Subscription can be retrieved via the ChangeLog entity.

Endpoints

GET /subscriptions?pageNumber={x}&pageSize={y}&startDate={yyyy-mm-dd}&endDate={yyyy-mm-dd}&state={z}

Get a list of Subscriptions at a given size by a given offset and date limitation. 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},
  "startDate": {
    yyyy-mm-dd
  },
  "endDate": {
    yyyy-mm-dd
  },
  "list": [
    {
      "subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
      "...": "..."
    },
    {
      "subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
      "...": "..."
    }
  ]
}

 

GET /subscription/{guid}

Get a single Subscription.

Response

HTTP	Description
200	OK
404	Subscription not found

HTTP 200 Example

{
  "subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
  "version": 1,
  "contactGuid": "",
  "agreementGuid": "",
  "state": "",
  "paymentMethodType": "",
  "paymentMethodGuid": "",
  "createdTs": "2019-01-01 00:00:00 +0100",
  "startDate": "",
  "expiresAfterDate": "",
  "cancelledTs": "",
  "cancelCode": "",
  "cancelDescription": "",
  "holdDescription": "",
  "archivedTs": "",
  "quantity": 1,
  "errorCode": "",
  "errorDescription": "",
  "nextDueDate": "",
  "externalId": "",
  "externalLink": "",
  "dataSetGuid": ""
}

 

POST /subscription

Insert a single Subscription.

Request

The following must be provided as the request body:

{
  "contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
  "agreementGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
  "paymentMethodType": "",
  "paymentMethodGuid": "",
  "startDate": "",
  "expiresAfterDate": "",
  "quantity": 1,
  "externalId": "",
  "externalLink": ""
}

Response

HTTP	Description
201	Created
400	Something's wrong with request body.

HTTP 201 Example

{
  "subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
  "...": "..."
}

 

PATCH /subscription/{guid}

Update a single Subscription. The following fields are patchable: expiresAfterDate, holdDescription, quantity, externalId and externalLink.

Request

The following must be provided as the request body:

[
  {
    "op": "add|replace|remove",
    "path": "/externalId",
    "value": "1001"
  }
]

Response

HTTP	Description
200	OK
400	Something's wrong with request body.
404	Subscription was not found

 

GET /subscription/{guid}/schedule

Get an array of five scheduled payment due dates, after the nextDueDate, for a single Subscription.

The example below correlates to a Monthly Subscription with the nextDueDate: 2019-05-01.

Response

HTTP	Description
200	OK
404	Subscription was not found

HTTP 200 Example

[
  "2019-06-01",
  "2019-07-01",
  "2019-08-01",
  "2019-09-01",
  "2019-10-01"
]

 

GET /subscription/{guid}/payments

Get a list of Payments for a single Subscription.

Response

HTTP	Description
200	OK
404	Subscription was not found

HTTP 200 Example

[
  {
    "paymentGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
    "...": "..."
  },
  {
    "paymentGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
    "...": "..."
  }
]

 

GET /subscription/{guid}/addOns

Get a list of Add Ons for a single Subscription.

Response

HTTP	Description
200	OK
404	Subscription was not found

HTTP 200 Example

[
  {
    "addOnGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
    "...": "..."
  },
  {
    "addOnGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
    "...": "..."
  }
]

POST /subscription/{guid}/Hold

Hold a Subscription.

Request

The following can be provided as the request body:

{
  "holdDescription": "..."
}

Response

HTTP	Description
200	OK
404	Subscription was not found

 

POST /subscription/{guid}/Restart

Restart a Subscription from Hold state.

Request

The following can be provided as the request body:

{
  "startDate": "2019-01-01 00:00:00 +0100",
  "expiresAfterDate": "2019-12-31 00:00:00 +0100"
}

Response

HTTP	Description
200	OK
400	Something's wrong with request body.
404	Subscription was not found

 

POST /subscription/{guid}/Cancel

Cancel a Subscription, but please note this does affect neither the Payment Method nor Pending Payments.

Request

The following can be provided as the request body:

{
  "cancelDescription": "..."
}

Response

HTTP	Description
200	OK
400	Something's wrong with request body.
404	Subscription was not found

 

POST /subscription/{guid}/Archive

Archive a Subscription.

Response

HTTP	Description
200	OK
404	Subscription was not found

 

POST /subscription/{guid}/ChangeAgreement

Change the Agreement of a Subscription. A new startDate and nextDueDate is calculated for the Subscription based on the new Agreement.
Triggers a Subscription updated webhook.

Request

The following must be provided as the request body:

{
  "agreementGuid": "a6195e22-f9c3-xxxx-9da6-4cb4d1fff778" 
}

Response

HTTP	Description
200	OK
400	Something's wrong with request body
404	Subscription was not found

HTTP 200 Example

{
  "subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
  "createdTs": "2021-06-10 13:43:10",
  "agreementGuid": "a6195e22-f9c3-xxxx-9da6-4cb4d1fff778",
  ... : ...
}

POST /subscription/{guid}/UpdatePaymentMethod

Update the PaymentMethod of a Subscription. A new startDate and nextDueDate is calculated for the Subscription based on the new PaymentMethod.
Triggers a Subscription updated webhook.

Request

The following must be provided as the request body:

{
  "paymentMethodGuid": "71209531-xxxx-xxxx-xxxx-49c0f59f1bfc" 
}

Response

HTTP	Description
200	OK
400	Something's wrong with request body
404	Subscription was not found

HTTP 200 Example

{
  "subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
  "createdTs": "2021-06-10 13:43:10",
  "paymentMethodGuid": "71209531-xxxx-xxxx-xxxx-49c0f59f1bfc",
  ... : ...
}

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

Get a list of changes to a Subscription.

Response

HTTP	Description
200	OK

HTTP 200 Example

[
  {
    "changeGuid": "242bf0de-5ed3-48a1-bb3a-xxxxxxxxxxxx",
    "createdTs": "2021-01-01 00:00:00 +0100",
    "entityType": "Subscription",
    "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": "Inactive",
        "oldValue": "Active",
        "fieldName": "state"
      }
    ]
  }
]

Properties

Name	Type	Mandatory	Default	Example	Description
subscriptionGuid	STRING	-			Unique GUID
merchantId	STRING	-			Readable ID of the merchant
contactGuid	STRING	YES
agreementGuid	STRING	YES
state	STRING	YES			Please see list of Subscription States below
paymentMethodType	STRING	-			Please see list of Payment Method Types under Payment Method
paymentMethodGuid	STRING	YES			GUID of Payment Method
createdTs	DATETIME	-			Timestamp of Subscription creation
startDate	DATETIME	YES		"2020-01-01", but most commonly the current date.	Date from which OnlineFundraising should begin charging the Subscription. Please consider the difference between startDate and originTs when importing existing Subscriptions.
expiresAfterDate	DATETIME	NO			Date of expiration
cancelledTs	DATETIME	-			Timestamp of cancellation
cancelCode	INTEGER	-			Please see list of Cancel Codes below
cancelDescription	STRING	NO			User friendly description of cancellation or custom string provided by Merchant
holdDescription	STRING	NO			Custom string provided by Merchant
archivedTs	DATETIME	-			Timestamp of archiving
inactivatedTs	DATETIME	-			Timestamp of deactivation
quantity	INTEGER	NO	1		Defaults to 1
errorCode	INTEGER	-			Please see list of Subscription Error Codes below
errorDescription	STRING	-			User friendly description of the provided error
nextDueDate	DATETIME	-			Date of next planned charge calculated by Agreement schedule configuration
externalId	STRING	NO			An external ID
externalLink	STRING	NO			An external URL to e.g. CRM
originTs	DATETIME	NO			Non-operational timestamp of origin, useful when importing data.
dataSetGuid	STRING	NO			The DataSet GUID used to create the Contact

 

Subscription States

Following is a list of Subscription states:

State	Description
Pending	Waiting for Payment Method to become active.
Active	Subscription is active and will result in future Payments.
Inactive	Subscription is inactive and is therefore not in consideration for future Payments.
Expired	Subscription has passed expiration date.
Archived	Subscription was archived and is therefore hidden from queries.
Error	Subscription has errorCode and errorDescription.

Subscription State Diagram

Subscription Error Codes and Descriptions

For further examples and ties to other entities, please see: Error and Cancel Codes

Error Code	Description	State
100001	Subscription has no active Payment Method, but Payments are required by the Agreement.	Active
100002	Subscription has no active Payment Method, and Payments are not required.	Inactive
100003	Subscription Payment Method not found at the time of scheduling.	Inactive

Subscription Cancel Codes

For further examples and ties to other entities, please see: Error and Cancel Codes

Cancel Code	Description	State
100101	Cancelled by Debtor.	Inactive
100102	Cancelled by Creditor in either UI or API integration.	Inactive
100103	Expired due to the defined expiresAfterDate.	Inactive
100104	Cancelled by System at the time of charge. Due to the Payment Method being cancelled at payment gateway.	Inactive