---
title: "Get purchase history"
method: GET
path: "/v1/purchases/"
tags: ["Purchases"]
---

# Get purchase history

`GET /v1/purchases/`

Returns paginated list of user's purchases with optional status filtering.

**Chronological Ordering.** Purchases are always returned **newest first** (descending by `created_at`).

**Pagination behavior**
- Results are consistent during session (no duplicates or missing items when paginating).
- `has_next: true` indicates more pages available.
- Maximum `page_size` is 50 items.

**Filtering.** Combine `status` filter with pagination for subset queries (e.g., all successful purchases).

## Query parameters

- `status` 'PENDING' | 'SUCCESS' | 'ERROR' | 'REFUND' — **Purchase Status Lifecycle.** `PENDING` (initial) → `SUCCESS` (after code request) or `ERROR` (provider failure). Any status can transition to `REFUND` via admin action. **Important.** Status is immutable once set to `SUCCESS`, `ERROR`, or `REFUND`. **Filter options** - `PENDING` - code not requested. - `SUCCESS` - code ready. - `ERROR` - provider failed. - `REFUND` - money returned.
- `page` integer, required — Page number.
- `page_size` integer, required — Number of items per page.

## Response `200`

Successful response.

- object — Successful response.
  - `items` object[], required
    - `id` integer, required — Unique purchase identifier.
    - `country_code` string, required — ISO 3166-1 alpha-2 country code.
    - `display_name` object, required
      - `ru` string, required — Name in Russian.
      - `en` string, required — Name in English.
    - `phone_number` string, nullable, required — **E.164 International Format.** Phone number with country code prefix (e.g., `+12025550123` for US, `+79991234567` for Russia). **Usage.** This is your Telegram account login. Use it with `verification.code` and `verification.password` to access the account.
    - `price` object, required — **Final Price After Discount.** The actual amount deducted from your balance, with your personal discount already applied. **To see pricing breakdown before purchase.** Check `GET /accounts/:country_code` which shows both discounted price and original `base_price`. **Discount eligibility.** Based on your total successful purchase count. Higher volume = bigger discounts.
      - `amount` string, required — Monetary amount as a string with up to 2 decimal places.
      - `currency_code` string, required — ISO 4217 currency code.
    - `status` 'PENDING' | 'SUCCESS' | 'ERROR' | 'REFUND', required — **Purchase Status Lifecycle.** `PENDING` (initial) → `SUCCESS` (after code request) or `ERROR` (provider failure). Any status can transition to `REFUND` via admin action. **Important.** Status is immutable once set to `SUCCESS`, `ERROR`, or `REFUND`. **Filter options** - `PENDING` - code not requested. - `SUCCESS` - code ready. - `ERROR` - provider failed. - `REFUND` - money returned.
    - `purchase_type` 'SINGLE' | 'BULK' | 'ADMIN', required — Type of purchase: SINGLE (regular), BULK (batch purchase), ADMIN (admin deduction)
    - `verification` object, nullable, required — **Verification Credentials.** Login credentials for the purchased Telegram account. Initially `null` after purchase creation. **Availability.** Populated after calling `POST /purchases/:id/request-code`. Once received, credentials are permanent and cannot be re-requested. **Security.** Verification data is only visible to the purchase owner.
      - `code` string, required — Verification code for account.
      - `password` string, required — Account password.
      - `received_at` string, required — **Code Retrieval Timestamp.** Marks when verification code was successfully fetched from the provider (not when purchase was created). **Example timeline.** - `created_at`: `2024-11-19T10:00:00Z` (purchase created) - `received_at`: `2024-11-19T10:05:02Z` (code requested 5 minutes later) **Note.** These timestamps may be identical if code is requested immediately after purchase.
    - `created_at` string, required — Purchase creation time in ISO 8601 format (UTC).
  - `pagination` object, required
    - `current_page` integer, required — Current page number.
    - `page_size` integer, required — Number of items per page.
    - `total_items` integer, required — Total number of items.
    - `total_pages` integer, required — Total number of pages.
    - `has_next` boolean, required — Whether there is a next page.
    - `has_previous` boolean, required — Whether there is a previous page.

---

[API](https://skmtc.net/getmytg/apis/get-my-tg-api.md) · [All operations](https://skmtc.net/getmytg/apis/get-my-tg-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getmytg/get-my-tg-api/versions/30f975c0d1e6/schema)