Public REST/JSON reference

Payment Recovery API

Recover the revenue you'd otherwise lose to failed card payments. List failed payments, retry one explicitly, run a multi-step dunning sequence (configurable per workspace), and pull recovery analytics — by decline code, by retry timing, and as a date-bounded report. Part of the Logic Igniter SaaS Growth & Retention bundle.

Access boundary

These examples describe public API calls only. Use the service output to review, score, summarize, analyze, or recommend; do not treat the API reference as permission for an assistant to write, send, publish, charge, schedule, notify, delete, or modify records.

Base URL

https://api.logicigniter.com

Auth

Authorization: Bearer YOUR_API_KEY

Version

OpenAPI 3.0.3 · 1.0.0

Spec

/api-specs/paymentrecovery.json

Operations rendered

Response models rendered

GET/api/v1/paymentrecovery/customers

List customers

Public REST/JSON operation

This operation is documented for direct API evaluation. It describes the public payload and response contract only; assistant/MCP usage remains read only and is covered in the MCP guide.

Parameters

Name	In	Type	Notes
`page_size`	query	integer
`page_token`	query	string

Request example

Replace placeholders with your confirmed access key and your own business data.

curl -X GET "https://api.logicigniter.com/api/v1/paymentrecovery/customers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Responses

200CustomersResponse

Page of customers

401Error

Missing or invalid API key.

POST/api/v1/paymentrecovery/customers

Provision a customer

Public REST/JSON operation

This operation is documented for direct API evaluation. It describes the public payload and response contract only; assistant/MCP usage remains read only and is covered in the MCP guide.

Request body (required)

Schema: CreateCustomerRequest

Sample JSON payload for evaluation.

{
  "email": "[email protected]",
  "name": "Example Inc."
}

Request example

Replace placeholders with your confirmed access key and your own business data.

curl -X POST "https://api.logicigniter.com/api/v1/paymentrecovery/customers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","name":"Example Inc."}'

Responses

201Customer

Customer created or returned

400Error

Invalid email or missing name

401Error

Missing or invalid API key.

GET/api/v1/paymentrecovery/customers/{id}

Get a customer by id

Public REST/JSON operation

This operation is documented for direct API evaluation. It describes the public payload and response contract only; assistant/MCP usage remains read only and is covered in the MCP guide.

Parameters

Name	In	Type	Notes
`id`required	path	string (uuid)

Request example

Replace placeholders with your confirmed access key and your own business data.

curl -X GET "https://api.logicigniter.com/api/v1/paymentrecovery/customers/:id" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Responses

200Customer

Customer record

401Error

Missing or invalid API key.

404Error

Customer not found

PUT/api/v1/paymentrecovery/customers/{id}

Update a customer

Public REST/JSON operation

This operation is documented for direct API evaluation. It describes the public payload and response contract only; assistant/MCP usage remains read only and is covered in the MCP guide.

Parameters

Name	In	Type	Notes
`id`required	path	string (uuid)

Request body (required)

Schema: UpdateCustomerRequest

Request example

Replace placeholders with your confirmed access key and your own business data.

curl -X PUT "https://api.logicigniter.com/api/v1/paymentrecovery/customers/:id" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{}'

Responses

200Customer

Updated customer

400Error

Invalid update

401Error

Missing or invalid API key.

404Error

Customer not found

GET/api/v1/paymentrecovery/failed

List failed payments

Paginated list of failed card payments with their amount (cents), decline_code, and recovery status. Status: ACTIVE (still attempting recovery), RECOVERED (a retry succeeded), CHURNED (gave up).

Public REST/JSON operation

This operation is documented for direct API evaluation. It describes the public payload and response contract only; assistant/MCP usage remains read only and is covered in the MCP guide.

Parameters

Name	In	Type	Notes
`page_size`	query	integer
`page_token`	query	string

Request example

Replace placeholders with your confirmed access key and your own business data.

curl -X GET "https://api.logicigniter.com/api/v1/paymentrecovery/failed" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Responses

200FailedPaymentsResponse

Page of failed payments

401Error

Missing or invalid API key.

POST/api/v1/paymentrecovery/failed/{id}/retry

Retry a failed payment now

Out-of-band retry that bypasses the dunning schedule. Returns a normalized retry outcome so you can route customer follow-up by success state, next retry time, and decline category.

Public REST/JSON operation

This operation is documented for direct API evaluation. It describes the public payload and response contract only; assistant/MCP usage remains read only and is covered in the MCP guide.

Parameters

Name	In	Type	Notes
`id`required	path	string (uuid)

Request example

Replace placeholders with your confirmed access key and your own business data.

curl -X POST "https://api.logicigniter.com/api/v1/paymentrecovery/failed/:id/retry" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Responses

200RetryResult

Retry result

401Error

Missing or invalid API key.

402Error

