TAtalkdesk
Retail Experience Cloud Bridge

Get Suggested Refund

Changed on

Calculate the suggested refund for an order or return. Supports two workflows: (1) direct refund from an order with specified line items, or (2) refund after a return where line items and totals are pre-calculated from the return.

Required fields:

  • order_id or return_id (one must be provided)

A successful request returns the suggested refund details for the specified order or return.

Returns with exchange items (return_id only):

  • Send the exchange items in exchange_line_items, together with the return line items in refund_line_items, to see what processing them together would do. Their prices are netted, and financial_outcome tells whether money is refunded (REFUND), the customer owes money (INVOICE), or nothing is owed either way (EVEN).
  • financial_outcome is for the whole order: the items are first netted against what the order already owes. The restocking fees and the return shipping fees are already taken out of it.
  • Without exchange_line_items, the amounts are calculated as for a return without exchange items, and return_context.exchange_line_items still lists the exchange items left to process.
  • The display data of the exchange items (title, variant_title, sku, image_url, unit_price) comes from the synced product catalog.
post/erc/ecommerce/refund/suggested

Request

  • Base URL
    https://api.talkdeskapp.com
  • URL
    https://api.talkdeskapp.com/erc/ecommerce/refund/suggested
  • Auth
    OAuth 2
    Authorization code: https://{account_name}.talkdeskid.com/oauth/authorize
    Token URL: https://{account_name}.talkdeskid.com/oauth/token scopes: erc-ecommerce-return:read

Request body

order_idstring

The order ID to calculate the suggested refund for. Either order_id or return_id must be provided.

return_idstring

The return ID to calculate the suggested refund for. Either order_id or return_id must be provided.

brandstring

The brand identifier. If the account is multi-brand, this parameter is required.

shipping_amountnumber

The shipping amount to refund. Must be positive.

refund_shippingboolean

Whether to include shipping in the refund.

suggest_full_refundboolean

Whether to suggest a full refund for the order.

Example request

{
  "order_id": "order789",
  "return_id": "28916416673",
  "brand": "The Brand",
  "refund_line_items": [
    {
      "line_item_id": "line_item_1",
      "quantity": 1
    }
  ],
  "exchange_line_items": [
    {
      "id": "1145438369",
      "quantity": 1
    }
  ],
  "shipping_amount": 10,
  "refund_duties": [
    {
      "duty_id": "duty_1"
    }
  ]
}

Response

The suggested refund details.

custom_fieldsobject

Additional custom fields.

taxes_includedboolean

Whether taxes are included in the refund.

Example response

{
  "amount": {
    "value": 30,
    "currency": "EUR"
  },
  "maximum_refundable": {
    "value": 30,
    "currency": "EUR"
  },
  "financial_outcome": {
    "type": "INVOICE",
    "amount": {
      "value": 30,
      "currency": "EUR"
    }
  },
  "subtotal": {
    "value": 30,
    "currency": "EUR"
  },
  "total_tax": {
    "value": 30,
    "currency": "EUR"
  },
  "total_duties": {
    "value": 30,
    "currency": "EUR"
  },
  "discounted_subtotal": {
    "value": 30,
    "currency": "EUR"
  },
  "shipping": {
    "amount": {
      "value": 30,
      "currency": "EUR"
    },
    "maximum_refundable": {
      "value": 30,
      "currency": "EUR"
    },
    "tax": {
      "value": 30,
      "currency": "EUR"
    }
  },
  "suggested_transactions": [
    {
      "gateway": "shopify_payments",
      "kind": "SUGGESTED_REFUND",
      "amount": {
        "value": 30,
        "currency": "EUR"
      },
      "maximum_refundable": {
        "value": 30,
        "currency": "EUR"
      },
      "parent_transaction_id": "txn_123"
    }
  ],
  "suggested_refund_methods": [
    {
      "type": "CREDIT_CARD",
      "amount": {
        "value": 30,
        "currency": "EUR"
      },
      "maximum_refundable": {
        "value": 30,
        "currency": "EUR"
      }
    }
  ],
  "refund_line_items": [
    {
      "line_item_id": "line_item_1",
      "title": "Blue T-Shirt",
      "sku": "BTS-001",
      "variant_title": "Size M",
      "image_url": "https://cdn.example.com/images/blue-tshirt.png",
      "quantity": 1,
      "max_refundable_quantity": 2,
      "restockable": true,
      "original_unit_price": {
        "value": 30,
        "currency": "EUR"
      },
      "subtotal": {
        "value": 30,
        "currency": "EUR"
      },
      "total_tax": {
        "value": 30,
        "currency": "EUR"
      }
    }
  ],
  "return_context": {
    "return_id": "return_001",
    "return_name": "Return #1234",
    "order_id": "order789",
    "status": "OPEN",
    "line_items": [
      {
        "line_item_id": "line_item_1",
        "quantity": 1,
        "processable_quantity": 1,
        "return_reason": "DEFECTIVE",
        "return_reason_note": "Item arrived damaged.",
        "restocking_fee_percentage": 10,
        "restocking_fee_amount": {
          "value": 30,
          "currency": "EUR"
        }
      }
    ],
    "exchange_line_items": [
      {
        "id": "1145438369",
        "variant_id": "41786405978273",
        "quantity": 1,
        "processable_quantity": 1,
        "title": "Blue T-Shirt",
        "variant_title": "L / Blue",
        "sku": "BTS-L-BLUE",
        "image_url": "https://cdn.example.com/images/blue-tshirt-l.png",
        "unit_price": {
          "value": 30,
          "currency": "EUR"
        }
      }
    ]
  },
  "deductions": {
    "return_shipping": {
      "value": 30,
      "currency": "EUR"
    },
    "restocking_fees": {
      "value": 30,
      "currency": "EUR"
    },
    "total": {
      "value": 30,
      "currency": "EUR"
    }
  },
  "refund_owed": {
    "value": 30,
    "currency": "EUR"
  },
  "return_item_discount": {
    "value": 30,
    "currency": "EUR"
  },
  "locations": [
    {
      "id": "location_001",
      "name": "Main Warehouse"
    }
  ],
  "_links": {
    "self": {
      "href": "http://api-docs.talkdesk.org/erc/ecommerce/refund/suggested"
    }
  }
}

Changes

  • f69c52fd7456Revision changes
    • info

      added the new optional request property

    • info

      added the optional property to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property /// to the response with the status