---
title: "Create subscription"
method: POST
path: "/partner/subscriptions"
tags: ["Subscriptions"]
---

# Create subscription

`POST /partner/subscriptions`

## Request

- Base URL: `https://api.consumer.upfort.com/api`
- URL: `https://api.consumer.upfort.com/api/partner/subscriptions`
- Auth: API key in header `X-API-Key`

Creates a new Upfort Home subscription for the authenticated partner.

This endpoint is keyed by `permanent_id`, not email. If `email` is present,
Upfort may use it for communications or account linking, but it is not
required and is not the deduplication key.

`sku_code` is resolved through Upfort's partner configuration and maps to
the appropriate internal subscription template or product configuration.

## Request body

- CreateSubscriptionRequest
  - `permanent_id` string, required: Partner's stable identifier for the subscriber, policy, or membership record.
  - `group_id` string: Partner-defined subgroup identifier for attribution, reporting, and partner-side account grouping.
  - `sku_code` string, required: Partner SKU alias or configured canonical Home SKU.
  - `auto_renew` boolean: Optional partner preference for whether the subscription should renew automatically. Final behavior may depend on partner configuration.
  - `first_name` string, required: Subscriber's first name.
  - `last_name` string, required: Subscriber's last name.
  - `email` string, email: Subscriber's email address, when available. Not required and not used as the lifecycle key.
  - `zip_code` string: 5-digit US zip code.
  - `start_date` string, date, required: Subscription effective start date in YYYY-MM-DD format.
  - `phone` string: Subscriber's phone number, when available.
  - `address_line_1` string: Subscriber street address, when available.
  - `address_line_2` string: Additional address details, when available.
  - `unit` string: Apartment, unit, suite, or similar address designator.
  - `city` string: Subscriber city, when available.
  - `state` string: Two-letter US state code, when available.
  - `country` string: ISO 3166-1 alpha-2 country code. Defaults to US when omitted.

## Response `201`

Subscription created.

- SubscriptionResponseEnvelope
  - `success` true, required
  - `data` SubscriptionResponse, required
    - `subscription_id` string, required: Upfort subscription identifier.
    - `permanent_id` string, required: Partner's stable identifier for the subscriber, policy, or membership record.
    - `group_id` string, nullable: Partner-defined subgroup identifier, when provided.
    - `sku_code` string, required: Resolved SKU code for the current subscription.
    - `status` 'active' | 'cancelled' | 'expired' | 'paused', required: Current subscription status.
    - `auto_renew` boolean, nullable: Whether the subscription is configured to renew automatically, when known.
    - `current_period_start` string, date, required: Current subscription period start date.
    - `current_period_end` string, date, nullable: Current subscription period end date, when applicable.
    - `created_at` string, date-time: Timestamp when Upfort created the subscription record.
    - `terminated_at` string, date-time, nullable: Timestamp when Upfort terminated the subscription, when applicable.
  - `timestamp` string, date-time, required

## Other responses

- `400`: Validation error, invalid date, missing zip code, or unknown SKU.
- `401`: Missing or invalid API key.
- `409`: A conflicting subscription already exists for this permanent ID.

---

[API](https://skmtc.dev/upfort/apis/upfort-home-partners-api.md) - [All operations](https://skmtc.dev/upfort/apis/upfort-home-partners-api/llms.txt) - [OpenAPI document](https://skmtc.dev/upfort/apis/upfort-home-partners-api/revisions/1923c2180e6a?raw)