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

# 停用促销码

> 永久停用促销码并释放它的码

停用促销码。停用后买家不能再使用它，它的码会立即释放：同一店铺、同一环境中新的促销码或优惠券可以使用这个码。

```
POST /v1/actions/promotion-code/deactivate-promotion-code
```

**认证方式：** API Key

> [!WARNING]
>
> 停用是**不可恢复**的。已停用的促销码无法重新启用。如需再次提供这个码，请用它新建一个促销码。

## 请求体

| 字段 | 类型 | 必需 | 说明 |
| - | - | - | - |
| `id` | string | 是 | 促销码 ID（Short ID 格式 `PMC_xxx`） |

## 请求示例

```typescript SDK theme={"system"}
const { promotionCode } = await client.promotionCodes.deactivate({ id: "PMC_6eYCunG3IMmIgcQOnaXdoA" });
console.log(promotionCode.status); // => "inactive"
```

```bash cURL theme={"system"}
MERCHANT_ID="MER_2aUyqjCzEIiEcYMKj7TZtw"
TIMESTAMP=$(date +%s)
BODY='{"id":"PMC_6eYCunG3IMmIgcQOnaXdoA"}'
BODY_HASH=$(echo -n "$BODY" | openssl dgst -sha256 -binary | base64 | tr -d '\n')
CANONICAL_REQUEST="POST
/v1/actions/promotion-code/deactivate-promotion-code
$TIMESTAMP
$BODY_HASH"

SIGNATURE=$(echo -n "$CANONICAL_REQUEST" | openssl dgst -sha256 -sign private_key.pem | base64 | tr -d '\n')

curl -X POST "https://api.waffo.ai/v1/actions/promotion-code/deactivate-promotion-code" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: $MERCHANT_ID" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -d "$BODY"
```

```python Python theme={"system"}
import hashlib, time, base64, json, requests
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding

merchant_id = "MER_2aUyqjCzEIiEcYMKj7TZtw"
timestamp = str(int(time.time()))
body = {"id": "PMC_6eYCunG3IMmIgcQOnaXdoA"}

body_json = json.dumps(body, separators=(",", ":"))
body_hash = base64.b64encode(hashlib.sha256(body_json.encode()).digest()).decode()
path = "/v1/actions/promotion-code/deactivate-promotion-code"
canonical = f"POST\n{path}\n{timestamp}\n{body_hash}"

with open("private_key.pem", "rb") as f:
    private_key = serialization.load_pem_private_key(f.read(), password=None)

signature = base64.b64encode(
    private_key.sign(canonical.encode(), padding.PKCS1v15(), hashes.SHA256())
).decode()

resp = requests.post(
    f"https://api.waffo.ai{path}",
    headers={
        "Content-Type": "application/json",
        "X-Merchant-Id": merchant_id,
        "X-Timestamp": timestamp,
        "X-Signature": signature,
    },
    data=body_json,
)
print(resp.json())
```

## 成功响应 (200)

```json theme={"system"}
{
  "data": {
    "promotionCode": {
      "id": "PMC_6eYCunG3IMmIgcQOnaXdoA",
      "couponId": "CPN_5dXBtmF2HLlHfbPNm0Wcnz",
      "code": "KOL-ALICE",
      "status": "inactive",
      "restrictions": {
        "customerEmails": [],
        "perCustomerLimit": null,
        "maxRedemptions": 100,
        "expiresAt": "2026-12-01T00:00:00.000Z",
        "minimumAmount": { "USD": "50.00" }
      },
      "batchId": null,
      "createdAt": "2026-11-02T08:00:00.000Z"
    }
  }
}
```

## 响应字段

与[创建促销码的响应](https://docs.waffo.ai/zh/api-reference/endpoints/promotion-codes/create-promotion-code.md)相同。

> [!NOTE]
>
> 已有订单保留下单时的码，不受影响。对已停用的促销码再次调用会返回 `200`，促销码保持不变。停用促销码不会停用它所属的优惠券。优惠券自己的码只能通过[停用优惠券](https://docs.waffo.ai/zh/api-reference/endpoints/coupons/deactivate-coupon.md)一并停用，同时停用它的全部促销码。

## 错误响应

> **重试策略**：4xx 一律不要重试 — 修正请求后重发。5xx 指数退避重试（起步 5s，最多 3 次）。

| 状态码 | `errors[0].message` | 含义 | 推荐处理 |
| - | - | - | - |
| 400 | `Missing or invalid header: x-context-environment` | 环境 header 缺失或不是 `test` / `prod` | 把 `X-Environment` 设为 `test` 或 `prod` |
| 400 | `Invalid JSON body` | 请求体不是合法 JSON | 修正请求体后重发 |
| 400 | `Missing required field: id` | 未提供 `id` | 补齐 `id` 后重发 |
| 400 | `Expected format: PMC_xxx, got "X"` | `id` 不是合法 Short ID | 使用 `PMC_` 前缀的 Short ID |
| 401 | `Authentication required` | 认证失败 | 检查 API Key、时间戳与签名 |
| 404 | `Promotion code not found` | 促销码不存在、属于其他商户，或在另一个环境中 | 核对 `id` 以及 API Key 所属环境 |
| 409 | `The coupon's own code can only be deactivated together with the coupon` | 该 ID 是优惠券自己的码，不是它的促销码 | 改为停用优惠券 |
| 500 | `Internal server error` | 服务端意外失败 | 指数退避重试（起步 5s，最多 3 次） |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.