Api Reference

Order Refunds

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

The refund model

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

Properties

Name	Type	Description
`id`	`string`	Unique identifier for the refund (starts with `refund_`).
`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`, `queued`, `processing`, `refunded`, `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`	`array`	Tax breakdown by rate being refunded. Array of objects with `taxRate` (`name`, `percentage`, `taxablePercentage`) and `amount` (Money).
`lines`	`array`	Array of refund line items. See RefundLine properties below.
`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).

Status values

Status	Description
`pending`	Refund is ready to be sent to the bank.
`queued`	Refund is queued due to a lack of balance.
`processing`	Refund is being processed (cancellation no longer possible).
`refunded`	Refund has been processed successfully.
`failed`	Refund has failed after processing.
`canceled`	Refund was canceled.

RefundLine Properties

Name	Type	Description
`id`	`string`	Unique identifier for this refund line (starts with `refund_item_`).
`resource`	`string`	The resource type. Always `refundline`.
`description`	`string`	Description of the refunded item.
`quantity`	`integer`	Number of units being refunded.
`basePrice`	`Money`	Refund amount per unit before taxes.
`total`	`Money`	Total refund amount including taxes.
`subtotal`	`Money`	Refund subtotal before taxes.
`taxes`	`array`	Tax breakdown by rate being refunded. Array of objects with `taxRate` and `amount`.

Create a refund

POST /v1/orders/:orderId/refunds

This endpoint allows you to create a partial refund for a specific order. You specify which order line items to refund and the amount for each.

Parameters

Name	Type	Description
`orderId`	`string`	The unique identifier of the order.

Request body

Name	Type	Description
`items`	`array`	(Required) Array of items to refund. Each item has: `itemId` (string, required) - ID of the order line item, `amount` (Money, required) - amount to refund before taxes, `description` (string, optional) - custom description, `descriptionAdditionalLine` (string, optional) - additional description line.
`metadata`	`object`	Arbitrary key-value metadata for your application.

curl -X POST https://api.vatly.com/v1/orders/order_Fp2kQrSvWm8NjLhYbUcP/refunds \
  -H "Authorization: Bearer live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "itemId": "order_item_Jk4pQrSvWm8NjLhYbUcP",
        "amount": {
          "value": "15.00",
          "currency": "EUR"
        },
        "description": "50% refund for service issue"
      }
    ]
  }'

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

$refund = $vatly->orders->refunds('order_Fp2kQrSvWm8NjLhYbUcP')->create([
    'items' => [
        [
            'itemId' => 'order_item_Jk4pQrSvWm8NjLhYbUcP',
            'amount' => [
                'value' => '15.00',
                'currency' => 'EUR',
            ],
            'description' => '50% refund for service issue',
        ],
    ],
]);

{
  "id": "refund_Mn6xBtPvKw2RjTgYcZaE",
  "resource": "refund",
  "orderId": null,
  "merchantId": "merchant_Fp2kQrSvWm8NjLhYbUcP",
  "customerId": "customer_Lp3mNvBxKw7RjTgYcZaE",
  "testmode": false,
  "status": "pending",
  "originalOrderId": "order_Fp2kQrSvWm8NjLhYbUcP",
  "total": {
    "value": "18.15",
    "currency": "EUR"
  },
  "subtotal": {
    "value": "15.00",
    "currency": "EUR"
  },
  "taxSummary": [
    {
      "taxRate": {
        "name": "VAT",
        "percentage": 21,
        "taxablePercentage": 100
      },
      "amount": {
        "value": "3.15",
        "currency": "EUR"
      }
    }
  ],
  "lines": [
    {
      "id": "refund_item_Tk7mNvBxKw2RjTgYcZaE",
      "resource": "refundline",
      "description": "50% refund for service issue",
      "quantity": 1,
      "basePrice": {
        "value": "15.00",
        "currency": "EUR"
      },
      "total": {
        "value": "18.15",
        "currency": "EUR"
      },
      "subtotal": {
        "value": "15.00",
        "currency": "EUR"
      },
      "taxes": [
        {
          "taxRate": {
            "name": "VAT",
            "percentage": 21,
            "taxablePercentage": 100
          },
          "amount": {
            "value": "3.15",
            "currency": "EUR"
          }
        }
      ]
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/refunds/refund_Mn6xBtPvKw2RjTgYcZaE",
      "type": "application/json"
    },
    "originalOrder": {
      "href": "https://api.vatly.com/v1/orders/order_Fp2kQrSvWm8NjLhYbUcP",
      "type": "application/json"
    },
    "order": null
  }
}

Create a full refund

POST /v1/orders/:orderId/refunds/full

This endpoint allows you to create a full refund for a specific order. This will refund the entire remaining amount of the order.

Parameters

Name	Type	Description
`orderId`	`string`	The unique identifier of the order.

Request body (optional)

Name	Type	Description
`metadata`	`object`	Arbitrary key-value metadata for your application.

curl -X POST https://api.vatly.com/v1/orders/order_Fp2kQrSvWm8NjLhYbUcP/refunds/full \
  -H "Authorization: Bearer live_your_api_key_here"

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

$refund = $vatly->orders->refunds('order_Fp2kQrSvWm8NjLhYbUcP')->full();

{
  "id": "refund_Rk5pQrSvWm8NjLhYbUcP",
  "resource": "refund",
  "orderId": null,
  "merchantId": "merchant_Bm7xNvPwKr3YjTgHcZaE",
  "customerId": "customer_Wt5mNvBxKw7YcZaEjLhR",
  "testmode": false,
  "status": "pending",
  "originalOrderId": "order_Fp2kQrSvWm8NjLhYbUcP",
  "total": {
    "value": "35.09",
    "currency": "EUR"
  },
  "subtotal": {
    "value": "29.00",
    "currency": "EUR"
  },
  "taxSummary": [
    {
      "taxRate": {
        "name": "VAT",
        "percentage": 21,
        "taxablePercentage": 100
      },
      "amount": {
        "value": "6.09",
        "currency": "EUR"
      }
    }
  ],
  "lines": [
    {
      "id": "refund_item_Bm7xNvPwKr3YjTgHcZaE",
      "resource": "refundline",
      "description": "Pro Monthly Subscription (Full Refund)",
      "quantity": 1,
      "basePrice": {
        "value": "29.00",
        "currency": "EUR"
      },
      "total": {
        "value": "35.09",
        "currency": "EUR"
      },
      "subtotal": {
        "value": "29.00",
        "currency": "EUR"
      },
      "taxes": [
        {
          "taxRate": {
            "name": "VAT",
            "percentage": 21,
            "taxablePercentage": 100
          },
          "amount": {
            "value": "6.09",
            "currency": "EUR"
          }
        }
      ]
    }
  ],
  "createdAt": "2024-01-21T09:00:00Z",
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/refunds/refund_Rk5pQrSvWm8NjLhYbUcP",
      "type": "application/json"
    },
    "originalOrder": {
      "href": "https://api.vatly.com/v1/orders/order_Fp2kQrSvWm8NjLhYbUcP",
      "type": "application/json"
    },
    "order": null
  }
}

List order refunds

GET /v1/orders/:orderId/refunds

This endpoint allows you to retrieve a list of all refunds for a specific order.

Parameters

Name	Type	Description
`orderId`	`string`	The unique identifier of the order.
`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 https://api.vatly.com/v1/orders/order_Fp2kQrSvWm8NjLhYbUcP/refunds \
  -H "Authorization: Bearer live_your_api_key_here"

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

