# Create order refund **⚠️ We no longer recommend using the Orders API. Please refer to the [Payments API](payments-api) instead.** When using the Orders API, refunds should be made for a specific order. If you want to refund arbitrary amounts, however, you can also use the [Create payment refund endpoint](create-refund) by creating a refund on the payment itself. If an order line is still in the `authorized` state, it cannot be refunded. You should cancel it instead. Order lines that are `paid`, `shipping` or `completed` can be refunded. > 🔑 Access with > > [API key](/reference/authentication) > > [Organization access token with **refunds.write**](/reference/authentication) > > [OAuth access with **refunds.write**](/reference/authentication) # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Receiving orders", "version": "1.0.0", "license": { "name": "Attribution-NonCommercial-ShareAlike 4.0 International", "identifier": "CC-BY-NC-SA-4.0" } }, "servers": [ { "url": "https://api.mollie.com/v2" } ], "security": [ { "apiKey": [] }, { "organizationAccessToken": [] }, { "oAuth": [] } ], "paths": { "/orders/{orderId}/refunds": { "parameters": [ { "name": "orderId", "description": "Provide the ID of the related order.", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ord_.+$", "example": "ord_5B8cwPMGnU" } } ], "post": { "deprecated": true, "summary": "Create order refund", "tags": [ "Orders API" ], "operationId": "create-order-refund", "x-speakeasy-name-override": "create-order", "security": [ { "apiKey": [] }, { "organizationAccessToken": [ "refunds.write" ] }, { "oAuth": [ "refunds.write" ] } ], "description": "**⚠️ We no longer recommend using the Orders API. Please refer to the [Payments API](payments-api) instead.**\n\nWhen using the Orders API, refunds should be made for a specific order.\n\nIf you want to refund arbitrary amounts, however, you can also use the [Create payment refund endpoint](create-refund) by creating a refund on the payment itself.\n\nIf an order line is still in the `authorized` state, it cannot be refunded. You should cancel it instead. Order lines that are `paid`, `shipping` or `completed` can be refunded.\n\n> 🔑 Access with\n>\n> [API key](/reference/authentication)\n>\n> [Organization access token with **refunds.write**](/reference/authentication)\n>\n> [OAuth access with **refunds.write**](/reference/authentication)", "requestBody": { "content": { "application/json": { "schema": { "required": [ "lines" ], "type": "object", "properties": { "resource": { "type": "string", "description": "Indicates the response contains a refund object. Will always contain the string `refund` for this endpoint.", "readOnly": true, "default": "refund" }, "id": { "allOf": [ { "type": "string", "pattern": "^re_.+$", "example": "re_5B8cwPMGnU" } ], "description": "The identifier uniquely referring to this refund. Mollie assigns this identifier at refund creation time. Mollie will always refer to the refund by this ID. Example: `re_4qqhO89gsT`.", "readOnly": true }, "mode": { "type": "string", "description": "Whether this entity was created in live mode or in test mode.\n\nPossible values: `live` `test`", "readOnly": true, "example": "live" }, "description": { "type": "string", "description": "The description of the refund that may be shown to your customer, depending on the payment method used.", "maxLength": 255, "example": "Refunding a Chess Board" }, "amount": { "description": "The amount refunded to your customer with this refund. The amount is allowed to be lower than the original payment amount.", "type": "object", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } }, "settlementAmount": { "allOf": [ { "type": [ "object", "null" ], "description": "In v2 endpoints, monetary amounts are represented as objects with a `currency` and `value` field.", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } } ], "description": "This optional field will contain the approximate amount that will be deducted from your account balance, converted to the currency your account is settled in.\n\nThe amount is a **negative** amount.\n\nIf the refund is not directly processed by Mollie, for example for PayPal refunds, the settlement amount will be zero.\n\nSince the field contains an estimated amount during refund processing, it may change over time. For example, while the refund is queued the settlement amount is likely not yet available.\n\nTo retrieve accurate settlement amounts we recommend using the [List balance transactions endpoint](list-balance-transactions) instead.", "readOnly": true }, "metadata": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "object", "properties": {}, "additionalProperties": true }, { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Provide any data you like, for example a string or a JSON object. We will save the data alongside the entity. Whenever you fetch the entity with our API, we will also include the metadata. You can use up to approximately 1kB." }, "orderId": { "allOf": [ { "type": "string", "pattern": "^ord_.+$", "example": "ord_5B8cwPMGnU" } ], "description": "The unique identifier of the order this refund was created for. For example: `ord_8wmqcHMN4U`. Not present if the refund was not created for an order.", "readOnly": true }, "settlementId": { "type": [ "string", "null" ], "allOf": [ { "type": "string", "pattern": "^stl_.+$", "example": "stl_5B8cwPMGnU" } ], "description": "The identifier referring to the settlement this refund was settled with. This field is omitted if the refund is not settled (yet).", "readOnly": true }, "status": { "allOf": [ { "type": "string", "enum": [ "queued", "pending", "processing", "refunded", "failed", "canceled" ], "example": "queued" } ], "description": "Refunds may take some time to get confirmed.", "readOnly": true }, "createdAt": { "type": "string", "description": "The entity's date and time of creation, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.", "readOnly": true, "example": "2024-03-20T09:13:37+00:00" }, "externalReference": { "type": "object", "properties": { "type": { "type": "string", "description": "Specifies the reference type\n\nPossible values: `acquirer-reference`", "example": "acquirer-reference" }, "id": { "type": "string", "description": "Unique reference from the payment provider", "example": 123456789012345 } } }, "testmode": { "type": [ "boolean", "null" ], "description": "Whether to create the entity in test mode or live mode.\n\nMost API credentials are specifically created for either live mode or test mode, in which case this parameter must not be sent. For organization-level credentials such as OAuth access tokens, you can enable test mode by setting `testmode` to `true`.", "writeOnly": true, "example": false }, "lines": { "type": "array", "description": "A refund can optionally be linked to specific order lines.\n\nThe lines will show the `quantity`, `discountAmount`, `vatAmount`, and `totalAmount` refunded. If the line was partially refunded, these values will be different from the values in response from the [Get payment](get-payment) endpoint.", "items": { "type": "object", "required": [ "resource", "id", "orderId", "name", "sku", "type", "status", "metadata", "isCancelable", "quantity", "unitPrice", "vatRate", "vatAmount", "totalAmount", "createdAt", "_links" ], "properties": { "resource": { "type": "string", "readOnly": true, "example": "orderline" }, "id": { "description": "The ID of the order line you wish to refund. For example: `odl_jp31y97yjz`.", "type": "string", "pattern": "^odl_.+$", "example": "odl_5B8cwPMGnU" }, "orderId": { "allOf": [ { "type": "string", "pattern": "^ord_.+$", "example": "ord_5B8cwPMGnU" } ], "readOnly": true }, "name": { "type": "string", "example": "Chess Board" }, "sku": { "type": [ "string", "null" ], "example": 5702016116977 }, "type": { "type": "string", "enum": [ "physical", "digital", "discount", "shipping_fee", "store_credit", "gift_card", "surcharge" ], "example": "physical", "default": "physical" }, "status": { "type": "string", "enum": [ "created", "authorized", "paid", "canceled", "shipping", "completed" ], "example": "created" }, "metadata": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "object", "properties": {}, "additionalProperties": true }, { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Provide any data you like, for example a string or a JSON object. We will save the data alongside the entity. Whenever you fetch the entity with our API, we will also include the metadata. You can use up to approximately 1kB." }, "isCancelable": { "type": "boolean", "example": false }, "quantity": { "type": "integer", "description": "The number of items that should be refunded for this order line. When this parameter is omitted, the whole order line will be refunded.\n\nMust be less than the number of items already refunded for this order line.", "example": 1 }, "quantityShipped": { "type": "integer", "example": 0 }, "amountShipped": { "type": "object", "description": "In v2 endpoints, monetary amounts are represented as objects with a `currency` and `value` field.", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } }, "quantityRefunded": { "type": "integer", "example": 0 }, "amountRefunded": { "type": "object", "description": "In v2 endpoints, monetary amounts are represented as objects with a `currency` and `value` field.", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } }, "quantityCanceled": { "type": "integer", "example": 0 }, "amountCanceled": { "type": "object", "description": "In v2 endpoints, monetary amounts are represented as objects with a `currency` and `value` field.", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } }, "amount": { "allOf": [ { "type": "object", "description": "In v2 endpoints, monetary amounts are represented as objects with a `currency` and `value` field.", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } } ], "description": "The amount that you want to refund. In almost all cases, Mollie can determine the amount automatically.\n\nThe amount is required only if you are partially refunding an order line which has a non-zero `discountAmount`.\n\nThe amount you can refund depends on various properties of the order line and the create order refund request. The maximum that can be refunded is `unit price x quantity to ship`.\n\nThe minimum amount depends on the discount applied to the line, the quantity already refunded or shipped, the amounts already refunded or shipped and the quantity you want to refund.\n\nIf you do not send an amount, Mollie will determine the amount automatically or respond with an error if the amount cannot be determined automatically. The error will contain the `extra.minimumAmount` and `extra.maximumAmount` properties that allow you pick the right amount.", "writeOnly": true }, "shippableQuantity": { "type": "integer", "example": 0 }, "refundableQuantity": { "type": "integer", "example": 0 }, "cancelableQuantity": { "type": "integer", "example": 0 }, "unitPrice": { "allOf": [ { "type": "object", "description": "In v2 endpoints, monetary amounts are represented as objects with a `currency` and `value` field.", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } } ], "readOnly": true }, "totalAmount": { "allOf": [ { "type": "object", "description": "In v2 endpoints, monetary amounts are represented as objects with a `currency` and `value` field.", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } } ], "readOnly": true }, "vatRate": { "type": "string", "example": "21.00" }, "vatAmount": { "allOf": [ { "type": "object", "description": "In v2 endpoints, monetary amounts are represented as objects with a `currency` and `value` field.", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } } ], "readOnly": true }, "createdAt": { "type": "string", "example": "2025-03-28T16:42:12+00:00" }, "discountedAmount": { "allOf": [ { "type": "object", "description": "In v2 endpoints, monetary amounts are represented as objects with a `currency` and `value` field.", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } } ], "readOnly": true }, "_links": { "type": "object", "description": "An object with several relevant URLs. Every URL object will contain an `href` and a `type` field.", "properties": { "productUr": { "type": "object", "description": "In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } }, "imageUrl": { "type": "object", "description": "In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } } }, "readOnly": true } } } }, "_links": { "type": "object", "description": "An object with several relevant URLs. Every URL object will contain an `href` and a `type` field.", "properties": { "self": { "type": "object", "description": "In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } }, "order": { "description": "The API resource URL of the [order](get-order) that this refund belongs to, if applicable.", "type": "object", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } }, "settlement": { "description": "The API resource URL of the [settlement](get-settlement) this refund has been settled with. Not present if not yet settled.", "type": [ "object", "null" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } }, "documentation": { "type": "object", "description": "In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } } }, "readOnly": true } } } } } }, "responses": { "201": { "description": "The newly created refund object.", "content": { "application/hal+json": { "schema": { "type": "object", "required": [ "resource", "id", "mode", "amount", "status", "createdAt", "description", "metadata", "orderId", "_links" ], "properties": { "resource": { "type": "string", "description": "Indicates the response contains a refund object. Will always contain the string `refund` for this endpoint.", "readOnly": true, "default": "refund" }, "id": { "allOf": [ { "type": "string", "pattern": "^re_.+$", "example": "re_5B8cwPMGnU" } ], "description": "The identifier uniquely referring to this refund. Mollie assigns this identifier at refund creation time. Mollie will always refer to the refund by this ID. Example: `re_4qqhO89gsT`.", "readOnly": true }, "mode": { "type": "string", "description": "Whether this entity was created in live mode or in test mode.\n\nPossible values: `live` `test`", "readOnly": true, "example": "live" }, "description": { "type": "string", "description": "The description of the refund that may be shown to your customer, depending on the payment method used.", "maxLength": 255, "example": "Refunding a Chess Board" }, "amount": { "description": "The amount refunded to your customer with this refund. The amount is allowed to be lower than the original payment amount.", "type": "object", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } }, "settlementAmount": { "allOf": [ { "type": [ "object", "null" ], "description": "In v2 endpoints, monetary amounts are represented as objects with a `currency` and `value` field.", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } } ], "description": "This optional field will contain the approximate amount that will be deducted from your account balance, converted to the currency your account is settled in.\n\nThe amount is a **negative** amount.\n\nIf the refund is not directly processed by Mollie, for example for PayPal refunds, the settlement amount will be zero.\n\nSince the field contains an estimated amount during refund processing, it may change over time. For example, while the refund is queued the settlement amount is likely not yet available.\n\nTo retrieve accurate settlement amounts we recommend using the [List balance transactions endpoint](list-balance-transactions) instead.", "readOnly": true }, "metadata": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "object", "properties": {}, "additionalProperties": true }, { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Provide any data you like, for example a string or a JSON object. We will save the data alongside the entity. Whenever you fetch the entity with our API, we will also include the metadata. You can use up to approximately 1kB." }, "orderId": { "allOf": [ { "type": "string", "pattern": "^ord_.+$", "example": "ord_5B8cwPMGnU" } ], "description": "The unique identifier of the order this refund was created for. For example: `ord_8wmqcHMN4U`. Not present if the refund was not created for an order.", "readOnly": true }, "settlementId": { "type": [ "string", "null" ], "allOf": [ { "type": "string", "pattern": "^stl_.+$", "example": "stl_5B8cwPMGnU" } ], "description": "The identifier referring to the settlement this refund was settled with. This field is omitted if the refund is not settled (yet).", "readOnly": true }, "status": { "allOf": [ { "type": "string", "enum": [ "queued", "pending", "processing", "refunded", "failed", "canceled" ], "example": "queued" } ], "description": "Refunds may take some time to get confirmed.", "readOnly": true }, "createdAt": { "type": "string", "description": "The entity's date and time of creation, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.", "readOnly": true, "example": "2024-03-20T09:13:37+00:00" }, "externalReference": { "type": "object", "properties": { "type": { "type": "string", "description": "Specifies the reference type\n\nPossible values: `acquirer-reference`", "example": "acquirer-reference" }, "id": { "type": "string", "description": "Unique reference from the payment provider", "example": 123456789012345 } } }, "testmode": { "type": [ "boolean", "null" ], "description": "Whether to create the entity in test mode or live mode.\n\nMost API credentials are specifically created for either live mode or test mode, in which case this parameter must not be sent. For organization-level credentials such as OAuth access tokens, you can enable test mode by setting `testmode` to `true`.", "writeOnly": true, "example": false }, "lines": { "type": "array", "description": "A refund can optionally be linked to specific order lines.\n\nThe lines will show the `quantity`, `discountAmount`, `vatAmount`, and `totalAmount` refunded. If the line was partially refunded, these values will be different from the values in response from the [Get payment](get-payment) endpoint.", "items": { "type": "object", "required": [ "resource", "id", "orderId", "name", "sku", "type", "status", "metadata", "isCancelable", "quantity", "unitPrice", "vatRate", "vatAmount", "totalAmount", "createdAt", "_links" ], "properties": { "resource": { "type": "string", "readOnly": true, "example": "orderline" }, "id": { "description": "The ID of the order line you wish to refund. For example: `odl_jp31y97yjz`.", "type": "string", "pattern": "^odl_.+$", "example": "odl_5B8cwPMGnU" }, "orderId": { "allOf": [ { "type": "string", "pattern": "^ord_.+$", "example": "ord_5B8cwPMGnU" } ], "readOnly": true }, "name": { "type": "string", "example": "Chess Board" }, "sku": { "type": [ "string", "null" ], "example": 5702016116977 }, "type": { "type": "string", "enum": [ "physical", "digital", "discount", "shipping_fee", "store_credit", "gift_card", "surcharge" ], "example": "physical", "default": "physical" }, "status": { "type": "string", "enum": [ "created", "authorized", "paid", "canceled", "shipping", "completed" ], "example": "created" }, "metadata": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "object", "properties": {}, "additionalProperties": true }, { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Provide any data you like, for example a string or a JSON object. We will save the data alongside the entity. Whenever you fetch the entity with our API, we will also include the metadata. You can use up to approximately 1kB." }, "isCancelable": { "type": "boolean", "example": false }, "quantity": { "type": "integer", "description": "The number of items that should be refunded for this order line. When this parameter is omitted, the whole order line will be refunded.\n\nMust be less than the number of items already refunded for this order line.", "example": 1 }, "quantityShipped": { "type": "integer", "example": 0 }, "amountShipped": { "type": "object", "description": "In v2 endpoints, monetary amounts are represented as objects with a `currency` and `value` field.", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } }, "quantityRefunded": { "type": "integer", "example": 0 }, "amountRefunded": { "type": "object", "description": "In v2 endpoints, monetary amounts are represented as objects with a `currency` and `value` field.", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } }, "quantityCanceled": { "type": "integer", "example": 0 }, "amountCanceled": { "type": "object", "description": "In v2 endpoints, monetary amounts are represented as objects with a `currency` and `value` field.", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } }, "amount": { "allOf": [ { "type": "object", "description": "In v2 endpoints, monetary amounts are represented as objects with a `currency` and `value` field.", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } } ], "description": "The amount that you want to refund. In almost all cases, Mollie can determine the amount automatically.\n\nThe amount is required only if you are partially refunding an order line which has a non-zero `discountAmount`.\n\nThe amount you can refund depends on various properties of the order line and the create order refund request. The maximum that can be refunded is `unit price x quantity to ship`.\n\nThe minimum amount depends on the discount applied to the line, the quantity already refunded or shipped, the amounts already refunded or shipped and the quantity you want to refund.\n\nIf you do not send an amount, Mollie will determine the amount automatically or respond with an error if the amount cannot be determined automatically. The error will contain the `extra.minimumAmount` and `extra.maximumAmount` properties that allow you pick the right amount.", "writeOnly": true }, "shippableQuantity": { "type": "integer", "example": 0 }, "refundableQuantity": { "type": "integer", "example": 0 }, "cancelableQuantity": { "type": "integer", "example": 0 }, "unitPrice": { "allOf": [ { "type": "object", "description": "In v2 endpoints, monetary amounts are represented as objects with a `currency` and `value` field.", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } } ], "readOnly": true }, "totalAmount": { "allOf": [ { "type": "object", "description": "In v2 endpoints, monetary amounts are represented as objects with a `currency` and `value` field.", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } } ], "readOnly": true }, "vatRate": { "type": "string", "example": "21.00" }, "vatAmount": { "allOf": [ { "type": "object", "description": "In v2 endpoints, monetary amounts are represented as objects with a `currency` and `value` field.", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } } ], "readOnly": true }, "createdAt": { "type": "string", "example": "2025-03-28T16:42:12+00:00" }, "discountedAmount": { "allOf": [ { "type": "object", "description": "In v2 endpoints, monetary amounts are represented as objects with a `currency` and `value` field.", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } } ], "readOnly": true }, "_links": { "type": "object", "description": "An object with several relevant URLs. Every URL object will contain an `href` and a `type` field.", "properties": { "productUr": { "type": "object", "description": "In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } }, "imageUrl": { "type": "object", "description": "In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } } }, "readOnly": true } } } }, "_links": { "type": "object", "description": "An object with several relevant URLs. Every URL object will contain an `href` and a `type` field.", "properties": { "self": { "type": "object", "description": "In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } }, "order": { "description": "The API resource URL of the [order](get-order) that this refund belongs to, if applicable.", "type": "object", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } }, "settlement": { "description": "The API resource URL of the [settlement](get-settlement) this refund has been settled with. Not present if not yet settled.", "type": [ "object", "null" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } }, "documentation": { "type": "object", "description": "In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } } }, "readOnly": true } } }, "examples": { "create-order-refund-201-1": { "summary": "The newly created refund object", "value": { "resource": "refund", "id": "re_4qqhO89gsT", "description": "Required quantity not in stock, refunding one photo book.", "lines": [ { "resource": "orderline", "id": "odl_dgtxyl", "orderId": "ord_stTC2WHAuS", "quantity": 1, "unitPrice": { "value": "9.95", "currency": "EUR" }, "totalAmount": { "value": "9.95", "currency": "EUR" } } ], "status": "pending", "metadata": "{\"bookkeeping_id\":12345}", "orderId": "ord_stTC2WHAuS", "createdAt": "2023-03-14T17:09:02+00:00", "_links": { "self": { "href": "...", "type": "application/hal+json" }, "order": { "href": "https://api.mollie.com/v2/orders/ord_stTC2WHAuS", "type": "application/hal+json" }, "documentation": { "href": "...", "type": "text/html" } } } } } } } }, "404": { "description": "No entity with this ID exists.", "content": { "application/hal+json": { "schema": { "type": "object", "description": "An error response object.", "required": [ "status", "title", "detail", "_links" ], "properties": { "status": { "type": "integer", "description": "The status code of the error message. This is always the same code as the status code of the HTTP message itself.", "minimum": 400, "maximum": 599, "example": 404 }, "title": { "type": "string", "description": "The HTTP reason phrase of the error. For example, for a `404` error, the `title` will be `Not Found`.", "example": "Not Found" }, "detail": { "type": "string", "description": "A detailed human-readable description of the error that occurred.", "example": "The resource does not exist" }, "field": { "type": "string", "description": "If the error was caused by a value provided by you in a specific field, the `field` property will contain the name of the field that caused the issue.", "example": "description" }, "_links": { "type": "object", "required": [ "documentation" ], "properties": { "documentation": { "type": "object", "description": "The URL to the generic Mollie API error handling guide.", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "example": "https://docs.mollie.com/errors" }, "type": { "type": "string", "example": "text/html" } } } } } } }, "example": { "status": 404, "title": "Not Found", "detail": "No entity exists with token 'uct_abcDEFghij123456789'", "_links": { "documentation": { "href": "...", "type": "text/html" } } } } } }, "422": { "description": "The request contains issues. For example, if the refund amount is missing.", "content": { "application/hal+json": { "schema": { "type": "object", "description": "An error response object.", "required": [ "status", "title", "detail", "_links" ], "properties": { "status": { "type": "integer", "description": "The status code of the error message. This is always the same code as the status code of the HTTP message itself.", "minimum": 400, "maximum": 599, "example": 404 }, "title": { "type": "string", "description": "The HTTP reason phrase of the error. For example, for a `404` error, the `title` will be `Not Found`.", "example": "Not Found" }, "detail": { "type": "string", "description": "A detailed human-readable description of the error that occurred.", "example": "The resource does not exist" }, "field": { "type": "string", "description": "If the error was caused by a value provided by you in a specific field, the `field` property will contain the name of the field that caused the issue.", "example": "description" }, "_links": { "type": "object", "required": [ "documentation" ], "properties": { "documentation": { "type": "object", "description": "The URL to the generic Mollie API error handling guide.", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "example": "https://docs.mollie.com/errors" }, "type": { "type": "string", "example": "text/html" } } } } } } }, "example": { "status": 422, "title": "Unprocessable Entity", "detail": "The 'amount' field is missing", "field": "amount", "_links": { "documentation": { "href": "...", "type": "text/html" } } } } } } }, "x-readme": { "code-samples": [ { "language": "shell", "code": "curl -X POST https://api.mollie.com/v2/orders/ord_stTC2WHAuS/refunds \\\n -H \"Authorization: Bearer live_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM\" \\\n -d \"description=Required quantity not in stock, refunding one photo book.\" \\\n -d \"metadata={\\\"bookkeeping_id\\\": 12345}\" \\\n -d \"lines=[{\\\"id\\\": \\\"odl_dgtxyl\\\", \\\"quantity\\\": 1}]\"" }, { "language": "php", "code": "$mollie = new \\Mollie\\Api\\MollieApiClient();\n$mollie->setApiKey(\"live_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM\");\n\n$order = $mollie->orders->get(\"ord_stTC2WHAuS\");\n $order->refund([\n \"lines\" => [\n [\n \"id\" => \"odl_dgtxyl\",\n \"quantity\" => 1,\n ],\n ],\n \"description\" => \"Required quantity not in stock, refunding one photo book.\",\n]);\n\n// Alternative shorthand for refunding all eligible order lines\n$order->refundAll([\n \"description\" => \"Required quantity not in stock, refunding one photo book.\",\n]);", "install": "composer require mollie/mollie-api-php" }, { "language": "node", "code": "const { createMollieClient } = require('@mollie/api-client');\nconst mollieClient = createMollieClient({ apiKey: 'live_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM' });\n\nconst refund = await mollieClient.orderRefunds.create({\n orderId: 'ord_stTC2WHAuS',\n lines: [{\n id: 'odl_dgtxyl',\n quantity: 1\n }],\n description: 'Required quantity not in stock, refunding one photo book.'\n});", "install": "npm install @mollie/api-client" }, { "language": "python", "code": "from mollie.api.client import Client\n\nmollie_client = Client()\nmollie_client.set_api_key(\"live_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM\")\n\norder = mollie_client.orders.get(\"ord_stTC2WHAuS\")\nrefund = order.refunds.create({\n \"lines\": [\n \"id\": \"odl_dgtxyl\",\n \"quantity\": 1,\n ],\n \"description\": \"Required quantity not in stock, refunding one photo book.\",\n})\n\n# Alternative shorthand for refunding all eligible order lines\nrefund = order.refunds.create()", "install": "pip install mollie-api-python" }, { "language": "ruby", "code": "require 'mollie-api-ruby'\n\nMollie::Client.configure do |config|\n config.api_key = 'live_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM'\nend\n\norder = Mollie::Order.get('ord_stTC2WHAuS')\nrefund = order.refund!(\n lines: [\n {\n id: 'odl_dgtxyl',\n quantity: 1\n }\n ],\n description: 'Required quantity not in stock, refunding one photo book.'\n)\n\n# Alternative shorthand for refunding all eligible order lines\norder.refund!", "install": "gem install mollie-api-ruby" } ] }, "x-examples": [ { "name": "Refund order", "code": 201, "x-request": "mol-public-api/v2/refunds-api/requests.yaml#/api-refund-order", "response": "mol-public-api/v2/refunds-api/examples.yaml#/components/responses/api-refund-order" }, { "name": "Refund order", "code": 201, "x-request": "mol-public-api/v2/refunds-api/requests.yaml#/oauth-refund-order", "response": "mol-public-api/v2/refunds-api/examples.yaml#/components/responses/oauth-refund-order" } ] } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "x-default": "live_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM" }, "organizationAccessToken": { "type": "http", "scheme": "bearer", "x-default": "access_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM" }, "oAuth": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://my.mollie.com/oauth2/authorize", "tokenUrl": "https://api.mollie.com/oauth2/tokens", "scopes": {} } } } } }, "x-readme": { "explorer-enabled": false, "samples-languages": [ "shell", "php", "node", "python", "ruby" ] } } ```