HTTP endpoints
markPayoutPaid
Record that the money reached the partner. Merchant payouts also mark their rewards delivered.
POST /api/v1/payouts/{payoutId}/paid
Requires payouts:write. Keep the Bearer key on your server.
SDK
ts
grizzlee.markPayoutPaid(payoutId: string, input: { externalReference: string; paidAt?: string | undefined; }): Promise<PayoutWithAllocations>HTTP
Use your backend's HTTP client. The cURL request shows the wire format. Replace path parameters and example values.
sh
curl --fail-with-body --request POST \
'https://app.grizzlee.ca/api/v1/payouts/{payoutId}/paid' \
-H "Authorization: Bearer $GRIZZLEE_SERVER_KEY" \
-H 'Content-Type: application/json' \
--data '{"externalReference":"externalReference-example"}'Request body
| Field | Type | Required | Details |
|---|---|---|---|
externalReference | string | Yes | |
paidAt | string | No | date-time |
Request schema
json
{
"type": "object",
"properties": {
"externalReference": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"paidAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"externalReference"
],
"additionalProperties": false
}Response
HTTP responses wrap this value in data. The SDK returns the value directly unless the note above describes a wrapper.
| Field | Type | Required | Details |
|---|---|---|---|
allocations | array | Yes | |
id | string | Yes | |
companyId | string | Yes | |
partnerId | string | Yes | |
currency | union | Yes | |
amountCents | number | Yes | Gross amount. Merchant allocations sum to this amount. |
nettedDebtCents | number | No | Debt kept from a merchant payout. Defaults to zero on older payouts. |
netAmountCents | number | No | Transfer amount, equal to amountCents minus nettedDebtCents. |
status | union | Yes | |
reversedCents | number | No | Cumulative Stripe transfer amount returned to the merchant, in minor units. |
reversedAt | string | No | When Grizzlee last recorded an increase in reversedCents. |
provider | union | Yes | manual: the merchant sends the money and marks the payout paid. stripe: Grizzlee sends a Stripe transfer from the merchant's Stripe balance and marks the payout paid or failed itself. |
mode | union | No | grizzlee_wallet reserves the partner's available wallet cash. merchant pays specific merchant-delivered rewards listed in allocations. Absent on payouts created before merchant payouts existed, which use the wallet. |
integrationId | string | No | Stripe connection that sends the transfer. Stripe payouts only. |
destination | string | No | Stripe connected account that receives the transfer. Stripe payouts only. |
providerReference | string | No | The Stripe transfer ID or the merchant's own payment reference once paid. |
transferGroup | string | No | Stripe transfer_group Grizzlee sets on the transfer, grizzlee_payout_<payout ID>. |
paidAt | string | No | When the partner received the money, if the merchant reported it. |
lastError | string | No | |
lastErrorParts | array | No | lastError as codes. Absent on errors recorded before codes existed. |
eventId | string | Yes | |
schedule | object | No | Present when Grizzlee created this merchant payout from the company's payout schedule. |
createdAt | string | Yes | |
updatedAt | string | Yes |
allocations[]
| Field | Type | Required | Details |
|---|---|---|---|
allocations.id | string | Yes | |
allocations.companyId | string | Yes | |
allocations.payoutId | string | Yes | |
allocations.partnerId | string | Yes | |
allocations.rewardId | string | Yes | |
allocations.orderId | string | No | The reward's order. Absent for milestone rewards. |
allocations.milestone | string | No | The reward's milestone. Absent for order rewards. |
allocations.programId | string | Yes | |
allocations.currency | union | Yes | |
allocations.amountCents | number | Yes | |
allocations.createdAt | string | Yes |
allocations.currency
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
currency
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
status
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
Variant 5
Type: string.
Variant 6
Type: string.
Variant 7
Type: string.
provider
Variant 1
Type: string.
Variant 2
Type: string.
mode
Variant 1
Type: string.
Variant 2
Type: string.
lastErrorParts[]
| Field | Type | Required | Details |
|---|---|---|---|
lastErrorParts.code | union | Yes | |
lastErrorParts.params | object | No |
lastErrorParts.code
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
Variant 5
Type: string.
Variant 6
Type: string.
Variant 7
Type: string.
Variant 8
Type: string.
Variant 9
Type: string.
Variant 10
Type: string.
Variant 11
Type: string.
Variant 12
Type: string.
Variant 13
Type: string.
Variant 14
Type: string.
Variant 15
Type: string.
Variant 16
Type: string.
Variant 17
Type: string.
Variant 18
Type: string.
Variant 19
Type: string.
Variant 20
Type: string.
Variant 21
Type: string.
Variant 22
Type: string.
Variant 23
Type: string.
Variant 24
Type: string.
Variant 25
Type: string.
Variant 26
Type: string.
Variant 27
Type: string.
Variant 28
Type: string.
Variant 29
Type: string.
lastErrorParts.params
Type: object.
schedule
| Field | Type | Required | Details |
|---|---|---|---|
schedule.dueOn | string | Yes | Due date of the run, YYYY-MM-DD in UTC. |
schedule.approvedBefore | string | Yes | The run paid rewards approved at or before this time: the due date minus the hold period. |
Response schema
json
{
"type": "object",
"properties": {
"allocations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"companyId": {
"type": "string"
},
"payoutId": {
"type": "string"
},
"partnerId": {
"type": "string"
},
"rewardId": {
"type": "string"
},
"orderId": {
"type": "string",
"description": "The reward's order. Absent for milestone rewards."
},
"milestone": {
"type": "string",
"description": "The reward's milestone. Absent for order rewards."
},
"programId": {
"type": "string"
},
"currency": {
"anyOf": [
{
"type": "string",
"const": "CAD"
},
{
"type": "string",
"const": "USD"
},
{
"type": "string",
"const": "EUR"
},
{
"type": "string",
"const": "GBP"
}
]
},
"amountCents": {
"type": "number"
},
"createdAt": {
"type": "string"
}
},
"required": [
"id",
"companyId",
"payoutId",
"partnerId",
"rewardId",
"programId",
"currency",
"amountCents",
"createdAt"
]
}
},
"id": {
"type": "string"
},
"companyId": {
"type": "string"
},
"partnerId": {
"type": "string"
},
"currency": {
"anyOf": [
{
"type": "string",
"const": "CAD"
},
{
"type": "string",
"const": "USD"
},
{
"type": "string",
"const": "EUR"
},
{
"type": "string",
"const": "GBP"
}
]
},
"amountCents": {
"type": "number",
"description": "Gross amount. Merchant allocations sum to this amount."
},
"nettedDebtCents": {
"type": "number",
"description": "Debt kept from a merchant payout. Defaults to zero on older payouts."
},
"netAmountCents": {
"type": "number",
"description": "Transfer amount, equal to amountCents minus nettedDebtCents."
},
"status": {
"anyOf": [
{
"type": "string",
"const": "reversed"
},
{
"type": "string",
"const": "failed"
},
{
"type": "string",
"const": "queued"
},
{
"type": "string",
"const": "processing"
},
{
"type": "string",
"const": "needs_action"
},
{
"type": "string",
"const": "paid"
},
{
"type": "string",
"const": "cancelled"
}
]
},
"reversedCents": {
"type": "number",
"description": "Cumulative Stripe transfer amount returned to the merchant, in minor units."
},
"reversedAt": {
"type": "string",
"description": "When Grizzlee last recorded an increase in reversedCents."
},
"provider": {
"anyOf": [
{
"type": "string",
"const": "manual"
},
{
"type": "string",
"const": "stripe"
}
],
"description": "manual: the merchant sends the money and marks the payout paid. stripe: Grizzlee sends a Stripe\ntransfer from the merchant's Stripe balance and marks the payout paid or failed itself."
},
"mode": {
"anyOf": [
{
"type": "string",
"const": "grizzlee_wallet"
},
{
"type": "string",
"const": "merchant"
}
],
"description": "grizzlee_wallet reserves the partner's available wallet cash. merchant pays specific\nmerchant-delivered rewards listed in allocations. Absent on payouts created before merchant\npayouts existed, which use the wallet."
},
"integrationId": {
"type": "string",
"description": "Stripe connection that sends the transfer. Stripe payouts only."
},
"destination": {
"type": "string",
"description": "Stripe connected account that receives the transfer. Stripe payouts only."
},
"providerReference": {
"type": "string",
"description": "The Stripe transfer ID or the merchant's own payment reference once paid."
},
"transferGroup": {
"type": "string",
"description": "Stripe transfer_group Grizzlee sets on the transfer, grizzlee_payout_<payout ID>."
},
"paidAt": {
"type": "string",
"description": "When the partner received the money, if the merchant reported it."
},
"lastError": {
"type": "string"
},
"lastErrorParts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"anyOf": [
{
"type": "string",
"const": "retries_stopped"
},
{
"type": "string",
"const": "connection_disabled"
},
{
"type": "string",
"const": "connection_unavailable"
},
{
"type": "string",
"const": "debt_settled"
},
{
"type": "string",
"const": "payout_changed"
},
{
"type": "string",
"const": "delivery_failed"
},
{
"type": "string",
"const": "no_transfer_sent"
},
{
"type": "string",
"const": "rewards_payable"
},
{
"type": "string",
"const": "refund_reduced_earnings"
},
{
"type": "string",
"const": "rewards_not_marked"
},
{
"type": "string",
"const": "contact_support"
},
{
"type": "string",
"const": "transfer_unmatched"
},
{
"type": "string",
"const": "stripe_key_rejected"
},
{
"type": "string",
"const": "stripe_key_permission"
},
{
"type": "string",
"const": "stripe_insufficient_funds"
},
{
"type": "string",
"const": "partner_onboarding"
},
{
"type": "string",
"const": "partner_account_missing"
},
{
"type": "string",
"const": "stripe_rejected"
},
{
"type": "string",
"const": "stripe_rejected_code"
},
{
"type": "string",
"const": "answer_kept"
},
{
"type": "string",
"const": "search_failed"
},
{
"type": "string",
"const": "not_confirmed"
},
{
"type": "string",
"const": "rewards_kept"
},
{
"type": "string",
"const": "earnings_reserved"
},
{
"type": "string",
"const": "transfer_conflict"
},
{
"type": "string",
"const": "transfers_conflict"
},
{
"type": "string",
"const": "check_transfer_group"
},
{
"type": "string",
"const": "check_transfer_metadata"
},
{
"type": "string",
"const": "cancelled_no_transfer"
}
]
},
"params": {
"type": "object",
"properties": {},
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
}
}
},
"required": [
"code"
]
},
"description": "lastError as codes. Absent on errors recorded before codes existed."
},
"eventId": {
"type": "string"
},
"schedule": {
"type": "object",
"properties": {
"dueOn": {
"type": "string",
"description": "Due date of the run, YYYY-MM-DD in UTC."
},
"approvedBefore": {
"type": "string",
"description": "The run paid rewards approved at or before this time: the due date minus the hold period."
}
},
"required": [
"dueOn",
"approvedBefore"
],
"description": "Present when Grizzlee created this merchant payout from the company's payout schedule."
},
"createdAt": {
"type": "string"
},
"updatedAt": {
"type": "string"
}
},
"required": [
"allocations",
"id",
"companyId",
"partnerId",
"currency",
"amountCents",
"status",
"provider",
"eventId",
"createdAt",
"updatedAt"
]
}Errors
Failures return { "error": { "code": "...", "message": "...", "details": {} } }. Details are optional. See error statuses. Reuse an unchanged event payload when retrying.