Update Subscription

PATCH

customer-portal

subscriptions

{id}

Python

from polar.v2027_01 import Polar

polar = Polar("polar_oat_xxx")

response = polar.customer_portal.subscriptions.update(
    '00000000-0000-4000-8000-000000000000',
    product_id='00000000-0000-4000-8000-000000000000',
)
print(response)

import { createPolar } from "@polar-sh/sdk/2027-01";

const polar = createPolar({
  accessToken: "polar_oat_xxx",
});

const response = await polar.customerPortal.subscriptions.update(
  "00000000-0000-4000-8000-000000000000",
  {
    "product_id": "00000000-0000-4000-8000-000000000000"
  },
);
console.log(response);

curl --request PATCH \
  --url https://api.polar.sh/v1/customer-portal/subscriptions/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "product_id": "<string>"
}
'

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({product_id: '<string>'})
};

fetch('https://api.polar.sh/v1/customer-portal/subscriptions/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.polar.sh/v1/customer-portal/subscriptions/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'product_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.polar.sh/v1/customer-portal/subscriptions/{id}"

	payload := strings.NewReader("{\n  \"product_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.polar.sh/v1/customer-portal/subscriptions/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"product_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.polar.sh/v1/customer-portal/subscriptions/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"product_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "created_at": "2026-01-01T00:00:00.000000Z",
  "modified_at": "2026-01-01T00:00:00.000000Z",
  "id": "<string>",
  "amount": 10000,
  "currency": "usd",
  "recurring_interval": "month",
  "recurring_interval_count": 123,
  "status": "active",
  "current_period_start": "2026-01-01T00:00:00.000000Z",
  "current_period_end": "2026-01-01T00:00:00.000000Z",
  "current_meter_period_start": "2026-01-01T00:00:00.000000Z",
  "current_meter_period_end": "2026-01-01T00:00:00.000000Z",
  "trial_start": "2026-01-01T00:00:00.000000Z",
  "trial_end": "2026-01-01T00:00:00.000000Z",
  "cancel_at_period_end": true,
  "canceled_at": "2026-01-01T00:00:00.000000Z",
  "started_at": "2026-01-01T00:00:00.000000Z",
  "ends_at": "2026-01-01T00:00:00.000000Z",
  "ended_at": "2026-01-01T00:00:00.000000Z",
  "pause_at_period_end": true,
  "paused_at": "2026-01-01T00:00:00.000000Z",
  "resumes_at": "2026-01-01T00:00:00.000000Z",
  "customer_id": "<string>",
  "product_id": "<string>",
  "discount_id": "<string>",
  "checkout_id": "<string>",
  "units": 123,
  "customer_cancellation_reason": "customer_service",
  "customer_cancellation_comment": "<string>",
  "product": {
    "id": "<string>",
    "created_at": "2026-01-01T00:00:00.000000Z",
    "modified_at": "2026-01-01T00:00:00.000000Z",
    "trial_interval": "day",
    "trial_interval_count": 123,
    "name": "<string>",
    "description": "<string>",
    "visibility": "draft",
    "recurring_interval": "day",
    "recurring_interval_count": 123,
    "meter_interval": "day",
    "meter_interval_count": 123,
    "is_recurring": true,
    "is_archived": true,
    "organization_id": "<string>",
    "prices": [
      {
        "created_at": "2026-01-01T00:00:00.000000Z",
        "modified_at": "2026-01-01T00:00:00.000000Z",
        "id": "<string>",
        "source": "catalog",
        "amount_type": "fixed",
        "price_currency": "<string>",
        "tax_behavior": "location",
        "is_archived": true,
        "product_id": "<string>",
        "price_amount": 123
      }
    ],
    "benefits": [
      {
        "id": "<string>",
        "created_at": "2026-01-01T00:00:00.000000Z",
        "modified_at": "2026-01-01T00:00:00.000000Z",
        "type": "custom",
        "description": "<string>",
        "selectable": true,
        "deletable": true,
        "is_deleted": true,
        "organization_id": "<string>"
      }
    ],
    "medias": [
      {
        "id": "<string>",
        "organization_id": "<string>",
        "name": "<string>",
        "path": "<string>",
        "mime_type": "<string>",
        "size": 123,
        "storage_version": "<string>",
        "checksum_etag": "<string>",
        "checksum_sha256_base64": "<string>",
        "checksum_sha256_hex": "<string>",
        "last_modified_at": "2026-01-01T00:00:00.000000Z",
        "version": "<string>",
        "service": "product_media",
        "is_uploaded": true,
        "created_at": "2026-01-01T00:00:00.000000Z",
        "size_readable": "<string>",
        "public_url": "<string>"
      }
    ],
    "organization": {
      "created_at": "2026-01-01T00:00:00.000000Z",
      "modified_at": "2026-01-01T00:00:00.000000Z",
      "id": "<string>",
      "name": "<string>",
      "slug": "<string>",
      "avatar_url": "<string>",
      "proration_behavior": "invoice",
      "allow_customer_updates": true,
      "customer_portal_settings": {
        "usage": {
          "show": true
        },
        "subscription": {
          "update_seats": true,
          "update_plan": true,
          "update_units": true,
          "pause": true
        },
        "customer": {
          "allow_email_change": true
        }
      },
      "organization_features": {
        "checkout_localization_enabled": false
      }
    }
  },
  "prices": [
    {
      "created_at": "2026-01-01T00:00:00.000000Z",
      "modified_at": "2026-01-01T00:00:00.000000Z",
      "id": "<string>",
      "source": "catalog",
      "amount_type": "fixed",
      "price_currency": "<string>",
      "tax_behavior": "location",
      "is_archived": true,
      "product_id": "<string>",
      "price_amount": 123
    }
  ],
  "meters": [
    {
      "created_at": "2026-01-01T00:00:00.000000Z",
      "modified_at": "2026-01-01T00:00:00.000000Z",
      "id": "<string>",
      "consumed_units": 25,
      "credited_units": 100,
      "amount": 0,
      "meter_id": "d498a884-e2cd-4d3e-8002-f536468a8b22",
      "meter": {
        "created_at": "2026-01-01T00:00:00.000000Z",
        "modified_at": "2026-01-01T00:00:00.000000Z",
        "id": "<string>",
        "name": "<string>"
      }
    }
  ],
  "pending_update": {
    "created_at": "2026-01-01T00:00:00.000000Z",
    "modified_at": "2026-01-01T00:00:00.000000Z",
    "id": "<string>",
    "applies_at": "2026-01-01T00:00:00.000000Z",
    "product_id": "<string>",
    "seats": 123,
    "units": 123,
    "discount_id": "<string>",
    "discount_unset": true
  },
  "past_due_at": "2026-01-01T00:00:00.000000Z",
  "seats": 123
}

{
  "error": "PaymentFailed",
  "detail": "<string>"
}

{
  "error": "AlreadyCanceledSubscription",
  "detail": "<string>"
}

{
  "error": "ResourceNotFound",
  "detail": "<string>"
}

{
  "error": "PaymentMethodRequired",
  "detail": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

Authorization

string

header

required

Customer session tokens are specific tokens that are used to authenticate customers on your organization. You can create those sessions programmatically using the Create Customer Session endpoint.

Scopes

customer_portal:write

customer_session

customer_portal:write

member_session

Path Parameters

string<uuid4>

required

The subscription ID.

Body

application/json

product_id

string<uuid4>

required

Update subscription to another product.

Response

Customer subscription updated.

created_at

string<date-time>

required

Creation timestamp of the object.

Example:

"2026-01-01T00:00:00.000000Z"

modified_at

string<date-time> | null

required

Last modification timestamp of the object.

Example:

"2026-01-01T00:00:00.000000Z"

string<uuid4>

required

The ID of the object.

amount

integer

required

The amount of the subscription.

Example:

10000

currency

string

required

The currency of the subscription.

Example:

"usd"

recurring_interval

enum<string>

required

The interval at which the subscription recurs.

Available options:

day,

week,

month,

year

Example:

"month"

recurring_interval_count

integer

required

Number of interval units of the subscription. If this is set to 1 the charge will happen every interval (e.g. every month), if set to 2 it will be every other month, and so on.

status

enum<string>

required

The status of the subscription.

Available options:

incomplete,

incomplete_expired,

trialing,

active,

past_due,

canceled,

unpaid,

paused

Example:

"active"

current_period_start

string<date-time>

required

The start timestamp of the current billing period.

Example:

"2026-01-01T00:00:00.000000Z"

current_period_end

string<date-time>

required

The end timestamp of the current billing period.

Example:

"2026-01-01T00:00:00.000000Z"

current_meter_period_start

string<date-time> | null

required

The start timestamp of the current meter period, if the product has a meter cycle set. Metered credits are granted and overage is settled on this cadence.

Example:

"2026-01-01T00:00:00.000000Z"

current_meter_period_end

string<date-time> | null

required

The end timestamp of the current meter period, if the product has a meter cycle set. This is when credits next renew.

Example:

"2026-01-01T00:00:00.000000Z"

trial_start

string<date-time> | null

required

The start timestamp of the trial period, if any.

Example:

"2026-01-01T00:00:00.000000Z"

trial_end

string<date-time> | null

required

The end timestamp of the trial period, if any.

Example:

"2026-01-01T00:00:00.000000Z"

cancel_at_period_end

boolean

required

Whether the subscription will be canceled at the end of the current period.

canceled_at

string<date-time> | null

required

The timestamp when the subscription was canceled. The subscription might still be active if cancel_at_period_end is true.

Example:

"2026-01-01T00:00:00.000000Z"

started_at

string<date-time>

required

The timestamp when the subscription started.

Example:

"2026-01-01T00:00:00.000000Z"

ends_at

string<date-time> | null

required

The timestamp when the subscription will end.

Example:

"2026-01-01T00:00:00.000000Z"

ended_at

string<date-time> | null

required

The timestamp when the subscription ended.

Example:

"2026-01-01T00:00:00.000000Z"

pause_at_period_end

boolean

required

Whether the subscription will be paused at the end of the current period.

paused_at

string<date-time> | null

required

The timestamp when the subscription was paused.

Example:

"2026-01-01T00:00:00.000000Z"

resumes_at

string<date-time> | null

required

The timestamp when a paused subscription is scheduled to automatically resume, if set.

Example:

"2026-01-01T00:00:00.000000Z"

customer_id

string<uuid4>

required

The ID of the subscribed customer.

product_id

string<uuid4>

required

The ID of the subscribed product.

discount_id

string<uuid4> | null

required

The ID of the applied discount, if any.

checkout_id

string<uuid4> | null

required

units

integer | null

required

The number of units for unit-based subscriptions. None for non-unit subscriptions.

customer_cancellation_reason

enum<string> | null

required

Available options:

customer_service,

low_quality,

missing_features,

switched_service,

too_complex,

too_expensive,

unused,

other

customer_cancellation_comment

string | null

required

product

CustomerSubscriptionProduct · object

required

Show child attributes

prices

required

List of enabled prices for the subscription.

A fixed price for a product.

Show child attributes

meters

CustomerSubscriptionMeter · object[]

required

List of meters associated with the subscription.

Show child attributes

pending_update

PendingSubscriptionUpdate · object | null

required

Pending subscription update that will be applied at the beginning of the next period. If null, there is no pending update.

Show child attributes

past_due_at

string<date-time> | null

The timestamp when the subscription entered past_due status.

Example:

"2026-01-01T00:00:00.000000Z"

seats

integer | null

The number of seats for seat-based subscriptions. None for non-seat subscriptions.

⌘I

Python

from polar.v2027_01 import Polar

polar = Polar("polar_oat_xxx")

response = polar.customer_portal.subscriptions.update(
    '00000000-0000-4000-8000-000000000000',
    product_id='00000000-0000-4000-8000-000000000000',
)
print(response)

import { createPolar } from "@polar-sh/sdk/2027-01";

const polar = createPolar({
  accessToken: "polar_oat_xxx",
});

const response = await polar.customerPortal.subscriptions.update(
  "00000000-0000-4000-8000-000000000000",
  {
    "product_id": "00000000-0000-4000-8000-000000000000"
  },
);
console.log(response);

curl --request PATCH \
  --url https://api.polar.sh/v1/customer-portal/subscriptions/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "product_id": "<string>"
}
'

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({product_id: '<string>'})
};

