---
updatedAt: 2026-06-30T16:05:21.000Z
agentTools:
projectIndex: https://docs.pelcro.com/llms.txt
---
# Update subscription
Update an existing subscription.
## 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.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "core-api",
"version": "1.88"
},
"servers": [
{
"url": "https://www.pelcro.com/api/v1/core"
}
],
"components": {
"securitySchemes": {
"sec0": {
"type": "apiKey",
"in": "header",
"name": "Authorization",
"x-bearer-format": "bearer"
},
"sec1": {
"type": "apiKey",
"in": "query",
"name": "site_id"
}
}
},
"security": [
{
"sec0": [],
"sec1": []
}
],
"paths": {
"/subscriptions/{id}": {
"put": {
"summary": "Update subscription",
"description": "Update an existing subscription.",
"operationId": "api-core-update-subscription",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The unique identifier of the subscription.",
"schema": {
"type": "integer",
"format": "int32"
},
"required": true
},
{
"name": "site_id",
"in": "query",
"description": "The unique identifier your site.",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "Authorization",
"in": "header",
"required": true,
"schema": {
"type": "string",
"default": "Bearer eyJ***"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"shipments_remaining": {
"type": "integer",
"description": "Shipments remaining to update the current one",
"format": "int32"
},
"auto_renew": {
"type": "boolean",
"description": "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": {
"type": "object",
"description": "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.",
"properties": {
"metadata_key": {
"type": "string"
}
}
},
"ip_addresses": {
"type": "array",
"description": "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](https://account.arin.net/public/cidrCalculator) calculate the appropriate CIDR notation for your needs.",
"items": {
"type": "string"
}
},
"domains": {
"type": "array",
"description": "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.",
"items": {
"type": "string"
}
},
"end_date": {
"type": "integer",
"description": "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. ",
"format": "int32"
},
"collection_method": {
"type": "string",
"description": "The payment collection method of subscription.",
"enum": [
"send_invoice",
"charge_automatically"
]
},
"recommended_plan_id": {
"type": "integer",
"description": "Plan ID to set as the recommended pricing plan for the subscription based on market-based pricing",
"format": "int32"
},
"is_imported": {
"type": "boolean",
"description": "A boolean that determines whether subscription is imported."
},
"source_id": {
"type": "integer",
"description": "The unique identifier of the payment method. Must be in a chargeable state. Required if `collection_method` is set to `charge_automatically`.",
"format": "int32"
},
"address_id": {
"type": "integer",
"description": "Shipping address ID. Cannot be updated together with plan_id when taxes are enabled."
},
"plan_id": {
"type": "integer",
"description": "Target plan ID to change to. Cannot be used with auto_renew. Cannot downgrade to a lower-priced plan."
},
"vendor_tip_amount": {
"type": "integer",
"minimum": 0,
"nullable": true,
"description": "Vendor tip amount. Minimum 0."
},
"proration_behavior": {
"type": "string",
"enum": [
"always_invoice",
"create_prorations",
"none"
],
"nullable": true,
"description": "Proration behavior when changing plan. Default: always_invoice. Only applicable when plan_id is set."
},
"payment_behavior": {
"type": "string",
"enum": [
"allow_incomplete",
"default_incomplete",
"error_if_incomplete",
"pending_if_incomplete"
],
"nullable": true,
"description": "Payment behavior for plan change. Default: allow_incomplete. Only applicable when plan_id is set."
},
"billing_cycle_anchor": {
"type": "string",
"nullable": true,
"description": "Billing cycle anchor for plan change. Values: unchanged (default), automatic, now, or a Unix timestamp. Only applicable when plan_id is set."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success.",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{\n \"data\": {\n \"id\": 284,\n \"address\": null,\n \"plan\": 141,\n \"coupon\": null,\n \"default_source\": null,\n \"latest_invoice\": 2673,\n \"user_id\": 11,\n \"address_required\": false,\n \"billing\": \"send_invoice\",\n \"cancel_at\": null,\n \"cancel_at_period_end\": 0,\n \"auto_renew\": 1,\n \"canceled_at\": null,\n \"created\": 1660238545,\n \"current_period_end\": 1660497745,\n \"current_period_start\": 1660238545,\n \"days_until_due\": 30,\n \"domains\": null,\n \"ended_at\": null,\n \"quantity\": 1,\n \"status\": \"active\",\n \"trial_end\": null,\n \"trial_start\": null,\n \"is_gift_donor\": null,\n \"is_gift_recipient\": null,\n \"is_imported\": false,\n \"ip_addresses\": null,\n \"gift_donor_subscription_id\": null,\n \"gift_code\": null,\n \"is_redeemed\": null,\n \"cancel_reason\": null,\n \"shipments_remaining\": 0,\n \"shipments_undeliverable\": false,\n \"shipments_suspended_until\": null,\n \"schedule\": null,\n \"metadata\": null,\n \"expires_at\": null,\n \"renews_at\": 1660497745,\n \"latest_churn_prediction\": null,\n \"start_date\": null,\n \"source\": \"api\",\n \"type\": \"regular\",\n \"is_membership\": false,\n \"old_provider_id\": null,\n \"end_date\": null,\n \"recommended_plan_id\": null,\n \"vendor_tip_amount\": null\n },\n \"status\": \"success\"\n}"
}
},
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 284,
"default": 0
},
"address": {},
"plan": {
"type": "integer",
"example": 141,
"default": 0
},
"coupon": {},
"default_source": {},
"latest_invoice": {
"type": "integer",
"example": 2673,
"default": 0
},
"user_id": {
"type": "integer",
"example": 11,
"default": 0
},
"address_required": {
"type": "boolean",
"example": false,
"default": true
},
"billing": {
"type": "string",
"example": "send_invoice"
},
"cancel_at": {},
"cancel_at_period_end": {
"type": "integer",
"example": 0,
"default": 0
},
"auto_renew": {
"type": "integer",
"example": 1,
"default": 0
},
"canceled_at": {},
"created": {
"type": "integer",
"example": 1660238545,
"default": 0
},
"current_period_end": {
"type": "integer",
"example": 1660497745,
"default": 0
},
"current_period_start": {
"type": "integer",
"example": 1660238545,
"default": 0
},
"days_until_due": {
"type": "integer",
"example": 30,
"default": 0
},
"domains": {},
"ended_at": {},
"quantity": {
"type": "integer",
"example": 1,
"default": 0
},
"status": {
"type": "string",
"example": "active"
},
"trial_end": {},
"trial_start": {},
"is_gift_donor": {},
"is_gift_recipient": {},
"is_imported": {
"type": "boolean",
"example": false,
"default": true
},
"ip_addresses": {},
"gift_donor_subscription_id": {},
"gift_code": {},
"is_redeemed": {},
"cancel_reason": {},
"shipments_remaining": {
"type": "integer",
"example": 0,
"default": 0
},
"shipments_undeliverable": {
"type": "boolean",
"example": false,
"default": true
},
"shipments_suspended_until": {},
"schedule": {},
"metadata": {},
"expires_at": {},
"renews_at": {
"type": "integer",
"example": 1660497745,
"default": 0
},
"latest_churn_prediction": {
"type": "object",
"nullable": true,
"description": "Latest churn prediction data, or null."
},
"start_date": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp when subscription started."
},
"type": {
"type": "string",
"nullable": true,
"description": "Subscription type: regular, membership, gift_donor, gift_recipient, donation."
},
"is_membership": {
"type": "boolean",
"description": "Whether this is a membership subscription."
},
"old_provider_id": {
"type": "string",
"nullable": true,
"description": "External provider ID for imported subscriptions."
},
"end_date": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp of fixed end date."
},
"recommended_plan_id": {
"type": "integer",
"nullable": true,
"description": "Recommended plan ID for upsell."
},
"vendor_tip_amount": {
"type": "integer",
"nullable": true,
"description": "Vendor tip amount."
},
"source": {
"type": "string",
"nullable": true,
"description": "Acquisition source label."
}
}
},
"status": {
"type": "string",
"example": "success"
}
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{\n \"error\": {\n \"status\": 400,\n \"message\": \"Invalid request, please try again.\"\n }\n}"
}
},
"schema": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 400,
"default": 0
},
"message": {
"type": "string",
"example": "Invalid request, please try again."
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthenticated.",
"content": {
"application/json": {
"examples": {
"Result": {
"value": {
"error": "Unauthenticated."
}
}
}
}
}
},
"404": {
"description": "Not found.",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{}"
}
},
"schema": {
"type": "object",
"properties": {}
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{}"
}
},
"schema": {
"type": "object",
"properties": {}
}
}
}
}
},
"deprecated": false,
"x-readme": {
"code-samples": [
{
"language": "php",
"code": "use GuzzleHttp\\Client;\n\n$site_id = 0; // (int) your site id here\n$address_id = 0; // (int) the address id here\n$shipments_remaining = 0; // (int) the subscription shipment remaining here\n$subscription_id = 0; // (int) the subscription id here\n$metadata = [\n\t'key' => 'value'\n];\n\n$api_key = '' // (string) your api key here\n$uri = \"subscriptions/{$subscription_id}\";\n\n$config = [\n 'base_uri' => 'https://www.pelcro.com/api/v1/core/'\n];\n\n$client = new Client($config);\n\n$options = [\n\t'jon' => [\n\t\t'site_id' => $site_id,\n\t\t'shipments_remaining' => $shipments_remaining,\n 'metadata' => $metadata,\n\t],\n\t'headers' => [\n\t\t'Accept' => 'application/json',\n\t\t'Authorization' => 'Bearer ' . $api_key\n\t]\n];\n\n$response = $client->request('PUT', $uri, $options);"
}
],
"samples-languages": [
"php"
]
}
}
}
},
"x-readme": {
"headers": [],
"explorer-enabled": true,
"proxy-enabled": true
},
"x-readme-fauxas": true
}
```
# Sibling pages
* [List subscriptions](https://docs.pelcro.com/reference/api-core-list-subcriptions.md)
* [Create subscription](https://docs.pelcro.com/reference/api-core-create-subscription.md)
* [Get subscription](https://docs.pelcro.com/reference/api-core-get-subscription.md)
* [Cancel subscription](https://docs.pelcro.com/reference/api-core-cancel-subscription.md)
* [Renew subscription](https://docs.pelcro.com/reference/api-core-renew-subscription.md)
* [Delete phase](https://docs.pelcro.com/reference/api-core-delete-phase.md)
* [Gifts](https://docs.pelcro.com/reference/api-core-gifts.md)