--- title: Merchant Analytics Requests slug: merchant-analytics-requests description: Learn how to use Butter's Merchant Analytics Requests API to collect customer analytics during server-side checkout, aiding in future dispute prevention. docTags: createdAt: 2024-12-09T23:31:31.548Z --- { "id": "ugwtRLKWKxxrcVGFyzowz", "type": "api-oas-v2", "data": { "method": "POST", "url": "https://api.disputes.services.butterpayments.com/v1/analytics/", "servers": [ { "url": "https://api.disputes.services.butterpayments.com/v1/analytics/" } ], "name": "Merchant Analytics Requests", "description": "

This endpoint is used to get customer analytics from the merchant's server-side checkout flow.

\n

The following are required fields:

\n\n

The following are conditionally required fields, at least one must be present, the more information provided the more accurate dispute matching will be:

\n\n

The following are optional fields:

\n", "contentType": "application/json", "request": { "pathParameters": [], "headerParameters": [], "queryParameters": [], "bodyDataParameters": [ { "kind": "required", "name": "body", "type": "object", "description": "", "customType": "DisputeMerchantAnalyticsCreate", "schema": [ { "name": "customer_email", "kind": "required", "type": "string", "example": "" }, { "name": "ipv4_address", "kind": "required", "type": "string", "example": "" }, { "name": "psp", "kind": "required", "type": "string", "description": "", "modelRef": "#/components/schemas/PSP", "customType": "PSP", "schema": [] }, { "name": "user_agent", "kind": "optional", "type": "string", "example": "" }, { "name": "customer_id", "kind": "optional", "type": "string", "example": "" }, { "name": "invoice_id", "kind": "optional", "type": "string", "example": "" }, { "name": "subscription_id", "kind": "optional", "type": "string", "example": "" }, { "name": "charge_id", "kind": "optional", "type": "string", "example": "" }, { "name": "transaction_id", "kind": "optional", "type": "string", "example": "" }, { "name": "network_transaction_id", "kind": "optional", "type": "string", "example": "" } ], "modelRef": "#/components/schemas/DisputeMerchantAnalyticsCreate", "isExpanded": true } ], "formDataParameters": [], "oAuthParameters": [ { "id": "HTTPBasic", "name": "HTTPBasic", "kind": "optional", "type": "http", "scheme": "basic" } ] }, "responses": [ { "statusCode": "200", "description": "Successful Response", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "DisputeMerchantAnalyticsResponse", "schema": [ { "name": "id", "kind": "required", "type": "string", "example": "" } ], "modelRef": "#/components/schemas/DisputeMerchantAnalyticsResponse", "isExpanded": true } ] }, { "statusCode": "422", "description": "Validation Error", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "HTTPValidationError", "schema": [ { "name": "detail", "kind": "optional", "type": "array", "description": "", "modelRef": "#/components/schemas/ValidationError", "customType": "ValidationError[]", "schema": [ { "name": "loc", "kind": "required", "type": "array", "example": "", "itemType": "object", "customType": "object[]", "itemExample": "", "itemDefault": "" }, { "name": "msg", "kind": "required", "type": "string", "example": "" }, { "name": "type", "kind": "required", "type": "string", "example": "" } ] } ], "modelRef": "#/components/schemas/HTTPValidationError", "isExpanded": true } ] } ], "examples": { "languages": [ { "id": "dNMsHlfN6kdd1TZTpm7N9", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://api.disputes.services.butterpayments.com/v1/analytics/ \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data '{\n \"customer_email\": \"\",\n \"ipv4_address\": \"\",\n \"psp\": \"\"\n }'" }, { "id": "Tzt6uu9QJUyOJuLp8jUjb", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar raw = JSON.stringify({\n \"customer_email\": \"\",\n \"ipv4_address\": \"\",\n \"psp\": \"\"\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://api.disputes.services.butterpayments.com/v1/analytics/\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "61l2z8wTZK6dDyiKsxam8", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.disputes.services.butterpayments.com/v1/analytics/\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest.body = JSON.dump({\n \"customer_email\": \"\",\n \"ipv4_address\": \"\",\n \"psp\": \"\"\n})\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "32pfR3f8QG0lICWP70GRx", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api.disputes.services.butterpayments.com/v1/analytics/\"\n\npayload = json.dumps({\n \"customer_email\": \"\",\n \"ipv4_address\": \"\",\n \"psp\": \"\"\n})\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "dNMsHlfN6kdd1TZTpm7N9" }, "results": { "languages": [ { "id": "xZecBAo9iVSczTWDceDLv", "language": "200", "code": "// Successful Response\n{\n \"id\": \"\"\n}" }, { "id": "sEAN7ApmohDKf0tDVPVLY", "language": "422", "code": "// Validation Error\n{\n \"detail\": [\n {\n \"loc\": [\n {}\n ],\n \"msg\": \"\",\n \"type\": \"\"\n }\n ]\n}" } ], "selectedLanguageId": "xZecBAo9iVSczTWDceDLv" } }, "children": [ { "id": "4-nkQdyZTS9dYW03Q94VL", "type": "paragraph", "children": [ { "text": "This endpoint is used to get customer analytics from the merchant's server-side checkout flow." } ] }, { "id": "rBoM4DnSi_H29MelW8X3R", "type": "paragraph", "children": [ { "text": "The following are required fields:" } ] }, { "id": "qdTHESONFnGSALd5MU-tH", "type": "bulleted-list", "children": [ { "id": "-4xwGulS5SUFCQ-APg2AX", "type": "list-item", "children": [ { "id": "_IUJ8cDCkbemXhuzEaJ2p", "type": "list-item-child", "children": [ { "text": "customer_email", "highlight": true }, { "text": ": A valid email address for the customer associated with the transaction." } ] } ] }, { "id": "Zggsb3So-WqG4UdUnGVLm", "type": "list-item", "children": [ { "id": "m60ciXIFG46vxt_FWJOqB", "type": "list-item-child", "children": [ { "text": "ipv4_address", "highlight": true }, { "text": ": The IPV4 address of the customer found in the request headers during checkout." } ] } ] }, { "id": "oFYdfWUUdGcOCxWSFoa34", "type": "list-item", "children": [ { "id": "CPPFkSV_wXCVZldQYT4Go", "type": "list-item-child", "children": [ { "text": "psp", "highlight": true }, { "text": ": The payment service provider used to process the transaction." } ] } ] } ] }, { "id": "ZVkd9nWW13xG8gAN2Y1mT", "type": "paragraph", "children": [ { "text": "The following are conditionally required fields, at least one must be present, the more information provided the more accurate dispute matching will be:" } ] }, { "id": "mqBlOVuE-50j-virUaijh", "type": "bulleted-list", "children": [ { "id": "vYuWD56LWIodH8oNQQIsm", "type": "list-item", "children": [ { "id": "6KeDgdWZg_GcUZlEYFJSu", "type": "list-item-child", "children": [ { "text": "invoice_id", "highlight": true }, { "text": ": The invoice ID associated with the transaction in the respective PSP." } ] } ] }, { "id": "_oYbXEphCDwTjrTYV7ZWb", "type": "list-item", "children": [ { "id": "iZzSI62s_crsrPaP2iX2l", "type": "list-item-child", "children": [ { "text": "subscription_id", "highlight": true }, { "text": ": The subscription ID associated with the transaction in the respective PSP." } ] } ] }, { "id": "KQ1ltpzfZQ4g8dIk2LAoA", "type": "list-item", "children": [ { "id": "zg4D4Z5RMU2N1_2xTrW62", "type": "list-item-child", "children": [ { "text": "charge_id", "highlight": true }, { "text": ": The charge ID associated with the transaction in the respective PSP." } ] } ] }, { "id": "hAmCkXhivta0puDVrXIJ_", "type": "list-item", "children": [ { "id": "4_LyTPU8YmKb6YDx6zN4j", "type": "list-item-child", "children": [ { "text": "transaction_id", "highlight": true }, { "text": ": The transaction ID associated with the transaction in the respective PSP." } ] } ] }, { "id": "ayxxD7P36WaKD7vSwqig8", "type": "list-item", "children": [ { "id": "HZq0dmhbjHa5o1fDniJBS", "type": "list-item-child", "children": [ { "text": "network_transaction_id", "highlight": true }, { "text": ": The network transaction ID associated with the transaction in the respective card network." } ] } ] } ] }, { "id": "LMVKXdhEih0BEWJzGRUKX", "type": "paragraph", "children": [ { "text": "The following are optional fields:" } ] }, { "id": "fwdIHts-wiPCm01G__IvJ", "type": "bulleted-list", "children": [ { "id": "jcyCFpOy_IFgtdpogy1VX", "type": "list-item", "children": [ { "id": "krzi89RQ1HsMGCXT3dwSg", "type": "list-item-child", "children": [ { "text": "customer_id", "highlight": true }, { "text": ": The customer ID associated with the transaction in the respective PSP." } ] } ] } ] } ] }