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

Profile types

PaymentKit supports two types of dunning profiles with fundamentally different retry strategies:

Adaptive profiles (system defaults)

Adaptive profiles are system-managed and use intelligent retry scheduling that responds to decline types:

Intelligent retry behaviors

Adaptive profiles automatically inject additional retry attempts based on decline type:

The renewal wall — 1 hour before the billing cycle ends — is not one of these behaviors. It applies to every profile, adaptive and custom alike. See The renewal wall below.

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

Custom profiles

Custom profiles give you full control over retry behavior with fixed, predictable intervals. Create custom profiles when you need deterministic retry schedules or have specific compliance requirements.

What custom profiles provide:

• Full 15-retry ceiling (the network maximum)
• Fixed retry_interval_hours for all retry attempts
• Consistent, predictable timing between retries

What custom profiles don’t include:

• No technical retries (TECHNICAL declines use standard interval)
• No liquidity retries (SOFT declines use standard interval)

Create a profile

$
curl -X POST https://app.paymentkit.com/api/{account_id}/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://app.paymentkit.com/api/{account_id}/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://app.paymentkit.com/api/{account_id}/dunning/profiles/{profile_id} \
>
  -H "Authorization: Bearer sk_live_..."

The renewal wall

Every dunning cycle for a subscription invoice ends at the renewal wall: 1 hour before the current billing period ends. The wall keeps a cycle’s retries from stacking into the next billing period.

The wall is a system constraint and cannot be overridden by profile configuration. It applies identically to adaptive and custom profiles:

• No retry is ever scheduled at or after the wall.
• The last attempt lands on the wall. If your configured interval would place the next retry past the wall, that attempt is pulled back to the wall and runs there as the final retry.
• Once the wall has passed, dunning ends and your configured failure handling is applied.

One-time invoices have no next billing period and therefore no renewal wall. Their retries are bounded by the one-time retry window instead.

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 3-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://app.paymentkit.com/api/{account_id}/dunning/profiles/{profile_id}/assignments \
>
  -H "Authorization: Bearer sk_live_..." \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "resource_type": "price",
>
    "resource_id": "price_prod_abc123"
>
  }'

Assign to a cycle length

Target all subscriptions with a specific billing cycle category:

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

Valid cycle lengths: daily, short, standard, long

List assignments

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

Delete an assignment

$
curl -X DELETE https://app.paymentkit.com/api/{account_id}/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
    "schema_version": 2,
4
    "profile_id": "dp_prod_abc123",
5
    "profile_name": "Premium Customers",
6
    "max_retries": 12,
7
    "retry_interval_hours": 72,
8
    "termination_action": "leave_active",
9
    "invoice_status_on_failure": "leave_open",
10
    "enable_emails": true,
11
    "email_map": [...],
12
    "is_system_default": false
13
  }
14
}

Best practices