Skip to main content
POST
/
v1
/
contracts
/
{contractId}
/
credits
/
promotional
/
grant
curl --request POST \
  --url https://api.monk.com/v1/contracts/{contractId}/credits/promotional/grant \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amountCents": 50000,
  "expiresAt": "2026-06-09T23:59:59.000Z",
  "description": "$500 promotional grant"
}
'
{
  "data": {
    "id": "entry-uuid-5678",
    "type": "grant",
    "amountCents": 50000,
    "creditAmount": 500,
    "creditRateCents": 100,
    "purchaseRateCents": 0,
    "currency": "USD",
    "description": "Free trial — 500 credits",
    "expiresAt": "2026-06-09T23:59:59.000Z",
    "isPromotional": true,
    "balanceAfterCents": 50000,
    "creditBalanceAfter": 500,
    "createdAt": "2026-03-09T10:00:00.000Z",
    "invoiceId": "inv-uuid-9012",
    "metadata": null
  }
}
Promotional Only: All credits granted via this API are promotional (no revenue recognition implications). For paid credit purchases, use the Monk dashboard.
Automatically enables the wallet if not already active. Credits apply to usage-based line items only. When multiple grants exist, credits are automatically deducted in optimal order (expiring soonest first, promotional before paid). Two modes:
  1. Dollar-only mode: Provide just amountCents — no credit tracking
  2. Rate mode: Provide creditRateCents + creditAmount → dollar amount is derived
ModeamountCentscreditRateCentscreditAmountResult
Dollar-only50000——$500 grant, no credit tracking
Rate mode—100500500(100×500),500creditsat500 (100 × 500), 500 credits at 1/credit
Free credits—0500$0, 500 free credits
Idempotency: Use externalId to prevent duplicate grants. Retrying with the same value returns the existing entry.
Scope: contracts:write

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
contractId
string
required

The unique identifier of the contract (UUID)

Body

application/json
​
expiresAt
string<date-time>
required

When these credits expire (ISO 8601). Required.

​
amountCents
integer

Dollar amount in cents (dollar-only mode). Use alone for grants without credit tracking.

Required range: x >= 0
​
creditRateCents
integer

Rate in cents per credit (rate mode). Must be provided with creditAmount.

Required range: x >= 0
​
creditAmount
number

Number of credits to grant (rate mode). Must be provided with creditRateCents.

Required range: x > 0
​
description
string
default:Promotional credit grant via API
Maximum string length: 500
​
externalId
string

Idempotency key — resending the same value returns the existing entry.

Maximum string length: 255
​
specifiers
object

Specifiers that control which usage this grant can be applied to. When omitted, grant applies to ALL usage.

​
metadata
object

Arbitrary key-value metadata to attach to the grant. Internal keys (isPromotional, deductionBatchId) are reserved and will be stripped from responses.

Response

Promotional credits granted

​
data
object

Response after granting credits