Skip to main content

​
Promotional Credits

This guide shows you how to use promotional credits for sign-up bonuses, referral programs, and marketing campaigns.
What makes credits “promotional”? Promotional credits have no cost basis ($0 amount) and are always marked promotional by Monk. They’re deducted before paid credits and don’t generate breakage revenue when expired.

​
When to Use Promotional Credits

Use CaseExample
Sign-up bonus”Get $50 in free credits when you sign up”
Referral reward”Refer a friend, both get $25 in credits”
Trial credits”Try our API with 1,000 free credits”
Goodwill gesture”Sorry for the outage — here’s $100 on us”
Marketing campaign”Black Friday: $200 bonus credits with any plan”

​
Granting Promotional Credits

​
Via Dashboard

When creating a contract, check Add bonus credits in the Commercial Terms step:
  1. Enable the credit wallet
  2. Configure prepaid credits (or set to $0 for promo-only)
  3. Check Add bonus credits
  4. Enter the number of bonus credits
  5. Set an expiration date (optional)
Add bonus credits checkbox with bonus credits input showing free promotional credits

​
Via API

curl -X POST "https://api.monk.com/v1/contracts/{contractId}/credits/promotional/grant" \
  -H "Authorization: Bearer mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "creditRateCents": 0,
    "creditAmount": 500,
    "expiresAt": "2026-06-30T23:59:59.000Z",
    "description": "Welcome bonus — 500 free credits",
    "externalId": "welcome-bonus-cust_123"
  }'
This endpoint is promotional-only. Do not send isPromotional; Monk sets it automatically. Include expiresAt, and provide either amountCents OR creditRateCents + creditAmount.

​
How Promotional Credits Differ

AspectPaid CreditsPromotional Credits
amountCents> 0Usually 0
isPromotionalfalsetrue
Deduction orderAfter promotionalFirst
ExpirationBreakage revenueNo revenue
Audit trailShows cost basisShows as free
Credit Wallet showing promotional credit block with PROMO and DEPLETED badges

​
Deduction Priority

When a customer has both paid and promotional credits, promotional credits are always used first: This benefits both parties:
  • Customer: Gets value from promotional credits first
  • Business: Preserves revenue recognition for paid credits

​
Common Patterns

​
Sign-Up Bonus

Grant credits when a new customer signs up: 
// In your signup webhook handler
const onCustomerCreated = async customer => {
  const contract = await getActiveContract(customer.id);

  await fetch(
    `${MONK_API}/contracts/${contract.id}/credits/promotional/grant`,
    {
      method: 'POST',
      headers: { Authorization: `Bearer ${MONK_API_KEY}` },
      body: JSON.stringify({
        creditRateCents: 0,
        creditAmount: 500,
        description: 'Welcome bonus — 500 free credits',
        expiresAt: addDays(new Date(), 90).toISOString(), // required
        externalId: `welcome-${customer.id}`,
      }),
    }
  );
};

​
Referral Program

Grant credits to both referrer and referee: 
const processReferral = async ({ referrerId, refereeId }) => {
  const referrerContract = await getActiveContract(referrerId);
  const refereeContract = await getActiveContract(refereeId);

  // Grant to referrer
  await grantPromotionalCredits(referrerContract.id, {
    creditRateCents: 0,
    creditAmount: 250,
    description: `Referral reward — referred ${refereeId}`,
    expiresAt: addDays(new Date(), 60).toISOString(),
    externalId: `referral-referrer-${referrerId}-${refereeId}`,
  });

  // Grant to referee
  await grantPromotionalCredits(refereeContract.id, {
    creditRateCents: 0,
    creditAmount: 250,
    description: `Referral bonus — referred by ${referrerId}`,
    expiresAt: addDays(new Date(), 60).toISOString(),
    externalId: `referral-referee-${referrerId}-${refereeId}`,
  });
};

​
Bonus on Purchase

Give bonus promotional credits when a customer buys paid credits elsewhere: 
const onCreditPurchase = async ({ contractId, purchaseAmountCents }) => {
  // Paid credit purchases are handled in Monk dashboard/contract workflows.
  // Here, grant only the promotional bonus via public API.
  const bonusCents = Math.floor(purchaseAmountCents * 0.2);

  await grantPromotionalCredits(contractId, {
    amountCents: bonusCents,
    description: '20% bonus credits on purchase',
    expiresAt: addDays(new Date(), 30).toISOString(),
    externalId: `bonus-${contractId}-${Date.now()}`,
  });
};

​
Time-Limited Campaign

Promotional credits with expiration for urgency: 
# Black Friday: $100 bonus expires in 7 days
curl -X POST ".../credits/promotional/grant" \
  -d '{
    "amountCents": 10000,
    "description": "Black Friday bonus — expires in 7 days!",
    "expiresAt": "2026-12-06T23:59:59.000Z"
  }'

​
Expiration and Breakage

​
Promotional Credits Don’t Generate Revenue

When promotional credits expire:
  1. An expiration entry is created in the ledger
  2. The balance is zeroed out
  3. No breakage revenue is recognized (because cost basis was $0)
This is different from paid credits, where expiration triggers revenue recognition.

​
Example: Mixed Wallet Expiration

Customer has:
  • $100 paid credits (expires Dec 31)
  • 500 promotional credits (expires Dec 31)
If both expire unused:
  • Paid credits → $100 breakage revenue recognized
  • Promotional credits → No revenue (just ledger entry)

​
Tracking and Reporting

​
Identify Promotional Usage

The ledger shows isPromotional for each entry: 
{
  "history": [
    {
      "type": "usage",
      "amountCents": -1600,
      "creditAmount": -50,
      "description": "API usage deduction",
      "isPromotional": true,
      "grantEntryId": "led_promo_abc123"
    }
  ]
}

​
Credit Usage Statement

The Credit Usage Statement shows which deductions came from promotional vs. paid credits, useful for:
  • Customer visibility
  • Internal reporting
  • Audit trails

​
Best Practices

POST /v1/contracts/{contractId}/credits/promotional/grant always marks the grant as promotional and applies the right deduction/accounting behavior.
Promotional credits should expire to create urgency. Common timeframes: - Sign-up bonus: 30-90 days - Referral: 60 days - Campaign: 7-30 days
“500 free credits” is clearer than “$16 in free credits” for promotional messaging.
Use the isPromotional field in reports to understand the cost of your promotional programs.

​
Next Steps

How Usage-Based Billing Works

See how credits fit into the full billing flow

Grant Credits API

See POST /v1/contracts/{contractId}/credits/promotional/grant

Prepaid Credits Guide

End-to-end prepaid credits setup

Credits Concepts

Deep dive into credit mechanics