Refund

A refund is a record of the money returned to the customer, and/or the return of any items on an order which may or may not have been restocked.

What can you do with Refund?

The haravan API lets you do the following with the Refund resource. More detailed versions of these general actions may be available:

Refund properties

created_at
"created_at": "2008-01-10T11:00:00-05:00"

The date and time when the refund was created. The API returns this value in ISO 8601 format.

processed_at
"processed_at": "2007-01-10T11:00:00-05:00"

The date and time when the refund was imported, in ISO 8601 format. This value can be set to dates in the past when importing from other systems. If no value is provided, it will be auto-generated.

id
"id": 92738740

The unique numeric identifier for the refund. This one is used for API purposes.

note
"note": "Item was damaged during shipping"

The optional note attached to a refund.

refund_line_items
"refund_line_items": [
  {
    "id": 209341123,
    "line_item": {},
    "line_item_id": 128323456,
    "quantity": 2
  }
]

Details about one returned/refunded item. It has the following properties:

  • id: The unique identifier of the refund line item.
  • line_item: The single line item being returned.
  • line_item_id: The id of the related line item.
  • quantity: The quantity of the associated line item that was returned.
restock
"restock": true

Whether or not the line items were added back to the store inventory.

transactions

The list of transactions involved in the refund.

user_id
"user_id": 238478920

The unique identifier of the user who performed the refund.

Endpoints

GET/admin/orders/450789469/refunds.json
Retrieve a list of Refunds for an Order
fields

Comma-separated list of fields to include in the response

Get all refunds from a specific order

GET /admin/orders/#{id}/refunds.json
Hide Response
HTTP/1.1 200 OK
{
  "refunds": [
    {
      "id": 509562969,
      "order_id": 450789469,
      "created_at": "2017-01-05T15:40:07-05:00",
      "note": "it broke during shipping",
      "restock": true,
      "user_id": 799407056,
      "processed_at": "2017-01-05T15:40:07-05:00",
      "refund_line_items": [
        {
          "id": 104689539,
          "quantity": 1,
          "line_item_id": 703073504,
          "subtotal": 195.67,
          "total_tax": 3.98,
          "line_item": {
            "id": 703073504,
            "variant_id": 457924702,
            "title": "IPod Nano - 8gb",
            "quantity": 1,
            "price": "199.00",
            "grams": 200,
            "sku": "IPOD2008BLACK",
            "variant_title": "black",
            "vendor": null,
            "fulfillment_service": "manual",
            "product_id": 632910392,
            "requires_shipping": true,
            "taxable": true,
            "gift_card": false,
            "name": "IPod Nano - 8gb - black",
            "variant_inventory_management": "haravan",
            "properties": [
            ],
            "product_exists": true,
            "fulfillable_quantity": 1,
            "total_discount": "0.00",
            "fulfillment_status": null,
            "tax_lines": [
              {
                "title": "State Tax",
                "price": "3.98",
                "rate": 0.06
              }
            ]
          }
        },
        {
          "id": 709875399,
          "quantity": 1,
          "line_item_id": 466157049,
          "subtotal": 195.66,
          "total_tax": 3.98,
          "line_item": {
            "id": 466157049,
            "variant_id": 39072856,
            "title": "IPod Nano - 8gb",
            "quantity": 1,
            "price": "199.00",
            "grams": 200,
            "sku": "IPOD2008GREEN",
            "variant_title": "green",
            "vendor": null,
            "fulfillment_service": "manual",
            "product_id": 632910392,
            "requires_shipping": true,
            "taxable": true,
            "gift_card": false,
            "name": "IPod Nano - 8gb - green",
            "variant_inventory_management": "haravan",
            "properties": [
              {
                "name": "Custom Engraving Front",
                "value": "Happy Birthday"
              },
              {
                "name": "Custom Engraving Back",
                "value": "Merry Christmas"
              }
            ],
            "product_exists": true,
            "fulfillable_quantity": 1,
            "total_discount": "0.00",
            "fulfillment_status": null,
            "tax_lines": [
              {
                "title": "State Tax",
                "price": "3.98",
                "rate": 0.06
              }
            ]
          }
        }
      ],
      "transactions": [
        {
          "id": 179259969,
          "order_id": 450789469,
          "amount": "209.00",
          "kind": "refund",
          "gateway": "bogus",
          "status": "success",
          "message": null,
          "created_at": "2005-08-05T12:59:12-04:00",
          "test": false,
          "authorization": "authorization-key",
          "currency": "USD",
          "location_id": null,
          "user_id": null,
          "parent_id": null,
          "device_id": null,
          "receipt": {},
          "error_code": null,
          "source_name": "web"
        }
      ],
      "order_adjustments": [
      ]
    }
  ]
}
GET/admin/orders/450789469/refunds/509562969.json
Retrieve a specific refund
fields

