---
title: "Checkout Number"
method: POST
path: "/v1/numbers/checkout"
tags: ["Phone Provisioning", "Phone Provisioning"]
---

# Checkout Number

`POST /v1/numbers/checkout`

## Request

- Base URL: `https://api.call2me.app`
- URL: `https://api.call2me.app/v1/numbers/checkout`
- Auth: HTTP bearer

Create a Paddle checkout session for buying a phone number.

Flow for trial users (no paid top-up yet):
  1. Validate the number is still available on Telnyx.
  2. Create a pending_number_purchases row (soft lock, 30 min TTL).
  3. Open Paddle checkout with custom_data = {intent: 'BUY_NUMBER', pending_id}.
  4. Webhook fires on payment → we order from Telnyx & bind to the user.

Paid users should just use /purchase directly — this endpoint is explicitly
for the first-time/no-balance path.

## Request body

- CheckoutRequest
  - `phone_number` string, required: E.164 format
  - `agent_id` string, nullable: Agent to bind after purchase
  - `provider` string, nullable: telnyx | twilio (auto by country if omitted)

## Response `200`

Successful Response

- SrcRoutersV1PhoneProvisioningCheckoutResponse
  - `pending_id` string, required
  - `paddle_transaction_id` string, required
  - `upfront_usd` number, required
  - `monthly_usd` number, required
  - `expires_at` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/call2me/apis/call2me-api.md) · [All operations](https://skmtc.dev/call2me/apis/call2me-api/llms.txt) · [OpenAPI document](https://skmtc.dev/call2me/apis/call2me-api/revisions/3951f9b7e47d?raw)