Refundid Provided APIs

refundid provides a set of apis that may be optionally invoked by the merchant's e commerce system to query and/or update the current state of refundid "return merchant authorizations" (referred to as rmas throughout the doc) merchants are not required to use these apis, as all of the necessary functionality is readily available to all merchants through the refundid merchant portal however, these apis are particularly useful for merchants who wish to integrate some or all of the returns processing functionality available through the refundid merchant portal directly into their existing returns processing system authentication and security refundid provided apis implement a layered security model similar to the one supported for merchant provided apis this allows merchants to choose from a range of authentication methods to ensure the authenticity of refundid api requests, aligning seamlessly with their unique e commerce platform architectures api key all requests to refundid provided apis must be submitted with a refundid api key, issued to the merchant by refundid this key is used to identify the merchant in the api request, and therefore is required for all requests the api key header has the following form "x refundid api key" the header name x api key is also accepted as an alias for x refundid api key the api key is generated by refundid and will consist of up to 256 arbitrary printable (i e , non whitespace) ascii characters if you require an api key generated for a particular environment please reach out to integrations\@refundid com mailto\ integrations\@refundid com return types and identifiers refundid processes two types of returns, and both are surfaced through these apis instant returns the customer is refunded before the item is returned identified by a numeric refundid id standard returns the item is returned and inspected first, then the resolution (refund, store credit, gift card, exchange, etc ) is processed identified by a numeric standard return id every return also carries an rma ref (the refundid rma reference shown in the merchant portal, e g "rma10425"), the merchant's order number , and optionally a merchant rma ref (a reference generated by the merchant's own returns system, if one was supplied) all monetary values in these apis are represented as an amount object of the form {"amount" 83 0, "currency" "aud"} { "name" "get returns", "method" "get", "url" "https //api refundid com/v1/merchant/returns", "description" "searches the refundid system for existing refundid rmas (both instant returns and standard returns), either active or historic, matching the specified search criteria \n\nthe response contains \\"returns\\" (a list of return objects see the return object reference section below for a field by field breakdown), \\"offset\\" (a copy of the offset request parameter) and \\"more\\" (whether more records are available after the current page) ", "tab" "examples", "examples" { "languages" \[ { "id" "n2bqdkear5gho5kgohfio", "language" "curl", "code" "curl location request get 'https //api refundid com/v1/merchant/returns?date from=2026 06 01\&date to=2026 06 30\&return statuses=approved%2cpending\&resolutions=instant%2cstore credit\&order by=created date\&limit=50' \\\\\n header 'accept application/json' \\\\\n header 'content type application/json' \\\\\n header 'x refundid api key {{merchant api key}}'", "customlabel" "" } ], "selectedlanguageid" "n2bqdkear5gho5kgohfio" }, "results" { "languages" \[ { "id" "wqouc5hrjhg03tku9wc x", "language" "200", "customlabel" "", "code" "{\n \\"returns\\" \[\n {\n \\"standard return id\\" \\"1042\\",\n \\"standard return encrypted id\\" \\"gaaaaabmhp ybgcgr 38v8cbhoswij5aliskh2apouen715xvbubc1chdfsnfnnu0vt bszfcxm0x0s5rl ovjccl7b6g lj9g==\\",\n \\"return resolution\\" \\"store credit\\",\n \\"status\\" \\"closed\\",\n \\"is flagged\\" true,\n \\"requested refund breakdown\\" {\n \\"subtotal\\" { \\"amount\\" 89 95, \\"currency\\" \\"aud\\" },\n \\"store return fee\\" { \\"amount\\" 6 95, \\"currency\\" \\"aud\\" },\n \\"customer shipping cost\\" { \\"amount\\" 0, \\"currency\\" \\"aud\\" },\n \\"total\\" { \\"amount\\" 83 0, \\"currency\\" \\"aud\\" }\n },\n \\"line items\\" \[\n {\n \\"return line item id\\" 884213,\n \\"merchant order ref\\" \\"5712345678901\\",\n \\"line item ref\\" \\"13987654321098\\",\n \\"quantity\\" 1,\n \\"price\\" { \\"amount\\" 89 95, \\"currency\\" \\"aud\\" },\n \\"tax detail\\" { \\"tax\\" { \\"amount\\" 8 18, \\"currency\\" \\"aud\\" }, \\"tax included\\" true },\n \\"return reason\\" \\"too small\\",\n \\"child return reason\\" null,\n \\"return reason notes\\" \[\n { \\"title\\" \\"tell us more\\", \\"value\\" \\"sleeves are too tight\\", \\"type\\" \\"text\\" }\n ],\n \\"sku\\" \\"drs blk 10\\",\n \\"product ref\\" \\"8123456789012\\",\n \\"variant ref\\" \\"44123456789012\\",\n \\"barcode\\" \\"9312345678907\\",\n \\"title\\" \\"linen midi dress\\",\n \\"variant\\" \\"black / 10\\",\n \\"image url\\" \\"https //cdn shopify com/s/files/1/0001/products/dress jpg\\",\n \\"resolution\\" \\"accept\\",\n \\"restock\\" true,\n \\"restock location ref\\" \\"70123456789\\",\n \\"notes\\" null,\n \\"disposition\\" { \\"id\\" 12, \\"name\\" \\"damaged\\" }\n }\n ],\n \\"rma ref\\" \\"rma10425\\",\n \\"order number\\" \\"#10245\\",\n \\"created at\\" \\"2026 06 18t04 21 09z\\",\n \\"estimated order to store currency exchange rate\\" null,\n \\"shipping label\\" {\n \\"tracking\\" {\n \\"carrier\\" \\"australia post\\",\n \\"tracking number\\" \\"33abc1234567\\",\n \\"status\\" \\"delivered\\",\n \\"status date\\" \\"2026 06 21t03 15 00z\\"\n },\n \\"purchase price\\" { \\"amount\\" 9 5, \\"currency\\" \\"aud\\" },\n \\"customer price\\" { \\"amount\\" 0, \\"currency\\" \\"aud\\" },\n \\"label url\\" \\"https //storage googleapis com/refundid labels/33abc1234567 pdf\\"\n },\n \\"close breakdown\\" {\n \\"final refund amount\\" { \\"amount\\" 83 0, \\"currency\\" \\"aud\\" },\n \\"outbound shipping refund amount\\" null,\n \\"closed on\\" \\"2026 06 22t01 12 44z\\",\n \\"closed by\\" \\"merchant\\",\n \\"refunds\\" \[\n { \\"refund method ref\\" \\"gift card\\", \\"amount\\" { \\"amount\\" 83 0, \\"currency\\" \\"aud\\" } }\n ]\n },\n \\"exchange\\" null,\n \\"customer\\" { \\"email\\" \\"jane doe\@example com\\" },\n \\"tags\\" \[\n { \\"id\\" 7, \\"name\\" \\"priority\\" }\n ]\n },\n {\n \\"standard return id\\" \\"1043\\",\n \\"standard return encrypted id\\" \\"gaaaaabmhq1kxcght 99v8cbhoswij5aliskh2apouen715xvbubc1chdfsnfnnu0vt bszfcxm0x0s5rl ovjccl7b6g xy2w==\\",\n \\"return resolution\\" \\"exchange\\",\n \\"status\\" \\"lodged\\",\n \\"is flagged\\" false,\n \\"requested refund breakdown\\" {\n \\"subtotal\\" { \\"amount\\" 89 95, \\"currency\\" \\"aud\\" },\n \\"store return fee\\" { \\"amount\\" 0, \\"currency\\" \\"aud\\" },\n \\"customer shipping cost\\" { \\"amount\\" 0, \\"currency\\" \\"aud\\" },\n \\"total\\" { \\"amount\\" 89 95, \\"currency\\" \\"aud\\" }\n },\n \\"line items\\" \[\n {\n \\"return line item id\\" 884214,\n \\"merchant order ref\\" \\"5712345678902\\",\n \\"line item ref\\" \\"13987654321100\\",\n \\"quantity\\" 1,\n \\"price\\" { \\"amount\\" 89 95, \\"currency\\" \\"aud\\" },\n \\"tax detail\\" { \\"tax\\" { \\"amount\\" 8 18, \\"currency\\" \\"aud\\" }, \\"tax included\\" true },\n \\"return reason\\" \\"wrong size\\",\n \\"child return reason\\" \\"too big\\",\n \\"return reason notes\\" \[],\n \\"sku\\" \\"drs blk 14\\",\n \\"product ref\\" \\"8123456789012\\",\n \\"variant ref\\" \\"44123456789014\\",\n \\"barcode\\" \\"9312345678921\\",\n \\"title\\" \\"linen midi dress\\",\n \\"variant\\" \\"black / 14\\",\n \\"image url\\" \\"https //cdn shopify com/s/files/1/0001/products/dress jpg\\",\n \\"resolution\\" null,\n \\"restock\\" false,\n \\"restock location ref\\" null,\n \\"notes\\" null,\n \\"disposition\\" null\n }\n ],\n \\"rma ref\\" \\"rma10431\\",\n \\"order number\\" \\"#10251\\",\n \\"created at\\" \\"2026 06 27t23 05 41z\\",\n \\"estimated order to store currency exchange rate\\" null,\n \\"shipping label\\" {\n \\"tracking\\" {\n \\"carrier\\" \\"australia post\\",\n \\"tracking number\\" \\"33abc7654321\\",\n \\"status\\" \\"transit\\",\n \\"status date\\" \\"2026 06 28t22 40 00z\\"\n },\n \\"purchase price\\" { \\"amount\\" 9 5, \\"currency\\" \\"aud\\" },\n \\"customer price\\" { \\"amount\\" 0, \\"currency\\" \\"aud\\" },\n \\"label url\\" \\"https //storage googleapis com/refundid labels/33abc7654321 pdf\\"\n },\n \\"close breakdown\\" null,\n \\"exchange\\" {\n \\"purchase request id\\" 5123,\n \\"status\\" \\"purchased\\",\n \\"expected shipping price\\" { \\"amount\\" 0, \\"currency\\" \\"aud\\" },\n \\"purchase request total value\\" { \\"amount\\" 89 95, \\"currency\\" \\"aud\\" },\n \\"customer invoice amount\\" { \\"amount\\" 0, \\"currency\\" \\"aud\\" },\n \\"fname\\" \\"jane\\",\n \\"lname\\" \\"doe\\",\n \\"email\\" \\"jane doe\@example com\\",\n \\"phone\\" \\"+61400123456\\",\n \\"shipping address\\" {\n \\"address1\\" \\"123 example st\\",\n \\"address2\\" null,\n \\"city\\" \\"sydney\\",\n \\"zip\\" \\"2000\\",\n \\"province\\" \\"nsw\\",\n \\"country\\" \\"australia\\",\n \\"country code\\" \\"au\\"\n },\n \\"line items\\" \[\n {\n \\"item ref\\" \\"44123456789013\\",\n \\"quantity\\" 1,\n \\"expected price\\" { \\"amount\\" 89 95, \\"currency\\" \\"aud\\" },\n \\"title\\" \\"linen midi dress\\",\n \\"variant\\" \\"black / 12\\",\n \\"image url\\" \\"https //cdn shopify com/s/files/1/0001/products/dress jpg\\",\n \\"sku\\" \\"drs blk 12\\",\n \\"product ref\\" \\"8123456789012\\",\n \\"variant ref\\" \\"44123456789013\\",\n \\"returned line item ref\\" \\"13987654321100\\"\n }\n ],\n \\"draft order ref\\" \\"1181116678321\\",\n \\"shipping rate ref\\" \\"shopify free%20shipping 0 00\\",\n \\"shipping rate title\\" \\"free shipping\\",\n \\"order name\\" \\"#10251e\\",\n \\"order ref\\" \\"5712345679999\\"\n },\n \\"customer\\" { \\"email\\" \\"jane doe\@example com\\" },\n \\"tags\\" \[]\n },\n {\n \\"refundid id\\" \\"20871\\",\n \\"rma ref\\" \\"rma20871\\",\n \\"order number\\" \\"#10198\\",\n \\"created at\\" \\"2026 06 20t09 33 50z\\",\n \\"merchant rma ref\\" null,\n \\"status\\" \\"closed\\",\n \\"is flagged\\" false,\n \\"line items\\" \[\n {\n \\"return line item id\\" 884215,\n \\"merchant order ref\\" \\"5712345678800\\",\n \\"line item ref\\" \\"13987654320001\\",\n \\"quantity\\" 1,\n \\"price\\" { \\"amount\\" 45 0, \\"currency\\" \\"aud\\" },\n \\"tax detail\\" { \\"tax\\" { \\"amount\\" 4 09, \\"currency\\" \\"aud\\" }, \\"tax included\\" true },\n \\"return reason\\" \\"changed my mind\\",\n \\"child return reason\\" null,\n \\"return reason notes\\" \[\n { \\"title\\" \\"photo of the item\\", \\"value\\" \\"https //storage googleapis com/refundid notes/20871 1 jpg\\", \\"type\\" \\"image\\" }\n ],\n \\"sku\\" \\"tee wht m\\",\n \\"product ref\\" \\"8123456789100\\",\n \\"variant ref\\" \\"44123456789200\\",\n \\"barcode\\" \\"9312345671234\\",\n \\"title\\" \\"organic cotton tee\\",\n \\"variant\\" \\"white / m\\",\n \\"image url\\" \\"https //cdn shopify com/s/files/1/0001/products/tee jpg\\",\n \\"resolution\\" \\"accept\\",\n \\"restock\\" true,\n \\"restock location ref\\" \\"70123456789\\",\n \\"notes\\" \\"returned in original packaging\\",\n \\"disposition\\" { \\"id\\" 4, \\"name\\" \\"restock\\" }\n }\n ],\n \\"refund breakdown\\" {\n \\"subtotal\\" { \\"amount\\" 45 0, \\"currency\\" \\"aud\\" },\n \\"store return fee\\" { \\"amount\\" 0, \\"currency\\" \\"aud\\" },\n \\"customer shipping cost\\" { \\"amount\\" 0, \\"currency\\" \\"aud\\" },\n \\"total\\" { \\"amount\\" 45 0, \\"currency\\" \\"aud\\" }\n },\n \\"shipping label\\" {\n \\"tracking\\" {\n \\"carrier\\" \\"australia post\\",\n \\"tracking number\\" \\"33abc9998887\\",\n \\"status\\" \\"delivered\\",\n \\"status date\\" \\"2026 06 23t05 02 00z\\"\n },\n \\"purchase price\\" null,\n \\"customer price\\" null,\n \\"label url\\" null\n },\n \\"reconciliation breakdown\\" {\n \\"discounted amount to reconcile from merchant\\" 45 0,\n \\"amount to reconcile from merchant\\" 45 0,\n \\"shipping to reconcile from merchant\\" 0,\n \\"merchant advance adjustment\\" 0,\n \\"refundid cut\\" 1 35,\n \\"discounted refundid cut\\" 1 35,\n \\"invoice created at\\" \\"2026 06 30t00 00 00z\\",\n \\"closed by\\" \\"merchant\\",\n \\"closed on\\" \\"2026 06 24t05 40 12z\\"\n },\n \\"customer\\" { \\"email\\" \\"sam smith\@example com\\" },\n \\"tags\\" \[\n { \\"id\\" 3, \\"name\\" \\"vip\\" }\n ]\n }\n ],\n \\"offset\\" 0,\n \\"more\\" false\n}" } ], "selectedlanguageid" "wqouc5hrjhg03tku9wc x" }, "request" { "pathparameters" \[], "queryparameters" \[ { "name" "return statuses", "kind" "optional", "type" "string", "description" "comma separated list containing any of the following \napproved, rejected, cancelled, pending, invoiced, double refunded, multi outcome, in review\n\nif left empty, all statuses are included ", "children" \[] }, { "name" "tracking statuses", "kind" "optional", "type" "string", "description" "comma separated list containing any of the following tracking statuses \nnot shipped yet, transit, delivered, maybe delivered, failure, lost in transit, unknown\n\nif left empty, all tracking statuses are included ", "children" \[] }, { "name" "resolutions", "kind" "optional", "type" "string", "description" "comma separated list of values each value is either \n instant (instant refunds)\n instant exchange (instant exchanges)\n the internal name of one of your standard resolutions (e g store credit) the available internal names for your store are returned by the return resolutions api ", "children" \[] }, { "name" "flagged", "kind" "optional", "type" "boolean", "description" "when true, restricts the results to returns that have been flagged (via the merchant portal or the flag return api) defaults to false, which includes both flagged and unflagged returns ", "children" \[] }, { "name" "date from", "kind" "optional", "type" "string", "description" "restricts the results to refundid rmas created on or after this date format yyyy mm dd if provided, date to must also be provided ", "children" \[] }, { "name" "date to", "kind" "optional", "type" "string", "description" "restricts the results to refundid rmas created on or before this date format yyyy mm dd if provided, date from must also be provided ", "children" \[] }, { "name" "limit", "kind" "optional", "type" "integer", "description" "restricts the result to at most limit records defaults to 50 if omitted; the maximum allowed value is 200 if more records match the specified search criteria, the result will include a \\"more=true\\" flag and the remaining records may be retrieved by specifying a suitable offset value ", "children" \[] }, { "name" "offset", "kind" "optional", "type" "number", "description" "begins the search after the first offset records matching the requested search criteria if specified, must be a non negative integer ", "children" \[] }, { "name" "query", "kind" "optional", "type" "string", "description" "used to search through the following fields \nexact match on \n customer first name\n customer last name\n customer mobile\n customer email\n customer full name\n rma id\n refundid order id\n tracking number\n\ncontains search on \n order number", "children" \[] }, { "name" "order by", "kind" "optional", "type" "string", "description" "can be one of the following \nrma id, email, created date, closed date, item number, amount, lost in transit date, delivered date, refund status, tracking status, resolution\n\ndefaults to created date ", "children" \[] }, { "name" "is desc", "kind" "optional", "type" "boolean", "description" "whether the ordering should be done in descending order (defaults to true if omitted) ", "children" \[] } ], "headerparameters" \[], "formdataparameters" \[], "bodydataparameters" \[] }, "currentnewparameter" { "label" "query parameter", "value" "queryparameters" }, "hastryitout" true, "autogeneratedanchorslug" "get returns", "legacyhash" "fmbvathmvqvw9q6dhetgv" } return object reference each entry in the returns list returned by get returns is either a standard return or an instant return you can tell them apart by their identifier standard returns carry a standard return id , while instant returns carry a refundid id standard return fields standard return id numeric id of the standard return, returned as a string (e g "1042" ) use this value as the standard return id when calling the post tracking, close returns, add return note and flag return apis standard return encrypted id an encrypted, hard to guess version of the same id, suitable for embedding in customer facing urls return resolution the internal name of the resolution the customer selected (e g store credit , gift card , or any resolution configured for your store) status one of lodging , lodged , closing , closed , failed is flagged whether the return is currently flagged in the merchant portal requested refund breakdown the refund amount requested by the customer subtotal (value of the returned items), store return fee (any return fee charged to the customer), customer shipping cost (return shipping charged to the customer) and total (the net amount owed to the customer) each field is an amount object line items the items in the return (see line item fields below) rma ref the refundid rma reference shown in the merchant portal (e g rma10425 ) order number the order number of the original order (e g #10245 ) created at when the return was submitted by the customer, as an iso 8601 utc datetime (e g 2026 06 18t04 21 09z ) estimated order to store currency exchange rate when the order was placed in a different currency than the store's base currency, an object of {from currency, to currency, exchange rate} describing the estimated conversion rate used null otherwise shipping label the return shipping label attached to the rma, if any (see shipping label fields below) close breakdown present once the return has been closed final refund amount the amount actually refunded, as an amount object outbound shipping refund amount the portion of final refund amount that reimbursed the original order's outbound shipping null for returns closed before this was tracked, or where the platform cannot source the original shipping amount closed on when the return was closed closed by merchant or refundid refunds a list of {refund method ref, amount} describing how the refund was paid out (e g gift card vs original payment method) exchange present when the customer requested an exchange / shop now purchase as part of the return (see exchange fields below) null otherwise customer an object containing the customer's email tags the merchant defined tags applied to the return in the merchant portal each entry has an id and a name empty when the return has no tags instant return fields refundid id numeric id of the instant return, returned as a string (e g "20871" ) use this value as the refundid id when calling the post tracking, close returns, add return note and flag return apis rma ref , order number , created at , merchant rma ref , line items , shipping label , customer , tags same meaning as for standard returns status one of refunding , refundid (the customer has been paid), closed , failed is flagged whether the return is currently flagged in the merchant portal refund breakdown same structure as requested refund breakdown above the amount instantly refunded to the customer reconciliation breakdown present once the instant return has been closed describes who pays for the refunded items amount to reconcile from merchant / discounted amount to reconcile from merchant item value owed by the merchant, without and with discounts applied shipping to reconcile from merchant shipping owed by the merchant merchant advance adjustment any adjustment to the merchant funded advance refundid cut / discounted refundid cut refundid's fee, without and with discounts invoice created at when the reconciliation was invoiced ( null if not yet invoiced) closed by merchant or refundid closed on when the return was closed line item fields return line item id refundid's own numeric id for the returned line this is the identifier to use when a refundid api asks you to nominate a specific returned line, such as the return line item id in the set item disposition api note that on a closed return a single returned line is reported as one entry per outcome, so several entries can share the same return line item id (for example when part of the quantity was approved and part rejected, or when some units were restocked and others were not) merchant order ref the e commerce platform's id of the original order line item ref the e commerce platform's id of the order line item being returned quantity the quantity being returned on this line price the unit price of the item, as an amount object tax detail {tax, tax included} the tax amount on the item, and whether it is already included in the price return reason the return reason the customer selected (e g "too small") child return reason the secondary/child reason, if your reason tree has one null otherwise return reason notes extra information the customer supplied for the reason each entry has a title (the question asked), value (the customer's answer, or an image url) and type ( text , image or choice ) sku , barcode the sku and barcode of the returned variant, when available product ref , variant ref the e commerce platform's product and variant ids title , variant , image url display details of the returned item resolution once the return has been closed, the per item resolution code applied (see the close returns api for the list of codes) null while the return is open restock whether the item was flagged for restocking when it was closed restock location ref the e commerce platform's location id the item was restocked into null when no specific location was recorded, in which case the platform default (e g the shopify fulfilling location) applied notes any merchant note recorded against the item when it was closed disposition the disposition assigned to the item when it was closed (e g "restock", "damaged"), as {id, name} null while the return is open or when no disposition was assigned where units of the same line item were given different dispositions, the line is split into one entry per disposition shipping label fields tracking {carrier, tracking number, status, status date} status is one of not shipped yet , transit , delivered , maybe delivered , failure , lost in transit , unknown (plus delivered to i w and returned via seko hub for cross border shipments routed through a consolidation hub) purchase price what the label cost to purchase, as an amount object null for merchant provided tracking customer price what the customer was charged for the label, as an amount object label url a url to download the label pdf, when the label was generated through refundid exchange fields purchase request id numeric id of the exchange purchase request status one of ready , purchasing , purchased , voided expected shipping price , purchase request total value , customer invoice amount amount objects describing the expected outbound shipping cost, the total value of the requested items, and any amount the customer paid extra for the exchange fname , lname , email , phone , shipping address the customer's delivery details for the exchange order line items the items being sent to the customer each has item ref , quantity , expected price , title , variant , image url , sku , product ref , variant ref , and returned line item ref (linking a variant exchange back to the returned line item, when applicable) draft order ref , shipping rate ref , shipping rate title references to the draft order and shipping rate on your e commerce platform order name , order ref the exchange order's name and platform id only populated once status is purchased { "name" "return eligibility", "method" "get", "url" "https //api refundid com/v1/return/eligibility", "description" "checks whether an order and each item on it is currently eligible to be returned through refundid this is useful for merchants who want to show return eligibility inside their own storefront or customer service tooling before sending the customer into the returns flow \n\nsee the eligibility response section below for a breakdown of the response fields and reason codes ", "tab" "examples", "examples" { "languages" \[ { "id" "elg1bmneligibility01", "language" "curl", "code" "curl location request get 'https //api refundid com/v1/return/eligibility?order number=%2310245\&email=jane doe%40example com' \\\\\n header 'accept application/json' \\\\\n header 'x refundid api key {{merchant api key}}'", "customlabel" "" } ], "selectedlanguageid" "elg1bmneligibility01" }, "results" { "languages" \[ { "id" "elg1bmneligibility02", "language" "200", "customlabel" "", "code" "{\n \\"orders\\" \[\n {\n \\"order number\\" \\"#10245\\",\n \\"return window days left\\" 12,\n \\"eligibility\\" {\n \\"eligible\\" true,\n \\"reasons\\" \[]\n },\n \\"line items\\" \[\n {\n \\"line item id\\" \\"13987654321098\\",\n \\"title\\" \\"linen midi dress black / 10\\",\n \\"quantity\\" 1,\n \\"eligibility\\" {\n \\"eligible\\" true,\n \\"reasons\\" \[]\n }\n },\n {\n \\"line item id\\" \\"13987654321099\\",\n \\"title\\" \\"gift card\\",\n \\"quantity\\" 1,\n \\"eligibility\\" {\n \\"eligible\\" false,\n \\"reasons\\" \[\n {\n \\"code\\" \\"non returnable rule\\",\n \\"message\\" \\"gift cards cannot be returned\\"\n }\n ]\n }\n }\n ]\n }\n ]\n}" }, { "id" "elg1bmneligibility03", "language" "400", "customlabel" "", "code" "{ \\"error\\" \\"merchant not found\\" }" } ], "selectedlanguageid" "elg1bmneligibility02" }, "request" { "pathparameters" \[], "queryparameters" \[ { "name" "order number", "kind" "required", "type" "string", "description" "the order number of the order to check (e g #10245) remember to url encode the # character as %23 ", "children" \[] }, { "name" "email", "kind" "required", "type" "string", "description" "the email address of the customer who placed the order ", "children" \[] }, { "name" "shop", "kind" "optional", "type" "string", "description" "the store's shop reference (e g your myshopify com domain) only used to identify the store when the request is not authenticated with an api key; ignored when an api key is supplied ", "children" \[] } ], "headerparameters" \[], "formdataparameters" \[], "bodydataparameters" \[] }, "currentnewparameter" { "label" "query parameter", "value" "queryparameters" }, "hastryitout" true, "autogeneratedanchorslug" "return eligibility", "legacyhash" "0rwj5puttmp5zilgp s3d" } eligibility response the response contains orders a list of matching orders (more than one order can be returned when the order number matches multiple orders for the customer) each order contains order number the order number of the matched order return window days left the number of days remaining in the order's return window (0 if expired) eligibility {eligible, reasons} eligible is true when at least one item on the order can be returned reasons lists why the order is ineligible, each with a machine readable code and a human readable message line items per item eligibility each entry contains line item id (the e commerce platform's line item id), title , quantity (the quantity still returnable through refundid, accounting for fulfilment status and previous returns) and its own eligibility object eligibility reason codes order expired the order's return window has expired ecommerce not returnable the item is not returnable on the e commerce platform (e g shopify has marked it non returnable) non returnable rule the item matched one of the store's configured non returnable rules (e g final sale items, gift cards) the message contains the rule's description { "name" "return resolutions", "method" "post", "url" "https //api refundid com/v1/return/resolutions", "description" "returns the resolutions (outcomes) that would be offered to a customer for a specific set of items on an order e g instant refund, instant exchange, store credit or a standard refund use this together with the return eligibility api to build a fully informed returns experience in your own systems \n\nsee the resolutions response section below for a breakdown of the response fields ", "tab" "examples", "examples" { "languages" \[ { "id" "reslnresolutions01", "language" "curl", "code" "curl location request post 'https //api refundid com/v1/return/resolutions' \\\\\n header 'accept application/json' \\\\\n header 'content type application/json' \\\\\n header 'x refundid api key {{merchant api key}}' \\\\\n data '{\n \\"order number\\" \\"#10245\\",\n \\"email\\" \\"jane doe\@example com\\",\n \\"return items\\" \[\n {\n \\"line item id\\" \\"13987654321098\\",\n \\"quantity\\" 1,\n \\"reason\\" \\"too small\\"\n }\n ]\n}'", "customlabel" "" } ], "selectedlanguageid" "reslnresolutions01" }, "results" { "languages" \[ { "id" "reslnresolutions02", "language" "200", "customlabel" "", "code" "{\n \\"order number\\" \\"#10245\\",\n \\"resolutions\\" \[\n {\n \\"type\\" \\"instant\\",\n \\"name\\" \\"instant refund\\",\n \\"internal name\\" \\"instant refund\\"\n },\n {\n \\"type\\" \\"instant\\",\n \\"name\\" \\"instant exchange\\",\n \\"internal name\\" \\"instant exchange\\"\n },\n {\n \\"type\\" \\"standard\\",\n \\"name\\" \\"store credit\\",\n \\"internal name\\" \\"store credit\\"\n },\n {\n \\"type\\" \\"standard\\",\n \\"name\\" \\"refund to original payment\\",\n \\"internal name\\" \\"standard refund\\"\n }\n ]\n}" }, { "id" "reslnresolutions03", "language" "400", "customlabel" "", "code" "{ \\"message\\" \\"unknown line item id values 999999\\" }" } ], "selectedlanguageid" "reslnresolutions02" }, "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[], "formdataparameters" \[], "bodydataparameters" \[ { "name" "order number", "kind" "required", "type" "string", "description" "the order number of the order the items belong to (e g #10245) ", "children" \[] }, { "name" "email", "kind" "required", "type" "string", "description" "the email address of the customer who placed the order ", "children" \[] }, { "name" "return items", "kind" "required", "type" "object", "description" "a json array of the items the customer wants to return must contain at least one item, and each line item id may appear at most once ", "children" \[ { "name" "line item id", "kind" "required", "type" "string", "description" "the e commerce platform's line item id (as returned by the return eligibility api) " }, { "name" "quantity", "kind" "required", "type" "integer", "description" "the quantity of this line item being returned must be a positive integer " }, { "name" "reason", "kind" "optional", "type" "string", "description" "the return reason selected by the customer " }, { "name" "child reason", "kind" "optional", "type" "string", "description" "the secondary/child return reason, if your reason tree has one " } ], "schema" \[ { "name" "line item id", "kind" "required", "type" "string", "description" "the e commerce platform's line item id (as returned by the return eligibility api) " }, { "name" "quantity", "kind" "required", "type" "integer", "description" "the quantity of this line item being returned must be a positive integer " }, { "name" "reason", "kind" "optional", "type" "string", "description" "the return reason selected by the customer " }, { "name" "child reason", "kind" "optional", "type" "string", "description" "the secondary/child return reason, if your reason tree has one " } ] }, { "name" "shop", "kind" "optional", "type" "string", "description" "the store's shop reference (e g your myshopify com domain) only used to identify the store when the request is not authenticated with an api key; ignored when an api key is supplied ", "children" \[] } ] }, "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" }, "hastryitout" true, "autogeneratedanchorslug" "return resolutions", "legacyhash" "ao6zjoq gvqjscmqhe4n1" } resolutions response order number the order number of the matched order resolutions the list of resolutions available for the requested items empty when the requested items are not returnable (e g return window expired, quantity unavailable, or a non returnable rule matched) each resolution contains type either instant (refundid instant resolutions, where the customer is paid before the item is returned) or standard (the item is inspected before the outcome is processed) name the display name of the resolution as configured for your store (e g "store credit") internal name the stable identifier of the resolution for instant resolutions this is one of instant refund , instant exchange or refundid wallet for standard resolutions it is the internal name configured for your store (e g store credit ) the get returns api accepts standard resolution internal name values, instant for instant refunds, and instant exchange for instant exchanges it does not accept instant refund or refundid wallet as filter values error responses (400) include duplicate line item id values, unknown line item id values, non positive quantities, and requests where the order number/email match more than one order and the items cannot disambiguate them ("unable to match return items to a single order") { "name" "post tracking", "method" "post", "url" "https //api refundid com/v1/merchant/tracking", "description" "this api may be used by the merchant to provide refundid with merchant purchased shipping labels to be used by the customer to return the goods to the merchant it should be used only by merchants who purchase the shipping labels themselves without refundid's involvement \n\nrefundid always requires a shipping label to be attached to every return before it can be approved by the merchant, and usually requires customers to enter a valid tracking number for an rma on the refundid dashboard within three days of receiving a refund if the merchant generates the shipping label themselves, they can streamline the process for their customer by providing refundid with these labels directly as soon as they have been generated and communicated to the customer providing the same carrier and tracking number that is already attached to an rma is a no op \n\nthe request body is a json array each entry identifies one rma (by exactly one of refundid id or standard return id) and the tracking to attach to it a 400 response is returned when duplicate ids appear in the request, or when any of the referenced returns cannot be found for your store in which case no updates are applied \n\nsee the tracking response section below for a breakdown of the 201 response ", "tab" "examples", "examples" { "languages" \[ { "id" "yp1w5wysbkkyiw7ywedsh", "language" "curl", "code" "curl location 'https //api refundid com/v1/merchant/tracking' \\\\\n header 'content type application/json' \\\\\n header 'x refundid api key {{merchant api key}}' \\\\\n data '\[\n {\n \\"refundid id\\" 20871,\n \\"tracking\\" { \\"carrier\\" \\"australia post\\", \\"tracking number\\" \\"33abc9998887\\" }\n },\n {\n \\"standard return id\\" 1042,\n \\"tracking\\" { \\"carrier\\" \\"aramex\\", \\"tracking number\\" \\"ar123456789\\" }\n }\n]'", "customlabel" "" } ], "selectedlanguageid" "yp1w5wysbkkyiw7ywedsh" }, "results" { "languages" \[ { "id" "3ovdpgsqsnxnph9xf8qul", "language" "201", "customlabel" "", "code" "\[\n {\n \\"tracking\\" {\n \\"tracking info id\\" 88231,\n \\"created on\\" \\"2026 06 20t04 22 10z\\",\n \\"carrier\\" \\"australia post\\",\n \\"tracking number\\" \\"33abc9998887\\",\n \\"tracking status\\" null,\n \\"tracking status date\\" null,\n \\"formatted tracking status\\" null,\n \\"reused\\" false,\n \\"lost in transit\\" false,\n \\"rmas using tracking\\" \[],\n \\"carrier aggregator\\" null\n },\n \\"shipping label\\" null,\n \\"return myself shipping option heading text override\\" null,\n \\"return myself shipping option body text override\\" null\n },\n {\n \\"tracking\\" {\n \\"tracking info id\\" 88232,\n \\"created on\\" \\"2026 06 20t04 22 10z\\",\n \\"carrier\\" \\"aramex\\",\n \\"tracking number\\" \\"ar123456789\\",\n \\"tracking status\\" null,\n \\"tracking status date\\" null,\n \\"formatted tracking status\\" null,\n \\"reused\\" false,\n \\"lost in transit\\" false,\n \\"rmas using tracking\\" \[],\n \\"carrier aggregator\\" null\n },\n \\"shipping label\\" null,\n \\"return myself shipping option heading text override\\" null,\n \\"return myself shipping option body text override\\" null\n }\n]" }, { "id" "qohcefbzd3j1uy5mkwu4m", "language" "400", "customlabel" "", "code" "{ \\"error\\" \\"instant refunds not found for ids \[20999] \\" }" } ], "selectedlanguageid" "3ovdpgsqsnxnph9xf8qul" }, "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[], "formdataparameters" \[], "bodydataparameters" \[ { "name" "refundid id", "kind" "optional", "type" "integer", "description" "field of each array entry the numeric id of the instant return to attach tracking to exactly one of refundid id or standard return id must be provided per entry ", "children" \[] }, { "name" "standard return id", "kind" "optional", "type" "integer", "description" "field of each array entry the numeric id of the standard return to attach tracking to exactly one of refundid id or standard return id must be provided per entry ", "children" \[] }, { "name" "tracking", "kind" "required", "type" "object", "description" "field of each array entry the tracking to attach to the rma ", "children" \[ { "name" "carrier", "kind" "required", "type" "string", "description" "the carrier the shipment was booked with (e g australia post) " }, { "name" "tracking number", "kind" "required", "type" "string", "description" "the tracking number of the shipment " } ], "schema" \[ { "name" "carrier", "kind" "required", "type" "string", "description" "the carrier the shipment was booked with (e g australia post) " }, { "name" "tracking number", "kind" "required", "type" "string", "description" "the tracking number of the shipment " } ] } ] }, "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" }, "hastryitout" true, "autogeneratedanchorslug" "post tracking", "legacyhash" "p3cjagskwxnw9zirgldu0" } tracking response the 201 response is a list of shipment info objects (one per rma) reflecting the shipment state after the update tracking the tracking now attached to the rma tracking info id (refundid's internal id for the tracking record), created on , carrier , tracking number , tracking status and tracking status date (null until the carrier reports a status), reused (true if this tracking number was already used on another rma), lost in transit , and rmas using tracking (other rmas sharing the same tracking number) shipping label the refundid generated label attached to the rma, if any (null for merchant provided tracking) { "name" "close returns", "method" "post", "url" "https //api refundid com/v1/merchant/close refunds", "description" "merchants who wish to finalise (approve or reject) refundid rmas through their existing returns processing system should use this api to notify refundid of the final resolution of every return processed through the refundid platform merchants who prefer to use the refundid merchant portal to finalise refundid rmas do not need to use this api, but will still be notified of the outcome if they implement the \\"post /refundid\\" webhook \n\nthe request body is a json array each entry identifies one return (by exactly one of refundid id or standard return id) and the per item resolutions to apply \n\nthe response is a json object keyed by each supplied id, with the value \\"success\\" or an error message describing why that particular return could not be closed a failure for one return does not prevent the others in the batch from being processed ", "tab" "examples", "examples" { "languages" \[ { "id" "qdsx0dgenesmdgmt5qpfe", "language" "curl", "code" "curl location 'https //api refundid com/v1/merchant/close refunds' \\\\\n header 'content type application/json' \\\\\n header 'x refundid api key {{merchant api key}}' \\\\\n data '\[\n {\n \\"refundid id\\" 20871,\n \\"merchant rma ref\\" \\"ret 000451\\",\n \\"line items\\" \[\n {\n \\"merchant order ref\\" \\"5712345678800\\",\n \\"line item ref\\" \\"13987654320001\\",\n \\"quantity\\" 1,\n \\"resolution\\" \\"accept\\",\n \\"restock\\" true,\n \\"restock location ref\\" \\"70123456789\\",\n \\"notes\\" \\"returned in original packaging\\"\n }\n ]\n },\n {\n \\"standard return id\\" 1042,\n \\"merchant rma ref\\" null,\n \\"reimburse outbound shipping\\" false,\n \\"line items\\" \[\n {\n \\"merchant order ref\\" \\"5712345678901\\",\n \\"line item ref\\" \\"13987654321098\\",\n \\"quantity\\" 1,\n \\"resolution\\" \\"reject used item\\",\n \\"restock\\" false,\n \\"notes\\" \\"item shows signs of wear\\"\n }\n ]\n }\n]'", "customlabel" "" } ], "selectedlanguageid" "qdsx0dgenesmdgmt5qpfe" }, "results" { "languages" \[ { "id" "roypkwb2zxcsmeyznusjj", "language" "200", "code" "{\n \\"20871\\" \\"success\\",\n \\"1042\\" \\"success\\"\n}", "customlabel" "" }, { "id" "roypkwb2zxcsmeyznusjk", "language" "200", "code" "{\n \\"20871\\" \\"success\\",\n \\"1099\\" \\"return 1099 does not exist\\"\n}", "customlabel" "200 (partial failure)" } ], "selectedlanguageid" "roypkwb2zxcsmeyznusjj" }, "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[], "formdataparameters" \[], "bodydataparameters" \[ { "name" "refundid id", "kind" "optional", "type" "integer", "description" "field of each array entry the numeric id of the instant return to close exactly one of refundid id or standard return id must be provided per entry ", "children" \[] }, { "name" "standard return id", "kind" "optional", "type" "integer", "description" "field of each array entry the numeric id of the standard return to close exactly one of refundid id or standard return id must be provided per entry ", "children" \[] }, { "name" "merchant rma ref", "kind" "optional", "type" "string", "description" "field of each array entry a merchant generated rma reference to record against the return ", "children" \[] }, { "name" "reimburse outbound shipping", "kind" "optional", "type" "boolean", "description" "field of each array entry standard returns only when true, additionally refund the original order's outbound shipping to the customer defaults to false currently only supported where the platform can source the original shipping amount (e g shopify) ", "children" \[] }, { "name" "line items", "kind" "required", "type" "object", "description" "field of each array entry a json array of the per item resolutions must contain at least one entry a given line item may be repeated more than once if a different resolution is required for different quantities of the underlying merchandise ", "children" \[ { "name" "merchant order ref", "kind" "required", "type" "string", "description" "the e commerce platform's order id " }, { "name" "line item ref", "kind" "required", "type" "string", "description" "the e commerce platform's line item id " }, { "name" "quantity", "kind" "required", "type" "integer", "description" "the quantity this resolution applies to " }, { "name" "resolution", "kind" "required", "type" "string", "description" "the resolution code to apply (matched case insensitively) one of \n accept approve the item \n reject used item, reject sale item, reject damaged item, reject empty package, reject not received, reject incorrect item, reject no tracking, reject dishonest, reject policy violation, reject other reason reject the item for the given reason \n cancelled by customer, cancelled by merchant cancel the item \n\nnote for instant returns, the specific cancel and reject codes may alter the fees charged to the customer for standard returns, any cancel code is treated as a standard cancel and any reject code is treated as a standard reject " }, { "name" "restock", "kind" "required", "type" "boolean", "description" "whether the item is being restocked " }, { "name" "restock location ref", "kind" "optional", "type" "string", "description" "the e commerce platform's location id to restock the item into only used when restock is true when omitted, your refundid workflow restock location rules decide, falling back to the platform default (e g the shopify fulfilling location) a location your platform does not recognise fails the whole return with \\"unknown restock location ref \<ref>\\" " }, { "name" "notes", "kind" "optional", "type" "string", "description" "free text notes to record against the item " } ], "schema" \[ { "name" "merchant order ref", "kind" "required", "type" "string", "description" "the e commerce platform's order id " }, { "name" "line item ref", "kind" "required", "type" "string", "description" "the e commerce platform's line item id " }, { "name" "quantity", "kind" "required", "type" "integer", "description" "the quantity this resolution applies to " }, { "name" "resolution", "kind" "required", "type" "string", "description" "the resolution code to apply (matched case insensitively) one of \n accept approve the item \n reject used item, reject sale item, reject damaged item, reject empty package, reject not received, reject incorrect item, reject no tracking, reject dishonest, reject policy violation, reject other reason reject the item for the given reason \n cancelled by customer, cancelled by merchant cancel the item \n\nnote for instant returns, the specific cancel and reject codes may alter the fees charged to the customer for standard returns, any cancel code is treated as a standard cancel and any reject code is treated as a standard reject " }, { "name" "restock", "kind" "required", "type" "boolean", "description" "whether the item is being restocked " }, { "name" "restock location ref", "kind" "optional", "type" "string", "description" "the e commerce platform's location id to restock the item into only used when restock is true when omitted, your refundid workflow restock location rules decide, falling back to the platform default (e g the shopify fulfilling location) a location your platform does not recognise fails the whole return with \\"unknown restock location ref \<ref>\\" " }, { "name" "notes", "kind" "optional", "type" "string", "description" "free text notes to record against the item " } ] } ] }, "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" }, "hastryitout" true, "autogeneratedanchorslug" "close returns", "legacyhash" "vesgmcv59pxq5zpz10z17" } { "name" "add return note", "method" "post", "url" "https //api refundid com/v1/merchant/note", "description" "adds one or more notes to refundid rmas the notes can be viewed against the return in the refundid merchant portal \n\nthe request body is a json array each entry identifies one rma (by exactly one of refundid id or standard return id) and the note to add \n\nthe response is a json object keyed by each supplied id each value is a list of result objects (one per note submitted for that id), each containing a \\"message\\" of \\"success\\", \\"rma not found\\", or an error description ", "tab" "examples", "examples" { "languages" \[ { "id" "notesexample000000001", "language" "curl", "code" "curl location 'https //api refundid com/v1/merchant/note' \\\\\n header 'content type application/json' \\\\\n header 'x refundid api key {{merchant api key}}' \\\\\n data '\[\n {\n \\"refundid id\\" 20871,\n \\"note\\" \\"customer contacted support item arrived at warehouse damaged\\"\n },\n {\n \\"standard return id\\" 1042,\n \\"note\\" \\"approved by returns team, batch 14\\"\n }\n]'", "customlabel" "" } ], "selectedlanguageid" "notesexample000000001" }, "results" { "languages" \[ { "id" "notesexample000000002", "language" "200", "code" "{\n \\"20871\\" \[\n { \\"message\\" \\"success\\" }\n ],\n \\"1042\\" \[\n { \\"message\\" \\"success\\" }\n ]\n}", "customlabel" "" }, { "id" "notesexample000000003", "language" "200", "code" "{\n \\"20999\\" \[\n { \\"message\\" \\"rma not found\\" }\n ]\n}", "customlabel" "200 (not found)" } ], "selectedlanguageid" "notesexample000000002" }, "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[], "formdataparameters" \[], "bodydataparameters" \[ { "name" "refundid id", "kind" "optional", "type" "integer", "description" "field of each array entry the numeric id of the instant return to add the note to exactly one of refundid id or standard return id must be provided per entry ", "children" \[] }, { "name" "standard return id", "kind" "optional", "type" "integer", "description" "field of each array entry the numeric id of the standard return to add the note to exactly one of refundid id or standard return id must be provided per entry ", "children" \[] }, { "name" "note", "kind" "required", "type" "string", "description" "field of each array entry the note text to record against the return ", "children" \[] } ] }, "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" }, "hastryitout" true, "autogeneratedanchorslug" "add return note", "legacyhash" "0algabcv8fmgn2po18djq" } { "name" "flag return", "method" "put", "url" "https //api refundid com/v1/merchant/flag", "description" "flags (or unflags) returns in the refundid merchant portal flagged returns can be filtered in the portal and via the \\"flagged\\" parameter of the get returns api \n\nthe request body is a json array each entry identifies one rma (by exactly one of refundid id or standard return id) and the flag state to set each rma may appear at most once in the request; duplicate ids are rejected with a 400 response \n\nthe response is a json object keyed by each supplied id each value is a list of result objects containing a \\"message\\" (\\"success\\", \\"rma not found\\", or an error description) and, on success, the return's current \\"is flagged\\" state ", "tab" "examples", "examples" { "languages" \[ { "id" "flagexample0000000001", "language" "curl", "code" "curl location request put 'https //api refundid com/v1/merchant/flag' \\\\\n header 'content type application/json' \\\\\n header 'x refundid api key {{merchant api key}}' \\\\\n data '\[\n {\n \\"refundid id\\" 20871,\n \\"is flagged\\" true\n },\n {\n \\"standard return id\\" 1042,\n \\"is flagged\\" false\n }\n]'", "customlabel" "" } ], "selectedlanguageid" "flagexample0000000001" }, "results" { "languages" \[ { "id" "flagexample0000000002", "language" "200", "code" "{\n \\"20871\\" \[\n { \\"message\\" \\"success\\", \\"is flagged\\" true }\n ],\n \\"1042\\" \[\n { \\"message\\" \\"success\\", \\"is flagged\\" false }\n ]\n}", "customlabel" "" }, { "id" "flagexample0000000003", "language" "400", "code" "{ \\"message\\" \\"duplicate return ids provided\\" }", "customlabel" "" } ], "selectedlanguageid" "flagexample0000000002" }, "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[], "formdataparameters" \[], "bodydataparameters" \[ { "name" "refundid id", "kind" "optional", "type" "integer", "description" "field of each array entry the numeric id of the instant return to flag/unflag exactly one of refundid id or standard return id must be provided per entry ", "children" \[] }, { "name" "standard return id", "kind" "optional", "type" "integer", "description" "field of each array entry the numeric id of the standard return to flag/unflag exactly one of refundid id or standard return id must be provided per entry ", "children" \[] }, { "name" "is flagged", "kind" "required", "type" "boolean", "description" "field of each array entry true to flag the return, false to remove the flag ", "children" \[] } ] }, "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" }, "hastryitout" true, "autogeneratedanchorslug" "flag return", "legacyhash" "s0g b1j5kuyewe r5ja8g" } item dispositions a disposition records the condition a returned item was found in when it was inspected (for example "resellable", "damaged" or "quarantine") dispositions are configured per store in the refundid merchant portal, and each one has a numeric id and a description one disposition is optionally marked as the store's default use get dispositions to retrieve the list configured for your store, then set item disposition to record one against a returned line dispositions can only be set on a return that has already been closed, and the disposition applies to the whole returned line regardless of the quantity returned on it { "name" "get dispositions", "method" "get", "url" "https //api refundid com/v1/merchant/dispositions", "description" "returns the list of item dispositions configured for your store in the refundid merchant portal \n\nthe response is a json array each entry has an \\"id\\" (use this as the disposition id when calling set item disposition), a \\"description\\" (the label shown in the merchant portal) and \\"is default\\" (whether this is the store's default disposition) at most one disposition is marked as the default ", "tab" "examples", "examples" { "languages" \[ { "id" "dispositions000000001", "language" "curl", "code" "curl location request get 'https //api refundid com/v1/merchant/dispositions' \\\\\n header 'accept application/json' \\\\\n header 'x refundid api key {{merchant api key}}'", "customlabel" "" } ], "selectedlanguageid" "dispositions000000001" }, "results" { "languages" \[ { "id" "dispositions000000002", "language" "200", "code" "\[\n {\n \\"id\\" 12,\n \\"description\\" \\"resellable\\",\n \\"is default\\" true\n },\n {\n \\"id\\" 13,\n \\"description\\" \\"damaged\\",\n \\"is default\\" false\n },\n {\n \\"id\\" 14,\n \\"description\\" \\"quarantine\\",\n \\"is default\\" false\n }\n]", "customlabel" "" } ], "selectedlanguageid" "dispositions000000002" }, "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[], "formdataparameters" \[], "bodydataparameters" \[] }, "currentnewparameter" { "label" "query parameter", "value" "queryparameters" }, "hastryitout" true, "autogeneratedanchorslug" "get dispositions", "legacyhash" "r2fpwdyony8ibxwh1bwdc" } { "name" "set item disposition", "method" "post", "url" "https //api refundid com/v1/merchant/dispositions", "description" "records a disposition against a single returned line on a closed refundid rma setting a disposition replaces whatever disposition was previously recorded against that line, including one applied automatically when the return was closed \n\nthe line is identified on its own by the return line item id returned by the get returns api (see the line item fields section) no return identifier is needed \n\nthe return the line belongs to must already be closed a request against an open return is rejected with a 400 a 404 is returned if the line or the disposition cannot be found against your store ", "tab" "examples", "examples" { "languages" \[ { "id" "dispositions000000003", "language" "curl", "code" "curl location 'https //api refundid com/v1/merchant/dispositions' \\\\\n header 'content type application/json' \\\\\n header 'x refundid api key {{merchant api key}}' \\\\\n data '{\n \\"return line item id\\" 884213,\n \\"disposition id\\" 13\n}'", "customlabel" "" } ], "selectedlanguageid" "dispositions000000003" }, "results" { "languages" \[ { "id" "dispositions000000004", "language" "200", "code" "{\n \\"message\\" \\"success\\"\n}", "customlabel" "" }, { "id" "dispositions000000005", "language" "404", "code" "{\n \\"message\\" \\"return line item not found\\"\n}", "customlabel" "404 (not found)" }, { "id" "dispositions000000006", "language" "400", "code" "{\n \\"message\\" \\"cannot set item disposition for an open rma\\"\n}", "customlabel" "400 (return still open)" } ], "selectedlanguageid" "dispositions000000004" }, "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[], "formdataparameters" \[], "bodydataparameters" \[ { "name" "return line item id", "kind" "required", "type" "integer", "description" "refundid's id for the returned line to set the disposition on, as returned in the return line item id field of each line item by the get returns api this is the only identifier needed it resolves the return as well as the line ", "children" \[] }, { "name" "disposition id", "kind" "required", "type" "integer", "description" "the id of the disposition to record, as returned by the get dispositions api the disposition must be one configured for your store ", "children" \[] } ] }, "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" }, "hastryitout" true, "autogeneratedanchorslug" "set item disposition", "legacyhash" "d2vlvxbul2rimlcfz49gj" } { "name" "get tags", "method" "get", "url" "https //api refundid com/v1/merchant/tags", "description" "lists the return tags configured for your store, as managed in the refundid merchant portal use the returned tag ids with the add return tags api \n\nthe response is a json array of tag objects, each containing the tag's \\"id\\" and \\"name\\" deleted tags are not included ", "tab" "examples", "examples" { "languages" \[ { "id" "gettagsexample0000001", "language" "curl", "code" "curl location 'https //api refundid com/v1/merchant/tags' \\\\\n header 'accept application/json' \\\\\n header 'x refundid api key {{merchant api key}}'", "customlabel" "" } ], "selectedlanguageid" "gettagsexample0000001" }, "results" { "languages" \[ { "id" "gettagsexample0000002", "language" "200", "code" "\[\n { \\"id\\" 1, \\"name\\" \\"damaged\\" },\n { \\"id\\" 2, \\"name\\" \\"urgent\\" }\n]", "customlabel" "" } ], "selectedlanguageid" "gettagsexample0000002" }, "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[], "formdataparameters" \[], "bodydataparameters" \[] }, "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" }, "hastryitout" true, "autogeneratedanchorslug" "get tags", "legacyhash" "otl6ithyi5xa0x zc 6hx" } { "name" "add return tags", "method" "post", "url" "https //api refundid com/v1/merchant/return tags", "description" "adds one or more tags to refundid rmas tagged returns can be viewed and filtered in the refundid merchant portal tag ids are returned by the get tags api \n\nthis endpoint only adds tags tags already on the return are kept (re adding an existing tag is a no op), and tags can be removed via the merchant portal \n\nthe request body is a json array each entry identifies one rma (by exactly one of refundid id or standard return id) and the tag ids to add \n\nthe response is a json object keyed by each supplied id each value is a list of result objects containing a \\"message\\" (\\"success\\", \\"rma not found\\", \\"unknown tag ids \[ ]\\", or an error description) and, on success, \\"tag ids\\" the full set of tag ids now on the return ", "tab" "examples", "examples" { "languages" \[ { "id" "rtagsexample000000001", "language" "curl", "code" "curl location 'https //api refundid com/v1/merchant/return tags' \\\\\n header 'content type application/json' \\\\\n header 'x refundid api key {{merchant api key}}' \\\\\n data '\[\n {\n \\"refundid id\\" 20871,\n \\"tag ids\\" \[1, 2]\n },\n {\n \\"standard return id\\" 1042,\n \\"tag ids\\" \[1]\n }\n]'", "customlabel" "" } ], "selectedlanguageid" "rtagsexample000000001" }, "results" { "languages" \[ { "id" "rtagsexample000000002", "language" "200", "code" "{\n \\"20871\\" \[\n { \\"message\\" \\"success\\", \\"tag ids\\" \[1, 2] }\n ],\n \\"1042\\" \[\n { \\"message\\" \\"success\\", \\"tag ids\\" \[1] }\n ]\n}", "customlabel" "" }, { "id" "rtagsexample000000003", "language" "200", "code" "{\n \\"20999\\" \[\n { \\"message\\" \\"rma not found\\" }\n ],\n \\"1042\\" \[\n { \\"message\\" \\"unknown tag ids \[99]\\" }\n ]\n}", "customlabel" "200 (errors)" } ], "selectedlanguageid" "rtagsexample000000002" }, "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[], "formdataparameters" \[], "bodydataparameters" \[ { "name" "refundid id", "kind" "optional", "type" "integer", "description" "field of each array entry the numeric id of the instant return to tag exactly one of refundid id or standard return id must be provided per entry ", "children" \[] }, { "name" "standard return id", "kind" "optional", "type" "integer", "description" "field of each array entry the numeric id of the standard return to tag exactly one of refundid id or standard return id must be provided per entry ", "children" \[] }, { "name" "tag ids", "kind" "required", "type" "string", "description" "field of each array entry the ids of the tags to add to the return (at least one), as returned by the get tags api ", "children" \[] } ] }, "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" }, "hastryitout" true, "autogeneratedanchorslug" "add return tags", "legacyhash" "oxcqkpsnl0likpgwrtm6s" } { "name" "purchase return shipping label", "method" "post", "url" "https //api refundid com/v1/merchant/return shipping label", "description" "purchases a standalone return shipping label through one of the refundid managed carrier accounts configured for your store this is intended for merchants who want to generate return labels from their own systems (for example, for returns that are processed outside a refundid rma) \n\nthe carrier account is selected via \\"carrier account ref\\" refundid will provide you with the references for the carrier accounts enabled for your store for international shipments, a \\"customs declaration\\" must be supplied and your store must have a customs signer configured with refundid \n\nsee the shipping label response section below for a breakdown of the response fields ", "tab" "examples", "examples" { "languages" \[ { "id" "shiplabelpost00000001", "language" "curl", "code" "curl location 'https //api refundid com/v1/merchant/return shipping label' \\\\\n header 'content type application/json' \\\\\n header 'x refundid api key {{merchant api key}}' \\\\\n data '{\n \\"carrier account ref\\" \\"ca 1a2b3c4d5e\\",\n \\"from address\\" {\n \\"name\\" \\"jane doe\\",\n \\"street1\\" \\"123 example st\\",\n \\"street2\\" null,\n \\"city\\" \\"sydney\\",\n \\"state\\" \\"nsw\\",\n \\"zip\\" \\"2000\\",\n \\"country\\" \\"au\\",\n \\"phone\\" \\"+61400123456\\",\n \\"email\\" \\"jane doe\@example com\\"\n },\n \\"to address\\" {\n \\"name\\" \\"acme apparel returns\\",\n \\"street1\\" \\"1 warehouse way\\",\n \\"street2\\" \\"dock 4\\",\n \\"city\\" \\"melbourne\\",\n \\"state\\" \\"vic\\",\n \\"zip\\" \\"3000\\",\n \\"country\\" \\"au\\",\n \\"phone\\" \\"+61390001111\\",\n \\"email\\" \\"returns\@acmeapparel com\\"\n },\n \\"parcel\\" {\n \\"length\\" 12,\n \\"width\\" 9,\n \\"height\\" 3,\n \\"weight\\" 16\n },\n \\"customer reference\\" \\"ret 000451\\"\n}'", "customlabel" "" } ], "selectedlanguageid" "shiplabelpost00000001" }, "results" { "languages" \[ { "id" "shiplabelpost00000002", "language" "200", "customlabel" "", "code" "{\n \\"id\\" 3312,\n \\"tracking number\\" \\"33abc5551234\\",\n \\"carrier\\" \\"australiapost\\",\n \\"service type\\" \\"parcelpost\\",\n \\"price\\" 10 45,\n \\"currency\\" \\"aud\\",\n \\"label binary b64\\" \\"jvberi0xljqkjcokw7zdtsofcjigmcbvymok \\",\n \\"label file type\\" \\"pdf\\"\n}" }, { "id" "shiplabelpost00000003", "language" "404", "customlabel" "", "code" "{ \\"error\\" \\"carrier account not found\\" }" } ], "selectedlanguageid" "shiplabelpost00000002" }, "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[], "formdataparameters" \[], "bodydataparameters" \[ { "name" "carrier account ref", "kind" "required", "type" "string", "description" "the reference of the refundid managed carrier account to purchase the label with provided to you by refundid ", "children" \[] }, { "name" "from address", "kind" "required", "type" "object", "description" "the pickup / sender address (typically the customer) ", "children" \[ { "name" "name", "kind" "required", "type" "string", "description" "the sender's full name " }, { "name" "street1", "kind" "required", "type" "string", "description" "the first street line " }, { "name" "street2", "kind" "optional", "type" "string", "description" "the second street line (unit, apartment, dock, etc ) " }, { "name" "city", "kind" "required", "type" "string", "description" "the city or suburb " }, { "name" "state", "kind" "optional", "type" "string", "description" "the state or province (e g nsw) " }, { "name" "zip", "kind" "optional", "type" "string", "description" "the postcode / zip code " }, { "name" "country", "kind" "required", "type" "string", "description" "the iso country code (e g au) " }, { "name" "phone", "kind" "optional", "type" "string", "description" "a contact phone number for the sender " }, { "name" "email", "kind" "optional", "type" "string", "description" "a contact email for the sender " } ], "schema" \[ { "name" "name", "kind" "required", "type" "string", "description" "the sender's full name " }, { "name" "street1", "kind" "required", "type" "string", "description" "the first street line " }, { "name" "street2", "kind" "optional", "type" "string", "description" "the second street line (unit, apartment, dock, etc ) " }, { "name" "city", "kind" "required", "type" "string", "description" "the city or suburb " }, { "name" "state", "kind" "optional", "type" "string", "description" "the state or province (e g nsw) " }, { "name" "zip", "kind" "optional", "type" "string", "description" "the postcode / zip code " }, { "name" "country", "kind" "required", "type" "string", "description" "the iso country code (e g au) " }, { "name" "phone", "kind" "optional", "type" "string", "description" "a contact phone number for the sender " }, { "name" "email", "kind" "optional", "type" "string", "description" "a contact email for the sender " } ] }, { "name" "to address", "kind" "required", "type" "object", "description" "the destination address (typically your returns warehouse) same fields as from address ", "children" \[ { "name" "name", "kind" "required", "type" "string", "description" "the recipient's name (e g your returns department) " }, { "name" "street1", "kind" "required", "type" "string", "description" "the first street line " }, { "name" "street2", "kind" "optional", "type" "string", "description" "the second street line (unit, apartment, dock, etc ) " }, { "name" "city", "kind" "required", "type" "string", "description" "the city or suburb " }, { "name" "state", "kind" "optional", "type" "string", "description" "the state or province (e g vic) " }, { "name" "zip", "kind" "optional", "type" "string", "description" "the postcode / zip code " }, { "name" "country", "kind" "required", "type" "string", "description" "the iso country code (e g au) " }, { "name" "phone", "kind" "optional", "type" "string", "description" "a contact phone number for the recipient " }, { "name" "email", "kind" "optional", "type" "string", "description" "a contact email for the recipient " } ], "schema" \[ { "name" "name", "kind" "required", "type" "string", "description" "the recipient's name (e g your returns department) " }, { "name" "street1", "kind" "required", "type" "string", "description" "the first street line " }, { "name" "street2", "kind" "optional", "type" "string", "description" "the second street line (unit, apartment, dock, etc ) " }, { "name" "city", "kind" "required", "type" "string", "description" "the city or suburb " }, { "name" "state", "kind" "optional", "type" "string", "description" "the state or province (e g vic) " }, { "name" "zip", "kind" "optional", "type" "string", "description" "the postcode / zip code " }, { "name" "country", "kind" "required", "type" "string", "description" "the iso country code (e g au) " }, { "name" "phone", "kind" "optional", "type" "string", "description" "a contact phone number for the recipient " }, { "name" "email", "kind" "optional", "type" "string", "description" "a contact email for the recipient " } ] }, { "name" "parcel", "kind" "required", "type" "object", "description" "the parcel dimensions and weight ", "children" \[ { "name" "length", "kind" "required", "type" "number", "description" "parcel length in inches " }, { "name" "width", "kind" "required", "type" "number", "description" "parcel width in inches " }, { "name" "height", "kind" "required", "type" "number", "description" "parcel height in inches " }, { "name" "weight", "kind" "required", "type" "number", "description" "parcel weight in ounces " } ], "schema" \[ { "name" "length", "kind" "required", "type" "number", "description" "parcel length in inches " }, { "name" "width", "kind" "required", "type" "number", "description" "parcel width in inches " }, { "name" "height", "kind" "required", "type" "number", "description" "parcel height in inches " }, { "name" "weight", "kind" "required", "type" "number", "description" "parcel weight in ounces " } ] }, { "name" "customs declaration", "kind" "optional", "type" "object", "description" "required for international shipments your store must also have a customs signer configured with refundid ", "children" \[ { "name" "customs items", "kind" "required", "type" "object", "description" "a json array of the items in the parcel each entry contains \n weight (number, required) the item weight in ounces \n quantity (integer, required) \n description (string, required) a description of the item \n origin country (string, required) the iso country code the item originates from \n amount (number, required) the value of the item \n currency (string, required) the iso 4217 currency of the amount \n sku (string, optional) \n return reason (string, optional) \n hs tariff number (string, optional) the harmonised system tariff code " }, { "name" "contents explanation", "kind" "required", "type" "string", "description" "a free text description of the parcel contents " }, { "name" "restriction type", "kind" "required", "type" "string", "description" "one of none, other, quarantine " }, { "name" "contents type", "kind" "required", "type" "string", "description" "one of return, merchandise, gift " }, { "name" "non delivery option", "kind" "required", "type" "string", "description" "what happens if the shipment cannot be delivered abandon or return " }, { "name" "preferred incoterm", "kind" "optional", "type" "string", "description" "defaults to dap " } ], "schema" \[ { "name" "customs items", "kind" "required", "type" "object", "description" "a json array of the items in the parcel each entry contains \n weight (number, required) the item weight in ounces \n quantity (integer, required) \n description (string, required) a description of the item \n origin country (string, required) the iso country code the item originates from \n amount (number, required) the value of the item \n currency (string, required) the iso 4217 currency of the amount \n sku (string, optional) \n return reason (string, optional) \n hs tariff number (string, optional) the harmonised system tariff code " }, { "name" "contents explanation", "kind" "required", "type" "string", "description" "a free text description of the parcel contents " }, { "name" "restriction type", "kind" "required", "type" "string", "description" "one of none, other, quarantine " }, { "name" "contents type", "kind" "required", "type" "string", "description" "one of return, merchandise, gift " }, { "name" "non delivery option", "kind" "required", "type" "string", "description" "what happens if the shipment cannot be delivered abandon or return " }, { "name" "preferred incoterm", "kind" "optional", "type" "string", "description" "defaults to dap " } ] }, { "name" "customer reference", "kind" "optional", "type" "string", "description" "a free text reference of your own (e g your internal return id) to associate with the shipment ", "children" \[] } ] }, "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" }, "hastryitout" true, "autogeneratedanchorslug" "purchase return shipping label", "legacyhash" "fpnu bqfwek1sb7bbbidg" } shipping label response the purchase return shipping label and get return shipping label apis return id the refundid shipment id use this id with the get return shipping label api to re download the label later tracking number the tracking number of the purchased label carrier the carrier the label was purchased with service type the carrier service used (e g express vs standard) price the price charged to the merchant for the label currency the currency of the price label binary b64 the label file, base64 encoded label file type the file type of the decoded label (e g pdf , png , zpl ) the list return shipping labels api returns the same fields per entry, excluding the label binary fetch an individual label by id to download it { "name" "list return shipping labels", "method" "get", "url" "https //api refundid com/v1/merchant/return shipping label", "description" "lists the return shipping labels previously purchased through the purchase return shipping label api, most useful for reconciliation of shipping spend \n\nthe response is a json array of label summaries see the shipping label response section above for field descriptions the label binary itself is not included in the listing; fetch an individual label by id to download it ", "tab" "examples", "examples" { "languages" \[ { "id" "shiplabellist00000001", "language" "curl", "code" "curl location request get 'https //api refundid com/v1/merchant/return shipping label?date from=2026 06 01\&date to=2026 06 30\&limit=50\&offset=0' \\\\\n header 'accept application/json' \\\\\n header 'x refundid api key {{merchant api key}}'", "customlabel" "" } ], "selectedlanguageid" "shiplabellist00000001" }, "results" { "languages" \[ { "id" "shiplabellist00000002", "language" "200", "customlabel" "", "code" "\[\n {\n \\"id\\" 3312,\n \\"tracking number\\" \\"33abc5551234\\",\n \\"carrier\\" \\"australiapost\\",\n \\"service type\\" \\"parcelpost\\",\n \\"price\\" 10 45,\n \\"currency\\" \\"aud\\"\n },\n {\n \\"id\\" 3298,\n \\"tracking number\\" \\"33abc5550021\\",\n \\"carrier\\" \\"australiapost\\",\n \\"service type\\" \\"expresspost\\",\n \\"price\\" 14 2,\n \\"currency\\" \\"aud\\"\n }\n]" }, { "id" "shiplabellist00000003", "language" "400", "customlabel" "", "code" "{ \\"message\\" \\"date from is greater than date to\\" }" } ], "selectedlanguageid" "shiplabellist00000002" }, "request" { "pathparameters" \[], "queryparameters" \[ { "name" "date from", "kind" "optional", "type" "string", "description" "restricts the results to labels purchased on or after this date (interpreted in your store's timezone) format yyyy mm dd if provided, date to must also be provided ", "children" \[] }, { "name" "date to", "kind" "optional", "type" "string", "description" "restricts the results to labels purchased on or before this date (inclusive, interpreted in your store's timezone) format yyyy mm dd if provided, date from must also be provided ", "children" \[] }, { "name" "limit", "kind" "optional", "type" "integer", "description" "restricts the result to at most limit records if specified, must be a positive integer ", "children" \[] }, { "name" "offset", "kind" "optional", "type" "number", "description" "begins the listing after the first offset records if specified, must be a non negative integer defaults to 0 ", "children" \[] } ], "headerparameters" \[], "formdataparameters" \[], "bodydataparameters" \[] }, "currentnewparameter" { "label" "query parameter", "value" "queryparameters" }, "hastryitout" true, "autogeneratedanchorslug" "list return shipping labels", "legacyhash" "dbnz ou833t f5fqiwxsu" } { "name" "get return shipping label", "method" "get", "url" "https //api refundid com/v1/merchant/return shipping label/{shipment id}", "description" "fetches a single previously purchased return shipping label, including the label file itself use this to re download a label after purchasing it, or to retrieve labels found via the list return shipping labels api \n\nsee the shipping label response section above for field descriptions ", "tab" "examples", "examples" { "languages" \[ { "id" "shiplabelget000000001", "language" "curl", "code" "curl location request get 'https //api refundid com/v1/merchant/return shipping label/3312' \\\\\n header 'accept application/json' \\\\\n header 'x refundid api key {{merchant api key}}'", "customlabel" "" } ], "selectedlanguageid" "shiplabelget000000001" }, "results" { "languages" \[ { "id" "shiplabelget000000002", "language" "200", "customlabel" "", "code" "{\n \\"id\\" 3312,\n \\"tracking number\\" \\"33abc5551234\\",\n \\"carrier\\" \\"australiapost\\",\n \\"service type\\" \\"parcelpost\\",\n \\"price\\" 10 45,\n \\"currency\\" \\"aud\\",\n \\"label binary b64\\" \\"jvberi0xljqkjcokw7zdtsofcjigmcbvymok \\",\n \\"label file type\\" \\"pdf\\"\n}" }, { "id" "shiplabelget000000003", "language" "404", "customlabel" "", "code" "{ \\"error\\" \\"shipment not found\\" }" } ], "selectedlanguageid" "shiplabelget000000002" }, "request" { "pathparameters" \[ { "name" "shipment id", "kind" "required", "type" "integer", "description" "the refundid shipment id, as returned by the purchase return shipping label and list return shipping labels apis ", "children" \[] } ], "queryparameters" \[], "headerparameters" \[], "formdataparameters" \[], "bodydataparameters" \[] }, "currentnewparameter" { "label" "path parameter", "value" "pathparameters" }, "hastryitout" true, "autogeneratedanchorslug" "get return shipping label", "legacyhash" "wc0bnlvgtyfbpu dcwpde" }