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

# Poll purchase status

> Polls a purchase session for fulfillment and returns the pulled items.

Polls a purchase session created by [`/api/v1/vm/buy/init`](/api-reference/purchase/init). Call this after `buy/init` until the status is fulfilled.

## Request body

<ParamField body="session_id" type="string" required>
  The `session_id` returned by [`/api/v1/vm/buy/init`](/api-reference/purchase/init).
</ParamField>

## Example request

```http theme={"dark"}
POST /api/v1/vm/buy/status
X-API-Key: <your_api_key>
Content-Type: application/json

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

## Response: fulfilled

<ResponseExample>
  ```json 200 theme={"dark"}
  {
    "result": {
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "user_abc123",
      "public_id": "_XKCD",
      "nfts": [
        {
          "id": "9XnY...mint_address",
          "buyback_price": 8.50,
          "mint_address": "9XnY...mint_address",
          "content": {
            "metadata": {
              "name": "Juan Soto RC Auto /25",
              "image": "https://cdn.phygitals.com/cards/soto-rc-auto.png",
              "back_image": "https://cdn.phygitals.com/cards/soto-rc-auto-back.png"
            },
            "links": {
              "image": "https://cdn.phygitals.com/cards/soto-rc-auto.png",
              "back_image": "https://cdn.phygitals.com/cards/soto-rc-auto-back.png"
            }
          }
        }
      ],
      "tx_hash": "transaction_hash"
    }
  }
  ```
</ResponseExample>

<ResponseField name="result.session_id" type="string">
  Echoes back the `session_id` from [`/api/v1/vm/buy/init`](/api-reference/purchase/init).
</ResponseField>

<ResponseField name="result.user_id" type="string">
  Echoes back the `user_id` from [`/api/v1/vm/buy/init`](/api-reference/purchase/init).
</ResponseField>

<ResponseField name="result.public_id" type="string">
  Short shareable transaction identifier (for example `_XKCD`).
</ResponseField>

<ResponseField name="result.nfts[].id" type="string">
  Item identifier. Used as `item_id` in [`/api/v1/vm/buyback`](/api-reference/sellback). Equal to `mint_address` for on-chain items.
</ResponseField>

<ResponseField name="result.nfts[].mint_address" type="string | null">
  On-chain mint address for the item. `null` for items that haven't been minted on-chain (in [sandbox](/enterprise-api/sandbox), always `null` for ebay-sourced items).
</ResponseField>

<ResponseField name="result.nfts[].buyback_price" type="number">
  Sellback value in USD.
</ResponseField>

<ResponseField name="result.nfts[].type" type="string">
  Item source. One of: `enft`, `ebay`, `fanatics`, `alt`, `external`.
</ResponseField>

<ResponseField name="result.nfts[].collection_address" type="string | null">
  On-chain collection address.
</ResponseField>

<ResponseField name="result.nfts[].token_standard" type="string | null">
  Token standard for on-chain items.
</ResponseField>

<ResponseField name="result.nfts[].content.metadata" type="object">
  Item metadata (`name`, `image`, `back_image`, `attributes`). Use `metadata.image` as the canonical image URL.
</ResponseField>

<ResponseField name="result.nfts[].content.metadata.back_image" type="string | null">
  CDN URL for the card back image, or `null` when not available.
</ResponseField>

<ResponseField name="result.nfts[].content.links.image" type="string">
  Direct CDN URL for the item image. In [sandbox](/enterprise-api/sandbox), this is **not populated** on `buy/status` responses (it only appears on inventory items). Treat it as a fallback when present.
</ResponseField>

<ResponseField name="result.nfts[].content.links.back_image" type="string | null">
  CDN URL for the card back image. Mirror of `content.metadata.back_image`.
</ResponseField>

<ResponseField name="result.tx_hash" type="string">
  On-chain transaction hash for the mint. In [sandbox](/enterprise-api/sandbox), `tx_hash` is a synthetic identifier of the form `sandbox_<base64url>` and **does not correspond to any on-chain transaction**.
</ResponseField>

See the [item shape reference](/item-shape) for the full canonical item schema.

## Response: pending

```json theme={"dark"}
{
  "status": "pending"
}
```

Returned if the server's internal poll window expires before the order is fulfilled. Wait a few seconds and call again.

<Note>
  **Sandbox:** the `{ "status": "pending" }` response is **never returned**. Sandbox fulfills synchronously inside `buy/init`, so the first `buy/status` call after a successful `buy/init` always returns the fulfilled `{ result: ... }` envelope. Any unknown `session_id` returns `400 { "error": "Transaction failed" }` immediately.
</Note>

## Response: failed

```json theme={"dark"}
{
  "error": "Transaction failed"
}
```

Returned with status `400` when the transaction could not be completed. The purchase should be considered cancelled.