curl --request POST \
--url https://api.grainledger.com/api/v1/settlements \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"estimatedArrivalDate": "2026-08-21",
"totalGross": 1025,
"totalFees": 25,
"totalNet": 1000,
"paymentCount": 8
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
estimatedArrivalDate: '2026-08-21',
totalGross: 1025,
totalFees: 25,
totalNet: 1000,
paymentCount: 8
})
};
fetch('https://api.grainledger.com/api/v1/settlements', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.grainledger.com/api/v1/settlements"
payload = {
"estimatedArrivalDate": "2026-08-21",
"totalGross": 1025,
"totalFees": 25,
"totalNet": 1000,
"paymentCount": 8
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"id": "<string>",
"provider": "STRIPE",
"externalId": "<string>",
"estimatedArrivalDate": "2023-11-07T05:31:56Z",
"recordedTotals": {
"gross": 123,
"fees": 123,
"net": 123,
"paymentCount": 123,
"donationCount": 123
},
"linkedContributionTotals": {
"gross": 123,
"fees": 123,
"net": 123,
"paymentCount": 123,
"donationCount": 123
},
"currency": "<string>",
"status": "PENDING",
"accounting": {
"disposition": "ELIGIBLE",
"reason": "<string>",
"journalEntry": {
"id": "<string>",
"entryNumber": "<string>",
"referenceNumber": "<string>"
}
},
"bankLink": {
"isLinked": true,
"transaction": {
"id": "<string>",
"date": "2023-11-07T05:31:56Z",
"amount": 123,
"description": "<string>"
}
},
"isFrozen": true,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"externalReference": "<string>",
"actualArrivalDate": "2023-11-07T05:31:56Z",
"settlementType": "<string>",
"errorMessage": "<string>",
"failureCode": "<string>",
"depositBasis": "GROSS",
"givingIntegration": {
"id": "<string>",
"provider": "<string>",
"name": "<string>"
},
"merchant": {
"id": "<string>",
"name": "<string>",
"campusId": "<string>",
"dimensionValueId": "<string>"
},
"dimensions": [
{
"dimensionId": "<string>",
"dimensionValueId": "<string>",
"dimensionName": "<string>",
"dimensionValueName": "<string>"
}
],
"batches": [
{
"id": "<string>",
"externalReference": "<string>",
"status": "<string>",
"batchDate": "2023-11-07T05:31:56Z",
"totalNet": 123
}
]
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}Create settlement
Creates a resource record only. It never posts a journal entry, links a bank transaction, or reconciles accounting. contributionIds and givingBatchIds are applied atomically.
curl --request POST \
--url https://api.grainledger.com/api/v1/settlements \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"estimatedArrivalDate": "2026-08-21",
"totalGross": 1025,
"totalFees": 25,
"totalNet": 1000,
"paymentCount": 8
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
estimatedArrivalDate: '2026-08-21',
totalGross: 1025,
totalFees: 25,
totalNet: 1000,
paymentCount: 8
})
};
fetch('https://api.grainledger.com/api/v1/settlements', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.grainledger.com/api/v1/settlements"
payload = {
"estimatedArrivalDate": "2026-08-21",
"totalGross": 1025,
"totalFees": 25,
"totalNet": 1000,
"paymentCount": 8
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"id": "<string>",
"provider": "STRIPE",
"externalId": "<string>",
"estimatedArrivalDate": "2023-11-07T05:31:56Z",
"recordedTotals": {
"gross": 123,
"fees": 123,
"net": 123,
"paymentCount": 123,
"donationCount": 123
},
"linkedContributionTotals": {
"gross": 123,
"fees": 123,
"net": 123,
"paymentCount": 123,
"donationCount": 123
},
"currency": "<string>",
"status": "PENDING",
"accounting": {
"disposition": "ELIGIBLE",
"reason": "<string>",
"journalEntry": {
"id": "<string>",
"entryNumber": "<string>",
"referenceNumber": "<string>"
}
},
"bankLink": {
"isLinked": true,
"transaction": {
"id": "<string>",
"date": "2023-11-07T05:31:56Z",
"amount": 123,
"description": "<string>"
}
},
"isFrozen": true,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"externalReference": "<string>",
"actualArrivalDate": "2023-11-07T05:31:56Z",
"settlementType": "<string>",
"errorMessage": "<string>",
"failureCode": "<string>",
"depositBasis": "GROSS",
"givingIntegration": {
"id": "<string>",
"provider": "<string>",
"name": "<string>"
},
"merchant": {
"id": "<string>",
"name": "<string>",
"campusId": "<string>",
"dimensionValueId": "<string>"
},
"dimensions": [
{
"dimensionId": "<string>",
"dimensionValueId": "<string>",
"dimensionName": "<string>",
"dimensionValueName": "<string>"
}
],
"batches": [
{
"id": "<string>",
"externalReference": "<string>",
"status": "<string>",
"batchDate": "2023-11-07T05:31:56Z",
"totalNet": 123
}
]
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}Authorizations
Organization API key created in Grain Settings → API. The key determines the organization and is limited to its assigned resource scopes. Write scopes imply the corresponding read scope.
Headers
Required with OAuth access tokens for resource requests. Omit only for GET /api/v1/organizations. Optional with organization API keys; if supplied with an API key, it must match the key's organization.
Body
x >= 0x >= 0x >= 0x >= 0STRIPE, PUSHPAY, SUBSPLASH, TITHELY, PLANNING_CENTER, ROCK_RMS, RAMP, DIVVY, MANUAL Generated when omitted for a manual settlement.
3PENDING, IN_TRANSIT, DEPOSITED, FAILED, CANCELLED GROSS, NET 1000010000Response
Created settlement
Recorded settlement values plus independently calculated linked-contribution totals. Accounting and bank-link state are read-only; raw provider metadata, sync diagnostics, accounting details, and fingerprints are excluded.
STRIPE, PUSHPAY, SUBSPLASH, TITHELY, PLANNING_CENTER, ROCK_RMS, RAMP, DIVVY, MANUAL Calendar day represented as a UTC-midnight ISO timestamp.
3PENDING, IN_TRANSIT, DEPOSITED, MATCHED, RECONCILED, FAILED, CANCELLED Hide child attributes
Hide child attributes
ELIGIBLE, NEEDS_REVIEW, RECORDED_EXTERNALLY Calendar day represented as a UTC-midnight ISO timestamp.
GROSS, NET