---
title: "Merge"
description: "Merge"
url: "https://www.contentstack.com/docs/developers/sdks/content-management-sdk/java/reference/merge"
product: "Contentstack"
doc_type: "guide"
audience:
  - developers
  - admins
version: "current"
last_updated: "2026-11-18"
---

# Merge

## Merge

A merge copies the changes in a compare branch into a base branch, by the merge strategy you choose. Use this class to

*   merge a branch into the base branch
*   list the recent merge jobs of the stack
*   read the status of one merge job

stack.branch("<BRANCH>").mergeQueue() returns a Merge with <BRANCH> as the base branch. Merge has no public constructor.

Name

Type

Description

branchUid

String

UID of the base branch. Pass it to stack.branch() before you call mergeQueue().

*   **Known issue:** In 1.16.0, a Merge object does not carry the api\_key and authorization headers of the stack, so its requests reach the API without credentials. Add both with [addHeader](/docs/developers/sdks/content-management-sdk/java/reference/merge#merge-addheader) on the Merge object, as every example on this page does.

## addHeader

addHeader adds one request header to this merge object.

```
Returns: Merge. The same merge object, for chaining.
ValidationThere is no client-side validation. A null key or value does not throw here.execute() throws IllegalArgumentException for a null key or value, because Retrofit rejects null entries in a header map.An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.Additional Resource: Refer to Content Management API Errors for the full error code list.
BehavioraddHeader stores the header in the header map of this object and sends nothing.A later call with the same name replaces the value.The header goes on every request of this merge object: branch, find, and fetch, and stays there for every later request.A new Merge object holds only a Content-Type header. It does not carry the api_key and authorization headers of the stack, so add them with this method before you send a request.ExampleBasic usage: add the stack credentials and list merge jobsimport com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Merge;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListMergeJobs {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();

        Merge merge = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
                .branch("main")
                .mergeQueue()
                // The Merge object does not inherit the stack credentials
                .addHeader("api_key", "<API_KEY>")
                .addHeader("authorization", "<MANAGEMENT_TOKEN>");

        Response<ResponseBody> response = merge.find().execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}
```

Name of the header.

Value of the header.

## addHeaders

addHeaders adds every entry of a map to the request headers of this merge object.

```
Returns: Merge. The same merge object, for chaining.
ValidationThrows NullPointerException if headers is null, because addHeaders copies every entry of the map.execute() throws IllegalArgumentException for a null key or value in the map, because Retrofit rejects null entries in a header map.An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.Additional Resource: Refer to Content Management API Errors for the full error code list.
BehavioraddHeaders copies the entries into the header map of this object and sends nothing.An entry replaces a header with the same name.The headers go on every request of this merge object: branch, find, and fetch, and stay there for every later request.A new Merge object holds only a Content-Type header. It does not carry the api_key and authorization headers of the stack, so add them with this method before you send a request.ExampleBasic usage: add the stack credentials from a mapimport com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Merge;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;
import java.util.HashMap;

public class ListMergeJobsWithHeaderMap {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();

        HashMap<String, String> headers = new HashMap<>();
        headers.put("api_key", "<API_KEY>");
        headers.put("authorization", "<MANAGEMENT_TOKEN>");

        Merge merge = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
                .branch("main")
                .mergeQueue()
                .addHeaders(headers);

        Response<ResponseBody> response = merge.find().execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}
```

Header names mapped to their values.

## addParam

addParam adds one query parameter to this merge object.

```
Returns: Merge. The same merge object, for chaining.
ValidationThere is no client-side validation. A null key or value does not throw here.execute() throws IllegalArgumentException for a null key or value, because Retrofit rejects null entries in a query map.An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.Additional Resource: Refer to Content Management API Errors for the full error code list.
BehavioraddParam stores the pair in the query parameter map of this object and sends nothing.A later call with the same key replaces the value.The parameter goes on every request of this merge object: branch, find, and fetch.The parameter stays on the object for every later request.The map already holds base_branch, the UID of the branch you called mergeQueue() on. A base_branch key that you add replaces it.ExampleBasic usage: merge into a different base branchimport com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Merge;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;

public class MergeIntoDevelopment {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();

        Merge merge = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
                .branch("main")
                .mergeQueue()
                .addHeader("api_key", "<API_KEY>")
                .addHeader("authorization", "<MANAGEMENT_TOKEN>")
                // Replaces base_branch "main", which mergeQueue() set
                .addParam("base_branch", "development");

        Response<ResponseBody> response = merge
                .branch("docs-test-branch", new JSONObject(), "merge_prefer_base", "Merge docs-test-branch into development")
                .execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}
```

Name of the query parameter.

Value of the query parameter, sent as its string form.

## addParams

addParams adds every entry of a map to the query parameters of this merge object.

```
Returns: Merge. The same merge object, for chaining.
ValidationThrows NullPointerException if params is null, because addParams copies every entry of the map.execute() throws IllegalArgumentException for a null key or value in the map, because Retrofit rejects null entries in a query map.An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.Additional Resource: Refer to Content Management API Errors for the full error code list.
BehavioraddParams copies the entries into the query parameter map of this object and sends nothing.An entry replaces a parameter with the same name.The parameters go on every request of this merge object: branch, find, and fetch.The parameters stay on the object for every later request.The map already holds base_branch, the UID of the branch you called mergeQueue() on. A base_branch key that you add replaces it.ExampleBasic usage: set the base branch from a mapimport com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Merge;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;
import java.util.HashMap;

public class MergeWithParamMap {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();

        HashMap<String, Object> params = new HashMap<>();
        params.put("base_branch", "development");

        Merge merge = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
                .branch("main")
                .mergeQueue()
                .addHeader("api_key", "<API_KEY>")
                .addHeader("authorization", "<MANAGEMENT_TOKEN>")
                .addParams(params);

        Response<ResponseBody> response = merge
                .branch("docs-test-branch", new JSONObject(), "merge_prefer_base", "Merge docs-test-branch into development")
                .execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}
```

Query parameter names mapped to their values.

## branch

branch builds the request that merges the compare branch you name into the base branch of this Merge, by the merge strategy you choose.

```
Returns: Call<ResponseBody>. The request that merges the compare branch into the base branch, sent when you call execute().
ValidationThere is no client-side validation of the four arguments.execute() throws IllegalArgumentException if requestBody is null, because Retrofit cannot build a request without a body. It throws the same exception if compareBranch, defaultMergeStrategy, or mergeComment is null, because Retrofit rejects null entries in a query map.An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().Additional Resource: Refer to Content Management API Errors for the full error code list.
BehaviorOne execute() sends one Merge branches request (POST /stacks/branches_merge) with requestBody as the JSON body.branch puts compare_branch, default_merge_strategy, and merge_comment into the query parameters of this object, beside base_branch. The values stay on the object, so later find and fetch requests send them too.The API reference lists the following seven values for defaultMergeStrategy:merge_prefer_base: merges the compare branch into the base branch and keeps the base branch changes on a conflict.merge_prefer_compare: merges the compare branch into the base branch and keeps the compare branch changes on a conflict.overwrite_with_compare: replaces the base branch with the compare branch and discards changes that are not in the compare branch.merge_new_only: adds only new items from the compare branch and ignores modified items.merge_modified_only_prefer_base: merges only modified items and keeps the base branch changes on a conflict.merge_modified_only_prefer_compare: merges only modified items and keeps the compare branch changes on a conflict.ignore: merges nothing directly. Pass item_merge_strategies in the body to choose a strategy per item.The merge covers content types and global fields only.The API responds with a merge job and its status before the merge finishes. Read the job with fetch.ExampleBasic usage: merge a branch into main, preferring main on conflictsimport com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Merge;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;

public class MergeBranch {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();

        // The Merge object does not inherit the stack credentials, so add them here
        Merge merge = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
                .branch("main")
                .mergeQueue()
                .addHeader("api_key", "<API_KEY>")
                .addHeader("authorization", "<MANAGEMENT_TOKEN>");

        Response<ResponseBody> response = merge
                .branch("docs-test-branch", new JSONObject(), "merge_prefer_base", "Merge docs-test-branch into main")
                .execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}All parameters: choose a strategy per content typeimport com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Merge;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;
import java.util.Collections;

public class MergeBranchPerItem {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();

        Merge merge = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
                .branch("main")
                .mergeQueue()
                .addHeader("api_key", "<API_KEY>")
                .addHeader("authorization", "<MANAGEMENT_TOKEN>");

        // With the "ignore" default, only the listed items merge
        JSONObject item = new JSONObject();
        item.put("uid", "<CONTENT_TYPE_UID>");
        item.put("type", "content_type");
        item.put("merge_strategy", "merge_prefer_compare");
        JSONObject body = new JSONObject();
        body.put("item_merge_strategies", Collections.singletonList(item));

        Response<ResponseBody> response = merge
                .branch("docs-test-branch", body, "ignore", "Merge one content type from docs-test-branch")
                .execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}
```

UID of the branch whose changes you merge.

Request body. Pass an empty object when you need no per-item strategy.

Overrides the default strategy for specific content types or global fields.

Merge strategy for every item, for example merge\_prefer\_base.

Comment that the merge shows.

## fetch

fetch builds the request that reads the status and configuration of one merge job.

```
Returns: Call<ResponseBody>. The request for the merge job, sent when you call execute().
ValidationThere is no client-side validation of mergeJobUid.execute() throws IllegalArgumentException if mergeJobUid is null, because Retrofit cannot fill the request path with null.An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().Additional Resource: Refer to Content Management API Errors for the full error code list.
BehaviorOne execute() sends one Get single merge job request (GET /stacks/branches_queue/{merge_job_uid}) with the headers and query parameters of this object.The response of branch carries the UID of the merge job it started.ExampleBasic usage: read the status of a merge jobimport com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Merge;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchMergeJob {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();

        // The Merge object does not inherit the stack credentials, so add them here
        Merge merge = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
                .branch("main")
                .mergeQueue()
                .addHeader("api_key", "<API_KEY>")
                .addHeader("authorization", "<MANAGEMENT_TOKEN>");

        Response<ResponseBody> response = merge.fetch("<JOB_UID>").execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}
```

UID of the merge job to read.

## find

find builds the request that lists the recent merge jobs of the stack.

```
Returns: Call<ResponseBody>. The request for the recent merge jobs, sent when you call execute().
ValidationThere is no client-side validation.An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().Additional Resource: Refer to Content Management API Errors for the full error code list.
BehaviorOne execute() sends one Get all merge jobs request (GET /stacks/branches_queue) with the headers and query parameters of this object.The query parameters always include base_branch, and the values from an earlier branch call on the same object. The API reference lists no query parameters for this request.The API returns the last 100 merge jobs by default.ExampleBasic usage: list the recent merge jobsimport com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Merge;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListMergeJobs {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();

        // The Merge object does not inherit the stack credentials, so add them here
        Merge merge = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
                .branch("main")
                .mergeQueue()
                .addHeader("api_key", "<API_KEY>")
                .addHeader("authorization", "<MANAGEMENT_TOKEN>");

        Response<ResponseBody> response = merge.find().execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}
```

## Merge | Java Management SDK | Contentstack

The Merge class in the Java Management SDK merges a compare branch into a base branch and reads the status of merge jobs.