Comma-separated list of fields to include in the response

Get a representation of a single refund

GET /admin/orders/#{id}/refunds/#{id}.json
Hide Response
HTTP/1.1 200 OK
{
  "refund": {
    "id": 509562969,
    "order_id": 450789469,
    "created_at": "2017-01-05T15:40:07-05:00",
    "note": "it broke during shipping",
    "restock": true,
    "user_id": 799407056,
    "processed_at": "2017-01-05T15:40:07-05:00",
    "refund_line_items": [
      {
        "id": 104689539,
        "quantity": 1,
        "line_item_id": 703073504,
        "subtotal": 195.67,
        "total_tax": 3.98,
        "line_item": {
          "id": 703073504,
          "variant_id": 457924702,
          "title": "IPod Nano - 8gb",
          "quantity": 1,
          "price": "199.00",
          "grams": 200,
          "sku": "IPOD2008BLACK",
          "variant_title": "black",
          "vendor": null,
          "fulfillment_service": "manual",
          "product_id": 632910392,
          "requires_shipping": true,
          "taxable": true,
          "gift_card": false,
          "name": "IPod Nano - 8gb - black",
          "variant_inventory_management": "haravan",
          "properties": [
          ],
          "product_exists": true,
          "fulfillable_quantity": 1,
          "total_discount": "0.00",
          "fulfillment_status": null,
          "tax_lines": [
            {
              "title": "State Tax",
              "price": "3.98",
              "rate": 0.06
            }
          ]
        }
      },
      {
        "id": 709875399,
        "quantity": 1,
        "line_item_id": 466157049,
        "subtotal": 195.66,
        "total_tax": 3.98,
        "line_item": {
          "id": 466157049,
          "variant_id": 39072856,
          "title": "IPod Nano - 8gb",
          "quantity": 1,
          "price": "199.00",
          "grams": 200,
          "sku": "IPOD2008GREEN",
          "variant_title": "green",
          "vendor": null,
          "fulfillment_service": "manual",
          "product_id": 632910392,
          "requires_shipping": true,
          "taxable": true,
          "gift_card": false,
          "name": "IPod Nano - 8gb - green",
          "variant_inventory_management": "haravan",
          "properties": [
            {
              "name": "Custom Engraving Front",
              "value": "Happy Birthday"
            },
            {
              "name": "Custom Engraving Back",
              "value": "Merry Christmas"
            }
          ],
          "product_exists": true,
          "fulfillable_quantity": 1,
          "total_discount": "0.00",
          "fulfillment_status": null,
          "tax_lines": [
            {
              "title": "State Tax",
              "price": "3.98",
              "rate": 0.06
            }
          ]
        }
      }
    ],
    "transactions": [
      {
        "id": 179259969,
        "order_id": 450789469,
        "amount": "209.00",
        "kind": "refund",
        "gateway": "bogus",
        "status": "success",
        "message": null,
        "created_at": "2005-08-05T12:59:12-04:00",
        "test": false,
        "authorization": "authorization-key",
        "currency": "USD",
        "location_id": null,
        "user_id": null,
        "parent_id": null,
        "device_id": null,
        "receipt": {},
        "error_code": null,
        "source_name": "web"
      }
    ],
    "order_adjustments": [
    ]
  }
}
POST/admin/orders/450789469/refunds.json
Create a Refund for an existing Order. It is highly suggested that you use the calculateendpoint to produce the transactions to submit.
restock

Boolean, whether or not to add the line items back to the store inventory.

notify

Boolean, set to <code>true</code> to send a refund notification to the customer.

note

An optional comment attached to a refund.

discrepancy_reason

An optional comment, used if there is a discrepancy between calculated and actual refund amounts (one of: restock, damage, customer, other)

shipping

Object to specify how much shipping to refund

  • full_refund - Boolean, set to true to refund all remaining shipping
  • amount - Set specific amount of shipping to refund. Takes precedence over full_refund.
refund_line_items

