---
title: "Compensation request"
method: POST
path: "/v2/unified-compensation-request/{id}"
tags: ["Compensation"]
---

# Compensation request

`POST /v2/unified-compensation-request/{id}`

Send information about a customer-initiated request for compensation, such as a refund or a reship, in order to receive a fraud or abuse decision. 
The request can be made on an order level or at the item level. The response may also include recommendations based on your abuse prevention policies.

## Path parameters

- `id` string, required

## Headers

- `api-version` string, required
- `x-forter-siteid` string, required
- `Authorization` string, required

## Request body

- UnifiedCompensationRequestRequest — Send information about a customer-initiated request for compensation, such as a refund or a reship, in order to receive a fraud or abuse decision. The request can be made on an order level or at the item level. The response may also include recommendations based on your abuse prevention policies.
  - `accountId` string, required — Customer's account UID in merchant's site. If the compensation request is from a guest account then this field should be populated with the original order id ending with the suffix '_GUEST'.
  - `additionalEventIdentifiers` object, nullable — Additional identifiers of the account event
  - `additionalInformation` object, nullable — General payload object
  - `compensationRequest` CompensationRequest, required — Includes specific details of the compensation request (type of compensation requested, on which items, for what reasons, etc.)
    - `initiationType` 'CALL_CENTER' | 'IN_STORE' | 'CHAT' | 'ONLINE' | 'SELF_SERVICE', required — What channel did the customer use to initiate the request for compensation
    - `items` CompensationItem[], required — A list of all items for which compensation is being requested
      - `basicItemData` BasicItemData, required — This is an item associated with the customer or transaction.
        - `category` string, nullable — Item category
        - `discount` object, nullable — This provides information relating to any kind of offer, coupon or other discount used by the customer.
          - `couponCodeUsed` string, required — Coupon code used
          - `couponDiscountAmount` object, nullable — A monetary amount in USD or local currenncy.
            - `amountLocalCurrency` string, nullable — Transaction amount in currency chosen by the buyer
            - `amountUSD` string, nullable — Transaction amount in USD
            - `currency` string, nullable — Transaction currency chosen by the buyer, 3-letter ISO-4217 format currency code
          - `couponDiscountPercent` string, nullable — Coupon discount amount
        - `name` string, required — Item name
        - `price` Amount, required — A monetary amount in USD or local currenncy.
          - `amountLocalCurrency` string, nullable — Transaction amount in currency chosen by the buyer
          - `amountUSD` string, nullable — Transaction amount in USD
          - `currency` string, nullable — Transaction currency chosen by the buyer, 3-letter ISO-4217 format currency code
        - `productId` string, nullable — Unique identifier for item that is common to all identical items (such as SKU, ISBN, etc.)
        - `quantity` number, required — Item quantity
        - `type` 'TANGIBLE' | 'NON_TANGIBLE', required — Tangible if physical item, non-tangible if any other product
      - `itemCompensationData` CompensationData, required — This is specific data regarding the compensation requested by the customer. Depending on the type of integration, this data could be provided at the order level or per item.
        - `compensationTypeRequested` 'REPLACEMENT' | 'REFUND' | 'REFUND_UPON_RETURN' | 'CREDIT' | 'MIXED' | 'UNKNOWN' | 'NO_COMPENSATION', nullable — Indicates whether the customer requested a refund, store credit, replacement etc.
        - `initiationTime` number, required — The time that the customer initiated the request for compensation in MILLISECONDS since unix epoch (Jan 1, 1970)
        - `internalReasonCategory` string, nullable — The reason for the request as defined by the merchant
        - `reasonCategory` 'CHANGED_MY_MIND' | 'DOES_NOT_FIT' | 'NOT_AS_DESCRIBED' | 'WRONG_ITEM' | 'ARRIVED_TOO_LATE' | 'LOW_QUALITY' | 'DAMAGED_GOODS' | 'GIFT_RETURN' | 'RETURN_TO_SENDER' | 'RETURN_POLICY_EXCEPTION' | 'OTHER' | 'UNKNOWN' | 'ITEM_NOT_RECEIVED' | 'ENTIRE_ORDER_NOT_RECEIVED' | 'OUTBOUND_ISSUE_CARRIER' | 'OUTBOUND_ISSUE_MERCHANT' | 'FAILED_DELIVERY' | 'INBOUND_LOSS' | 'INBOUND_ISSUE_CARRIER', nullable — Reason for compensation request
        - `requestedReturnType` 'SHIP_TO_WAREHOUSE' | 'IN_STORE' | 'NO_RETURN', required — Method of return requested by customer (or the request to not return item at all)
    - `orderCompensationData` object, nullable — This is specific data regarding the compensation requested by the customer. Depending on the type of integration, this data could be provided at the order level or per item.
      - `compensationTypeRequested` 'REPLACEMENT' | 'REFUND' | 'REFUND_UPON_RETURN' | 'CREDIT' | 'MIXED' | 'UNKNOWN' | 'NO_COMPENSATION', nullable — Indicates whether the customer requested a refund, store credit, replacement etc.
      - `initiationTime` number, required — The time that the customer initiated the request for compensation in MILLISECONDS since unix epoch (Jan 1, 1970)
      - `internalReasonCategory` string, nullable — The reason for the request as defined by the merchant
      - `reasonCategory` 'CHANGED_MY_MIND' | 'DOES_NOT_FIT' | 'NOT_AS_DESCRIBED' | 'WRONG_ITEM' | 'ARRIVED_TOO_LATE' | 'LOW_QUALITY' | 'DAMAGED_GOODS' | 'GIFT_RETURN' | 'RETURN_TO_SENDER' | 'RETURN_POLICY_EXCEPTION' | 'OTHER' | 'UNKNOWN' | 'ITEM_NOT_RECEIVED' | 'ENTIRE_ORDER_NOT_RECEIVED' | 'OUTBOUND_ISSUE_CARRIER' | 'OUTBOUND_ISSUE_MERCHANT' | 'FAILED_DELIVERY' | 'INBOUND_LOSS' | 'INBOUND_ISSUE_CARRIER', nullable — Reason for compensation request
      - `requestedReturnType` 'SHIP_TO_WAREHOUSE' | 'IN_STORE' | 'NO_RETURN', required — Method of return requested by customer (or the request to not return item at all)
    - `totalRequestedAmount` Amount, required — A monetary amount in USD or local currenncy.
      - `amountLocalCurrency` string, nullable — Transaction amount in currency chosen by the buyer
      - `amountUSD` string, nullable — Transaction amount in USD
      - `currency` string, nullable — Transaction currency chosen by the buyer, 3-letter ISO-4217 format currency code
  - `connectionInformation` ConnectionInformation, required — This object contains connection info which is usually found in the HTTP request header.
    - `checkoutToolsSessionId` string, nullable — CheckoutToolsSessionId received from the SDK
    - `customerIP` string, required — Customer IP address in IPv4 or IPv6 format. If missing should be populated with 127.0.0.1
    - `forterMobileUID` string, nullable — mobile UID. The device identifier such as IMEI in android or identifier for vendor in iOS. This should match the deviceId sent via the mobile events API (for mobile transactions only)
    - `forterTokenCookie` string, nullable — Forter token cookie from request headers
    - `merchantDeviceIdentifier` string, nullable — A unique device identifier generated by merchant
    - `merchantProvidedSessionId` string, nullable — An identifier of the merchant session
    - `userAgent` string, required — Customer's User agent
  - `eventId` string, required — Unique identifier of this compensation request
  - `eventTime` number, required — The time that the trigger event occurred in MILLISECONDS since unix epoch (Jan 1, 1970)
  - `hasProofOfPurchase` boolean, nullable — Whether the user has a proof of purchase
  - `isGuestAccount` boolean, required — Boolean field indicating if account is a guest account.
  - `merchantAgentData` object, nullable — Name and Id of the merchant's agent processing the compensation request
    - `merchantAgentId` string, nullable — Unique identifier of the agent processing the customer's request
    - `merchantAgentName` string, nullable — Name of the agent processing the customer's request
  - `merchantIdentifiers` object, nullable — If a merchant operates a number of sites, Merchant Identifiers help Forter's system to identify the right transactions with the right sites.
    - `merchantDomain` string, nullable — Use if merchant operates several sites (such as a regular site and a related discount brand)
    - `merchantName` string, nullable — Use if merchant operates several sites (such as a regular site and a related discount brand)
  - `originalOrderId` string, required — Unique order/transaction identifier for which compensation is being requested in this compensation event. Note that Forter treats this ID as case-insensitive; Order123 and ORDER123 will be identified as the same order.
  - `status` object, nullable — Status of the compensation request
    - `hasProofOfPurchase` boolean, nullable
    - `itemStatus` ItemCompensationStatus[], required — A list of all items for which compensation was requested
      - `basicItemData` BasicItemData, required — This is an item associated with the customer or transaction.
        - `category` string, nullable — Item category
        - `discount` object, nullable — This provides information relating to any kind of offer, coupon or other discount used by the customer.
          - `couponCodeUsed` string, required — Coupon code used
          - `couponDiscountAmount` object, nullable — A monetary amount in USD or local currenncy.
            - `amountLocalCurrency` string, nullable — Transaction amount in currency chosen by the buyer
            - `amountUSD` string, nullable — Transaction amount in USD
            - `currency` string, nullable — Transaction currency chosen by the buyer, 3-letter ISO-4217 format currency code
          - `couponDiscountPercent` string, nullable — Coupon discount amount
        - `name` string, required — Item name
        - `price` Amount, required — A monetary amount in USD or local currenncy.
          - `amountLocalCurrency` string, nullable — Transaction amount in currency chosen by the buyer
          - `amountUSD` string, nullable — Transaction amount in USD
          - `currency` string, nullable — Transaction currency chosen by the buyer, 3-letter ISO-4217 format currency code
        - `productId` string, nullable — Unique identifier for item that is common to all identical items (such as SKU, ISBN, etc.)
        - `quantity` number, required — Item quantity
        - `type` 'TANGIBLE' | 'NON_TANGIBLE', required — Tangible if physical item, non-tangible if any other product
      - `statusData` ItemCompensationStatusData, required — This is update on the specific data regarding the compensation requested by the customer for this item.
        - `compensationTypeGranted` 'REPLACEMENT' | 'REFUND' | 'REFUND_UPON_RETURN' | 'CREDIT' | 'MIXED' | 'UNKNOWN' | 'NO_COMPENSATION', required — Indicates whether the customer was granted a refund, store credit, replacement etc.
        - `internalReasonCategory` string, nullable — The reason for the request as defined by the merchant
        - `reasonCategory` 'CHANGED_MY_MIND' | 'DOES_NOT_FIT' | 'NOT_AS_DESCRIBED' | 'WRONG_ITEM' | 'ARRIVED_TOO_LATE' | 'LOW_QUALITY' | 'DAMAGED_GOODS' | 'GIFT_RETURN' | 'RETURN_TO_SENDER' | 'RETURN_POLICY_EXCEPTION' | 'OTHER' | 'UNKNOWN' | 'ITEM_NOT_RECEIVED' | 'ENTIRE_ORDER_NOT_RECEIVED' | 'OUTBOUND_ISSUE_CARRIER' | 'OUTBOUND_ISSUE_MERCHANT' | 'FAILED_DELIVERY' | 'INBOUND_LOSS' | 'INBOUND_ISSUE_CARRIER', required — Reason for compensation request
        - `returnCondition` 'GOOD_CONDITION' | 'DAMAGED' | 'WRONG_ITEM' | 'NO_ITEM' | 'NOT_ARRIVED' | 'NO_RETURN', nullable — Condition of the item returned
        - `returnMethodGranted` 'SHIP_TO_WAREHOUSE' | 'IN_STORE' | 'NO_RETURN', required — Method of return granted to customer
        - `statusLog` object, nullable — Status of the return process per item
          - `arrivedToWarehouseTime` number, nullable — Time returned items arrived to the merchant's warehouse
          - `initiationTime` number, nullable — The time that the customer initiated the request for compensation in MILLISECONDS since unix epoch (Jan 1, 1970)
          - `initiationType` 'CALL_CENTER' | 'IN_STORE' | 'CHAT' | 'ONLINE' | 'SELF_SERVICE', nullable — What channel did the customer use to initiate the request for compensation
          - `shippedByCustomerTime` number, nullable — Time returned items were shipped by the customer
        - `updatedStatus` 'ACCEPTED_BY_MERCHANT' | 'REJECTED_BY_MERCHANT' | 'WITHDRAWN_BY_CUSTOMER', required — The updated compensation request status
    - `merchantAgentData` object, nullable — Name and Id of the merchant's agent processing the compensation request
      - `merchantAgentId` string, nullable — Unique identifier of the agent processing the customer's request
      - `merchantAgentName` string, nullable — Name of the agent processing the customer's request
    - `replacementOrderId` string, nullable — Unique order/transaction identifier for a replacement order issued by the merchant in response to this request
    - `shippingRefunded` boolean, nullable — Indicates whether merchant reimbursed the customer for shipping expenses
    - `shippingRefundedAmount` object, nullable — A monetary amount in USD or local currenncy.
      - `amountLocalCurrency` string, nullable — Transaction amount in currency chosen by the buyer
      - `amountUSD` string, nullable — Transaction amount in USD
      - `currency` string, nullable — Transaction currency chosen by the buyer, 3-letter ISO-4217 format currency code
    - `statusData` object, nullable — This is update on the specific data regarding the compensation requested by the customer for this item.
      - `compensationTypeGranted` 'REPLACEMENT' | 'REFUND' | 'REFUND_UPON_RETURN' | 'CREDIT' | 'MIXED' | 'UNKNOWN' | 'NO_COMPENSATION', required — Indicates whether the customer was granted a refund, store credit, replacement etc.
      - `internalReasonCategory` string, nullable — The reason for the request as defined by the merchant
      - `reasonCategory` 'CHANGED_MY_MIND' | 'DOES_NOT_FIT' | 'NOT_AS_DESCRIBED' | 'WRONG_ITEM' | 'ARRIVED_TOO_LATE' | 'LOW_QUALITY' | 'DAMAGED_GOODS' | 'GIFT_RETURN' | 'RETURN_TO_SENDER' | 'RETURN_POLICY_EXCEPTION' | 'OTHER' | 'UNKNOWN' | 'ITEM_NOT_RECEIVED' | 'ENTIRE_ORDER_NOT_RECEIVED' | 'OUTBOUND_ISSUE_CARRIER' | 'OUTBOUND_ISSUE_MERCHANT' | 'FAILED_DELIVERY' | 'INBOUND_LOSS' | 'INBOUND_ISSUE_CARRIER', required — Reason for compensation request
      - `returnCondition` 'GOOD_CONDITION' | 'DAMAGED' | 'WRONG_ITEM' | 'NO_ITEM' | 'NOT_ARRIVED' | 'NO_RETURN', nullable — Condition of the item returned
      - `returnMethodGranted` 'SHIP_TO_WAREHOUSE' | 'IN_STORE' | 'NO_RETURN', required — Method of return granted to customer
      - `statusLog` object, nullable — Status of the return process per item
        - `arrivedToWarehouseTime` number, nullable — Time returned items arrived to the merchant's warehouse
        - `initiationTime` number, nullable — The time that the customer initiated the request for compensation in MILLISECONDS since unix epoch (Jan 1, 1970)
        - `initiationType` 'CALL_CENTER' | 'IN_STORE' | 'CHAT' | 'ONLINE' | 'SELF_SERVICE', nullable — What channel did the customer use to initiate the request for compensation
        - `shippedByCustomerTime` number, nullable — Time returned items were shipped by the customer
      - `updatedStatus` 'ACCEPTED_BY_MERCHANT' | 'REJECTED_BY_MERCHANT' | 'WITHDRAWN_BY_CUSTOMER', required — The updated compensation request status
    - `totalGrantedAmount` Amount, required — A monetary amount in USD or local currenncy.
      - `amountLocalCurrency` string, nullable — Transaction amount in currency chosen by the buyer
      - `amountUSD` string, nullable — Transaction amount in USD
      - `currency` string, nullable — Transaction currency chosen by the buyer, 3-letter ISO-4217 format currency code

## Response `200`

Example unifiedCompensationRequestResponse

- UnifiedCompensationRequestResponse — The response object of a forter compensation request call
  - `correlationId` string, required — A Forter unique identifier that was provided as part of a Forter API response. Used to correlate between the compensation request event and final status update
  - `decisionReason` string, required
  - `forterDecision` string, required — The message containing the decision
  - `merchantPolicyId` string, required — UID of the custom policy created in Forter's Policies tool that resulted in this decision
  - `recommendations` string[], required — Forter's recommendations for the optimal way of proceeding with the compensation request
  - `status` string, required — Status of the request processing

## Other responses

- `400` — Bad Request (Often missing a required parameter)
- `401` — Unauthorized (No valid API key provided)
- `404` — Not Found (The requested item doesn't exist)
- `429` — Too Many Requests (The client exceeded a rate limit). Honor Retry-After before retrying.
- `500` — Server Error (Something went wrong on Forter's end)
- `default` — Typed error envelope for any undeclared 4xx / 5xx status.

---

[API](https://skmtc.net/forter/apis/forter-api.md) · [All operations](https://skmtc.net/forter/apis/forter-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/forter/forter-api/revisions/d7b02e919b34/schema)