# Promote a stack to organization scope

Every blueprint stack has a scope that determines which resource types it can manage. By default, stacks are scoped to a project. To deploy organization-level resources like scheduled functions, you need to promote the stack to organization scope.

## When you need organization scope

[Scheduled functions](https://www.sanity.io/docs/functions/scheduled-function-quickstart) (`sanity.function.cron`) run on a timer rather than responding to document changes in a specific project. Because they operate independently of any single project, they require organization scope.

If you add a scheduled function to a project-scoped stack and run `sanity blueprints deploy`, the deployment will fail with an error indicating that the resource requires organization scope. Promoting your stack resolves this.

## Prerequisites

- An existing project-scoped blueprint stack. If you have not initialized a blueprint yet, see the [Blueprints introduction](https://www.sanity.io/docs/blueprints/blueprints-introduction) or one of the Blueprint or Function guides.
- A role (such as Administrator) with the `sanity.organization.update` permission on the organization that owns the project. Project-level permissions alone are not sufficient.
- The project must belong to an organization. Standalone projects cannot be promoted.
- No active deployments or operations running on the stack.
- Deploying an organization-scoped blueprint requires an organization admin role, or a robot token with the `sanity.blueprints.deploy` permission.

## Check your current scope

Before promoting, confirm that your stack is currently project-scoped by running the `config` command:

**CLI**

```sh
npx sanity@latest blueprints config
```

If the output shows `Scoped to: Project <id>`, the stack is project-scoped and eligible for promotion.

## Promote the stack

Run the promote command from a directory containing your configured blueprint:

**CLI**

```sh
npx sanity@latest blueprints promote
```

The CLI will ask you to confirm the promotion. After confirming, the command performs a single atomic operation that:

- Changes the stack's scope from project to organization.
- Sets a value on the stack to preserve the original project ID so your existing project-scoped resources continue to work. You can also explicitly set the project for each resource, but this keeps your existing resources working as expected.
- Updates your local `.sanity/blueprint.config.json` by removing `projectId` and adding `organizationId`.

> [!TIP]
> No redeploy needed
> Promotion does not affect the state of already-deployed resources. Your existing document functions, webhooks, CORS origins, and other project-scoped resources continue working without any changes.

You can optionally pass the `--force` flag to skip the confirmation prompt, or `--stack <name-or-id>` to target a specific stack if you have more than one.

## Verify the promotion

After promotion, confirm the scope change by running the `config` command again:

**CLI**

```sh
npx sanity@latest blueprints config
```

The output should now show `Scoped to: Organization <id>`. You can also check `sanity blueprints logs` to see the promotion operation recorded in the stack's history.

## Deploy with scheduled functions

With the stack promoted, you can now define both project-scoped and organization-scoped resources in the same blueprint:

**sanity.blueprint.ts**

```typescript
import {
  defineBlueprint,
  defineDocumentFunction,
  defineScheduledFunction,
} from '@sanity/blueprints'

export default defineBlueprint({
  resources: [
    // Existing project-scoped resource, still works via defaultProjectId
    defineDocumentFunction({
      name: 'on-publish',
      event: {on: ['create', 'update']},
      // Or, explicitly set the project resource:
      project: `<your-project-id>`
    }),

    // New org-scoped resource, enabled by promotion
    defineScheduledFunction({
      name: 'daily-digest',
      event: {expression: '0 9 * * *'}, // you can also use the day, minute, hour, year syntax
    }),
  ],
})
```

When you run `sanity blueprints deploy`, the scope resolver handles each resource appropriately. Project-scoped resources like document functions resolve through `project`, while organization-scoped resources like scheduled functions use the organization scope directly. See each definer’s [reference documentation](https://reference.sanity.io/_sanity/blueprints/) for further configuration details.

## Things to keep in mind

### Promotion is one-way

There is no command to demote a stack back to project scope. Organization scope is strictly broader than project scope, so an org-scoped stack can do everything a project-scoped stack can. If you promote by mistake, your existing resources continue working exactly as before.

### Configuration changes

The promote command automatically updates your `.sanity/blueprint.config.json` file. If your CI/CD pipeline reads from this file, no pipeline changes are needed. However, if your pipeline sets `SANITY_PROJECT_ID` as an environment variable, switch to `SANITY_ORGANIZATION_ID` after promotion.

### Multiple projects

After promotion, the stack is updated with details from the original project. To target resources in a different project, add an explicit `project` attribute to individual resource definitions. This allows a single org-scoped stack to manage resources across multiple projects.

### Stack limits

Stacks are limited to 3 per scope. After promotion, the stack belongs to the organization and is no longer counted against the project's stack limit. Stack names must be unique within a scope. If the organization already has a stack with the same name, the promotion will fail.

## Troubleshooting

### Permission denied (403)

Promotion requires the `sanity.organization.update` permission. If you receive a 403 error, ask an organization administrator to grant you the required permission.

### Operation in progress (409)

You cannot promote a stack while a deployment or other operation is active. Wait for the current operation to complete, then retry the promote command.

### Duplicate stack name

Stack names must be unique within a scope. If the organization already has a stack with the same name, promotion fails with a `DuplicateStackNameError`. To resolve this, destroy and recreate one of the stacks with a different name.

### Stack already promoted

The promote command is idempotent. Running it on an already-promoted stack returns success without making any changes. You can safely retry the command if you are unsure whether a previous promotion completed.