Request refund for shipment

​
Path Parameters
  • id
    Type: string
    required

    Shipment id

Responses
  • application/json
Request Example for post/shipments/{id}/refund
curl 'https://api.test.vesyl.com/v2/shipments/{id}/refund' \
  --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "id": "shp_1234",
  "created_at": "2025-09-16T17:52:32Z",
  "updated_at": "2025-09-16T17:52:45Z",
  "object": "Shipment",
  "reference": null,
  "from_address": {
    "street1": "333 Bush St.",
    "street2": "Apt 4206",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "name": "Bob Jones",
    "company": null,
    "phone": "1112223333",
    "email": null,
    "residential": null
  },
  "to_address": {
    "street1": "333 Bush St.",
    "street2": "Apt 4206",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "name": "Bob Jones",
    "company": null,
    "phone": "1112223333",
    "email": null,
    "residential": null
  },
  "return_address": null,
  "buyer_address": null,
  "parcel": {
    "id": "prcl_12345",
    "length": 10.5,
    "width": 5,
    "height": 3.2,
    "weight": 1.75,
    "predefined_package": "PARCEL",
    "items": [
      {
        "description": "T-shirt",
        "quantity": 2,
        "weight": 0.3,
        "value": 15,
        "unit_weight": 0.15,
        "unit_value": 7.5,
        "currency": "USD",
        "hs_tariff_number": "6109.10.0012",
        "code": "SKU123",
        "origin_country": "US",
        "external_id": "item_789",
        "taxes": [
          {
            "title": "VAT",
            "rate": 0.2,
            "amount": 3
          }
        ]
      }
    ]
  },
  "parcels": [
    {
      "id": "prcl_12345",
      "length": 10.5,
      "width": 5,
      "height": 3.2,
      "weight": 1.75,
      "predefined_package": "PARCEL",
      "items": [
        {
          "description": "T-shirt",
          "quantity": 2,
          "weight": 0.3,
          "value": 15,
          "unit_weight": 0.15,
          "unit_value": 7.5,
          "currency": "USD",
          "hs_tariff_number": "6109.10.0012",
          "code": "SKU123",
          "origin_country": "US",
          "external_id": "item_789",
          "taxes": [
            {
              "title": "VAT",
              "rate": 0.2,
              "amount": 3
            }
          ]
        }
      ]
    }
  ],
  "customs_info": {
    "id": "cstinfo_123",
    "contents_type": "merchandise",
    "contents_explanation": "Clothing for retail sale",
    "customs_certify": true,
    "customs_signer": "John Doe",
    "eel_pfc": "NOEEI 30.37(a)",
    "non_delivery_option": "return",
    "restriction_type": "none",
    "restriction_comments": null,
    "customs_items": [
      {
        "id": "string",
        "description": "T-shirt",
        "quantity": 2,
        "weight": 0.5,
        "value": 20,
        "currency": "USD",
        "hs_tariff_number": "6109.10.0012",
        "code": "ABC123",
        "origin_country": "US",
        "manufacturer": "string",
        "eccn": "string",
        "printed_commodity_identifier": "string"
      }
    ]
  },
  "rates": [
    {
      "id": "rate_e47cf7d5ff4a46986ba56273e7214af0",
      "created_at": "2024-07-17T02:40:25Z",
      "updated_at": "2024-07-17T02:40:25Z",
      "object": "Rate",
      "carrier_account_id": "ca_bdda800c23dac20c9ca313d73926abea",
      "shipment_id": null,
      "service": "Express",
      "carrier": "USPS",
      "rate": "26.35",
      "currency": "USD",
      "list_rate": "26.35",
      "list_currency": "USD",
      "retail_rate": "30.45",
      "retail_currency": "USD",
      "billing_type": null,
      "carrier_readable": "USPS",
      "delivery_date": null,
      "delivery_datetime": null,
      "delivery_date_guaranteed": null,
      "delivery_days": null,
      "details": {
        "billing_weight": "FLAT",
        "surcharges": {
          "INSURANCE": 3.15,
          "FUEL": 1.25
        },
        "total_surcharges": "4.40",
        "total_freight": "26.35",
        "usps_cubic": false,
        "zone": "08"
      }
    }
  ],
  "selected_rate": {
    "id": "rate_e47cf7d5ff4a46986ba56273e7214af0",
    "created_at": "2024-07-17T02:40:25Z",
    "updated_at": "2024-07-17T02:40:25Z",
    "object": "Rate",
    "carrier_account_id": "ca_bdda800c23dac20c9ca313d73926abea",
    "shipment_id": null,
    "service": "Express",
    "carrier": "USPS",
    "rate": "26.35",
    "currency": "USD",
    "list_rate": "26.35",
    "list_currency": "USD",
    "retail_rate": "30.45",
    "retail_currency": "USD",
    "billing_type": null,
    "carrier_readable": "USPS",
    "delivery_date": null,
    "delivery_datetime": null,
    "delivery_date_guaranteed": null,
    "delivery_days": null,
    "details": {
      "billing_weight": "FLAT",
      "surcharges": {
        "INSURANCE": 3.15,
        "FUEL": 1.25
      },
      "total_surcharges": "4.40",
      "total_freight": "26.35",
      "usps_cubic": false,
      "zone": "08"
    }
  },
  "tracker": null,
  "forms": [
    {}
  ],
  "postage_label": null,
  "scan_form": null,
  "batch_id": null,
  "insurance": null,
  "is_return": null,
  "refund_status": "rejected",
  "status": "unknown",
  "tracking_code": "1Z999AA10123456784",
  "usps_zone": 9,
  "options": {
    "label_size": "4x6",
    "label_format": "png",
    "additionalProperty": "anything"
  }
}

successful