暂停、恢复和取消订阅

Transactions

修改订阅状态以暂停、恢复或取消。使用status参数控制操作类型，并根据目标状态包含相关参数。

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

This endpoint requires the subscriptions.write scope.

Authorizations

Authorizationstringheaderrequired

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

Headers

x-merchant-account-idstringrequired

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

Examples:""default""

Path Parameters

subscription_idstringrequired

要修改的订阅的唯一标识符。

Examples:"sub_1234567890abcdef"

Body

application/json

statusstringrequired

订阅的目标状态。

Examples:"paused""active""cancelled"

pause_behaviorstring

暂停时如何处理未付发票：mark_uncollectible、keep_as_draft、void。

Default:"mark_uncollectible"

Examples:"mark_uncollectible""keep_as_draft""void"

resume_atstring

自动恢复时间（ISO 8601格式）。

Examples:"2024-03-01T00:00:00Z"

reasonstring

状态变更的原因。

Length:1 - 255

Examples:"Customer requested temporary pause""Payment failed""Customer request"

billing_cycle_anchorstring

恢复时的计费周期锚点：unchanged、now。

Default:"unchanged"

Examples:"unchanged""now"

proration_behaviorstring

恢复时的按比例计算行为：create_prorations、none。

Default:"create_prorations"

Examples:"create_prorations""none"

at_period_endboolean

是否在当前期间结束时取消。

Default:false

Examples:"false""true"

cancellation_reasonstring

取消的原因。

Examples:"customer_request""payment_failed""service_discontinued""downgrade""other"

prorateboolean

是否按比例退还未使用部分。

Default:false

Examples:"true""false"

metadataobject

与状态变更相关的自定义元数据。

Examples:"{"cancelled_by": "customer", "feedback": "switching_to_competitor"}"

Response

application/json

Successful Response

idstringrequired

唯一订阅标识符。

Examples:"sub_1234567890abcdef"

objectstringrequired

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

Examples:"subscription"

statusstringrequired

当前订阅状态。

Examples:"paused""active""cancelled""failed"

pause_collectionobject | null

暂停配置详情（当状态为paused时）。

paused_atstring | null

订阅暂停的时间（如果适用）。

Examples:"2024-01-20T14:22:00Z""null"

resumed_atstring | null

订阅恢复的时间（如果适用）。

Examples:"2024-02-20T10:15:00Z""null"

canceled_atstring | null

订阅取消的时间（如果适用）。

Examples:"2024-01-20T14:22:00Z""null"

cancellation_detailsobject | null

取消详情（当状态为cancelled时）。

ended_atstring | null

订阅结束的时间（如果取消）。

Examples:"2024-01-20T14:22:00Z""null"

next_billing_datestring | null

下次计费日期（暂停/取消时为null）。

Examples:"2024-02-20""null"

customerobjectrequired

带有生成ID的客户信息。

planobjectrequired

订阅计划详情。

payment_methodobjectrequired

支付方式详情。

current_period_startstringrequired

当前计费期开始时间。

Examples:"2024-01-15T10:30:00Z"

current_period_endstringrequired

当前计费期结束时间。

Examples:"2024-02-15T10:30:00Z"

metadataobject

自定义元数据。

Examples:"{}"

livemodebooleanrequired

这是否为生产模式订阅。

Examples:"false"

curl --request POST \
  --url https://api.efundpay.com/v4/subscriptions/sub_1234567890abcdef/status \
  --header 'Authorization: Bearer <token>' \
  --header 'x-merchant-account-id: <x-merchant-account-id>' \
  --header 'Content-Type: application/json' \

  --data '{
    "status": "paused",
    "pause_behavior": "mark_uncollectible",
    "resume_at": "2024-03-01T00:00:00Z",
    "reason": "Customer requested temporary pause"
  }'

{
  "id": "sub_1234567890abcdef",
  "object": "subscription",
  "status": "paused",
  "pause_collection": {
    "behavior": "mark_uncollectible",
    "resume_at": "2024-03-01T00:00:00Z"
  },
  "paused_at": "2024-01-20T14:22: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": "Basic Monthly",
    "currency": "USD",
    "amount": 1000,
    "interval": "month",
    "trial_period_days": 14,
    "billing_cycle_anchor": "immediate"
  },
  "payment_method": {
    "token_id": "tok_a1b2c3d4",
    "type": "card",
    "card": {
      "number": "4111111111111111",
      "expiration_date": "12/27",
      "security_code": "123"
    }
  },
  "current_period_start": "2024-01-15T10:30:00Z",
  "current_period_end": "2024-02-15T10:30:00Z",
  "next_billing_date": null,
  "livemode": false
}