如何通过 REST API 创建 WooCommerce Subscription Product？

结论

创建 WooCommerce Subscriptions 商品时，仍需通过顶层字段 "type": "subscription" 指定商品类型。订阅价格、计费周期、注册费和试用期等参数则通常写入商品的 meta_data。

regular_price 是 WooCommerce 的核心商品字段，但 WooCommerce Subscriptions 在计算订阅价格时还会读取 _subscription_price 等扩展元数据。如果只提交 regular_price，后台显示的价格可能与实际订阅价格不一致。

请求数据结构

以下示例创建一个简单订阅商品：每 2 个月收费 99 元，注册费 20 元，提供 14 天试用，订阅持续 12 个月。

data = {
    "name": "会员订阅",
    "type": "subscription",
    "status": "publish",
    "regular_price": "99.00",
    "meta_data": [
        {
            "key": "_subscription_price",
            "value": "99.00"
        },
        {
            "key": "_subscription_period",
            "value": "month"
        },
        {
            "key": "_subscription_period_interval",
            "value": "2"
        },
        {
            "key": "_subscription_length",
            "value": "12"
        },
        {
            "key": "_subscription_sign_up_fee",
            "value": "20.00"
        },
        {
            "key": "_subscription_trial_period",
            "value": "day"
        },
        {
            "key": "_subscription_trial_length",
            "value": "14"
        }
    ]
}

response = wcapi.post("products", data)

对应的原始 JSON 请求如下：

{
  "name": "会员订阅",
  "type": "subscription",
  "status": "publish",
  "regular_price": "99.00",
  "meta_data": [
    {
      "key": "_subscription_price",
      "value": "99.00"
    },
    {
      "key": "_subscription_period",
      "value": "month"
    },
    {
      "key": "_subscription_period_interval",
      "value": "2"
    },
    {
      "key": "_subscription_length",
      "value": "12"
    },
    {
      "key": "_subscription_sign_up_fee",
      "value": "20.00"
    },
    {
      "key": "_subscription_trial_period",
      "value": "day"
    },
    {
      "key": "_subscription_trial_length",
      "value": "14"
    }
  ]
}

请求端点通常为：

POST /wp-json/wc/v3/products

字段说明

例如：

{
  "_subscription_period": "month",
  "_subscription_period_interval": "2"
}

这表示每两个月收费一次。

_subscription_length 指订阅的总持续时间，不是扣款次数。例如，周期为 month、间隔为 2、总时长为 12 时，订阅会持续 12 个月，通常包含 6 个计费周期。

创建无注册费、无试用期的持续订阅

data = {
    "name": "月度会员",
    "type": "subscription",
    "regular_price": "49.00",
    "meta_data": [
        {
            "key": "_subscription_price",
            "value": "49.00"
        },
        {
            "key": "_subscription_period",
            "value": "month"
        },
        {
            "key": "_subscription_period_interval",
            "value": "1"
        },
        {
            "key": "_subscription_length",
            "value": "0"
        },
        {
            "key": "_subscription_sign_up_fee",
            "value": "0"
        },
        {
            "key": "_subscription_trial_length",
            "value": "0"
        }
    ]
}

response = wcapi.post("products", data)

为什么价格会设置错误

如果只传入：

{
    "type": "subscription",
    "regular_price": "99.00"
}

请求只会设置 WooCommerce 的核心商品价格。订阅插件还需要 _subscription_price、_subscription_period 和 _subscription_period_interval 等元数据，才能生成完整的订阅价格规则。

创建普通订阅价格时，可以把 regular_price 和 _subscription_price 设置为相同的字符串金额，避免两处价格不一致：

"regular_price": "99.00"

{
  "key": "_subscription_price",
  "value": "99.00"
}

价格应以字符串形式传递。例如，应使用 "99.00"，而不是浮点数 99.00。

注意事项

这些以下划线开头的字段是 WooCommerce Subscriptions 的商品元数据，不属于 WooCommerce 核心 REST API 的通用产品字段。它们能否使用取决于：

• WooCommerce Subscriptions 是否已安装并启用；
• 当前用户是否有创建和编辑商品的权限；
• WordPress 是否允许通过 REST API 写入这些元数据；
• 当前使用的 WooCommerce 和 WooCommerce Subscriptions 版本是否仍采用相同的内部字段。

如果请求成功，但相关字段没有保存，可以先通过 GET /wp-json/wc/v3/products/{id} 检查返回的 meta_data。部分版本或站点配置会限制受保护的商品元数据。遇到这种情况，需要在 WordPress 端注册相应的 REST 字段，或者编写自定义 REST 端点，调用 WooCommerce Subscriptions 提供的 PHP API。

此外，subscription 和 variable-subscription 是两种不同的商品类型。创建可变订阅商品时，还需要创建 variations，并分别为每个 variation 设置订阅价格和周期。仅在父商品上提交上述简单订阅结构是不够的。

备注：内容仅供参考。