$refunds = $vatly->orders->refunds('order_Fp2kQrSvWm8NjLhYbUcP')->page();

{
  "data": [
    {
      "id": "refund_Bm7xNvPwKr3YjTgHcZaE",
      "resource": "refund",
      "orderId": null,
      "merchantId": "merchant_Bm7xNvPwKr3YjTgHcZaE",
      "customerId": "customer_Wt5mNvBxKw7YcZaEjLhR",
      "testmode": false,
      "status": "pending",
      "originalOrderId": "order_Fp2kQrSvWm8NjLhYbUcP",
      "total": {
        "value": "12.10",
        "currency": "EUR"
      },
      "subtotal": {
        "value": "10.00",
        "currency": "EUR"
      },
      "taxSummary": [
        {
          "taxRate": {
            "name": "VAT",
            "percentage": 21,
            "taxablePercentage": 100
          },
          "amount": {
            "value": "2.10",
            "currency": "EUR"
          }
        }
      ],
      "lines": [
        {
          "id": "refund_item_Jk4pQrSvWm8NjLhYbUcP",
          "resource": "refundline",
          "description": "Partial refund for service issue",
          "quantity": 1,
          "basePrice": {
            "value": "10.00",
            "currency": "EUR"
          },
          "total": {
            "value": "12.10",
            "currency": "EUR"
          },
          "subtotal": {
            "value": "10.00",
            "currency": "EUR"
          },
          "taxes": [
            {
              "taxRate": {
                "name": "VAT",
                "percentage": 21,
                "taxablePercentage": 100
              },
              "amount": {
                "value": "2.10",
                "currency": "EUR"
              }
            }
          ]
        }
      ],
      "createdAt": "2024-01-20T14:00:00Z",
      "links": {
        "self": {
          "href": "https://api.vatly.com/v1/refunds/refund_Bm7xNvPwKr3YjTgHcZaE",
          "type": "application/json"
        },
        "originalOrder": {
          "href": "https://api.vatly.com/v1/orders/order_Fp2kQrSvWm8NjLhYbUcP",
          "type": "application/json"
        },
        "order": null
      }
    }
  ],
  "count": 1,
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/orders/order_Fp2kQrSvWm8NjLhYbUcP/refunds",
      "type": "application/json"
    },
    "next": null,
    "prev": null
  }
}

