Renew subscription

post

https://www.pelcro.com/api/v1/sdk/subscription/renew

Renew a subscription onto a plan for the next term.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Overview

Renew an existing subscription onto a plan for the next term. plan_id and subscription_id are required; payment fields (source_id or payment_gateway + gateway_token), coupon_code, language, and address_id (when the plan ships) are optional. Returns the customer resource with a fresh JWT.

Example:

curl --request POST \
  --url 'https://www.pelcro.com/api/v1/sdk/subscription/renew?site_id=1232' \
  --header 'Authorization: Bearer <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{ "subscription_id": 4055, "plan_id": 4051, "source_id": 9001 }'

Notes

Protected — requires the customer's JWT.
Validation failures and business errors return 400 with a message.

Query Params

site_id

int32

required

The unique identifier of the site associated with your account.

Body Params

plan_id

int32

required

The unique identifier of plan the subscription should renew on. If you associated a customer segment to the plan, a validation will be performed. Therefore, it is recommended to validate against eligible plans for the customer first. Always required.

subscription_id

int32

required

The unique identifier of the subscription to renew. Always required.

language

string

The customer’s preferred language as a two-letter code, defined by ISO 639-1 standard. Always required.

payment_gateway

string

enum

Defaults to stripe

The optional payment gateway, one of stripe, braintree, vantiv, tap or cybersource. Always defaults to stripe.

Allowed:

gateway_token

string

The single-use token that represents the payment method details. Typically generated using the payment gateway's tools and libraries. This payment method will be used to attempt payments for the subscription.

address_id

int32

The identifier of the shipping address to associate with the subscription. Required if related product requires an address, if product is available only in certain countries, or if tax feature is enabled under your account.

source_id

int32

The unique identifier of chargeable payment method already attached to the customer, which will be used to attempt payments for this subscription.

campaign_key

string

An optional campaign key associated to the subscription. If the key does not already exist, it will be created. The campaign key must be between 3 and 191 characters in length and include only letters, numbers, dashes and underscores without space.

coupon_code

string

An optional coupon code to apply a discount to the subscription renewal. If you associated a customer segment to the coupon, a validation will be performed. Therefore, it is recommended to validate against eligible coupons for the customer first.

quantity

int32

Defaults to 1

Quantity for this subscription, always 1 by default.

source

string

An arbitrary string specifying the origin of the subscription request. (ex: web, bobile, blow-in/letter, phone, API, imported, etc.)

replace_upcoming_phases

boolean

Defaults to false

A boolean flag that, when true, deletes all scheduled future phases before adding a new renewal phase. Used primarily for save offer flows during cancellation to replace existing renewals with a single discounted phase.

stripe_token

string | null

Legacy Stripe card token. Prefer payment_gateway + gateway_token or source_id.

apple_iap_receipt

string

The Apple in-app purchase receipt. Typically populated by leveraging our iOS SDK.

gift_recipient_email

string | null

Email of the gift recipient. Supplying it creates a gift subscription with the authenticated customer as the donor.

gift_start_date

string | null

When the gift is delivered/activated. A future date delays the gift notification.

collection_method

string | null

enum

How the subscription is billed, either charge_automatically or send_invoice.

Allowed:

Responses

Overview

Notes

200Success.

400Invalid request.

401Unauthorized.