Update Subscription

PATCH

subscriptions

{id}

package main

import(
	"context"
	"os"
	polargo "github.com/polarsource/polar-go"
	"github.com/polarsource/polar-go/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := polargo.New(
        polargo.WithSecurity(os.Getenv("POLAR_ACCESS_TOKEN")),
    )

    res, err := s.Subscriptions.Update(ctx, "<value>", components.CreateSubscriptionUpdateSubscriptionCancel(
        components.SubscriptionCancel{
            CancelAtPeriodEnd: false,
        },
    ))
    if err != nil {
        log.Fatal(err)
    }
    if res.Subscription != nil {
        // handle response
    }
}

{
  "created_at": "2023-11-07T05:31:56Z",
  "modified_at": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "amount": 123,
  "currency": "<string>",
  "recurring_interval": "month",
  "status": "incomplete",
  "current_period_start": "2023-11-07T05:31:56Z",
  "current_period_end": "2023-11-07T05:31:56Z",
  "cancel_at_period_end": true,
  "canceled_at": "2023-11-07T05:31:56Z",
  "started_at": "2023-11-07T05:31:56Z",
  "ends_at": "2023-11-07T05:31:56Z",
  "ended_at": "2023-11-07T05:31:56Z",
  "customer_id": "<string>",
  "product_id": "<string>",
  "discount_id": "<string>",
  "checkout_id": "<string>",
  "customer_cancellation_reason": "customer_service",
  "customer_cancellation_comment": "<string>",
  "metadata": {},
  "custom_field_data": {},
  "customer": {
    "id": "992fae2a-2a17-4b7a-8d9e-e287cf90131b",
    "created_at": "2023-11-07T05:31:56Z",
    "modified_at": "2023-11-07T05:31:56Z",
    "metadata": {},
    "external_id": "usr_1337",
    "email": "customer@example.com",
    "email_verified": true,
    "name": "John Doe",
    "billing_address": {
      "line1": "<string>",
      "line2": "<string>",
      "postal_code": "<string>",
      "city": "<string>",
      "state": "<string>",
      "country": "US"
    },
    "tax_id": [
      "911144442",
      "us_ein"
    ],
    "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
    "deleted_at": "2023-11-07T05:31:56Z",
    "avatar_url": "https://www.gravatar.com/avatar/xxx?d=blank"
  },
  "product": {
    "created_at": "2023-11-07T05:31:56Z",
    "modified_at": "2023-11-07T05:31:56Z",
    "id": "<string>",
    "name": "<string>",
    "description": "<string>",
    "recurring_interval": "month",
    "is_recurring": true,
    "is_archived": true,
    "organization_id": "<string>",
    "metadata": {},
    "prices": [
      {
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "id": "<string>",
        "amount_type": "<string>",
        "is_archived": true,
        "product_id": "<string>",
        "type": "<string>",
        "recurring_interval": "month",
        "price_currency": "<string>",
        "price_amount": 123,
        "legacy": true
      }
    ],
    "benefits": [
      {
        "id": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "type": "<string>",
        "description": "<string>",
        "selectable": true,
        "deletable": true,
        "organization_id": "<string>",
        "metadata": {},
        "properties": {
          "note": "<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": "2023-11-07T05:31:56Z",
        "version": "<string>",
        "service": "<string>",
        "is_uploaded": true,
        "created_at": "2023-11-07T05:31:56Z",
        "size_readable": "<string>",
        "public_url": "<string>"
      }
    ],
    "attached_custom_fields": [
      {
        "custom_field_id": "<string>",
        "custom_field": {
          "created_at": "2023-11-07T05:31:56Z",
          "modified_at": "2023-11-07T05:31:56Z",
          "id": "<string>",
          "metadata": {},
          "type": "<string>",
          "slug": "<string>",
          "name": "<string>",
          "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
          "properties": {
            "form_label": "<string>",
            "form_help_text": "<string>",
            "form_placeholder": "<string>",
            "textarea": true,
            "min_length": 1,
            "max_length": 1
          }
        },
        "order": 123,
        "required": true
      }
    ]
  },
  "discount": {
    "duration": "once",
    "type": "fixed",
    "amount": 123,
    "currency": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "modified_at": "2023-11-07T05:31:56Z",
    "id": "<string>",
    "metadata": {},
    "name": "<string>",
    "code": "<string>",
    "starts_at": "2023-11-07T05:31:56Z",
    "ends_at": "2023-11-07T05:31:56Z",
    "max_redemptions": 123,
    "redemptions_count": 123,
    "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737"
  },
  "prices": [
    {
      "created_at": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "amount_type": "<string>",
      "is_archived": true,
      "product_id": "<string>",
      "type": "<string>",
      "recurring_interval": "month",
      "price_currency": "<string>",
      "price_amount": 123,
      "legacy": true
    }
  ],
  "meters": [
    {
      "created_at": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "consumed_units": 25,
      "credited_units": 100,
      "amount": 0,
      "meter_id": "d498a884-e2cd-4d3e-8002-f536468a8b22",
      "meter": {
        "metadata": {},
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "id": "<string>",
        "name": "<string>",
        "filter": {
          "conjunction": "and",
          "clauses": [
            {
              "property": "<string>",
              "operator": "eq",
              "value": "<string>"
            }
          ]
        },
        "aggregation": {
          "func": "count"
        },
        "organization_id": "<string>"
      }
    }
  ]
}

Authorizations

Authorization

string

header

required

You can generate an Organization Access Token from your organization's settings.

Path Parameters

string

required

The subscription ID.

Body

application/json

product_id

string

required

Update subscription to another product.

proration_behavior

enum<string> | null

Determine how to handle the proration billing. If not provided, will use the default organization setting.

Available options:

invoice,

prorate

product_id

string

required

Update subscription to another product.

proration_behavior

enum<string> | null

Determine how to handle the proration billing. If not provided, will use the default organization setting.

Available options:

invoice,

prorate

cancel_at_period_end

boolean

required

Cancel an active subscription once the current period ends.

Or uncancel a subscription currently set to be revoked at period end.

customer_cancellation_reason

enum<string> | null

Customer reason for cancellation.

Helpful to monitor reasons behind churn for future improvements.

Only set this in case your own service is requesting the reason from the customer. Or you know based on direct conversations, i.e support, with the customer.

too_expensive: Too expensive for the customer.
missing_features: Customer is missing certain features.
switched_service: Customer switched to another service.
unused: Customer is not using it enough.
customer_service: Customer is not satisfied with the customer service.
low_quality: Customer is unhappy with the quality.
too_complex: Customer considers the service too complicated.
other: Other reason(s).

Available options:

customer_service,

low_quality,

missing_features,

switched_service,

too_complex,

too_expensive,

unused,

other

customer_cancellation_comment

string | null

Customer feedback and why they decided to cancel.

IMPORTANT: Do not use this to store internal notes! It's intended to be input from the customer and is therefore also available in their Polar purchases library.

Only set this in case your own service is requesting the reason from the customer. Or you copy a message directly from a customer conversation, i.e support.

revoke

boolean

required

Cancel and revoke an active subscription immediately

customer_cancellation_reason

enum<string> | null

Customer reason for cancellation.

Helpful to monitor reasons behind churn for future improvements.

Only set this in case your own service is requesting the reason from the customer. Or you know based on direct conversations, i.e support, with the customer.

too_expensive: Too expensive for the customer.
missing_features: Customer is missing certain features.
switched_service: Customer switched to another service.
unused: Customer is not using it enough.
customer_service: Customer is not satisfied with the customer service.
low_quality: Customer is unhappy with the quality.
too_complex: Customer considers the service too complicated.
other: Other reason(s).

Available options:

customer_service,

low_quality,

missing_features,

switched_service,

too_complex,

too_expensive,

unused,

other

customer_cancellation_comment

string | null

Customer feedback and why they decided to cancel.

IMPORTANT: Do not use this to store internal notes! It's intended to be input from the customer and is therefore also available in their Polar purchases library.

Only set this in case your own service is requesting the reason from the customer. Or you copy a message directly from a customer conversation, i.e support.

Response

200

application/json

Subscription updated.

created_at

string

required

Creation timestamp of the object.

modified_at

string | null

required

Last modification timestamp of the object.

string

required

The ID of the object.

amount

integer

required

The amount of the subscription.

currency

string

required

The currency of the subscription.

recurring_interval

enum<string>

required

The interval at which the subscription recurs.

Available options:

month,

year

status

enum<string>

required

The status of the subscription.

Available options:

incomplete,

incomplete_expired,

trialing,

active,

past_due,

canceled,

unpaid

current_period_start

string

required

The start timestamp of the current billing period.

current_period_end

string | null

required

The end timestamp of the current billing period.

cancel_at_period_end

boolean

required

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

canceled_at

string | null

required

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

started_at

string | null

required

The timestamp when the subscription started.

ends_at

string | null

required

The timestamp when the subscription will end.

ended_at

string | null

required

The timestamp when the subscription ended.

customer_id

string

required

The ID of the subscribed customer.

product_id

string

required

The ID of the subscribed product.

discount_id

string | null

required

The ID of the applied discount, if any.

checkout_id

string | null

required

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

metadata

object

required

customer

object

required

customer.id

string

required

The ID of the customer.

Examples:

"992fae2a-2a17-4b7a-8d9e-e287cf90131b"

customer.created_at

string

required

Creation timestamp of the object.

customer.modified_at

string | null

required

Last modification timestamp of the object.

customer.metadata

object

required

customer.external_id

string | null

required

The ID of the customer in your system. This must be unique within the organization. Once set, it can't be updated.

Examples:

"usr_1337"

customer.email

string

required

The email address of the customer. This must be unique within the organization.

Examples:

"customer@example.com"

customer.email_verified

boolean

required

Whether the customer email address is verified. The address is automatically verified when the customer accesses the customer portal using their email address.

Examples:

true

customer.name

string | null

required

The name of the customer.

Examples:

"John Doe"

customer.billing_address

object | null

required

customer.tax_id

any[] | null

required

Examples:

["911144442", "us_ein"]

["FR61954506077", "eu_vat"]

customer.organization_id

string

required

The ID of the organization owning the customer.

Examples:

"1dbfc517-0bbf-4301-9ba8-555ca42b9737"

customer.deleted_at

string | null

required

Timestamp for when the customer was soft deleted.

customer.avatar_url

string

required

Examples:

"https://www.gravatar.com/avatar/xxx?d=blank"

product

object

required

A product.

product.created_at

string

required

Creation timestamp of the object.

product.modified_at

string | null

required

Last modification timestamp of the object.

product.id

string

required

The ID of the product.

product.name

string

required

The name of the product.

product.description

string | null

required

The description of the product.

product.recurring_interval

enum<string> | null

required

The recurring interval of the product. If None, the product is a one-time purchase.

Available options:

month,

year

product.is_recurring

boolean

required

Whether the product is a subscription.

product.is_archived

boolean

required

Whether the product is archived and no longer available.

product.organization_id

string

required

The ID of the organization owning the product.

product.metadata

object

required

product.prices

object[]

required

List of prices for this product.

A recurring price for a product, i.e. a subscription.

Deprecated: The recurring interval should be set on the product itself.

product.benefits

object[]

required

List of benefits granted by the product.

A benefit of type custom.

Use it to grant any kind of benefit that doesn't fit in the other types.

product.medias

object[]

required

List of medias associated to the product.

File to be used as a product media file.

product.attached_custom_fields

object[]

required

List of custom fields attached to the product.

Schema of a custom field attached to a resource.

product.attached_custom_fields.custom_field_id

string

required

ID of the custom field.

product.attached_custom_fields.custom_field

object

required

Schema for a custom field of type text.

product.attached_custom_fields.order

integer

required

Order of the custom field in the resource.

product.attached_custom_fields.required

boolean

required

Whether the value is required for this custom field.

discount

object | null

required

prices

object[]

required

List of enabled prices for the subscription.

A recurring price for a product, i.e. a subscription.

Deprecated: The recurring interval should be set on the product itself.

meters

object[]

required

List of meters associated with the subscription.

Current consumption and spending for a subscription meter.

custom_field_data

object

Key-value object storing custom field values.

List Subscriptions

Revoke Subscription

package main

import(
	"context"
	"os"
	polargo "github.com/polarsource/polar-go"
	"github.com/polarsource/polar-go/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := polargo.New(
        polargo.WithSecurity(os.Getenv("POLAR_ACCESS_TOKEN")),
    )

    res, err := s.Subscriptions.Update(ctx, "<value>", components.CreateSubscriptionUpdateSubscriptionCancel(
        components.SubscriptionCancel{
            CancelAtPeriodEnd: false,
        },
    ))
    if err != nil {
        log.Fatal(err)
    }
    if res.Subscription != nil {
        // handle response
    }
}

