Skip to main content
POST
Create a pipeline stage

Supported products

Authorizations

Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Scopes

crm.schemas.quotes.write
crm.schemas.invoices.write
crm.schemas.orders.write
crm.schemas.commercepayments.write
crm.schemas.courses.write
tickets.sensitive.v2
e-commerce
crm.schemas.appointments.write
crm.schemas.tasks.write
crm.schemas.contacts.write
crm.schemas.carts.write
crm.schemas.companies.write
crm.objects.tickets.sensitive.write
crm.schemas.subscriptions.write
crm.schemas.emails.write
crm.schemas.custom.write
crm.schemas.listings.write
crm.pipelines.orders.write
crm.objects.users.write
tickets.highly_sensitive.v2
crm.schemas.services.write
crm.schemas.notes.write
crm.objects.orders.write
crm.schemas.meetings.write
crm.schemas.deals.write
crm.schemas.calls.write
crm.objects.carts.write
crm.objects.tickets.highly_sensitive.write

Path Parameters

objectType
string
required
pipelineId
string
required

Body

application/json

An input used to create or replace a pipeline stage's definition.

displayOrder
integer<int32>
required

The order for displaying this pipeline stage. If two pipeline stages have a matching displayOrder, they will be sorted alphabetically by label.

label
string
required

A label used to organize pipeline stages in HubSpot's UI. Each pipeline stage's label must be unique within that pipeline.

metadata
object
required

A JSON object containing properties that are not present on all object pipelines.

For deals pipelines, the probability field is required ({ "probability": 0.5 }), and represents the likelihood a deal will close. Possible values are between 0.0 and 1.0 in increments of 0.1.

For tickets pipelines, the ticketState field is optional ({ "ticketState": "OPEN" }), and represents whether the ticket remains open or has been closed by a member of your Support team. Possible values are OPEN or CLOSED.

stageId
string

Response

successful operation

A pipeline stage definition.

archived
boolean
required

Whether the pipeline is archived.

createdAt
string<date-time>
required

The date the pipeline stage was created. The stages on default pipelines will have createdAt = 0.

displayOrder
integer<int32>
required

The order for displaying this pipeline stage. If two pipeline stages have a matching displayOrder, they will be sorted alphabetically by label.

id
string
required

A unique identifier generated by HubSpot that can be used to retrieve and update the pipeline stage.

label
string
required

A label used to organize pipeline stages in HubSpot's UI. Each pipeline stage's label must be unique within that pipeline.

metadata
object
required

A JSON object containing properties that are not present on all object pipelines.

For deals pipelines, the probability field is required ({ "probability": 0.5 }), and represents the likelihood a deal will close. Possible values are between 0.0 and 1.0 in increments of 0.1.

For tickets pipelines, the ticketState field is optional ({ "ticketState": "OPEN" }), and represents whether the ticket remains open or has been closed by a member of your Support team. Possible values are OPEN or CLOSED.

updatedAt
string<date-time>
required

The date the pipeline stage was last updated.

archivedAt
string<date-time>

The date the pipeline was archived. archivedAt will only be present if the pipeline is archived.

writePermissions
enum<string>

Defines the level of write access for the pipeline stage, with possible values being CRM_PERMISSIONS_ENFORCEMENT, READ_ONLY, or INTERNAL_ONLY.

Available options:
CRM_PERMISSIONS_ENFORCEMENT,
INTERNAL_ONLY,
READ_ONLY
Last modified on March 30, 2026