Postman Variable Scopes

Postman stores variables at several levels called scopes. A scope decides where a variable is visible and which value wins when two variables share one name. Mastering scopes prevents the confusing situation where a request uses a value you did not expect.

The Scope Ladder

Think of scopes as nested boxes. The smallest box sits closest to the request and has the highest priority. A variable in a smaller box overrides a variable with the same name in a larger box.

  HIGHEST PRIORITY
  ┌──────────────────────────────────────┐
  │ 1. Local      (one script run)       │
  │ ┌──────────────────────────────────┐ │
  │ │ 2. Data       (runner data file) │ │
  │ │ ┌──────────────────────────────┐ │ │
  │ │ │ 3. Environment (chosen set)  │ │ │
  │ │ │ ┌──────────────────────────┐ │ │ │
  │ │ │ │ 4. Collection            │ │ │ │
  │ │ │ │ ┌──────────────────────┐ │ │ │ │
  │ │ │ │ │ 5. Global (all work) │ │ │ │ │
  │ │ │ │ └──────────────────────┘ │ │ │ │
  │ │ │ └──────────────────────────┘ │ │ │
  │ │ └──────────────────────────────┘ │ │
  │ └──────────────────────────────────┘ │
  └──────────────────────────────────────┘
  LOWEST PRIORITY

Meet Each Scope

Scope	Lifetime	Typical Use
Local	One request run	Temporary values inside a script
Data	One runner iteration	Rows from a CSV or JSON file
Environment	Until you change it	Server URLs and tokens per stage
Collection	Until you change it	Values shared by every request in one collection
Global	Until you change it	Values needed across all collections

Read and Write Variables in Scripts

The pm object offers one method set for each scope.

// Local scope
pm.variables.set("tempId", 42);
pm.variables.get("tempId");

// Environment scope
pm.environment.set("token", "abc123");
pm.environment.get("token");

// Collection scope
pm.collectionVariables.set("page", 1);
pm.collectionVariables.get("page");

// Global scope
pm.globals.set("appName", "ShopApp");
pm.globals.get("appName");

The call pm.variables.get("name") searches every scope in priority order and returns the first match. Use it when you want the winning value without caring about its origin.

Use Variables in Requests

Wrap the variable name in double curly braces anywhere in the URL, headers, params, or body.

GET {{baseUrl}}/users/{{userId}}
Authorization: Bearer {{token}}

Postman highlights resolved variables in orange and unresolved ones in red. Hover over a variable to see its value and the scope it came from.

Priority in Action

Suppose the name baseUrl exists in three places.

  Global       baseUrl = https://api.example.com
  Collection   baseUrl = https://api.example.com/v1
  Environment  baseUrl = https://staging.example.com

  Active environment: Staging
  Winner: https://staging.example.com   (Environment beats Collection and Global)

Remove the environment selection and the collection value wins. Delete the collection variable and the global value takes over.

Initial Value and Current Value

Initial Value

The initial value syncs to the Postman cloud and appears for teammates in shared workspaces. Place only safe, shareable data here.

Current Value

The current value stays on your computer. Postman uses it when sending requests and never uploads it. Passwords and tokens belong in the current value column.

Choosing the Right Scope

• Pick environment variables for anything that changes between dev, staging, and production.
• Pick collection variables for constants tied to a single API, such as a version number.
• Pick global variables rarely. Overuse leads to name clashes between projects.
• Pick local variables for calculations that must vanish after the request ends.

Common Problems

• A variable shows in red because the environment dropdown reads "No Environment".
• A script sets a global value while a stale environment value with the same name hides it.
• A teammate sees an empty value because you typed the secret in the initial column instead of the current column.

Key Points

• Postman offers five scopes: local, data, environment, collection, and global.
• Narrower scopes override broader scopes.
• Curly braces insert variable values into any request field.
• Initial values sync to the cloud, and current values remain private.
• Hovering over a variable reveals its value and source scope.