> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slickerhq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Launch guide

> Plan, build, test, and roll out a custom billing integration

Use this guide when your billing system is custom-built or heavily customized. It turns the custom integration pieces into an end-to-end launch plan: data sync, recovery decisions, webhook handling, historical data, testing, rollout, and monitoring.

For endpoint details, see the [custom API reference](/integrations/billing/custom/api/overview). For the overall integration model, start with the [custom billing overview](/integrations/billing/custom/overview).

## What You Are Building

A custom billing integration has four core parts:

1. **Data sync**: Send subscriptions, invoices, and transaction attempts to Slicker.
2. **Recovery decision path**: Receive Slicker's retry and dunning recommendations by webhook, or query them from the API.
3. **Historical backfill**: Send enough past billing and payment activity for Slicker to understand your recovery patterns.
4. **Operational monitoring**: Track data freshness, webhook delivery, recovery action execution, and mismatches against your billing system.

<Info>
  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.
</Info>

## 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.        |

The most important rule is stable identity. Use the same external IDs for historical backfill and future live events so Slicker can connect invoices, transactions, and recovery outcomes over time.

## Phase 2: Build the Data Sync

Send data in dependency order when possible:

<Steps>
  <Step title="Sync subscriptions">
    Send the active and historical subscriptions that invoices belong to. Include customer, plan, currency, billing cycle, status, and lifecycle timestamps when available.
  </Step>

  <Step title="Sync invoices">
    Send invoices with their current collection state, amount, currency, due date, subscription ID, customer ID, and timestamps.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Keep records fresh">
    Send updates when invoice status, subscription status, transaction outcome, customer details, or payment-method context changes.
  </Step>
</Steps>

### 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](/integrations/billing/custom/api/overview#request-limits).
* 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 `2xx` response 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-`2xx` responses or processing failures.

See [Webhook Implementation](/integrations/billing/custom/api/webhook) for payload structure and event-specific references.

### 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](/integrations/billing/custom/api/slicker/list_recovery_actions) for endpoint details.

## Phase 4: Backfill Historical Data

Historical data helps Slicker learn payment behavior before live recovery begins.

Recommended approach:

1. Select a backfill window with the Slicker integration team. Six to twelve months is often useful when available.
2. Backfill subscriptions first, then invoices, then transactions.
3. Preserve original timestamps and final states.
4. Include recovered, unrecovered, refunded, voided, and still-open invoices when available.
5. Reconcile counts against your billing system before launch.

Useful reconciliation checks:

| 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:

<Steps>
  <Step title="Shadow mode">
    Send live data and inspect recovery recommendations without executing automated retries from Slicker.
  </Step>

  <Step title="Limited cohort">
    Enable recovery execution for a small, representative cohort such as one business entity, country, product, or plan family.
  </Step>

  <Step title="Measure and reconcile">
    Compare Slicker recovery actions, billing-system retries, invoice outcomes, and customer impact.
  </Step>

  <Step title="Expand">
    Increase the rollout scope once data freshness, webhook success, and recovery results are stable.
  </Step>
</Steps>

## 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.

If any metric regresses, pause expansion and review the affected payloads with the Slicker integration team.

## Next Steps

* Review endpoint details in the [custom API reference](/integrations/billing/custom/api/overview).
* Implement webhook handling with [Webhook Implementation](/integrations/billing/custom/api/webhook).
* Add your payment processors from the [payment provider integrations](/integrations/overview#payment-providers).