ATUM REST API

Order refunds

ATUM

The ATUM order refunds API allows you to view the refunds of all the WooCommerce orders at once, without having to request them order by order.

WooCommerce's order refunds endpoint (/wp-json/wc/v3/orders/<order_id>/refunds) only lists the refunds of one order. This ATUM endpoint lists the refunds of every order and adds the ID of the refunded order (parent_id) to each of them. It's read-only: to create or delete refunds, use the WooCommerce endpoint.

Only the refunds of WooCommerce orders are returned. Requesting a refund that belongs to another type of order returns the atum_rest_invalid_order_refund_id error (404).

Order refund properties

AttributeTypeDescription
idintegerUnique identifier for the resource. read-only
parent_idintegerID of the refunded order. read-only
date_createddate-timeThe date the order refund was created, in the site's timezone. read-only
date_created_gmtdate-timeThe date the order refund was created, as GMT. read-only
amountstringRefund amount. read-only
reasonstringReason for refund. read-only
refunded_byintegerUser ID of user who created the refund. read-only
refunded_paymentbooleanIf the payment was refunded via the API. read-only
meta_dataarrayMeta data. See Order refund - Meta data properties read-only
line_itemsarrayLine items data. See Order refund - Line items properties read-only
shipping_linesarrayShipping lines data. Same properties as the order's shipping lines. read-only
tax_linesarrayTax lines data. Same properties as the order's tax lines. read-only
fee_linesarrayFee lines data. Same properties as the order's fee lines. read-only
cost_of_goods_soldobjectCost of Goods Sold data (total_value). Only included when the WooCommerce's Cost of Goods Sold feature is enabled. read-only

Order refund - Meta data properties

AttributeTypeDescription
idintegerMeta ID. read-only
keystringMeta key. read-only
valuemixedMeta value. read-only

Order refund - Line items properties

The amounts and quantities of the refunded items are negative.

AttributeTypeDescription
idintegerItem ID. read-only
namestringProduct name. read-only
product_idintegerProduct ID. read-only
variation_idintegerVariation ID, if applicable. read-only
quantityintegerQuantity refunded. read-only
tax_classstringTax class of product. read-only
subtotalstringLine subtotal (before discounts). read-only
subtotal_taxstringLine subtotal tax (before discounts). read-only
totalstringLine total (after discounts). read-only
total_taxstringLine total tax (after discounts). read-only
taxesarrayLine taxes. See Order refund - Taxes properties read-only
meta_dataarrayMeta data, including display_key and display_value. The _refunded_item_id meta holds the ID of the refunded order item. read-only
skustringProduct SKU. read-only
global_unique_idstringProduct's GTIN, UPC, EAN or ISBN. read-only
pricenumberProduct price. read-only
imageobjectProduct image (id and src). read-only
parent_namestringParent product name, if the product is a variation. read-only

Order refund - Taxes properties

AttributeTypeDescription
idintegerTax rate ID. read-only
totalstringTax total. read-only
subtotalstringTax subtotal. read-only

Retrieve an order refund

This API lets you retrieve and view a specific refund by its ID, without knowing the order it belongs to.

HTTP request

GET/wp-json/wc/v3/atum/order-refunds/<id>
curl https://example.com/wp-json/wc/v3/atum/order-refunds/731 \
	-u consumer_key:consumer_secret
JSON response example
{
  "id": 731,
  "date_created": "2019-03-25T10:12:40",
  "date_created_gmt": "2019-03-25T13:12:40",
  "amount": "3.23",
  "reason": "Damaged item",
  "refunded_by": 1,
  "refunded_payment": false,
  "meta_data": [],
  "line_items": [
    {
      "id": 320,
      "name": "Woo Single #1",
      "product_id": 93,
      "variation_id": 0,
      "quantity": -1,
      "tax_class": "",
      "subtotal": "-3.00",
      "subtotal_tax": "-0.23",
      "total": "-3.00",
      "total_tax": "-0.23",
      "taxes": [
        {
          "id": 75,
          "total": "-0.23",
          "subtotal": "-0.23"
        }
      ],
      "meta_data": [
        {
          "id": 2210,
          "key": "_refunded_item_id",
          "value": "315",
          "display_key": "_refunded_item_id",
          "display_value": "315"
        }
      ],
      "sku": "",
      "global_unique_id": "",
      "price": 3,
      "image": {
        "id": 0,
        "src": ""
      },
      "parent_name": null
    }
  ],
  "shipping_lines": [],
  "tax_lines": [
    {
      "id": 321,
      "rate_code": "US-CA-STATE TAX",
      "rate_id": 75,
      "label": "State Tax",
      "compound": false,
      "tax_total": "-0.23",
      "shipping_tax_total": "0.00",
      "rate_percent": 7.5,
      "meta_data": []
    }
  ],
  "fee_lines": [],
  "parent_id": 727,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v3/atum/order-refunds/731"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v3/atum/order-refunds"
      }
    ],
    "up": [
      {
        "href": "https://example.com/wp-json/wc/v3/orders/727"
      }
    ]
  }
}

Available parameters

