---
title: "Create Subscription"
method: POST
path: "/v1/subscriptions/"
tags: ["subscriptions", "public"]
---

# Create Subscription

`POST /v1/subscriptions/`

Create a subscription programmatically.

This endpoint only allows to create subscription on free products.
For paid products, use the checkout flow.

No initial order will be created and no confirmation email will be sent.

**Scopes**: `subscriptions:write`

## Request body

- union
  - SubscriptionCreateCustomer — Create a subscription for an existing customer.
    - `metadata` object — Key-value object allowing you to store additional information. The key must be a string with a maximum length of **40 characters**. The value must be either: * A string with a maximum length of **500 characters** * An integer * A floating-point number * A boolean You can store up to **50 key-value pairs**.
    - `product_id` string, uuid4, required — The ID of the recurring product to subscribe to. Must be a free product, otherwise the customer should go through a checkout flow.
    - `customer_id` string, uuid4, required — The ID of the customer to create the subscription for.
  - SubscriptionCreateExternalCustomer — Create a subscription for an existing customer identified by an external ID.
    - `metadata` object — Key-value object allowing you to store additional information. The key must be a string with a maximum length of **40 characters**. The value must be either: * A string with a maximum length of **500 characters** * An integer * A floating-point number * A boolean You can store up to **50 key-value pairs**.
    - `product_id` string, uuid4, required — The ID of the recurring product to subscribe to. Must be a free product, otherwise the customer should go through a checkout flow.
    - `external_customer_id` string, required — The ID of the customer in your system to create the subscription for. It must already exist in Polar.

## Response `201`

Subscription created.

- Subscription — unresolved $ref

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/polar/apis/polar-api.md) · [All operations](https://skmtc.net/polar/apis/polar-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/polar/polar-api/revisions/1ee4b8be5abd/schema)