Overview

Dunning profiles let you customize payment recovery behavior beyond the default settings. Each profile defines:

• Retry schedule: How many retries and how often
• Failure handling: What happens when all retries fail
• Email notifications: Which emails to send at each retry step

System default profiles

Every account comes with four system default profiles optimized for different billing cycles:

System defaults cannot be modified or deleted, but you can clone them to create custom variations.

Custom profiles

Create custom profiles to tailor dunning behavior for specific use cases.

Create a profile

$
curl -X POST https://api.paymentkit.com/v1/dunning/profiles \
>
  -H "Authorization: Bearer sk_live_..." \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "name": "Premium Customers",
>
    "description": "Extended recovery for high-value subscriptions",
>
    "max_retries": 12,
>
    "retry_interval_hours": 72,
>
    "termination_action": "leave_active",
>
    "invoice_status_on_failure": "leave_open",
>
    "enable_emails": true,
>
    "email_map": [
>
      {"retry_step": 0, "template": "payment_failed"},
>
      {"retry_step": 3, "template": "payment_reminder"},
>
      {"retry_step": -1, "template": "final_warning"}
>
    ]
>
  }'

Profile settings

Email map

The email_map array controls which email templates are sent at each retry step:

1
{
2
  "email_map": [
3
    {"retry_step": 0, "template": "payment_failed"},     // First retry
4
    {"retry_step": 2, "template": "payment_reminder"},   // Third retry
5
    {"retry_step": -1, "template": "final_warning"}      // Final retry (special value)
6
  ]
7
}

Use retry_step: -1 to target the final retry, regardless of how many retries are configured.

Clone a profile

Create a copy of an existing profile (including system defaults):

$
curl -X POST https://api.paymentkit.com/v1/dunning/profiles/{profile_id}/clone \
>
  -H "Authorization: Bearer sk_live_..." \
>
  -H "Content-Type: application/json" \
>
  -d '{"name": "My Custom Monthly Profile"}'

Archive a profile

Archiving soft-deletes a profile. Archived profiles don’t appear in the default list but remain accessible by ID. In-flight dunning cycles using the profile continue unaffected.

$
curl -X DELETE https://api.paymentkit.com/v1/dunning/profiles/{profile_id} \
>
  -H "Authorization: Bearer sk_live_..."

Profile assignments

By default, PaymentKit selects a system default profile based on the subscription’s billing cycle. Use profile assignments to override this for specific prices or billing cycle categories.

Resolution order

When a dunning cycle starts, PaymentKit resolves the profile using a 2-tier priority:

1. Price assignment — If the subscription’s price has a profile assigned, use that profile
2. Cycle-length assignment — If no price assignment, check for a cycle_length category assignment
3. System default — Fall back to the system default for the billing cycle type

Assign to a price

Target a specific product price for custom dunning behavior:

$
curl -X POST https://api.paymentkit.com/v1/dunning/profiles/{profile_id}/assignments \
>
  -H "Authorization: Bearer sk_live_..." \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "resource_type": "price",
>
    "resource_id": "prc_live_abc123"
>
  }'

Assign to a cycle length

Target all subscriptions with a specific billing cycle category:

$
curl -X POST https://api.paymentkit.com/v1/dunning/profiles/{profile_id}/assignments \
>
  -H "Authorization: Bearer sk_live_..." \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "resource_type": "cycle_length",
>
    "resource_id": "monthly"
>
  }'

Valid cycle lengths: daily, short, medium, long

List assignments

$
curl https://api.paymentkit.com/v1/dunning/profiles/{profile_id}/assignments \
>
  -H "Authorization: Bearer sk_live_..."

Delete an assignment

$
curl -X DELETE https://api.paymentkit.com/v1/dunning/profiles/{profile_id}/assignments/{assignment_id} \
>
  -H "Authorization: Bearer sk_live_..."

Profile snapshots

When a dunning cycle starts, PaymentKit captures a snapshot of the assigned profile’s settings. This snapshot is immutable for the duration of the dunning cycle.

This ensures predictable behavior:

• Updating max_retries from 8 to 5 won’t suddenly cut short an in-progress cycle
• Archiving a profile won’t disrupt active dunning cycles using it
• New dunning cycles always get the latest profile settings

The snapshot is stored in the dunning state and includes all profile fields:

1
{
2
  "profile_snapshot": {
3
    "profile_id": "dp_live_abc123",
4
    "profile_name": "Premium Customers",
5
    "max_retries": 12,
6
    "retry_interval_hours": 72,
7
    "termination_action": "leave_active",
8
    "invoice_status_on_failure": "leave_open",
9
    "enable_emails": true,
10
    "email_map": [...]
11
  }
12
}

Best practices