Get an order refund

GET /v1/orders/:orderId/refunds/:refundId

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

Parameters

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

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

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

$refund = $vatly->orders->refunds('order_Fp2kQrSvWm8NjLhYbUcP')->get('refund_Xk9pQrSvWm4NjLhYbUcP');

{
  "id": "refund_Xk9pQrSvWm4NjLhYbUcP",
  "resource": "refund",
  "orderId": "order_Bm7xNvPwKr3YjTgHcZaE",
  "merchantId": "merchant_Bm7xNvPwKr3YjTgHcZaE",
  "customerId": "customer_Wt5mNvBxKw7YcZaEjLhR",
  "testmode": false,
  "status": "refunded",
  "originalOrderId": "order_Fp2kQrSvWm8NjLhYbUcP",
  "total": {
    "value": "18.15",
    "currency": "EUR"
  },
  "subtotal": {
    "value": "15.00",
    "currency": "EUR"
  },
  "taxSummary": [
    {
      "taxRate": {
        "name": "VAT",
        "percentage": 21,
        "taxablePercentage": 100
      },
      "amount": {
        "value": "3.15",
        "currency": "EUR"
      }
    }
  ],
  "lines": [
    {
      "id": "refund_item_Mn6xBtPvKw2RjTgYcZaE",
      "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": [
        {
          "taxRate": {
            "name": "VAT",
            "percentage": 21,
            "taxablePercentage": 100
          },
          "amount": {
            "value": "3.15",
            "currency": "EUR"
          }
        }
      ]
    }
  ],
  "createdAt": "2024-01-20T14:00:00Z",
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/refunds/refund_Xk9pQrSvWm4NjLhYbUcP",
      "type": "application/json"
    },
    "originalOrder": {
      "href": "https://api.vatly.com/v1/orders/order_Fp2kQrSvWm8NjLhYbUcP",
      "type": "application/json"
    },
    "order": {
      "href": "https://api.vatly.com/v1/orders/order_Bm7xNvPwKr3YjTgHcZaE",
      "type": "application/json"
    }
  }
}

Cancel an order refund

DELETE /v1/orders/:orderId/refunds/:refundId

This endpoint allows you to cancel a pending refund for a specific order. Only pending refunds can be cancelled.

Parameters

Name	Type	Description
`orderId`	`string`	The unique identifier of the order.
`refundId`	`string`	The unique identifier of the refund to cancel.

curl -X DELETE https://api.vatly.com/v1/orders/order_Fp2kQrSvWm8NjLhYbUcP/refunds/refund_Mn6xBtPvKw2RjTgYcZaE \
  -H "Authorization: Bearer live_your_api_key_here"

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

$vatly->orders->refunds('order_Fp2kQrSvWm8NjLhYbUcP')->cancel('refund_Mn6xBtPvKw2RjTgYcZaE');

Returns 204 No Content on success.

Edit this pageorReport an issue

Orders

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

Refunds

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