---
title: بازپرداخت سفارش — POST /api/v1/orders/{id}/refund | Stard API
url: https://stard-market.ir/docs/reference/orders-refund
markdown: https://stard-market.ir/docs/reference/orders-refund.md
language: fa
updated: 2026-11-18
description: بازپرداخت خودکار سفارشی که هنوز انجامش شروع نشده؛ کل مبلغ به همان کیف پول برمی‌گردد. سفارش انجام‌شده خودکار قابل بازپرداخت نیست (برای آن با پشتیبانی تماس ب
---

# بازپرداخت سفارش

`POST /api/v1/orders/{id}/refund`

> بازپرداخت خودکار سفارشی که هنوز انجامش شروع نشده؛ کل مبلغ به همان کیف پول برمی‌گردد. سفارش انجام‌شده خودکار قابل بازپرداخت نیست (برای آن با پشتیبانی تماس بگیر). برای بوست، اگر سفارش به پنل ارسال شده باشد بازپرداخت پذیرفته نمی‌شود.

## درخواست

| نام | محل | نوع |  | توضیح |
|---|---|---|---|---|
| `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` |
| `id` | path | `string` | الزامی | کد پیگیری سفارش (ord_… یا کد live) |

## نمونه

```bash
curl -X POST "https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/refund" \
  -H "Authorization: Bearer $STARD_API_KEY"
```

```javascript
const res = await fetch("https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/refund", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STARD_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);
```

```typescript
type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } };

const res = await fetch("https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/refund", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STARD_API_KEY}`,
  },
});
if (!res.ok) {
  const { error } = (await res.json()) as StardError;
  throw new Error(`${error.code}: ${error.message} (${error.request_id})`);
}
const data: Record<string, unknown> = await res.json();
```

```python
import os
import requests

r = requests.post(
    "https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/refund",
    headers={
    "Authorization": f"Bearer {os.environ['STARD_API_KEY']}",
    },
    timeout=20,
)
data = r.json()
if r.status_code >= 400:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)
```

```php
<?php
$ch = curl_init("https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/refund");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("STARD_API_KEY"),
  ],
  CURLOPT_TIMEOUT => 20,
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($status >= 400) {
  throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]);
}
print_r($data);
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/refund", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	b, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode, string(b))
}
```

**پاسخ — 200**

```json
{
  "object": "order",
  "id": "ord_test_9pq3kfjbTmRLfMDR",
  "order_id": null,
  "environment": "test",
  "status": "cancelled",
  "raw_status": "cancelled",
  "title": "⭐ 500 استارز برای @username (test)",
  "product_id": null,
  "product_tag": null,
  "type": "stars",
  "quantity": 500,
  "recipient": "@username",
  "amount": {
    "amount": 2249000,
    "currency": "IRT"
  },
  "paid": {
    "amount": 2249000,
    "currency": "IRT"
  },
  "failure_reason": null,
  "metadata": {
    "invoice": "INV-1042"
  },
  "created_at": "2026-10-02T17:43:22Z",
  "updated_at": "2026-10-02T17:43:22Z"
}
```

**هدرهای پاسخ**

```http
content-type: application/json
x-request-id: req_dAlugYNqQS5ouO3hP82I
x-ratelimit-limit: 1000
x-ratelimit-remaining: 996
```

## کاربرد و نکته‌ها

**کی به کار می‌آید؟** وقتی سفارشی را ثبت کرده‌ای ولی هنوز انجامش شروع نشده و می‌خواهی پول برگردد؛ مثلاً یوزرنیم گیرنده اشتباه وارد شده یا مشتری فروشگاهت پشیمان شده است.

1. وضعیت سفارش را با [`GET /orders/{id}`](https://stard-market.ir/docs/reference/orders-get) بگیر؛ فقط سفارشی که انجامش شروع نشده خودکار برمی‌گردد.
2. `POST /orders/{id}/refund` را بزن. پاسخ همان شیء سفارش با وضعیت تازه است و کل مبلغ به همان کیف پولی که از آن کسر شده بود برمی‌گردد.
3. نتیجه را با [`GET /orders/{id}/refund`](https://stard-market.ir/docs/reference/orders-refund-status) یا وب‌هوک `order.*` تأیید کن.

- سفارش انجام‌شده (استارز تحویل‌شده، گیفت ارسال‌شده) خودکار برنمی‌گردد و خطای `409 order_not_refundable` می‌دهد؛ برای آن با پشتیبانی تماس بگیر.
- سفارش بوستی که به پنل تحویل ارسال شده هم خودکار برنمی‌گردد؛ بخش تحویل‌نشده‌ی بوست را خود سیستم خودکار برمی‌گرداند.
- در محیط test هیچ پول واقعی جابه‌جا نمی‌شود؛ رفتار پاسخ همان live است.

## خطاها

| HTTP | code | کی |
|---|---|---|
| `409` | `order_not_refundable` | انجام سفارش شروع شده یا تمام شده |
| `404` | `order_not_found` | سفارش پیدا نشد |
| `403` | `insufficient_scope` | کلید scope `orders:write` را ندارد |
| `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است |
| `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست |

## محدودیت نرخ

پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits).
