Customers

Merge two customers

Changed on Nov 3, 2026

Merge two customers according to the data sent in the payload. The data of the source customer will be merged into the target customer and then deleted. In case both customers have data for the same integration a conflict will occur with the API returning an error.

put/api/customers/merge

Request

Base URL
https://your-domain.gorgias.com
Auth
HTTP basic
TypeScript
https://skmtc.dev/gorgias/apis/gorgias-rest-api/docs/api/customers/merge/put.ts
A function with typed inputs. Its response is checked against the schema.

Query parameters

source_idinteger required

Example:4

The ID of the customer to merge (which will be merged into the targeted customer).

target_idinteger required

Example:4

The ID of the targeted customer (which will still be here after the merge).

Request body

emailstring email nullable

Primary email address of the customer.

external_idstring nullable

ID of the customer in a foreign system (Stripe, Aircall, etc...). This field is not used by Gorgias, feel free to set it as you wish.

language'aa' | 'ab' | 'af' | 'ak' | 'sq' | 'am' | 'ar' | 'an' | 'hy' | 'as' | 'av' | 'ae' | 'ay' | 'az' | 'ba' | 'bm' | 'eu' | 'be' | 'bn' | 'bh' | 'bi' | 'bs' | 'br' | 'bg' | 'my' | 'ca' | 'ch' | 'ce' | 'zh' | 'cu' | 'cv' | 'kw' | 'co' | 'cr' | 'cs' | 'da' | 'dv' | 'nl' | 'dz' | 'en' | 'eo' | 'et' | 'ee' | 'fo' | 'fj' | 'fi' | 'fr' | 'fy' | 'ff' | 'ka' | 'de' | 'gd' | 'ga' | 'gl' | 'gv' | 'el' | 'gn' | 'gu' | 'ht' | 'ha' | 'he' | 'hz' | 'hi' | 'ho' | 'hr' | 'hu' | 'ig' | 'is' | 'io' | 'ii' | 'iu' | 'ie' | 'ia' | 'id' | 'ik' | 'it' | 'jv' | 'ja' | 'kl' | 'kn' | 'ks' | 'kr' | 'kk' | 'km' | 'ki' | 'rw' | 'ky' | 'kv' | 'kg' | 'ko' | 'kj' | 'ku' | 'lo' | 'la' | 'lv' | 'li' | 'ln' | 'lt' | 'lb' | 'lu' | 'lg' | 'mk' | 'mh' | 'ml' | 'mi' | 'mr' | 'ms' | 'mg' | 'mt' | 'mn' | 'na' | 'nv' | 'nr' | 'nd' | 'ng' | 'ne' | 'nn' | 'nb' | 'no' | 'ny' | 'oc' | 'oj' | 'or' | 'om' | 'os' | 'pa' | 'fa' | 'pi' | 'pl' | 'pt' | 'ps' | 'qu' | 'rc' | 'rm' | 'ro' | 'rn' | 'ru' | 'sg' | 'sa' | 'si' | 'sk' | 'sl' | 'se' | 'sm' | 'sn' | 'sd' | 'so' | 'st' | 'es' | 'sc' | 'sr' | 'ss' | 'su' | 'sw' | 'sv' | 'ty' | 'ta' | 'tt' | 'te' | 'tg' | 'tl' | 'th' | 'bo' | 'ti' | 'to' | 'tn' | 'ts' | 'tk' | 'tr' | 'tw' | 'ug' | 'uk' | 'ur' | 'uz' | 've' | 'vi' | 'vo' | 'cy' | 'wa' | 'wo' | 'xh' | 'yi' | 'yo' | 'za' | 'zu' nullable

The customer's preferred language (format: ISO_639-1).

namestring nullable

Full name of the customer.

The customer's preferred timezone (format: IANA timezone name).

Example request

{
  "channels": [
    {
      "type": "email",
      "address": "john@example.com",
      "preferred": true
    }
  ],
  "email": "john@example.com",
  "external_id": "customer-84203241",
  "language": "fr",
  "name": "John Smith",
  "timezone": "UTC"
}

Response

The updated target customer.

idinteger

ID of the customer.

created_datetimestring date-time nullable

When the customer was created.

