Update Subscription

Transactions

Update the plan, quantity, or other attributes of an existing subscription. Supports switching to different plans with optional prorated billing.

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

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""

Idempotency-Keystringrequired

Unique identifier to prevent duplicate update requests.

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

Path Parameters

subscription_idstringrequired

Unique identifier of the subscription to update.

Examples:"sub_0001"

Body

application/json

planobject

New subscription plan details.

quantityinteger

Subscription quantity (for per-seat pricing).

Range:x >= 1

Examples:"5"

prorateboolean

Whether to prorate subscription changes.

Default:true

Examples:"true""false"

billing_cycle_anchorstring

Billing cycle anchor: unchanged, now.

Examples:"unchanged""now"

payment_methodobject

New payment method details.

descriptionstring

Updated subscription description.

Length:1 - 255

Examples:"Upgraded to yearly plan"

metadataobject

Custom key-value pairs for additional information.

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

Response

application/json

Successful Response

idstringrequired

Unique subscription identifier.

Examples:"sub_0001"

objectstringrequired

Object type, always "subscription".

Examples:"subscription"

createdstringrequired

Subscription creation time (ISO 8601).

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

updatedstringrequired

Last update time (ISO 8601).

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

customerobjectrequired

Customer information with generated ID.

planobjectrequired

Subscription plan details.

payment_methodobjectrequired

Payment method details.

statusstringrequired

Subscription status.

Examples:"active"

quantityintegerrequired

Subscription quantity.

Examples:"1"

current_period_startstringrequired

Current billing period start time.

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

current_period_endstringrequired

Current billing period end time.

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

next_billing_datestringrequired

Next billing date (YYYY-MM-DD format).

Examples:"2026-08-15"

trial_startstring | null

Trial period start time (if applicable).

Examples:"null"

trial_endstring | null

Trial period end time (if applicable).

Examples:"null"

descriptionstring | null

Subscription description.

Examples:"Upgraded to yearly plan"

metadataobject

Custom metadata.

Examples:"{}"

proration_detailsobject | null

Proration details (if applicable).

livemodebooleanrequired

Whether this is a production mode subscription.

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
}