--- title: "Order refund trial" doc_type: openapi doc_category: openapi doc_version: v20270301 source_url: html: 'https://developer.shopline.com/docs/admin-rest-api/order/order-management/order-refund-trial' md: 'https://developer.shopline.com/docs/admin-rest-api/order/order-management/order-refund-trial.md' --- # Order refund trial - **Base URL:** `https://{handle}.myshopline.com/admin/openapi` - **Required Scopes:** `write_orders` - **API Version:** v20270301 - **API Type:** Admin - **API Protocol:** RESTful ## Endpoint ```http POST /orders/:order_id/refunds/calculate.json ``` ## Base URL * `https://{handle}.myshopline.com/admin/openapi` * `{handle}`: `handle` : The store's unique identifier, which is the prefix of the store's domain name. For example, if a store's domain name is `open001.myshopline.com` , the store handle is `open001` . ## Required Permissions * `write_orders` ## Request ### Path Parameters * `order_id` string (required) Order id ### Request Headers * `Content-Type` string (required) The field must be set to the fixed value `application/json; charset=utf-8`. * `Authorization` string (required) The access token for the API resource. Refer to [App authorization](https://developer.shopline.com/docs/apps/api-instructions-for-use/app-authorization.md?lang=en) to obtain the access token, and then pass the obtained token in the Bearer format. ### Request Body * `shipping` object Shipping rates * `amount` string Shipping amount to be returned , double type string , accuracy 2 * `full_refund` boolean Return shipping fee or not * `currency` string Settlement currency of the order, which is optional. If the input currency is null, the application will verify whether the order settlement currency is the store currency, If it is not the store currency, an error will be reported, prompting like: "currency must be X”; If the input currency is passed, check whether the currency is the settlement currency of the order. If not, an error will be reported and the prompt will be: "currency must be X" * `refund_line_items` array Trial Product * `line_item_id` string Trial refund Product row id * `quantity` long Trial refund Product quantity * `type` string The Product to calculate belongs to , Unshipped : Product not shipped , Returned : the product has been returned ## Response ### Status Codes * `200` For the complete list of codes and messages, see [Http status code](https://developer.shopline.com/docs/apps/api-instructions-for-use/http-status-code.md?lang=en). * `401` * `429` ### Response Headers * `traceId` A globally unique identifier for the request. It is used to track the request flow throughout the system, allowing for easy location and debugging when issues arise. ### Response Body #### 200 * `refund` object Trial results * `total_duties_set` object Refund total duty * `presentment_money` object Buyer side amount information * `currency_code` string Currency * `amount` string Amount * `shop_money` object Sell side amount information * `amount` string Amount * `currency_code` string Currency * `transactons` array When the trial amount is greater than 0 , the original return system automatically returns the payment slip and amount according to the rules * `kind` string suggested_refund * `maximum_refundable` string Current payment slip when the largest amount is returned * `order_id` string Order number * `parent_id` string Payment slip number * `amount` string payment amount, which the corresponding amount in the settlement currency of the payment order * `currency` string the currency, which the settlement currency corresponding of the payment * `gateway` string Payment channels * `currency` string the currency, which the settlement currency corresponding to the refund * `refund_line_items` array When Product should return the amount to the request for trial , return * `line_item_id` string Product line ( Product line in ginseng ) * `price` string Product selling price * `quantity` integer Quantity ( actual can be returned ) * `subtotal` string Product should be refunded * `total_tax` string Product the tax refund amount should be available * `type` string The Product to calculate belongs to , Unshipped : Product not shipped , Shipped : Product has been shipped , Returned : the product has been returned * `discount_total_amount` string Product total discount amount * `shipping` object When shipping charges are required return * `amount` string Order shipping * `maximum_refundable` string Maximum return shipping * `tax` string Order shipping tax #### 401 * `errors` string Error message. #### 429 * `errors` string Error message. ## OpenAPI Definition ```json { "externalDocs": { "description": "Permission point used by the interface is `write_orders` , For more information about the use of permission points, see", "url": "ec20/3cv5d7wpfgr6a8z5/xabczf5442284vkq?lang=en", "errorTableDescription": "" }, "operationId": "WdjOC38Q", "parameters": [ { "name": "order_id", "in": "path", "description": "Order id", "required": true, "style": "simple", "schema": { "name": "order_id", "description": "Order id", "type": "string", "example": "" }, "example": "" }, { "name": "Content-Type", "in": "header", "description": "The field must be set to the fixed value `application/json; charset=utf-8`.", "required": true, "style": "string", "schema": { "name": "Content-Type", "type": "string", "example": "application/json; charset=utf-8" } }, { "name": "Authorization", "in": "header", "description": " The access token for the API resource. Refer to [App authorization](https://developer.shopline.com/docs/apps/api-instructions-for-use/app-authorization.md?lang=en) to obtain the access token, and then pass the obtained token in the Bearer format. ", "required": true, "style": "string", "schema": { "name": "Authorization", "description": " The access token for the API. Please refer to [App authorization](https://developer.shopline.com/docs/apps/api-instructions-for-use/app-authorization.md?lang=en) to obtain the access token, and then put the obtained access token into the API request header in Bearer Token.", "type": "string", "example": "Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6MCwiYXBwS2V5IjoiNzU2ZjI1NWE2NjdlZTcwNTk1MzM0ZjVjYzk4NzU5MzBmN2E3NGZjMSIsImV4cCI6MTg3OTQ4MjA3NiwiaXNzIjoieXNvdWwiLCJzZWxsZXJJZCI6IjIwMDAyMzQ4ODAiLCJzdG9yZUlkIjoiMTY3MjM2OTcyOTYwNiIsInRpbWVzdGFtcCI6MTc4NDc4NzY3NjY2MSwidmVyc2lvbiI6IlYyIn0.3ZzbGAH4cLU1QR2VPEvMOQInUDvus-C4amkINSQIPuNVlXsFKj0sAt1c0KnUy9MWUOFV9cHlkf7J90r2y1FzpA" }, "example": "Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6MCwiYXBwS2V5IjoiNzU2ZjI1NWE2NjdlZTcwNTk1MzM0ZjVjYzk4NzU5MzBmN2E3NGZjMSIsImV4cCI6MTg3OTQ4MjA3NiwiaXNzIjoieXNvdWwiLCJzZWxsZXJJZCI6IjIwMDAyMzQ4ODAiLCJzdG9yZUlkIjoiMTY3MjM2OTcyOTYwNiIsInRpbWVzdGFtcCI6MTc4NDc4NzY3NjY2MSwidmVyc2lvbiI6IlYyIn0.3ZzbGAH4cLU1QR2VPEvMOQInUDvus-C4amkINSQIPuNVlXsFKj0sAt1c0KnUy9MWUOFV9cHlkf7J90r2y1FzpA" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "shipping": { "name": "shipping", "description": "Shipping rates", "type": "object", "properties": { "amount": { "name": "amount", "description": "Shipping amount to be returned , double type string , accuracy 2", "type": "string", "example": "\"10.00\"" }, "full_refund": { "name": "full_refund", "description": "Return shipping fee or not", "type": "boolean", "example": true } }, "example": { "amount": "\"10.00\"", "full_refund": true } }, "currency": { "name": "currency", "description": "Settlement currency of the order, which is optional. If the input currency is null, the application will verify whether the order settlement currency is the store currency, If it is not the store currency, an error will be reported, prompting like: \"currency must be X”;\nIf the input currency is passed, check whether the currency is the settlement currency of the order. If not, an error will be reported and the prompt will be: \"currency must be X\"", "type": "string", "example": "USD" }, "refund_line_items": { "name": "refund_line_items", "description": "Trial Product", "type": "array", "items": { "name": "refund_line_items", "description": "Trial Product", "type": "object", "properties": { "line_item_id": { "name": "line_item_id", "description": "Trial refund Product row id", "type": "string", "example": "\"12343423111\"" }, "quantity": { "name": "quantity", "description": "Trial refund Product quantity", "type": "long", "example": 1 }, "type": { "name": "type", "description": "The Product to calculate belongs to , Unshipped : Product not shipped , Returned : the product has been returned", "type": "string", "example": "" } }, "required": [ "type" ], "example": { "quantity": 1, "type": "", "line_item_id": "\"12343423111\"" } }, "example": [ { "line_item_id": "\"12343423111\"", "quantity": 1, "type": "" } ] } }, "example": { "shipping": { "full_refund": true, "amount": "\"10.00\"" }, "currency": "USD", "refund_line_items": [ { "quantity": 1, "type": "", "line_item_id": "\"12343423111\"" } ] } } } }, "required": true }, "responses": { "200": { "description": "For the complete list of codes and messages, see [Http status code](https://developer.shopline.com/docs/apps/api-instructions-for-use/http-status-code.md?lang=en).", "headers": { "traceId": { "description": "A globally unique identifier for the request. It is used to track the request flow throughout the system, allowing for easy location and debugging when issues arise." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "refund": { "name": "refund", "description": "Trial results", "type": "object", "properties": { "total_duties_set": { "name": "total_duties_set", "description": "Refund total duty", "type": "object", "properties": { "presentment_money": { "name": "presentment_money", "description": "Buyer side amount information", "type": "object", "properties": { "currency_code": { "name": "currency_code", "description": "Currency", "type": "string", "example": "\"USD\"" }, "amount": { "name": "amount", "description": "Amount", "type": "string", "example": "8.88" } }, "example": { "amount": "8.88", "currency_code": "\"USD\"" } }, "shop_money": { "name": "shop_money", "description": "Sell side amount information", "type": "object", "properties": { "amount": { "name": "amount", "description": "Amount", "type": "string", "example": "8.88" }, "currency_code": { "name": "currency_code", "description": "Currency", "type": "string", "example": "USD" } }, "example": { "currency_code": "USD", "amount": "8.88" } } }, "example": { "presentment_money": { "amount": "8.88", "currency_code": "\"USD\"" }, "shop_money": { "amount": "8.88", "currency_code": "USD" } } }, "transactons": { "name": "transactons", "description": "When the trial amount is greater than 0 , the original return system automatically returns the payment slip and amount according to the rules", "type": "array", "items": { "name": "transactons", "description": "When the trial amount is greater than 0 , the original return system automatically returns the payment slip and amount according to the rules", "type": "object", "properties": { "kind": { "name": "kind", "description": "suggested_refund", "type": "string", "example": "suggested_refund" }, "maximum_refundable": { "name": "maximum_refundable", "description": "Current payment slip when the largest amount is returned", "type": "string", "example": "\"41.89\"" }, "order_id": { "name": "order_id", "description": "Order number", "type": "string", "example": "\"21056836827909126061559008\"" }, "parent_id": { "name": "parent_id", "description": "Payment slip number", "type": "string", "example": "\"26056836827909126061559008\"" }, "amount": { "name": "amount", "description": "payment amount, which the corresponding amount in the settlement currency of the payment order", "type": "string", "example": "\"41.89\"" }, "currency": { "name": "currency", "description": "the currency, which the settlement currency corresponding of the payment", "type": "string", "example": "USD" }, "gateway": { "name": "gateway", "description": "Payment channels", "type": "string", "example": "bogus" } }, "example": { "amount": "\"41.89\"", "currency": "USD", "gateway": "bogus", "kind": "suggested_refund", "maximum_refundable": "\"41.89\"", "order_id": "\"21056836827909126061559008\"", "parent_id": "\"26056836827909126061559008\"" } }, "example": [ { "parent_id": "\"26056836827909126061559008\"", "amount": "\"41.89\"", "currency": "USD", "gateway": "bogus", "kind": "suggested_refund", "maximum_refundable": "\"41.89\"", "order_id": "\"21056836827909126061559008\"" } ] }, "currency": { "name": "currency", "description": "\nthe currency, which the settlement currency corresponding to the refund", "type": "string", "example": "USD" }, "refund_line_items": { "name": "refund_line_items", "description": "When Product should return the amount to the request for trial , return", "type": "array", "items": { "name": "refund_line_items", "description": "When Product should return the amount to the request for trial , return", "type": "object", "properties": { "line_item_id": { "name": "line_item_id", "description": "Product line ( Product line in ginseng )", "type": "string", "example": "\"33121216544\"" }, "price": { "name": "price", "description": "Product selling price", "type": "string", "example": "\"199.00\"" }, "quantity": { "name": "quantity", "description": "Quantity ( actual can be returned )", "type": "integer", "example": 1 }, "subtotal": { "name": "subtotal", "description": "Product should be refunded", "type": "string", "example": "\"195.67\"" }, "total_tax": { "name": "total_tax", "description": "Product the tax refund amount should be available", "type": "string", "example": "\"195.67\"" }, "type": { "name": "type", "description": "The Product to calculate belongs to , Unshipped : Product not shipped , Shipped : Product has been shipped , Returned : the product has been returned", "type": "string", "example": "" }, "discount_total_amount": { "name": "discount_total_amount", "description": "Product total discount amount", "type": "string", "example": "\"199.00\"" } }, "example": { "subtotal": "\"195.67\"", "total_tax": "\"195.67\"", "type": "", "discount_total_amount": "\"199.00\"", "line_item_id": "\"33121216544\"", "price": "\"199.00\"", "quantity": 1 } }, "example": [ { "line_item_id": "\"33121216544\"", "price": "\"199.00\"", "quantity": 1, "subtotal": "\"195.67\"", "total_tax": "\"195.67\"", "type": "", "discount_total_amount": "\"199.00\"" } ] }, "shipping": { "name": "shipping", "description": "When shipping charges are required return", "type": "object", "properties": { "amount": { "name": "amount", "description": "Order shipping", "type": "string", "example": "\"5.00\"" }, "maximum_refundable": { "name": "maximum_refundable", "description": "Maximum return shipping", "type": "string", "example": "\"10.00\"" }, "tax": { "name": "tax", "description": "Order shipping tax", "type": "string", "example": "\"1.00\"" } }, "example": { "amount": "\"5.00\"", "maximum_refundable": "\"10.00\"", "tax": "\"1.00\"" } } }, "example": { "shipping": { "amount": "\"5.00\"", "maximum_refundable": "\"10.00\"", "tax": "\"1.00\"" }, "total_duties_set": { "presentment_money": { "currency_code": "\"USD\"", "amount": "8.88" }, "shop_money": { "amount": "8.88", "currency_code": "USD" } }, "transactons": [ { "gateway": "bogus", "kind": "suggested_refund", "maximum_refundable": "\"41.89\"", "order_id": "\"21056836827909126061559008\"", "parent_id": "\"26056836827909126061559008\"", "amount": "\"41.89\"", "currency": "USD" } ], "currency": "USD", "refund_line_items": [ { "type": "", "discount_total_amount": "\"199.00\"", "line_item_id": "\"33121216544\"", "price": "\"199.00\"", "quantity": 1, "subtotal": "\"195.67\"", "total_tax": "\"195.67\"" } ] } } }, "example": { "refund": { "total_duties_set": { "shop_money": { "amount": "8.88", "currency_code": "USD" }, "presentment_money": { "currency_code": "\"USD\"", "amount": "8.88" } }, "transactons": [ { "maximum_refundable": "\"41.89\"", "order_id": "\"21056836827909126061559008\"", "parent_id": "\"26056836827909126061559008\"", "amount": "\"41.89\"", "currency": "USD", "gateway": "bogus", "kind": "suggested_refund" } ], "currency": "USD", "refund_line_items": [ { "discount_total_amount": "\"199.00\"", "line_item_id": "\"33121216544\"", "price": "\"199.00\"", "quantity": 1, "subtotal": "\"195.67\"", "total_tax": "\"195.67\"", "type": "" } ], "shipping": { "maximum_refundable": "\"10.00\"", "tax": "\"1.00\"", "amount": "\"5.00\"" } } } } } } }, "401": { "headers": { "traceId": { "description": "A globally unique identifier for the request. It is used to track the request flow throughout the system, allowing for easy location and debugging when issues arise." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "Error message. ", "type": "string" } }, "required": [ "errors" ] } } } }, "429": { "headers": { "traceId": { "description": "A globally unique identifier for the request. It is used to track the request flow throughout the system, allowing for easy location and debugging when issues arise." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "Error message. ", "type": "string" } }, "required": [ "errors" ] } } } } }, "security": [ { "oauth2": [] } ], "method": "post", "path": "/orders/:order_id/refunds/calculate.json", "servers": [ { "url": "https://{handle}.myshopline.com/admin/openapi", "variables": { "handle": { "default": "openapiceshidianpu", "description": "`handle` : The store's unique identifier, which is the prefix of the store's domain name. For example, if a store's domain name is `open001.myshopline.com` , the store handle is `open001` ." } } } ], "info": { "title": "Order refund trial", "version": "v20270301" }, "authIndexes": [ "write_orders" ] } ```