Update subscription

put

https://www.pelcro.com/api/v1/core/subscriptions/{id}

Update an existing subscription.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Overview

Update an existing subscription. You can modify various attributes like metadata, shipping address, or auto-renewal settings. When plan_id is provided, the subscription is changed to the new plan with proration.

Example: Update a subscription's shipping address when a customer moves to a new location. Or change from a Monthly to an Annual plan with prorated billing.

Conditional Requirements

Condition	Required Fields
`collection_method=charge_automatically`	`source_id`
`plan_id` is set (plan change)	`proration_behavior`, `payment_behavior`, `billing_cycle_anchor` auto-default if not provided
`end_date` is set	Must be a Unix timestamp >= current period end
`auto_renew` is set	Cannot also set `plan_id` in the same request
`plan_id` + `address_id` when taxes enabled	Not allowed — update address and plan separately
Subscription is scheduled	Cannot be updated
Subscription has pending payment	Cannot be updated

Webhooks

All updates trigger the subscription.updated webhook event.

Plan changes additionally trigger the subscription.changed webhook event.

Path Params

int32

required

The unique identifier of the subscription.

Query Params

site_id

int32

required

The unique identifier your site.

Body Params

shipments_remaining

int32

Shipments remaining to update the current one

auto_renew

boolean

A boolean that determines whether the subscription will auto-renew or not at the end of the last phase. (overrides the plan configuration when set)

metadata

object

Set of key-value pairs that can be saved on subscription level. This can be useful for storing additional information about the object in a structured format.

ip_addresses

array of strings

IP addresses that will identify end-users as members of this subscription upon registration/login. This attribute can only be set when the subscription plan type is membership. Two format are accepted for strings:

A single public IP address
This should be a valid public IP address following the standard IPv4 format (e.g., 192.168.1.100).

A range of public IP addresses
This should be a range of public IP addresses following the CIDR notation (e.g., 198.51.100.0/24).

You can use this tool calculate the appropriate CIDR notation for your needs.

ip_addresses

domains

array of strings

Email domains that will allow end-users with these domains to be members of this subscription upon registration/login. It can only be sent when the subscription plan type is membership.

domains

end_date

int32

A valid Unix timestamp in the future represents the exact day to which the subscription will be extended. Note: While you can set an exact Unix timestamp, the end_date will be rounded to the end of that specified day (23:59:59 in UTC). Please note you may only change the end date to a time after the current period end.

collection_method

string

enum

The payment collection method of subscription.

Allowed:

recommended_plan_id

int32

Plan ID to set as the recommended pricing plan for the subscription based on market-based pricing

is_imported

boolean

A boolean that determines whether subscription is imported.

source_id

int32

The unique identifier of the payment method. Must be in a chargeable state. Required if collection_method is set to charge_automatically.

address_id

integer

Shipping address ID. Cannot be updated together with plan_id when taxes are enabled.

plan_id

integer

Target plan ID to change to. Cannot be used with auto_renew. Cannot downgrade to a lower-priced plan.

vendor_tip_amount

integer | null

≥ 0

Vendor tip amount. Minimum 0.

proration_behavior

string | null

enum

Proration behavior when changing plan. Default: always_invoice. Only applicable when plan_id is set.

Allowed:

payment_behavior

string | null

enum

Payment behavior for plan change. Default: allow_incomplete. Only applicable when plan_id is set.

Allowed:

billing_cycle_anchor

string | null

Billing cycle anchor for plan change. Values: unchanged (default), automatic, now, or a Unix timestamp. Only applicable when plan_id is set.

Headers

Authorization

string

required

Defaults to Bearer eyJ***

Responses

Overview

Conditional Requirements

Webhooks

200Success.

400Invalid request.

401Unauthenticated.

404Not found.

500Server error.