emailstring email nullable

Primary email address of the customer.

external_idstring nullable

ID of the customer in a foreign system (Stripe, Aircall, etc...). This field is not used by Gorgias, feel free to set it as you wish.

firstnamestring

First name of the customer.

integrationsobject

Data coming from integrations (Shopify, Recharge, HTTP, etc...) associated with the customer. Keys of the object are integration IDs, values are raw data collected from the integrations.

The customer's preferred language (format: ISO_639-1).

lastnamestring

Last name of the customer.

namestring nullable

Full name of the customer.

notestring nullable

A note associated with the customer.

The customer's preferred timezone (format: IANA timezone name).

updated_datetimestring date-time nullable

When the customer was last updated.

external_dataobject

The external (third-party) application data of the customer, keyed by the OAuth2 client ID of the application.

ecommerce_dataobject

The ecommerce data of the customer, keyed by store uuid.

Example response

{
  "id": 3924,
  "channels": [
    {
      "id": 49182
    }
  ],
  "created_datetime": "2019-04-13T03:27:56.973873",
  "email": "john@example.com",
  "external_id": "customer-84203241",
  "firstname": "John",
  "integrations": {
    "6": {
      "orders": [
        {
          "id": 772803526679,
          "total_tax": "0.02",
          "created_at": "2018-12-04T03:29:37-08:00",
          "line_items": [
            {
              "id": 1760305053719,
              "sku": "0987654321",
              "name": "Acidulous candy",
              "grams": 10,
              "price": "0.10",
              "title": "acidulous candy",
              "taxable": true,
              "quantity": 1,
              "price_set": {
                "shop_money": {
                  "amount": "0.10",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "0.10",
                  "currency_code": "USD"
                }
              },
              "tax_lines": [
                {
                  "rate": 0.2,
                  "price": "0.02",
                  "title": "tva",
                  "price_set": {
                    "shop_money": {
                      "amount": "0.02",
                      "currency_code": "USD"
                    },
                    "presentment_money": {
                      "amount": "0.02",
                      "currency_code": "USD"
                    }
                  }
                }
              ],
              "product_id": 8345093387,
              "variant_id": 28442938955,
              "total_discount": "0.00",
              "requires_shipping": true,
              "fulfillment_status": null,
              "total_discount_set": {
                "shop_money": {
                  "amount": "0.00",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "0.00",
                  "currency_code": "USD"
                }
              },
              "fulfillment_service": "manual",
              "fulfillable_quantity": 1
            }
          ],
          "contact_email": "marie@gorgias.io",
          "billing_address": {
            "zip": "94103",
            "city": "SAN FRANCISCO",
            "name": "Marie Curie",
            "country": "United States",
            "address1": "52 Washburn Street",
            "address2": "",
            "province": "California",
            "last_name": "Curie",
            "first_name": "Marie",
            "country_code": "US",
            "province_code": "CA"
          }
        }
      ],
      "customer": {
        "id": 667928133655,
        "note": "",
        "tags": "",
        "email": "marie@gorgias.io",
        "first_name": "Marie",
        "last_name": "Curie",
        "orders_count": 1,
        "default_address": {
          "id": 707106144279,
          "zip": "94103",
          "city": "SAN FRANCISCO",
          "name": "Marie Curie",
          "country": "United States",
          "default": true,
          "address1": "52 Washburn Street",
          "address2": "",
          "province": "California",
          "last_name": "Curie",
          "first_name": "Marie",
          "customer_id": 667928133655,
          "country_code": "US",
          "country_name": "United States",
          "province_code": "CA"
        }
      },
      "__integration_type__": "shopify"
    }
  },
  "language": "fr",
  "lastname": "Smith",
  "name": "John Smith",
  "note": "Our best customer.",
  "timezone": "UTC",
  "updated_datetime": "2019-09-25T06:18:22.839271",
  "external_data": {
    "my-awesome-3rd-party-app-ID": {
      "badge": "Best customer",
      "points": 22,
      "__app_name__": "My awesome 3rd party app"
    }
  }
}

Changes

Nov 3, 20263fdfcb5b6678 Revision changes
- breaking
  the response's property type changed from array to object for status

Operation history