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

# Unified GMT purchase history

`GET /v1/purchases/history`

## Request

- Base URL: `https://api.getmytg.com`
- URL: `https://api.getmytg.com/v1/purchases/history`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Own purchases and wholesale orders sorted and paginated together. Wholesale accounts appear only inside their order. Search matches country names in Russian or English, phone fragments (including accounts inside wholesale orders), and order ID fragments. Pending single purchases are listed separately.

## Query parameters

- `include` 'code_request': Opt in to durable purchase status and current code_request. Without this option, legacy response fields and status semantics are preserved.
- `page` integer: Page number.
- `page_size` integer: Number of items per page.
- `sort` 'date_asc' | 'date_desc': Sort purchases by creation date
- `status` 'PENDING' | 'SUCCESS' | 'ERROR' | 'REFUND' | 'EXPIRED': Legacy status projection: PENDING while the current retail code request is pending or failed, SUCCESS when its code is available. With include=code_request, status describes the durable purchase; code_request describes the current request. REFUND and access rules still apply.
- `phone_number` string: Filter purchases by phone number fragment (partial match). Example: '123' matches '+71234567890'.
- `search` string: Russian or English country name fragment, phone number fragment, or order ID fragment. Use instead of phone_number.

## Response `200`

Response for status 200

- object
  - `items` union[], required
    - union
      - object
        - `code_request` object, nullable: Current code request, separate from historical verification. Read-only polling never starts a cycle. / Текущий запрос отдельно от сохранённого кода; чтение не запускает цикл.
          - `status` 'not_requested' | 'pending' | 'success' | 'failed', required
          - `requested_at` string, nullable, required
          - `expires_at` string, nullable, required
          - `attempt` integer, required
          - `next_attempt_at` string, nullable, required
          - `attempt_finishes_at` string, nullable, required
        - `id` integer, required: Unique purchase identifier.
        - `country_code` string, required: ISO 3166-1 alpha-2 country code.
        - `emoji` string, required: Country flag emoji.
        - `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' | 'EXPIRED', required: Legacy status projection: PENDING while the current retail code request is pending or failed, SUCCESS when its code is available. With include=code_request, status describes the durable purchase; code_request describes the current request. REFUND and access rules still apply.
        - `purchase_type` 'SINGLE' | 'BULK' | 'ADMIN', required: Type of purchase: SINGLE (regular), BULK (batch purchase), ADMIN (admin deduction)
        - `purchase_source` 'BOT' | 'WEB' | 'API', required: Purchase channel: BOT (Telegram), WEB (site JWT), API (x-api-key)
        - `verification` object, nullable, required: Current verification credentials, or null while waiting/after failure. A completed request returns its stored result. With include=code_request, the current request state is available separately in code_request. Previous verification credentials are internal and are not returned.
          - `code` string, required: Verification code for account.
          - `password` string, nullable, required: Account password.
          - `received_at` string, required: Legacy timestamp retained for compatibility: the purchase creation time. It does not identify a code request.
        - `created_at` string, required: Purchase creation time in ISO 8601 format (UTC).
        - `kind` 'purchase', required
      - object
        - `id` integer, required: Unique purchase identifier.
        - `country_code` string, required: ISO 3166-1 alpha-2 country code.
        - `status` 'PENDING' | 'SUCCESS' | 'ERROR' | 'REFUND' | 'EXPIRED', 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.
        - `created_at` string, required: Purchase creation time in ISO 8601 format (UTC).
        - `kind` 'bulk', required
        - `refunded_quantity` integer, required: Number of delivered accounts subsequently refunded. Any positive value revokes the entire original archive. Undelivered accounts compensated during export are excluded.
        - `quantity` integer, required
        - `price` object, nullable, required
          - `amount` string, required: Monetary amount as a string with up to 2 decimal places.
          - `currency_code` string, required: ISO 4217 currency code.
  - `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.

## Other responses

- `400`: Response for status 400
- `401`: Response for status 401
- `403`: Response for status 403
- `429`: Response for status 429
- `500`: Internal server error
- `503`: Service unavailable

## Changes

- **2026-11-13** `875ef52a8fe6`: 1 breaking, 2 info
  - removed the required property `items/items/oneOf[subschema #1]/code_page` from the response with the `200` status
  - added the new optional `query` request parameter `include`
  - added the optional property `items/items/oneOf[subschema #1]/code_request` to the response with the `200` status
- **2026-11-10** `070a156a08a6`: 1 info
  - added the required property `items/items/oneOf[subschema #1]/code_page/brand_name` to the response with the `200` status
- **2026-11-07** `6cc5398ec5d4`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/getmytg/apis/get-my-tg-api/changes/v1/purchases/history/get.md)

---

[API](https://skmtc.dev/getmytg/apis/get-my-tg-api.md) - [All operations](https://skmtc.dev/getmytg/apis/get-my-tg-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getmytg/apis/get-my-tg-api/revisions/875ef52a8fe6?raw)