Array of line item IDs and quantities to refund

transactions

Array of transactions to process as refunds

Create a new refund for an order

POST /admin/orders/#{id}/refunds.json
{
  "refund": {
    "restock": true,
    "notify": true,
    "note": "wrong size",
    "shipping": {
      "full_refund": true
    },
    "refund_line_items": [
      {
        "line_item_id": 518995019,
        "quantity": 1
      }
    ],
    "transactions": [
      {
        "parent_id": 801038806,
        "amount": 199.65,
        "kind": "refund",
        "gateway": "bogus"
      }
    ]
  }
}
Hide Response
HTTP/1.1 201 Created
{
  "refund": {
    "id": 929361464,
    "order_id": 450789469,
    "created_at": "2017-01-05T15:40:24-05:00",
    "note": "wrong size",
    "restock": true,
    "user_id": 0,
    "processed_at": "2017-01-05T15:40:24-05:00",
    "refund_line_items": [
      {
        "id": 1058498311,
        "quantity": 1,
        "line_item_id": 518995019,
        "subtotal": 195.67,
        "total_tax": 3.98,
        "line_item": {
          "id": 518995019,
          "variant_id": 49148385,
          "title": "IPod Nano - 8gb",
          "quantity": 1,
          "price": "199.00",
          "grams": 200,
          "sku": "IPOD2008RED",
          "variant_title": "red",
          "vendor": null,
          "fulfillment_service": "manual",
          "product_id": 632910392,
          "requires_shipping": true,
          "taxable": true,
          "gift_card": false,
          "name": "IPod Nano - 8gb - red",
          "variant_inventory_management": "haravan",
          "properties": [
          ],
          "product_exists": true,
          "fulfillable_quantity": 0,
          "total_discount": "0.00",
          "fulfillment_status": null,
          "tax_lines": [
            {
              "title": "State Tax",
              "price": "3.98",
              "rate": 0.06
            }
          ]
        }
      }
    ],
    "transactions": [
      {
        "id": 1068278486,
        "order_id": 450789469,
        "amount": "199.65",
        "kind": "refund",
        "gateway": "bogus",
        "status": "success",
        "message": "Bogus Gateway: Forced success",
        "created_at": "2017-01-05T15:40:24-05:00",
        "test": true,
        "authorization": null,
        "currency": "USD",
        "location_id": null,
        "user_id": null,
        "parent_id": 801038806,
        "device_id": null,
        "receipt": {},
        "error_code": null,
        "source_name": "755357713"
      }
    ],
    "order_adjustments": [
    ]
  }
}

Refunding a specific amount of shipping

POST /admin/orders/#{id}/refunds.json
{
  "refund": {
    "shipping": {
      "amount": 5.0
    },
    "transactions": [
      {
        "parent_id": 801038806,
        "amount": 5.0,
        "kind": "refund",
        "gateway": "bogus"
      }
    ]
  }
}
Hide Response
HTTP/1.1 201 Created
{
  "refund": {
    "id": 929361465,
    "order_id": 450789469,
    "created_at": "2017-01-05T15:40:25-05:00",
    "note": null,
    "restock": null,
    "user_id": 0,
    "processed_at": "2017-01-05T15:40:25-05:00",
    "refund_line_items": [
    ],
    "transactions": [
      {
        "id": 1068278487,
        "order_id": 450789469,
        "amount": "5.00",
        "kind": "refund",
        "gateway": "bogus",
        "status": "success",
        "message": "Bogus Gateway: Forced success",
        "created_at": "2017-01-05T15:40:26-05:00",
        "test": true,
        "authorization": null,
        "currency": "USD",
        "location_id": null,
        "user_id": null,
        "parent_id": 801038806,
        "device_id": null,
        "receipt": {},
        "error_code": null,
        "source_name": "755357713"
      }
    ],
    "order_adjustments": [
      {
        "id": 1030976843,
        "order_id": 450789469,
        "refund_id": 929361465,
        "amount": "-5.00",
        "tax_amount": "0.00",
        "kind": "shipping_refund",
        "reason": "Shipping refund"
      }
    ]
  }
}

Haravan - Công ty công nghệ cung cấp giải pháp kinh doanh thương mại điện tử, duy nhất tại Việt Nam được Google lựa chọn vào chương trình bệ phóng tiềm năng với hỗ trợ và đào tạo công nghệ để vươn ra thị trường quốc tế vững chắc.