Skip to main content
PATCH
/
v1
/
subscriptions
/
{id}
/
upcoming_period
Upcoming Period
curl --request PATCH \
  --url https://{defaultHost}/v1/subscriptions/{id}/upcoming_period \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "subscription": {
    "quantity": 2
  }
}
'
{
  "id": "7c07aa44-e05c-4d15-92ac-78b73f4c5748",
  "object": "period",
  "ad_hoc_amount": null,
  "end_at": 1770588180,
  "next_payment_retry_at": null,
  "payment_retry_count": 0,
  "payoff": false,
  "quantity": 2,
  "renewal": false,
  "renewal_reminder_sent_at": null,
  "restoral": false,
  "skip_proration": false,
  "start_at": 1767909780,
  "status": "draft",
  "checkout": "86b52fa0-c780-4e56-b583-0faaea05d363",
  "price": "51af2290-4cdb-4355-9d82-d6853ff8616c",
  "subscription": "67ed19bf-48f3-4a17-bfb6-a9dbea40e99f",
  "variant": null,
  "created_at": 1767909780,
  "updated_at": 1767909780
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
id
string
required

Query Parameters

​
pay_off
boolean

When set to true the upcoming period will simulate paying off the subscription.

​
refresh_price_version
boolean

When set to true the price that is associated with the subscription will be refreshed to reference the most recent version.

​
skip_product_group_validation
boolean

When set to true you can update a subscription's price regardless of the product group it belongs to.

​
skip_proration
boolean

When set to true the next period generated during an immediate update will not be prorated.

​
update_behavior
string

The strategy to use when updating this subscription – one of immediate or pending. If no value is provided, the corresponding subscription protocol downgrade_behavior or upgrade_behavior will be be used.

Body

application/json
​
subscription
object

Response

200 - application/json

Success

​
id
string | null

The UUID of the specific object.

​
object
string

A string describing the object type returned.

​
end_at
integer | null

End of the period. This will be null when the period is for a subscription with a one-time price.

​
ad_hoc_amount
integer | null

The amount to use for this period when the associated price is ad_hoc=true.

​
next_payment_retry_at
integer | null

The time at which payment will be automatically retried.

​
payment_retry_count
integer

Number of payment retries made for this period, from the perspective of the payment retry schedule. Only automatic retries increment the count.

​
payoff
boolean

Indicates whether or not this period paid off all remaining periods.

​
quantity
integer

The quantity of products being purchased.

​
renewal
boolean

Whether or not this period has been generated automatically for a subscription renewal.

​
renewal_reminder_sent_at
integer | null

The time at which the renewal reminder notification was sent to the customer.

​
restoral
boolean

Whether or not this period was generated from a subscription restoral.

​
skip_proration
boolean

Whether or not proration should be skipped when generating this period's checkout.

​
start_at
integer | null

Start of the period.

​
status
string

The current status of this period, which can be one of pending, payment_failed, paid, processing, or void.

​
checkout

Expandable – The associated checkout ID.

​
price

Expandable – The associated price ID.

​
subscription

Expandable – The associated subscription ID.

​
variant

Expandable – The associated variant ID.

​
created_at
integer | null

Time at which the object was created. Measured in seconds since the Unix epoch.

​
updated_at
integer | null

Time at which the object was last updated. Measured in seconds since the Unix epoch.