{
  "created_at": "2023-11-07T05:31:56Z",
  "modified_at": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "amount": 123,
  "currency": "<string>",
  "recurring_interval": "month",
  "status": "incomplete",
  "current_period_start": "2023-11-07T05:31:56Z",
  "current_period_end": "2023-11-07T05:31:56Z",
  "cancel_at_period_end": true,
  "canceled_at": "2023-11-07T05:31:56Z",
  "started_at": "2023-11-07T05:31:56Z",
  "ends_at": "2023-11-07T05:31:56Z",
  "ended_at": "2023-11-07T05:31:56Z",
  "customer_id": "<string>",
  "product_id": "<string>",
  "discount_id": "<string>",
  "checkout_id": "<string>",
  "customer_cancellation_reason": "customer_service",
  "customer_cancellation_comment": "<string>",
  "metadata": {},
  "custom_field_data": {},
  "customer": {
    "id": "992fae2a-2a17-4b7a-8d9e-e287cf90131b",
    "created_at": "2023-11-07T05:31:56Z",
    "modified_at": "2023-11-07T05:31:56Z",
    "metadata": {},
    "external_id": "usr_1337",
    "email": "customer@example.com",
    "email_verified": true,
    "name": "John Doe",
    "billing_address": {
      "line1": "<string>",
      "line2": "<string>",
      "postal_code": "<string>",
      "city": "<string>",
      "state": "<string>",
      "country": "US"
    },
    "tax_id": [
      "911144442",
      "us_ein"
    ],
    "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
    "deleted_at": "2023-11-07T05:31:56Z",
    "avatar_url": "https://www.gravatar.com/avatar/xxx?d=blank"
  },
  "product": {
    "created_at": "2023-11-07T05:31:56Z",
    "modified_at": "2023-11-07T05:31:56Z",
    "id": "<string>",
    "name": "<string>",
    "description": "<string>",
    "recurring_interval": "month",
    "is_recurring": true,
    "is_archived": true,
    "organization_id": "<string>",
    "metadata": {},
    "prices": [
      {
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "id": "<string>",
        "amount_type": "<string>",
        "is_archived": true,
        "product_id": "<string>",
        "type": "<string>",
        "recurring_interval": "month",
        "price_currency": "<string>",
        "price_amount": 123,
        "legacy": true
      }
    ],
    "benefits": [
      {
        "id": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "type": "<string>",
        "description": "<string>",
        "selectable": true,
        "deletable": true,
        "organization_id": "<string>",
        "metadata": {},
        "properties": {
          "note": "<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": "2023-11-07T05:31:56Z",
        "version": "<string>",
        "service": "<string>",
        "is_uploaded": true,
        "created_at": "2023-11-07T05:31:56Z",
        "size_readable": "<string>",
        "public_url": "<string>"
      }
    ],
    "attached_custom_fields": [
      {
        "custom_field_id": "<string>",
        "custom_field": {
          "created_at": "2023-11-07T05:31:56Z",
          "modified_at": "2023-11-07T05:31:56Z",
          "id": "<string>",
          "metadata": {},
          "type": "<string>",
          "slug": "<string>",
          "name": "<string>",
          "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
          "properties": {
            "form_label": "<string>",
            "form_help_text": "<string>",
            "form_placeholder": "<string>",
            "textarea": true,
            "min_length": 1,
            "max_length": 1
          }
        },
        "order": 123,
        "required": true
      }
    ]
  },
  "discount": {
    "duration": "once",
    "type": "fixed",
    "amount": 123,
    "currency": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "modified_at": "2023-11-07T05:31:56Z",
    "id": "<string>",
    "metadata": {},
    "name": "<string>",
    "code": "<string>",
    "starts_at": "2023-11-07T05:31:56Z",
    "ends_at": "2023-11-07T05:31:56Z",
    "max_redemptions": 123,
    "redemptions_count": 123,
    "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737"
  },
  "prices": [
    {
      "created_at": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "amount_type": "<string>",
      "is_archived": true,
      "product_id": "<string>",
      "type": "<string>",
      "recurring_interval": "month",
      "price_currency": "<string>",
      "price_amount": 123,
      "legacy": true
    }
  ],
  "meters": [
    {
      "created_at": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "consumed_units": 25,
      "credited_units": 100,
      "amount": 0,
      "meter_id": "d498a884-e2cd-4d3e-8002-f536468a8b22",
      "meter": {
        "metadata": {},
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "id": "<string>",
        "name": "<string>",
        "filter": {
          "conjunction": "and",
          "clauses": [
            {
              "property": "<string>",
              "operator": "eq",
              "value": "<string>"
            }
          ]
        },
        "aggregation": {
          "func": "count"
        },
        "organization_id": "<string>"
      }
    }
  ]
}

Core API

Customer Portal API

Webhook Events

OAuth 2.0 API

Update Subscription

Authorizations

Path Parameters

Body

Response