Endpoint requires an active subscription. Free tier covers failed-payment listing + recovery rate analytics; paid plans unlock retries, dunning sequencing, and date-bounded reports.

404Error

Payment not found

POST/api/v1/paymentrecovery/failed/{id}/dunning/start

Trigger the dunning sequence

Starts the configured DunningSequence for the customer attached to the failed payment. Typical sequence: day 0 friendly reminder → day 3 update payment method → day 7 final notice. Steps configurable via PUT /dunning/config.

Public REST/JSON operation

This operation is documented for direct API evaluation. It describes the public payload and response contract only; assistant/MCP usage remains read only and is covered in the MCP guide.

Parameters

Name	In	Type	Notes
`id`required	path	string (uuid)

Request example

Replace placeholders with your confirmed access key and your own business data.

curl -X POST "https://api.logicigniter.com/api/v1/paymentrecovery/failed/:id/dunning/start" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Responses

200TriggerResult

Sequence started

401Error

Missing or invalid API key.

402Error

Endpoint requires an active subscription. Free tier covers failed-payment listing + recovery rate analytics; paid plans unlock retries, dunning sequencing, and date-bounded reports.

404Error

Payment not found

POST/api/v1/paymentrecovery/failed/{id}/dunning/pause

Pause dunning for a customer

Useful when a customer has reached out with context (e.g. "renewing card next week") and shouldn't get the next dunning email.

Public REST/JSON operation

This operation is documented for direct API evaluation. It describes the public payload and response contract only; assistant/MCP usage remains read only and is covered in the MCP guide.

Parameters

Name	In	Type	Notes
`id`required	path	string (uuid)

Request example

Replace placeholders with your confirmed access key and your own business data.

curl -X POST "https://api.logicigniter.com/api/v1/paymentrecovery/failed/:id/dunning/pause" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Responses

200PauseResult

Paused

401Error

Missing or invalid API key.

404Error

Failed payment not found

GET/api/v1/paymentrecovery/failed/{id}/dunning/status

Get dunning status for the customer attached to a failed payment

Public REST/JSON operation

This operation is documented for direct API evaluation. It describes the public payload and response contract only; assistant/MCP usage remains read only and is covered in the MCP guide.

Parameters

Name	In	Type	Notes
`id`required	path	string (uuid)

Request example

Replace placeholders with your confirmed access key and your own business data.

curl -X GET "https://api.logicigniter.com/api/v1/paymentrecovery/failed/:id/dunning/status" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Responses

200DunningStatus

Dunning status

401Error

Missing or invalid API key.

404Error

Failed payment not found

PUT/api/v1/paymentrecovery/dunning/config

Configure the dunning sequence

Replace the workspace's dunning sequence with an ordered list of (template, delay_days) steps. Each step's delay_days is measured from the previous step's send.

Public REST/JSON operation

This operation is documented for direct API evaluation. It describes the public payload and response contract only; assistant/MCP usage remains read only and is covered in the MCP guide.

Request body (required)

Schema: ConfigureRequest

Sample JSON payload for evaluation.

{
  "steps": [
    {
      "step": 1,
      "template": "friendly-reminder",
      "delay_days": 0
    },
    {
      "step": 2,
      "template": "update-payment-method",
      "delay_days": 3
    },
    {
      "step": 3,
      "template": "final-notice",
      "delay_days": 4
    }
  ]
}

Request example

Replace placeholders with your confirmed access key and your own business data.

curl -X PUT "https://api.logicigniter.com/api/v1/paymentrecovery/dunning/config" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"steps":[{"step":1,"template":"friendly-reminder","delay_days":0},{"step":2,"template":"update-payment-method","delay_days":3},{"step":3,"template":"final-notice","delay_days":4}]}'

Responses

200DunningConfig

Updated config

400Error

Empty steps or unknown template name

401Error

Missing or invalid API key.

402Error

Endpoint requires an active subscription. Free tier covers failed-payment listing + recovery rate analytics; paid plans unlock retries, dunning sequencing, and date-bounded reports.

GET/api/v1/paymentrecovery/analytics/recovery-rate

Recovery rate over a date range

Total failed, total recovered, recovery_rate (0–1), and revenue_recovered_cents (the dollar number you take to the board).

Public REST/JSON operation

This operation is documented for direct API evaluation. It describes the public payload and response contract only; assistant/MCP usage remains read only and is covered in the MCP guide.

Parameters

Name	In	Type	Notes
`start_date`	query	string (date-time)
`end_date`	query	string (date-time)

Request example

Replace placeholders with your confirmed access key and your own business data.

curl -X GET "https://api.logicigniter.com/api/v1/paymentrecovery/analytics/recovery-rate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Responses

200RecoveryStats

Recovery stats

401Error

Missing or invalid API key.

GET/api/v1/paymentrecovery/analytics/decline-breakdown

