Api Reference

Refunds

On this page, we'll dive into the global refund endpoints for managing refunds across your entire account.

The refund model

The refund model contains all the information about refunds, including the refund lines, amounts, and tax information.

Properties

Name	Type	Description
`id`	`string`	Unique identifier for the refund (starts with `ref_`).
`resource`	`string`	The resource type. Always `refund`.
`orderId`	`string \| null`	ID of the credit note order created for this refund. Only present after the refund is processed.
`merchantId`	`string`	ID of the merchant.
`customerId`	`string`	ID of the customer receiving the refund.
`testmode`	`boolean`	Whether this refund is in test mode.
`status`	`string`	The current status of the refund. Can be `pending`, `completed`, `failed`, or `canceled`.
`originalOrderId`	`string`	ID of the original order being refunded.
`total`	`Money`	Total refund amount including taxes. A Money object with `value` (decimal string) and `currency` (ISO 4217 code).
`subtotal`	`Money`	Refund subtotal before taxes.
`taxSummary`	`Money`	Total tax amount being refunded.
`lines`	`array`	Array of refund line items. Each line includes `id`, `resource`, `description`, `quantity`, `basePrice`, `total`, `subtotal`, and `taxes`.
`createdAt`	`string`	When this refund was created (ISO 8601 format).
`links`	`object`	HATEOAS links to related resources. Contains `self`, `originalOrder`, and optionally `order` (the credit note).

List all refunds

GET /v1/refunds

This endpoint allows you to retrieve a paginated list of all refunds across your account.

Optional parameters

Name	Type	Description
`limit`	`integer`	The number of refunds to return (default: 10, max: 100).
`startingAfter`	`string`	A cursor for use in pagination. Returns results after this refund ID.
`endingBefore`	`string`	A cursor for use in pagination. Returns results before this refund ID.

curl -G https://api.vatly.com/v1/refunds \
  -H "Authorization: Bearer live_your_api_key_here" \
  -d limit=10

$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');

$refunds = $vatly->refunds->page();

{
  "data": [
    {
      "id": "ref_abc123def456",
      "resource": "refund",
      "orderId": "ord_credit123",
      "merchantId": "mer_abc123",
      "customerId": "cus_xyz789",
      "testmode": false,
      "status": "completed",
      "originalOrderId": "ord_original123",
      "total": {
        "value": "18.15",
        "currency": "EUR"
      },
      "subtotal": {
        "value": "15.00",
        "currency": "EUR"
      },
      "taxSummary": {
        "value": "3.15",
        "currency": "EUR"
      },
      "lines": [
        {
          "id": "rli_abc123",
          "resource": "refundline",
          "description": "Pro Monthly Subscription (Refund)",
          "quantity": 1,
          "basePrice": {
            "value": "15.00",
            "currency": "EUR"
          },
          "total": {
            "value": "18.15",
            "currency": "EUR"
          },
          "subtotal": {
            "value": "15.00",
            "currency": "EUR"
          },
          "taxes": {
            "value": "3.15",
            "currency": "EUR"
          }
        }
      ],
      "createdAt": "2024-01-15T10:30:00Z",
      "links": {
        "self": {
          "href": "https://api.vatly.com/v1/refunds/ref_abc123def456",
          "type": "application/json"
        },
        "originalOrder": {
          "href": "https://api.vatly.com/v1/orders/ord_original123",
          "type": "application/json"
        },
        "order": {
          "href": "https://api.vatly.com/v1/orders/ord_credit123",
          "type": "application/json"
        }
      }
    }
  ],
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/refunds?limit=10",
      "type": "application/json"
    },
    "next": null,
    "prev": null
  },
  "count": 1
}

Get a refund

GET /v1/refunds/:refundId

This endpoint allows you to retrieve details of a specific refund.

Parameters

Name	Type	Description
`refundId`	`string`	The unique identifier of the refund.

curl https://api.vatly.com/v1/refunds/ref_abc123def456 \
  -H "Authorization: Bearer live_your_api_key_here"

$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');

$refund = $vatly->refunds->get('ref_abc123def456');

{
  "id": "ref_abc123def456",
  "resource": "refund",
  "orderId": "ord_credit123",
  "merchantId": "mer_abc123",
  "customerId": "cus_xyz789",
  "testmode": false,
  "status": "completed",
  "originalOrderId": "ord_original123",
  "total": {
    "value": "18.15",
    "currency": "EUR"
  },
  "subtotal": {
    "value": "15.00",
    "currency": "EUR"
  },
  "taxSummary": {
    "value": "3.15",
    "currency": "EUR"
  },
  "lines": [
    {
      "id": "rli_abc123",
      "resource": "refundline",
      "description": "Pro Monthly Subscription (Refund)",
      "quantity": 1,
      "basePrice": {
        "value": "15.00",
        "currency": "EUR"
      },
      "total": {
        "value": "18.15",
        "currency": "EUR"
      },
      "subtotal": {
        "value": "15.00",
        "currency": "EUR"
      },
      "taxes": {
        "value": "3.15",
        "currency": "EUR"
      }
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/refunds/ref_abc123def456",
      "type": "application/json"
    },
    "originalOrder": {
      "href": "https://api.vatly.com/v1/orders/ord_original123",
      "type": "application/json"
    },
    "order": {
      "href": "https://api.vatly.com/v1/orders/ord_credit123",
      "type": "application/json"
    }
  }
}

Edit this pageorReport an issue

Order Refunds

On this page, we'll dive into the different order refund endpoints you can use to manage refunds programmatically.

Chargebacks

On this page, we'll dive into the different chargeback endpoints you can use to query chargebacks programmatically.