---
title: "Merge a branch"
method: PATCH
path: "/projects/{project_id}/branches/{name}/merge"
tags: ["Branches"]
---

# Merge a branch

`PATCH /projects/{project_id}/branches/{name}/merge`

Merge an existing branch back into its base branch.

The merge runs asynchronously. The branch transitions to `merging_branch` and settles in `merged`, `merge_error`, or `merge_conflict` once the background job completes; the response body for this request is empty. Poll the branch resource to observe the final state.

A branch cannot be merged while it still has open jobs or open translation orders attached to its branch project — in that case the request is rejected with `409 Conflict`. A branch whose current `state` does not allow a merge is rejected with `422 Unprocessable Entity`.

Requires the Branching feature to be enabled on the account.

*Note: Merging a branch may take several minutes depending on diff size.*

## Path parameters

- `project_id` string, required
- `name` string, required

## Headers

- `X-PhraseApp-OTP` string

## Request body

- object
  - `strategy` 'use_main' | 'use_branch' — Conflict resolution strategy applied when the branch and its base have diverged. `use_main` keeps the values from the base branch; `use_branch` keeps the values from the branch being merged.

## Response `200`

OK. The merge has been scheduled. The response body is empty; observe progress by polling the branch resource.

## Other responses

- `400` — Bad request. The request could not be parsed or a parameter failed validation. Verify the request body, the content type, and the parameter types, then retry.
- `401` — Unauthorized. Authentication failed because the access token is missing, expired, or invalid. Supply a valid access token and retry.
- `403` — Forbidden. The credentials are valid but not permitted for this request: the access token may lack the required scope, the user may lack permission on the resource, or the account plan may not include the feature. Use a token with the required scope on an account and user that hold the necessary permissions.
- `404` — Not found. The requested resource does not exist or is not visible to the authenticated user. Verify the identifiers in the request path and that the token has access to them, then retry.
- `409` — Conflict. The request conflicts with the current state of the resource. Reconcile the conflicting state and retry.
- `422` — Unprocessable entity. The request was well-formed but failed validation. The response body lists each offending field in the `errors` array, with its resource, field, and a human-readable message. Correct the listed fields and retry.
- `429` — Too many requests. The rate limit has been exceeded. Wait until the time indicated by the `X-Rate-Limit-Reset` response header before retrying.

---

[API](https://skmtc.net/phrase/apis/control-hub-service.md) · [All operations](https://skmtc.net/phrase/apis/control-hub-service/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/phrase/control-hub-service/revisions/98ecac7ba2bf/schema)