name 是唯一可以修改的字段:码、优惠内容、生效周期、到期时间和次数上限在创建后都不能再改。如需调整,请新建一张优惠券,并停用旧的。
POST /v1/actions/coupon/update-coupon
请求体
| 字段 | 类型 | 必需 | 说明 |
|---|---|---|---|
id | string | 是 | 优惠券 ID(Short ID 格式 CPN_xxx) |
name | string | 是 | 新的内部名称(最多 64 个字符),买家看不到 |
pending 外任何状态(含 inactive、failed)的优惠券都可以改名。
请求示例
const { coupon } = await client.coupons.update({
id: "CPN_5dXBtmF2HLlHfbPNm0Wcnz",
name: "Black Friday 20% off (extended)",
});
MERCHANT_ID="MER_2aUyqjCzEIiEcYMKj7TZtw"
TIMESTAMP=$(date +%s)
BODY='{"id":"CPN_5dXBtmF2HLlHfbPNm0Wcnz","name":"Black Friday 20% off (extended)"}'
BODY_HASH=$(echo -n "$BODY" | openssl dgst -sha256 -binary | base64 | tr -d '\n')
CANONICAL_REQUEST="POST
/v1/actions/coupon/update-coupon
$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/coupon/update-coupon" \
-H "Content-Type: application/json" \
-H "X-Merchant-Id: $MERCHANT_ID" \
-H "X-Timestamp: $TIMESTAMP" \
-H "X-Signature: $SIGNATURE" \
-d "$BODY"
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": "CPN_5dXBtmF2HLlHfbPNm0Wcnz",
"name": "Black Friday 20% off (extended)",
}
body_json = json.dumps(body, separators=(",", ":"))
body_hash = base64.b64encode(hashlib.sha256(body_json.encode()).digest()).decode()
path = "/v1/actions/coupon/update-coupon"
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)
{
"data": {
"coupon": {
"id": "CPN_5dXBtmF2HLlHfbPNm0Wcnz",
"storeId": "STO_2aUyqjCzEIiEcYMKj7TZtw",
"name": "Black Friday 20% off (extended)",
"code": "BF2026",
"status": "active",
"discountType": "percentage",
"percentOff": 20,
"amountOff": null,
"duration": "repeating",
"durationInPeriods": 3,
"productIds": [],
"maxRedemptions": 1000,
"redeemBy": "2026-12-01T00:00:00.000Z",
"createdAt": "2026-11-01T08:00:00.000Z",
"updatedAt": "2026-11-20T09:15:00.000Z"
}
}
}
响应字段
与创建优惠券的响应相同,但不含promotionCodes。
错误响应
重试策略: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 / Missing required field: name | 必填字段缺失 | 补齐字段后重发 |
| 400 | name must not exceed 64 characters | name 过长 | 缩短 name 后重发 |
| 400 | Expected format: CPN_xxx, got "X" | id 不是合法 Short ID | 使用 CPN_ 前缀的 Short ID |
| 401 | Authentication required | 认证失败 | 检查 API Key、时间戳与签名 |
| 404 | Coupon not found | 优惠券不存在、属于其他商户,或在另一个环境中 | 核对 id 以及 API Key 所属环境 |
| 409 | Coupon is not active (status: pending) | 优惠券为 pending:创建优惠券的请求仍在处理中,或请求中途中断、尚未被清理 | 等创建优惠券的请求结束后再重试 |
| 500 | Internal server error | 服务端意外失败 | 指数退避重试(起步 5s,最多 3 次) |