fetch('https://api.polar.sh/v1/customer-portal/subscriptions/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.polar.sh/v1/customer-portal/subscriptions/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'product_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.polar.sh/v1/customer-portal/subscriptions/{id}"

	payload := strings.NewReader("{\n  \"product_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.polar.sh/v1/customer-portal/subscriptions/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"product_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.polar.sh/v1/customer-portal/subscriptions/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"product_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "created_at": "2026-01-01T00:00:00.000000Z",
  "modified_at": "2026-01-01T00:00:00.000000Z",
  "id": "<string>",
  "amount": 10000,
  "currency": "usd",
  "recurring_interval": "month",
  "recurring_interval_count": 123,
  "status": "active",
  "current_period_start": "2026-01-01T00:00:00.000000Z",
  "current_period_end": "2026-01-01T00:00:00.000000Z",
  "current_meter_period_start": "2026-01-01T00:00:00.000000Z",
  "current_meter_period_end": "2026-01-01T00:00:00.000000Z",
  "trial_start": "2026-01-01T00:00:00.000000Z",
  "trial_end": "2026-01-01T00:00:00.000000Z",
  "cancel_at_period_end": true,
  "canceled_at": "2026-01-01T00:00:00.000000Z",
  "started_at": "2026-01-01T00:00:00.000000Z",
  "ends_at": "2026-01-01T00:00:00.000000Z",
  "ended_at": "2026-01-01T00:00:00.000000Z",
  "pause_at_period_end": true,
  "paused_at": "2026-01-01T00:00:00.000000Z",
  "resumes_at": "2026-01-01T00:00:00.000000Z",
  "customer_id": "<string>",
  "product_id": "<string>",
  "discount_id": "<string>",
  "checkout_id": "<string>",
  "units": 123,
  "customer_cancellation_reason": "customer_service",
  "customer_cancellation_comment": "<string>",
  "product": {
    "id": "<string>",
    "created_at": "2026-01-01T00:00:00.000000Z",
    "modified_at": "2026-01-01T00:00:00.000000Z",
    "trial_interval": "day",
    "trial_interval_count": 123,
    "name": "<string>",
    "description": "<string>",
    "visibility": "draft",
    "recurring_interval": "day",
    "recurring_interval_count": 123,
    "meter_interval": "day",
    "meter_interval_count": 123,
    "is_recurring": true,
    "is_archived": true,
    "organization_id": "<string>",
    "prices": [
      {
        "created_at": "2026-01-01T00:00:00.000000Z",
        "modified_at": "2026-01-01T00:00:00.000000Z",
        "id": "<string>",
        "source": "catalog",
        "amount_type": "fixed",
        "price_currency": "<string>",
        "tax_behavior": "location",
        "is_archived": true,
        "product_id": "<string>",
        "price_amount": 123
      }
    ],
    "benefits": [
      {
        "id": "<string>",
        "created_at": "2026-01-01T00:00:00.000000Z",
        "modified_at": "2026-01-01T00:00:00.000000Z",
        "type": "custom",
        "description": "<string>",
        "selectable": true,
        "deletable": true,
        "is_deleted": true,
        "organization_id": "<string>"
      }
    ],
    "medias": [
      {
        "id": "<string>",
        "organization_id": "<string>",
        "name": "<string>",
        "path": "<string>",
        "mime_type": "<string>",
        "size": 123,
        "storage_version": "<string>",
        "checksum_etag": "<string>",
        "checksum_sha256_base64": "<string>",
        "checksum_sha256_hex": "<string>",
        "last_modified_at": "2026-01-01T00:00:00.000000Z",
        "version": "<string>",
        "service": "product_media",
        "is_uploaded": true,
        "created_at": "2026-01-01T00:00:00.000000Z",
        "size_readable": "<string>",
        "public_url": "<string>"
      }
    ],
    "organization": {
      "created_at": "2026-01-01T00:00:00.000000Z",
      "modified_at": "2026-01-01T00:00:00.000000Z",
      "id": "<string>",
      "name": "<string>",
      "slug": "<string>",
      "avatar_url": "<string>",
      "proration_behavior": "invoice",
      "allow_customer_updates": true,
      "customer_portal_settings": {
        "usage": {
          "show": true
        },
        "subscription": {
          "update_seats": true,
          "update_plan": true,
          "update_units": true,
          "pause": true
        },
        "customer": {
          "allow_email_change": true
        }
      },
      "organization_features": {
        "checkout_localization_enabled": false
      }
    }
  },
  "prices": [
    {
      "created_at": "2026-01-01T00:00:00.000000Z",
      "modified_at": "2026-01-01T00:00:00.000000Z",
      "id": "<string>",
      "source": "catalog",
      "amount_type": "fixed",
      "price_currency": "<string>",
      "tax_behavior": "location",
      "is_archived": true,
      "product_id": "<string>",
      "price_amount": 123
    }
  ],
  "meters": [
    {
      "created_at": "2026-01-01T00:00:00.000000Z",
      "modified_at": "2026-01-01T00:00:00.000000Z",
      "id": "<string>",
      "consumed_units": 25,
      "credited_units": 100,
      "amount": 0,
      "meter_id": "d498a884-e2cd-4d3e-8002-f536468a8b22",
      "meter": {
        "created_at": "2026-01-01T00:00:00.000000Z",
        "modified_at": "2026-01-01T00:00:00.000000Z",
        "id": "<string>",
        "name": "<string>"
      }
    }
  ],
  "pending_update": {
    "created_at": "2026-01-01T00:00:00.000000Z",
    "modified_at": "2026-01-01T00:00:00.000000Z",
    "id": "<string>",
    "applies_at": "2026-01-01T00:00:00.000000Z",
    "product_id": "<string>",
    "seats": 123,
    "units": 123,
    "discount_id": "<string>",
    "discount_unset": true
  },
  "past_due_at": "2026-01-01T00:00:00.000000Z",
  "seats": 123
}

{
  "error": "PaymentFailed",
  "detail": "<string>"
}

{
  "error": "AlreadyCanceledSubscription",
  "detail": "<string>"
}

{
  "error": "ResourceNotFound",
  "detail": "<string>"
}

{
  "error": "PaymentMethodRequired",
  "detail": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

General

Core API

Customer Portal API

Webhook Events

Integrations

Update Subscription

Authorizations

Scopes

Path Parameters

Body

Response