Pause, Resume and Cancel Subscription

Transactions

Modify subscription status to pause, resume, or cancel. Use the status parameter to control the operation type and include relevant parameters based on the target status.

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

This endpoint requires the subscriptions.write scope.

Authorizations

Authorizationstringheaderrequired

Bearer authentication header in the format `Bearer <token>`, where `<token>` is your authentication token.

Headers

x-merchant-account-idstringrequired

Merchant account ID for this request.

Examples:""default""

Path Parameters

subscription_idstringrequired

Unique identifier of the subscription to modify.

Examples:"sub_1234567890abcdef"

Body

application/json

statusstringrequired

Target status of the subscription.

Examples:"paused""active""cancelled"

pause_behaviorstring

How to handle unpaid invoices when pausing: mark_uncollectible, keep_as_draft, void.

Default:"mark_uncollectible"

Examples:"mark_uncollectible""keep_as_draft""void"

resume_atstring

Automatic resume time (ISO 8601 format).

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

reasonstring

Reason for the status change.

Length:1 - 255

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

billing_cycle_anchorstring

Billing cycle anchor when resuming: unchanged, now.

Default:"unchanged"

Examples:"unchanged""now"

proration_behaviorstring

Proration behavior when resuming: create_prorations, none.

Default:"create_prorations"

Examples:"create_prorations""none"

at_period_endboolean

Whether to cancel at the end of the current period.

Default:false

Examples:"false""true"

cancellation_reasonstring

Reason for cancellation.

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

prorateboolean

Whether to prorate refund for unused portion.

Default:false

Examples:"true""false"

metadataobject

Custom metadata related to status changes.

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

Response

application/json

Successful Response

idstringrequired

Unique subscription identifier.

Examples:"sub_1234567890abcdef"

objectstringrequired

Object type, always "subscription".

Examples:"subscription"

statusstringrequired

Current subscription status.

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

pause_collectionobject | null

Pause configuration details (when status is paused).

paused_atstring | null

Time when subscription was paused (if applicable).

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

resumed_atstring | null

Time when subscription was resumed (if applicable).

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

canceled_atstring | null

Time when subscription was canceled (if applicable).

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

cancellation_detailsobject | null

Cancellation details (when status is cancelled).

ended_atstring | null

Time when subscription ended (if cancelled).

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

next_billing_datestring | null

Next billing date (null when paused/cancelled).

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

customerobjectrequired

Customer information with generated ID.

planobjectrequired

Subscription plan details.

payment_methodobjectrequired

Payment method details.

current_period_startstringrequired

Current billing period start time.

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

current_period_endstringrequired

Current billing period end time.

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

metadataobject

Custom metadata.

Examples:"{}"

livemodebooleanrequired

Whether this is a production mode subscription.

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
}