Breakdown by decline code

Per-decline-code stats: total_count, recovery_count, recovery_rate. Useful for spotting which processor decline codes recover well (insufficient_funds → 80%) vs poorly (card_velocity_exceeded → 5%).

Public REST/JSON operation

This operation is documented for direct API evaluation. It describes the public payload and response contract only; assistant/MCP usage remains read only and is covered in the MCP guide.

Request example

Replace placeholders with your confirmed access key and your own business data.

curl -X GET "https://api.logicigniter.com/api/v1/paymentrecovery/analytics/decline-breakdown" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Responses

200DeclineBreakdown

Decline-code breakdown

401Error

Missing or invalid API key.

GET/api/v1/paymentrecovery/analytics/retry-rates

Retry-timing success rates

Success rate per timing bucket (e.g. "0-1d", "1-3d", "3-7d", "7-14d"). Use to tune dunning step delays — pick the bucket with the highest success rate as the optimal first retry.

Public REST/JSON operation

This operation is documented for direct API evaluation. It describes the public payload and response contract only; assistant/MCP usage remains read only and is covered in the MCP guide.

Request example

Replace placeholders with your confirmed access key and your own business data.

curl -X GET "https://api.logicigniter.com/api/v1/paymentrecovery/analytics/retry-rates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Responses

200RetryRates

Retry rates

401Error

Missing or invalid API key.

GET/api/v1/paymentrecovery/analytics/report

Date-bounded recovery report

Aggregate report: total_failed_cents, total_recovered_cents, recovery_rate, churned_count.

Public REST/JSON operation

This operation is documented for direct API evaluation. It describes the public payload and response contract only; assistant/MCP usage remains read only and is covered in the MCP guide.

Parameters

Name	In	Type	Notes
`start_date`	query	string (date-time)
`end_date`	query	string (date-time)

Request example

Replace placeholders with your confirmed access key and your own business data.

curl -X GET "https://api.logicigniter.com/api/v1/paymentrecovery/analytics/report" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Responses

200RecoveryReport

Recovery report

401Error

Missing or invalid API key.

402Error

Endpoint requires an active subscription. Free tier covers failed-payment listing + recovery rate analytics; paid plans unlock retries, dunning sequencing, and date-bounded reports.

Data models

Error

Field	Type	Notes
`error`required	string

FailedPaymentStatus

FailedPayment

Field	Type	Notes
`amount_cents`	integer (int64)
`decline_code`	string
`status`	FailedPaymentStatus
`failed_at`	string (date-time)

FailedPaymentsResponse

Field	Type	Notes
`items`	array<FailedPayment>
`next_page_token`	string
`total_count`	integer

RetryResult

Field	Type	Notes
`id`	string (uuid)
`success`	boolean
`message`	string
`scheduled_at`	string (date-time)

TriggerResult

Field	Type	Notes
`id`	string (uuid)
`success`	boolean

PauseResult

Field	Type	Notes
`id`	string (uuid)
`success`	boolean

DunningStatus

Field	Type	Notes
`id`	string (uuid)
`customer_id`	string (uuid)
`current_step`	integer
`paused`	boolean
`started_at`	string (date-time)

DunningStep

Field	Type	Notes
`step`required	integer
`template`required	string
`delay_days`	integer

ConfigureRequest

Field	Type	Notes
`steps`required	array<DunningStep>

DunningConfig

Field	Type	Notes
`id`	string (uuid)
`steps`	array<DunningStep>

RecoveryStats

Field	Type	Notes
`id`	string (uuid)
`total_failed`	integer
`total_recovered`	integer
`recovery_rate`	number (double)
`revenue_recovered_cents`	integer (int64)

DeclineCodeStat

Field	Type	Notes
`decline_code`	string
`total_count`	integer
`recovery_count`	integer
`recovery_rate`	number (double)

DeclineBreakdown

Field	Type	Notes
`id`	string (uuid)
`codes`	array<DeclineCodeStat>

RetryTimingRate

Field	Type	Notes
`timing_bucket`	string
`success_rate`	number (double)
`sample_size`	integer

RetryRates

Field	Type	Notes
`id`	string (uuid)
`rates`	array<RetryTimingRate>

RecoveryReport

Field	Type	Notes
`id`	string (uuid)
`total_failed_cents`	integer (int64)
`total_recovered_cents`	integer (int64)
`recovery_rate`	number (double)
`churned_count`	integer

CreateCustomerRequest

Field	Type	Notes
`email`required	string (email)
`name`required	string

UpdateCustomerRequest

Field	Type	Notes
`email`	string (email)
`name`	string

Customer

Field	Type	Notes
`id`	string (uuid)
`email`	string (email)
`name`	string
`created_at`	string (date-time)

CustomersResponse

Field	Type	Notes
`items`	array<Customer>
`next_page_token`	string
`total_count`	integer