ParameterTypeDescription
contextstringScope under which the request is made; determines fields present in response. Options: view and edit. Default is view.
dpintegerNumber of decimal points to use in each resource. Default is the store's number of decimals.

List all order refunds

This API helps you to view all the refunds of all the WooCommerce orders.

HTTP request

GET/wp-json/wc/v3/atum/order-refunds
curl https://example.com/wp-json/wc/v3/atum/order-refunds \
	-u consumer_key:consumer_secret
JSON response example
[
  {
    "id": 731,
    "date_created": "2019-03-25T10:12:40",
    "date_created_gmt": "2019-03-25T13:12:40",
    "amount": "3.23",
    "reason": "Damaged item",
    "refunded_by": 1,
    "refunded_payment": false,
    "meta_data": [],
    "line_items": [
      {
        "id": 320,
        "name": "Woo Single #1",
        "product_id": 93,
        "variation_id": 0,
        "quantity": -1,
        "tax_class": "",
        "subtotal": "-3.00",
        "subtotal_tax": "-0.23",
        "total": "-3.00",
        "total_tax": "-0.23",
        "taxes": [
          {
            "id": 75,
            "total": "-0.23",
            "subtotal": "-0.23"
          }
        ],
        "meta_data": [
          {
            "id": 2210,
            "key": "_refunded_item_id",
            "value": "315",
            "display_key": "_refunded_item_id",
            "display_value": "315"
          }
        ],
        "sku": "",
        "global_unique_id": "",
        "price": 3,
        "image": {
          "id": 0,
          "src": ""
        },
        "parent_name": null
      }
    ],
    "shipping_lines": [],
    "tax_lines": [
      {
        "id": 321,
        "rate_code": "US-CA-STATE TAX",
        "rate_id": 75,
        "label": "State Tax",
        "compound": false,
        "tax_total": "-0.23",
        "shipping_tax_total": "0.00",
        "rate_percent": 7.5,
        "meta_data": []
      }
    ],
    "fee_lines": [],
    "parent_id": 727,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v3/atum/order-refunds/731"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v3/atum/order-refunds"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v3/orders/727"
        }
      ]
    }
  },
  {
    "id": 726,
    "date_created": "2019-03-21T18:05:11",
    "date_created_gmt": "2019-03-21T21:05:11",
    "amount": "10.00",
    "reason": "",
    "refunded_by": 1,
    "refunded_payment": false,
    "meta_data": [],
    "line_items": [],
    "shipping_lines": [
      {
        "id": 312,
        "method_title": "Flat Rate",
        "method_id": "flat_rate",
        "instance_id": "1",
        "total": "-10.00",
        "total_tax": "0.00",
        "taxes": [],
        "meta_data": [
          {
            "id": 2188,
            "key": "_refunded_item_id",
            "value": "309",
            "display_key": "_refunded_item_id",
            "display_value": "309"
          }
        ]
      }
    ],
    "tax_lines": [],
    "fee_lines": [],
    "parent_id": 723,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v3/atum/order-refunds/726"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v3/atum/order-refunds"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v3/orders/723"
        }
      ]
    }
  }
]

Available parameters

ParameterTypeDescription
contextstringScope under which the request is made; determines fields present in response. Options: view and edit. Default is view.
pageintegerCurrent page of the collection. Default is 1.
per_pageintegerMaximum number of items to be returned in result set. Default is 10. Maximum is 100.
searchstringLimit results to those matching a string.
afterstringLimit response to resources created after a given ISO8601 compliant date.
beforestringLimit response to resources created before a given ISO8601 compliant date.
modified_afterstringLimit response to resources modified after a given ISO8601 compliant date.
modified_beforestringLimit response to resources modified before a given ISO8601 compliant date.
dates_are_gmtbooleanWhether to consider GMT dates when limiting response by created or modified date. Default is false.
excludearrayEnsure result set excludes specific IDs.
includearrayLimit result set to specific IDs.
offsetintegerOffset the result set by a specific number of items.
orderstringOrder sort attribute ascending or descending. Options: asc and desc. Default is desc.
orderbystringSort collection by object attribute. Options: date, id, include, title, slug and modified. Default is date.
parentarrayLimit result set to those of particular parent IDs. Currently ignored by this endpoint: to get the refunds of specific orders, use WooCommerce's /orders/<order_id>/refunds endpoint.
parent_excludearrayLimit result set to all items except those of particular parent (order) IDs.
dpintegerNumber of decimal points to use in each resource. Default is 2.
order_item_display_metabooleanOnly show meta which is meant to be displayed for an order. Default is false.
include_metaarrayLimit meta_data to specific keys. Inherited from the orders endpoint, it doesn't filter the refunds' meta data.
exclude_metaarrayEnsure meta_data excludes specific keys. Inherited from the orders endpoint, it doesn't filter the refunds' meta data.

Order notes

Previous Page

Pick & Pack

Next Page

On this page

Order refund propertiesOrder refund - Meta data propertiesOrder refund - Line items propertiesOrder refund - Taxes propertiesRetrieve an order refundHTTP requestAvailable parametersList all order refundsHTTP requestAvailable parameters