The legacy /v1/charges endpoint is retiring

We're sunsetting the original v1 charges endpoint. It predates idempotency keys, scoped roles, and the structured error format every newer route relies on — and keeping it alive holds those improvements back.

What's changing

Every payment operation now lives under /v2/payments. The good news: this is a path change, not a contract change. The fields you send and receive are identical, so for most integrations the migration is a single search-and-replace.

• POST /v1/charges becomes POST /v2/payments
• GET /v1/charges/:id becomes GET /v2/payments/:id
• The amount, currency, and metadata fields are unchanged.

Migrating a request

Here's a typical charge before and after. The only edit is the URL:

# before — retiring Apr 1, 2026
curl -X POST https://api.acme.dev/v1/charges \
  -d '{ "amount": 4200, "currency": "usd" }'

# after — use this
curl -X POST https://api.acme.dev/v2/payments \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "amount": 4200, "currency": "usd" }'

We recommend adding an Idempotency-Key header while you're in there — v2 honors it to make retries safe, which v1 never did.

The v1 charges reference now shows this banner with a one-click jump to the v2 guide.

How to know you're done

Open Settings → API logs and filter by path. Once you see zero traffic to /v1/charges for a full billing cycle, you're clear. We'll also email the account owner if any v1 traffic appears in the final two weeks before sunset.

“The path-only change meant our migration was one PR and a deploy — under an hour, including tests.”

Questions? Reply to this entry's digest email, or reach the API team in the developer Slack. Read the full v2 payments guide →