RefundRequest_Post

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/bigcommerce/main/json-schema/bigcommerce-refund-request-post-schema.json",
  "title": "RefundRequest_Post",
  "description": "Request body for refund requests.",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/bigcommerce-payment-actions-api-openapi.yml#/components/schemas/RefundRequest_Post",
  "type": "object",
  "x-internal": false,
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ItemsRefund"
      }
    },
    "payments": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/PaymentRequest"
      }
    },
    "merchant_calculated_override": {
      "$ref": "#/$defs/MerchantOverride"
    }
  },
  "required": [
    "items",
    "payments"
  ],
  "$defs": {
    "Amount": {
      "type": "number",
      "format": "float",
      "description": "A non-negative 2 decimal place rounded value that represents the amount that can be charged/refunded with payment providers.",
      "title": "Amount",
      "x-internal": false
    },
    "AmountBoundItem": {
      "type": "object",
      "title": "Amount Bound Item",
      "description": "Amount Bound Item\n\nType of refund item that capture refunding of items in the order that are of type amount.\n* `PRODUCT`\n* `ORDER`\n* `GIFT_WRAPPING`\n* `SHIPPING`\n* `HANDLING`\n* `TAX`",
      "x-internal": false,
      "properties": {
        "item_type": {
          "type": "string",
          "enum": [
            "PRODUCT",
            "ORDER",
            "GIFT_WRAPPING",
            "SHIPPING",
            "HANDLING",
            "TAX"
          ],
          "description": "Type of refund."
        },
        "item_id": {
          "type": "integer",
          "description": "Order address ID."
        },
        "amount": {
          "$ref": "#/$defs/Amount"
        },
        "quantity": {
          "type": "integer",
          "description": "Number of items in refund."
        },
        "reason": {
          "type": "string",
          "description": "Explanation of refund.",
          "minLength": 0,
          "maxLength": 1000
        }
      }
    },
    "ItemsRefund": {
      "title": "ItemsRefund",
      "x-internal": false,
      "oneOf": [
        {
          "$ref": "#/$defs/AmountBoundItem"
        },
        {
          "$ref": "#/$defs/QuantityBoundItem"
        },
        {
          "$ref": "#/$defs/TaxExemptItem"
        }
      ]
    },
    "MerchantOverride": {
      "type": "object",
      "title": "Merchant Calculated Override",
      "description": "Merchant explicitly provided override based on their own calculation.\n\nThis override gives merchants the flexibility to\n- bypass any tax correction due to tax rate/providers changes between when a customer places an order and a merchant initiates a refund\n- use explicit values calculated by external systems (e.g., merchants' own Extended Producer Responsibility or Order Management System)\n\nNote: when using the override, BC internal tax based refund calculation is skipped and therefore order/taxes records are not updated.",
      "properties": {
        "total_amount": {
          "$ref": "#/$defs/Amount"
        },
        "total_tax": {
          "type": "number",
          "description": "Total tax amount refunded back to the shopper. Use 0 value if there is no tax liability change for the refund or tax does not need to be recorded on the refund and would be handled externally."
        }
      },
      "required": [
        "total_amount",
        "total_tax"
      ],
      "x-internal": false
    },
    "PaymentRequest": {
      "type": "object",
      "properties": {
        "provider_id": {
          "type": "string",
          "description": "Reference to payment provider."
        },
        "amount": {
          "type": "number",
          "description": "Amount refunded with this provider."
        },
        "offline": {
          "type": "boolean",
          "description": "Whether the payment was marked as offline or performed through an online payment service."
        }
      },
      "title": "Payment Request",
      "x-internal": false
    },
    "QuantityBoundItem": {
      "type": "object",
      "title": "Quantity Bound Item",
      "description": "Quantity Bound Item\n\nType of refund item that capture refunding of items in the order that are of type quantity.\n* `ORDER`\n* `PRODUCT`\n* `GIFT_WRAPPING`\n* `SHIPPING`\n* `HANDLING`\n* `TAX`\n",
      "properties": {
        "item_type": {
          "type": "string",
          "enum": [
            "ORDER",
            "PRODUCT",
            "GIFT_WRAPPING",
            "SHIPPING",
            "HANDLING",
            "TAX"
          ],
          "description": "Type of refund."
        },
        "item_id": {
          "type": "integer",
          "description": "Order Product ID."
        },
        "quantity": {
          "type": "integer"
        },
        "reason": {
          "type": "string",
          "description": "Reason for refund.",
          "minLength": 0,
          "maxLength": 1000
        }
      },
      "x-internal": false
    },
    "TaxExemptItem": {
      "type": "object",
      "title": "Tax Exempt (Order Level)",
      "description": "Use this to refund a custom value at the order level. When `item_type` is set to `ORDER`, tax is not re-calculated.",
      "x-internal": false,
      "properties": {
        "item_type": {
          "type": "string",
          "description": "The type of refund. When `item_type` is set to `ORDER`, tax is not re-calculated.",
          "enum": [
            "ORDER"
          ]
        },
        "item_id": {
          "type": "number",
          "description": "Numeric ID of the product in the order."
        },
        "amount": {
          "$ref": "#/$defs/Amount"
        },
        "reason": {
          "type": "string",
          "description": "Reason for the refund.",
          "minLength": 0,
          "maxLength": 1000
        }
      }
    }
  }
}