---
title: "Subscription"
method: POST
path: "/workspaces/{workspace_id}/subscription"
tags: ["subscription"]
---

# Subscription

`POST /workspaces/{workspace_id}/subscription`

## Request

- Base URL: `https://localhost:8080/api/v9`
- URL: `https://localhost:8080/api/v9/workspaces/{workspace_id}/subscription`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/toggl/apis/toggl-api/docs/workspaces/:workspace_id/subscription/post.ts> (a function with typed inputs; its response is checked against the schema)

Allows to create a new subscription, cancel existing one or change the pricing plan.

## Path parameters

- `workspace_id` integer, required

## Request body

- SubscriptionPayload
  - `contact_details` SubscriptionContactDetailRequest
    - `company_address` string, required
    - `company_city` string
    - `company_name` string, required
    - `contact_email` string, required
    - `contact_person` string
    - `country_id` integer, required
    - `country_subdivision_id` integer: CountrySubdivisionID is the ID of the country subdivision (state in USA) This field is required if country_id == 235 (United states)
    - `subDivision` ModelsSubdivision
      - `company_id` integer
      - `country_id` integer
      - `country_subdivision_id` integer
      - `iso_code` string
      - `name` string
    - `tax_number` string
    - `zip_code` string: ZIPCode field is required if country_id == 235 (United states)
  - `inc_terms_accepted` boolean: True if user accepted ToS for the Toggl Inc company. Ignored if company is not customer of Toggl INC.
  - `master_signup` boolean: True if user want to sign up to the Master program.
  - `pricing_plan_id` integer, required: Numeric ID of the pricing plan.

## Response `200`

Returns subscription data.

- ModelsSubscription
  - `auto_renew` boolean
  - `card_details` ModelsCardDetails
    - `added_at` string
    - `card_number` string
    - `card_type` string
    - `creator_id` integer
    - `creator_name` string
    - `expiry_date` string
    - `holder_name` string
  - `company_id` integer
  - `contact_detail` ModelsContactDetail
    - `company_address` string
    - `company_city` string
    - `company_name` string
    - `contact_detail_id` integer
    - `contact_email` string
    - `contact_person` string
    - `country_id` integer
    - `country_subdivision_id` integer
    - `created_at` string
    - `customer_id` integer
    - `is_eu_resident` boolean
    - `updated_at` string
    - `user_id` integer
    - `vat_number` string
    - `vat_number_valid` boolean: DEPRECATED
    - `vat_number_validated_at` string: DEPRECATED
    - `zip_code` string
  - `created_at` string, date-time
  - `currency` string
  - `customer_id` integer
  - `deleted_at` string, date-time
  - `last_pricing_plan_id` integer
  - `organization_id` integer
  - `payment_details` ModelsPaymentDetail
    - `created_at` string
    - `currency` string
    - `customer_id` integer
    - `payment_type` string
    - `reference` string
    - `user_id` integer
  - `pricing_plan_id` integer
  - `renewal_at` string, date-time
  - `subscription_id` integer
  - `subscription_period` ModelsPeriod
    - `created_at` string
    - `finished_on` string
    - `started_on` string
    - `subscription_id` integer
    - `subscription_period_id` integer
    - `trial` boolean
    - `user_count` integer
  - `workspace_id` integer

## Other responses

- `400`: Possible error messages: * pricing\_plan\_id required * the company\_name field is required * the company\_address field is required * Missing e-mail * Invalid e-mail: * country\_id invalid * invalid country\_subdivision\_id * invalid country/subdivision combination * the country\_subdivision\_id field is required for US customers * the zip\_code field is required for US customers * invalid zip\_code * Pricing Plan Id must be valid * No subscription to cancel * Workspace with subscription already present in organization
- `403`: Admin permissions required.
- `404`: Possible error messages: * Pricing Plan Id must be valid * Workspace not found/accessible
- `500`: Internal Server Error

---

[API](https://skmtc.dev/toggl/apis/toggl-api.md) - [All operations](https://skmtc.dev/toggl/apis/toggl-api/llms.txt) - [OpenAPI document](https://skmtc.dev/toggl/apis/toggl-api/revisions/3085aee16990?raw)