---
updatedAt: 2026-06-18T14:49:46.000Z
agentTools:
  siteIndex: https://developer.paylocity.com/llms.txt
  projectIndex: https://developer.paylocity.com/integrations/llms.txt
---

# Upsert Subscription

> 🚧 Partner Restricted
> All assessment API endpoints are restricted to assessment providers that have signed a Paylocity technology partnership agreement. 
[Please reach out to our team](https://www.paylocity.com/contact/partner-form/) if you would like to discuss partnership opportunities.

**Summary Description**

This endpoint is used for updating or creating a subscription for a company within Paylocity's platform by the companyId.

**Use Cases**

- Single Subscription Per Company: Each company can have only one subscription, eliminating the need for an ID in the request
- Create or Update: The Partner can use this endpoint to either create a new subscription or update an existing one
- Mandatory Subscription Object: Orders cannot be submitted without a subscription object, subject to confirmation with the partner

# OpenAPI definition

```json
{
  "openapi": "3.0.4",
  "info": {
    "title": "Assessments API",
    "version": "v1"
  },
  "servers": [
    {
      "url": "dc1demogwext.paylocity.com"
    }
  ],
  "paths": {
    "/apiHub/performanceManagement/v1/companies/{companyId}/assessmentOrders/subscription": {
      "put": {
        "tags": [
          "Subscription"
        ],
        "summary": "Upsert Subscription",
        "description": "> 🚧 Partner Restricted\n> All assessment API endpoints are restricted to assessment providers that have signed a Paylocity technology partnership agreement. \n[Please reach out to our team](https://www.paylocity.com/contact/partner-form/) if you would like to discuss partnership opportunities.\n\n**Summary Description**\n\nThis endpoint is used for updating or creating a subscription for a company within Paylocity's platform by the companyId.\n\n**Use Cases**\n\n- Single Subscription Per Company: Each company can have only one subscription, eliminating the need for an ID in the request\n- Create or Update: The Partner can use this endpoint to either create a new subscription or update an existing one\n- Mandatory Subscription Object: Orders cannot be submitted without a subscription object, subject to confirmation with the partner",
        "x-explorer-enabled": false,
        "parameters": [
          {
            "name": "testMode",
            "in": "header",
            "description": "If true all responses are mocked and generated randomly.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "companyId",
            "in": "path",
            "description": "The Paylocity Company Identifier. This is the unique value provided by Paylocity to each specific Payroll Entity.\r\n                **Allowable Values:**\r\n                9 char max.",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "A12345"
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "Authorization token. Ex. Bearer ...",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "The subscription details to be updated or created.",
          "content": {
            "application/json-patch+json": {
              "schema": {
                "$ref": "#/components/schemas/SubscriptionDto"
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubscriptionDto"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/SubscriptionDto"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/SubscriptionDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created - Resource has been created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionDto"
                }
              }
            }
          },
          "204": {
            "description": "No Content - Resource has been updated."
          },
          "400": {
            "description": "Bad Request - Returns the details of the error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericErrorResponse"
                }
              }
            }
          },
          "415": {
            "description": "Unsupported Media Type - Returns the details of the error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BillingCodeDto": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "The Billing code created on your side that applies to the client specifically for invoicing purposes.\r\nMax length = 150.\r\nRequired.",
            "nullable": true
          },
          "isActive": {
            "type": "boolean",
            "description": "Optional field to make a billing code active or inactive.\r\nIf active, it will show in the UI for users to select for a specific job.\r\nInactive codes will not show in the UI.\r\nOptional."
          }
        },
        "additionalProperties": {
          "type": "object",
          "nullable": true
        },
        "description": "Billing code payload."
      },
      "ErrorDto": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "nullable": true
          },
          "message": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": {
          "type": "object",
          "nullable": true
        }
      },
      "GenericErrorResponse": {
        "type": "object",
        "properties": {
          "correlationId": {
            "type": "string",
            "nullable": true
          },
          "value": {
            "$ref": "#/components/schemas/ErrorDto"
          },
          "count": {
            "type": "integer",
            "description": "Gets the count of items in the Values list.",
            "format": "int32",
            "nullable": true,
            "readOnly": true
          },
          "values": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ValidationErrorDto"
            },
            "description": "A list of items.",
            "nullable": true
          }
        },
        "additionalProperties": {
          "type": "object",
          "nullable": true
        }
      },
      "SubscriptionDto": {
        "type": "object",
        "properties": {
          "level": {
            "type": "string",
            "description": "The level of the client's subscription (e.g., premium, basic, etc.).\r\nMax length = 150. Optional.",
            "nullable": true
          },
          "price": {
            "type": "number",
            "description": "The value of the subscription.\r\nOptional.",
            "format": "double",
            "nullable": true
          },
          "currency": {
            "type": "string",
            "description": "The currency code (USD, EUR, GBP, CAD...).\r\nOptional.",
            "nullable": true
          },
          "term": {
            "type": "string",
            "description": "The term of the client's subscription (e.g., monthly, quarterly, annually).\r\nMax length = 150. Optional.",
            "nullable": true
          },
          "expirationDate": {
            "type": "string",
            "description": "The date the subscription will expire (in UTC).\r\nOptional.",
            "format": "date-time",
            "nullable": true
          },
          "billingCodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BillingCodeDto"
            },
            "description": "An array of billing codes.\r\nOptional.",
            "nullable": true
          }
        },
        "additionalProperties": {
          "type": "object",
          "nullable": true
        },
        "description": "Subscription payload."
      },
      "ValidationErrorDto": {
        "type": "object",
        "properties": {
          "fields": {
            "type": "string",
            "description": "Gets or sets a string detailing the fields involved in the validation error.",
            "nullable": true
          },
          "code": {
            "type": "string",
            "nullable": true
          },
          "message": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": {
          "type": "object",
          "nullable": true
        }
      }
    }
  }
}
```