用途
批量生成 N 个唯一折扣码（例如为网红抽奖生成 100 个码，为合作伙伴分发生成 500 个码），这些码共享同一前缀，并可配置折扣值、使用次数上限和有效期。每个码都作为独立的 DiscountCodeBasic 折扣节点创建，因此可以在 Shopify 后台单独追踪，若发生泄露也可单独撤销。典型用法：把每个码发给不同的接收者，使每次兑换都能对应到具体某个人。
主要能力
- 生成带统一前缀的唯一折扣码，格式为
<prefix>-<suffix>，后缀为 6 位大写字母数字随机字符。 - 支持三种折扣类型：percentage（百分比）、fixed_amount（固定金额）、free_shipping（免运费）。
- 可配置每个码的使用次数上限（usage_limit，默认 1）。
- 可配置生效时间（starts_at，默认 now）和过期时间（ends_at，可省略表示不过期）。
- 可设置适用范围：order（整单）或 shipping_only（仅运费，配合 free_shipping 使用）。
- 支持 human 或 json 两种输出格式。
- 默认 dry_run 为 true，先预览将要创建的码，不执行实际变更。
- 完成后输出 CSV 文件，包含 code、discount_node_id、value_type、value、usage_limit、starts_at、ends_at、created_at、status 等列。
使用方式
前置条件：
- 已认证的 Shopify CLI 会话：
shopify store auth --store <domain> --scopes write_discounts - API 权限范围：read_discounts、write_discounts
参数：
- store（字符串，必填）：店铺域名，例如 mystore.myshopify.com。
- format（字符串，可选，默认 human）：输出格式，human 或 json。
- dry_run（布尔，可选，默认 true）：预览将要创建的码，不执行变更。
- prefix（字符串，必填）：每个生成码的前缀，例如 GIVEAWAY 会生成 GIVEAWAY-A4F2X9。
- count（整数，必填）：要生成的唯一码数量，单次最多 1000。
- value_type（字符串，必填）：折扣类型，percentage、fixed_amount 或 free_shipping。
- value（浮点数，条件必填）：percentage 时为折扣百分比（1–100）；fixed_amount 时为货币金额；free_shipping 时忽略。
- usage_limit（整数，可选，默认 1）：每个码可被兑换的次数。
- starts_at（字符串，可选，默认 now）：码生效的 ISO8601 时间。
- ends_at（字符串，可选）：码过期的 ISO8601 时间，省略表示不过期。
- applies_to（字符串，可选，默认 order）：适用范围，order（整单）或 shipping_only（配合 free_shipping）。
工作流程：
- 生成 count 个唯一随机后缀（每个 6 位大写字母数字），拼接为
<prefix>-<suffix>，校验内存中无重复且长度不超过 32。 - 对每个码执行一次 discountCodeBasicCreate mutation，输入包括标题、码、生效/过期时间、使用上限、appliesOncePerCustomer 为 true、customerGets 的折扣值、items.all 为 true、customerSelection.all 为 true。
- 返回 codeDiscountNode.id、码值及 userErrors。
GraphQL 操作（discountCodeBasicCreate，已针对 api_version 2025-01 校验）：
mutation PromoCodeCreate($basicCodeDiscount: DiscountCodeBasicInput!) {
discountCodeBasicCreate(basicCodeDiscount: $basicCodeDiscount) {
codeDiscountNode {
id
codeDiscount {
... on DiscountCodeBasic {
title
startsAt
endsAt
usageLimit
appliesOncePerCustomer
codes(first: 1) {
edges {
node {
code
}
}
}
customerGets {
value {
... on DiscountPercentage {
percentage
}
... on DiscountAmount {
amount {
amount
currencyCode
}
}
... on DiscountOnQuantity {
effect {
... on DiscountPercentage {
percentage
}
}
}
}
}
}
}
}
userErrors {
field
message
code
}
}
}
适用场景
- 网红抽奖：为每位接收者发放一个私有码，配合 usage_limit 为 1。
- 合作伙伴分发：批量生成带统一前缀的码，便于在后台和收入报表中筛选。
- 公开分发但需硬性上限：使用 usage_limit 为 N 的码。
- 活动结束后可配合 discount-roi-calculator 按前缀衡量每个码的投资回报。
限制与注意事项
- 第 1 步会为每个生成的码执行一次 discountCodeBasicCreate mutation。码创建后立即出现在 Shopify 后台，并在 starts_at 时变为可兑换。
- 码无法通过 Admin API 批量删除，必须用 discountCodeDelete 逐个移除。
- 默认 dry_run 为 true，建议先确认数量、前缀和折扣值再提交。
- 数量超过 100 时，需确认 usage_limit 是否符合意图；若不需要每个接收者唯一，单个高上限的码通常优于 N 个单次使用的码。
- 单次运行数量上限为 1000，超过需拆分为多次运行。
- 错误处理：THROTTLED 时等待 2 秒并最多重试 3 次；TAKEN 表示码与现有折扣冲突，需重新生成后缀并重试；百分比超出 1–100 或固定金额为负需在提交前校验；批量中途网络失败会导致部分完成，CSV 会记录已创建与待处理项，可仅用待处理后缀列表重跑。
- 最佳实践：为网红类抽奖使用 usage_limit 为 1；选择有意义的前缀（如 INFLUENCER-Q2、GIVEAWAY-LAUNCH）便于筛选；始终设置 ends_at，避免长期折扣成本并简化 ROI 分析；先运行 dry_run 检查生成的后缀；free_shipping 时设置 applies_to 为 shipping_only 且不设 value。