更新订阅

Transactions

更新现有订阅的计划、数量或其他属性。支持切换到不同计划，可选择按比例计费。

POSThttps://api.efundpay.com/v4/subscriptions/{subscription_id}

This endpoint requires the subscriptions.write scope.

Authorizations

Authorizationstringheaderrequired

Bearer认证头，格式为 `Bearer <token>`，其中 `<token>` 是您的认证令牌。

Headers

x-merchant-account-idstringrequired

用于此请求的商户账户ID。

Examples:""default""

Idempotency-Keystringrequired

防止重复更新的请求的唯一标识符。

Examples:""550e8400-e29b-41d4-a716-446655440001""

Path Parameters

subscription_idstringrequired

要更新的订阅的唯一标识符。

Examples:"sub_0001"

Body

application/json

planobject

新的订阅计划详情。

quantityinteger

订阅数量（用于按座位定价）。

Range:x >= 1

Examples:"5"

prorateboolean

是否按比例计算订阅变更。

Default:true

Examples:"true""false"

billing_cycle_anchorstring

计费周期锚点：unchanged、now。

Examples:"unchanged""now"

payment_methodobject

新的支付方式详情。

descriptionstring

更新的订阅描述。

Length:1 - 255

Examples:"Upgraded to yearly plan"

metadataobject

用于附加信息的自定义键值对。

Examples:"{"plan_type": "yearly", "upgraded_by": "customer"}"

Response

application/json

Successful Response

idstringrequired

唯一订阅标识符。

Examples:"sub_0001"

objectstringrequired

对象类型，始终为"subscription"。

Examples:"subscription"

createdstringrequired

订阅创建时间（ISO 8601）。

Examples:"2025-08-12T09:00:00Z"

updatedstringrequired

最后更新时间（ISO 8601）。

Examples:"2025-08-15T14:30:00Z"

customerobjectrequired

带有生成ID的客户信息。

planobjectrequired

订阅计划详情。

payment_methodobjectrequired

支付方式详情。

statusstringrequired

订阅状态。

Examples:"active"

quantityintegerrequired

订阅数量。

Examples:"1"

current_period_startstringrequired

当前计费期开始时间。

Examples:"2025-08-15T14:30:00Z"

current_period_endstringrequired

当前计费期结束时间。

Examples:"2026-08-15T14:30:00Z"

next_billing_datestringrequired

下次计费日期（YYYY-MM-DD格式）。

Examples:"2026-08-15"

trial_startstring | null

试用期开始时间（如果适用）。

Examples:"null"

trial_endstring | null

试用期结束时间（如果适用）。

Examples:"null"

descriptionstring | null

订阅描述。

Examples:"Upgraded to yearly plan"

metadataobject

自定义元数据。

Examples:"{}"

proration_detailsobject | null

按比例计算详情（如果适用）。

livemodebooleanrequired

这是否为生产模式订阅。

Examples:"false"

curl --request POST \
  --url https://api.efundpay.com/v4/subscriptions/sub_0001 \
  --header 'Authorization: Bearer <token>' \
  --header 'x-merchant-account-id: <x-merchant-account-id>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001' \
  --data '{
    "plan": {
      "name": "Premium Yearly",
      "currency": "USD",
      "amount": 9999,
      "interval": "year",
      "trial_period_days": 30,
      "billing_cycle_anchor": "first_of_month"
    },
    "prorate": true,
    "metadata": {
      "plan_type": "yearly",
      "upgraded_by": "customer"
    }
  }'

{
  "id": "sub_0001",
  "object": "subscription",
  "created": "2025-08-12T09:00:00Z",
  "updated": "2025-08-15T14:30:00Z",
  "customer": {
    "id": "cus_abc123",
    "display_name": "John Doe",
    "external_identifier": "customer-12345",
    "first_name": "John",
    "last_name": "Doe",
    "email_address": "john@example.com",
    "phone_number": "+1234567890",
    "account_number": "123456789"
  },
  "plan": {
    "name": "Premium Yearly",
    "currency": "USD",
    "amount": 9999,
    "interval": "year",
    "trial_period_days": 30,
    "billing_cycle_anchor": "first_of_month"
  },
  "payment_method": {
    "token_id": "tok_a1b2c3d4",
    "type": "card",
    "card": {
      "number": "4111111111111111",
      "expiration_date": "12/27",
      "security_code": "123"
    }
  },
  "status": "active",
  "quantity": 1,
  "current_period_start": "2025-08-15T14:30:00Z",
  "current_period_end": "2026-08-15T14:30:00Z",
  "next_billing_date": "2026-08-15",
  "trial_start": null,
  "trial_end": null,
  "description": "Upgraded to yearly plan",
  "metadata": {
    "plan_type": "yearly",
    "upgraded_by": "customer"
  },
  "proration_details": {
    "credit_amount": 2500,
    "debit_amount": 9999,
    "net_amount": 7499,
    "invoice_id": "in_proration_001"
  },
  "livemode": false
}