What You Are Building
A custom billing integration has four core parts:- Data sync: Send subscriptions, invoices, and transaction attempts to Slicker.
- Recovery decision path: Receive Slicker’s retry and dunning recommendations by webhook, or query them from the API.
- Historical backfill: Send enough past billing and payment activity for Slicker to understand your recovery patterns.
- Operational monitoring: Track data freshness, webhook delivery, recovery action execution, and mismatches against your billing system.
Connect payment processor integrations whenever possible. Processor data gives Slicker richer authorization outcomes, gateway error codes, scheme response codes, issuer details, and payment-method metadata.
Phase 1: Confirm the Integration Shape
Before writing code, agree the following details with your Slicker integration team:| Decision | What to Confirm |
|---|---|
| Canonical IDs | Which IDs uniquely identify customers, subscriptions, invoices, and transactions in your billing system. |
| Sync model | Whether you will send events in near real time, run scheduled batch syncs, or use both. |
| Payment source of truth | Which system owns final payment state and transaction outcomes. |
| Recovery execution | Whether your system will execute retries from webhooks, poll recovery actions, or use a hybrid model. |
| Dunning ownership | Which system sends recovery emails and when collection should pause or complete. |
| Historical window | How many months of invoices, subscriptions, and transactions to backfill before launch. |
| Rollout cohort | Whether launch starts with all traffic or a subset by product, country, plan, or business entity. |
Phase 2: Build the Data Sync
Send data in dependency order when possible:Sync subscriptions
Send the active and historical subscriptions that invoices belong to. Include customer, plan, currency, billing cycle, status, and lifecycle timestamps when available.
Sync invoices
Send invoices with their current collection state, amount, currency, due date, subscription ID, customer ID, and timestamps.
Sync transactions
Send each payment attempt, including failed attempts and retries. A transaction is one authorization attempt; multiple retries for the same invoice should be sent as separate transactions.
Sync Rules
- Treat API requests as idempotent from your side: retry failed requests safely and keep your external IDs stable.
- Preserve original event timestamps. Do not replace historical timestamps with the sync time.
- Send failed and successful payment attempts. Recovery analysis needs both sides of the funnel.
- Keep batch sizes within API limits. See the custom API overview.
- Log every request ID, response status, and failed payload reference so issues can be replayed.
Phase 3: Implement Recovery Actions
Slicker can tell your system when to retry a payment, when to request a payment-method change, when to pause collection, and when dunning should complete.Webhook Path
If you use webhooks, implement one HTTPS endpoint that accepts Slicker events:- Authenticate requests with the agreed bearer token or basic auth credentials.
- Return a
2xxresponse quickly after validating and queuing the event. - Process events asynchronously when retry execution may take longer than a few seconds.
- Deduplicate by webhook event ID.
- Store the original payload for audit and replay.
- Alert on repeated non-
2xxresponses or processing failures.
Polling Path
If you poll recovery actions, run the poller frequently enough to act before recommended retry windows pass. Store the last successful poll time, deduplicate actions by ID, and alert if polling stops or returns repeated errors. See List recovery actions for endpoint details.Phase 4: Backfill Historical Data
Historical data helps Slicker learn payment behavior before live recovery begins. Recommended approach:- Select a backfill window with the Slicker integration team. Six to twelve months is often useful when available.
- Backfill subscriptions first, then invoices, then transactions.
- Preserve original timestamps and final states.
- Include recovered, unrecovered, refunded, voided, and still-open invoices when available.
- Reconcile counts against your billing system before launch.
| Check | Expected Result |
|---|---|
| Invoice count by month | Matches your billing system within the agreed scope. |
| Transaction count by month | Matches payment attempts, not just invoices. |
| Failed transaction count | Includes initial failures and failed retries. |
| Recovery outcomes | Paid-after-failure invoices are distinguishable from first-attempt successes. |
| Currency and country coverage | High-volume segments are present and mapped correctly. |
Phase 5: Test Before Launch
Run these tests in a non-production or controlled rollout environment before enabling full recovery automation:| Scenario | What to Verify |
|---|---|
| Successful first-attempt invoice | Invoice and transaction sync without entering recovery. |
| Failed invoice | Failed transaction creates the expected recovery context. |
| Retry succeeds | The successful retry is sent as a new transaction and closes the invoice. |
| Retry fails | The failed retry is sent as a new transaction and recovery remains open. |
| Payment-method change needed | Your system can route the customer to the correct update flow. |
| Pause collection event | Your billing system pauses its own collection logic when instructed. |
| Complete dunning event | Your billing system stops dunning for the invoice when instructed. |
| Duplicate webhook delivery | Processing is idempotent and does not double-retry. |
| Webhook delivery failure | Slicker retries delivery and your alerts fire. |
| API failure | Your sync retries with backoff and preserves failed payloads for replay. |
Launch Checklist
Before launch, confirm:- API credentials are stored securely and not exposed in client-side code.
- Subscriptions, invoices, and transactions are syncing successfully.
- Historical data has been reconciled for the agreed launch scope.
- Webhook authentication, idempotency, and alerting are live.
- Recovery actions are being executed in the correct billing-system environment.
- Payment provider integrations are connected where applicable.
- Your team has an owner for integration incidents.
- You have a rollback plan, such as pausing webhook execution or disabling the rollout cohort.
Rollout Plan
Start with visibility before automation:Shadow mode
Send live data and inspect recovery recommendations without executing automated retries from Slicker.
Limited cohort
Enable recovery execution for a small, representative cohort such as one business entity, country, product, or plan family.
Measure and reconcile
Compare Slicker recovery actions, billing-system retries, invoice outcomes, and customer impact.
Monitor After Launch
Track these signals during the first weeks after launch:- API ingestion failures and retry volume.
- Data freshness for invoices, subscriptions, and transactions.
- Webhook delivery success rate and processing latency.
- Recovery action backlog or actions missed after their ideal retry time.
- Invoice recovery rate, failed recovery rate, and recovered amount.
- Differences between Slicker counts and your billing system counts.
Next Steps
- Review endpoint details in the custom API reference.
- Implement webhook handling with Webhook Implementation.
- Add your payment processors from the payment provider integrations.