Use this endpoint to simulate subscription billing events while your request is in test mode.

Simulation helps you test reminders, due charges, retries, failed card payments, manual invoices, and overdue reminders without waiting for the normal billing schedule.

-H "x-api-key: your_secret_key"
-H "x-kyshi-mode: test"

POST {{host}}/v1/subscriptions/{id}/simulate

Path Parameters

Field	Data Type	Required	Description
id	string	Yes	Subscription ID or code.

Request Body

Field	Data Type	Required	Description
event	string	Yes	Simulation event to trigger.
redirectUrl	string	No	Redirect URL used when the simulation creates a payment or recovery checkout flow.

Events

Event	Use For	Description
`pre_charge_reminder`	Card subscriptions	Queues the pre-charge reminder email for a card subscription.
`due_charge`	Card or manual subscriptions	Moves the subscription due time to now and runs the due charge flow.
`payment_failed`	Card subscriptions	Simulates a failed card renewal and queues the payment failure recovery flow.
`retry_due`	Card or manual subscriptions	Moves retry time to now and runs the retry charge flow.
`retry_failed_cancel`	Card subscriptions	Simulates a final failed card retry that can cancel the subscription.
`manual_invoice_due`	Manual subscriptions	Creates or retrieves the invoice checkout URL and queues the invoice due reminder.
`manual_overdue_reminder`	Manual subscriptions	Marks the invoice as overdue and queues the overdue reminder.

Manual subscriptions are subscriptions created with payment methods such as bank_transfer, bank, or mobile_money.

{
  "event": "manual_invoice_due",
  "redirectUrl": "https://merchant.example.com/subscriptions/return"
}

{
  "status": true,
  "simulated": "manual_invoice_due",
  "subscriptionId": "0f7c6ad8-64a2-4503-b1be-3c56de000001",
  "invoice": {
    "id": "9af78530-7728-4c7f-bca0-b54ec3000001",
    "code": "INV_abc123",
    "status": "PENDING"
  },
  "paymentUrl": "https://checkout.example.com/pay/abc123",
  "reminder": "manual_invoice_due"
}

Notes

This endpoint only works in test mode.
Use card simulation events for card subscriptions.
Use manual invoice events for manual subscriptions.