Webhooks

sandbox setup if you require setup on a sandbox environment please reach out to integrations\@refundid com mailto\ integrations\@refundid com you will need to provide the webhook urls for all the endpoints you plan to implement, e g https //examplemerchant com/order https //examplemerchant com/orderhttps //examplemerchant com/refundid https //examplemerchant com/refundid the authentication method (see below for auth methods) you will be using along with any keys/secrets required for configuration, e g api key header some header api key some key authentication and security refundid implements a layered security model, allowing merchants to choose from a number of different means of verifying authenticity of refundid api requests to suit their specific e commerce platform architecture transport layer validation all requests to the merchant provided apis in production and sandbox environments originate from predetermined ip addresses, published under the following dns names in production environment, all requests will originate from “ rapi refundid com ” in sandbox environment, all requests will originate from “ rapi sandbox refundid com " merchants may choose to restrict access to their apis to these originating ip addresses ssl certificate validation all requests to the merchant provided apis in production and sandbox environments are made over the https protocol using publicly verifiable ssl certificates with the following subject names in production environment, “ cn=rapi refundid com ” in sandbox environment, “ cn=rapi sandbox refundid com ” merchants may choose to verify these certificates in their https server standard request headers every webhook request from refundid includes an accept application/json header and a date mime header (rfc 1123 format, gmt) requests that carry a body additionally include content type application/json and a content md5 header containing the base64 encoded md5 digest of the raw request body, which merchants may use as an integrity check requests time out after 120 seconds bearer token merchants may choose to configure their apis with bearer token authentication, using a merchant provided bearer token if a bearer token is provided to the refundid, all requests to the merchant provided api will be submitted with the following header authorization bearer the must be no longer than 256 characters and confirm to rfc 6750 requirements, i e , consist entirely of ascii letters, digits and/or characters ' ', ' ', ' ', ' ', '+' and '/', followed by zero or more '=' characters api key in addition to bearer authorisation, merchants may choose to request that all requests to their apis are issued with a merchant provided api key when enabled, all requests to the merchant provided api will be submitted with the following header under this scheme, both the and must be provided by the merchant the api key may consist of up to 256 arbitrary printable (i e , non whitespace) ascii characters request signature last but not least, refundid can be configured to protect all requests to the merchant provided apis with the following hmac based signature header x refundid signature where is one of hmac sha1, hmac sha224, hmac sha256, hmac sha384 or hmac sha512 is a lowercase hexadecimal hmac signature computed using the selected hmac algorithm and the merchant provided secret key over a utf 8 string of the form \n or if body is not defined (for example on the get /order request) where is the content of the " date" mime header in the request and is the raw, unprocessed http request body, excluding any mime headers webhooks the post /refundid and post /standard return endpoints configured as the primary rapi ecommerce integration can approve or reject an in progress operation a 2xx response approves it and a 4xx response rejects it additional webhook endpoints configured in the merchant portal are notification only refundid records unsuccessful deliveries to those additional endpoints, but their responses do not change or stop the return order webhook return schema models # used to fetch order information using either order number and email or merchant order ref when invoking the “ get /order ” api, refundid may choose to identify the order either by a merchant generated unique identifier ("merchant order ref"), or by a combination of a customer "email" and a merchant generated "order number" provided to the customer both variants must be supported (two separate webhook urls are configured one for lookup by order number and one for lookup by merchant order ref and both may point at the same endpoint ) when using the customer " email " and " order number ", the api is expected to match the " order number " both with and without any optional or decorative prefixes such as “#”, in accordance with the merchant specific convention consistent with other communication channels between the merchant and their customers for example, if merchant's invoices decorate order numbers with the “#order " prefix and a version suffix ( xxx), then, for best customer experience, an order number of "#order 123456 xxx" should be matched by all of “order number=#order 123456 xxx", "order number=order 123456 xxx", "order number=123456 xxx" and "order number=123456" if no order matches the request, respond with a 404 status refundid treats this as "order not found" rather than an error a successful response must have status 200 , a content type application/json header, and a body of the models # structure shown in the example below the returnable quantity on each line item should exclude quantities already refunded or returned by other means, and non returnable reasons should list any merchant side reasons an item cannot be returned (an empty list means the item is returnable) { "name" "order", "method" "get", "url" "https //{{merchant url}}/order", "description" "called by refundid to fetch order information from the merchant's system respond with 200 and a rapiorder json body, or 404 when no order matches ", "tab" "examples", "examples" { "languages" \[ { "id" "pc7wsmduint7omzloarv ", "language" "curl", "code" "curl location g request get 'https //{{merchant url}}/order?order number=order 123456 xxx\&email=someone\@refundid com' \\\\\n header 'accept application/json' \\\\\n header 'date mon, 22 jun 2026 01 12 44 gmt'", "customlabel" "by order number" }, { "id" "pc7wsmduint7omzloarw ", "language" "curl", "code" "curl location g request get 'https //{{merchant url}}/order?merchant order ref=5712345678901' \\\\\n header 'accept application/json' \\\\\n header 'date mon, 22 jun 2026 01 12 44 gmt'", "customlabel" "by merchant order ref" } ], "selectedlanguageid" "pc7wsmduint7omzloarv " }, "results" { "languages" \[ { "id" "61wfy aekaaf5oicvzdl3", "language" "200", "customlabel" "", "code" "{\n \\"merchant order ref\\" \\"5712345678901\\",\n \\"order number\\" \\"#order 123456 xxx\\",\n \\"email\\" \\"someone\@refundid com\\",\n \\"purchased at\\" \\"2026 06 14t09 33 50\\",\n \\"fulfilled at\\" \\"2026 06 16t09 10 32\\",\n \\"payment method\\" \\"afterpay\\",\n \\"is giftcard used\\" false,\n \\"delivery info\\" {\n \\"address\\" {\n \\"address1\\" \\"89 york street\\",\n \\"address2\\" \\"901\\",\n \\"city\\" \\"sydney\\",\n \\"zip\\" \\"2030\\",\n \\"province\\" \\"new south wales\\",\n \\"country\\" \\"au\\"\n },\n \\"tracking\\" {\n \\"carrier\\" \\"australia post\\",\n \\"tracking number\\" \\"sk40010043214\\",\n \\"status\\" null,\n \\"status date\\" null\n }\n },\n \\"line items\\" \[\n {\n \\"line item ref\\" \\"10000001\\",\n \\"title\\" \\"long line shirt\\",\n \\"variant\\" \\"large\\",\n \\"price\\" {\n \\"amount\\" 33 33,\n \\"currency\\" \\"aud\\"\n },\n \\"tax detail\\" {\n \\"tax\\" {\n \\"amount\\" 3 03,\n \\"currency\\" \\"aud\\"\n },\n \\"tax included\\" true\n },\n \\"quantity\\" 2,\n \\"returnable quantity\\" 2,\n \\"discount\\" {\n \\"amount\\" 0,\n \\"currency\\" \\"aud\\"\n },\n \\"image url\\" \\"https //via placeholder com/150\\",\n \\"weight in kilograms\\" 5 3,\n \\"product ref\\" \\"product 1\\",\n \\"variant ref\\" \\"variant 1\\",\n \\"sku\\" \\"sku 1\\",\n \\"categories\\" \[\n \\"shirt\\",\n \\"summer\\"\n ],\n \\"non returnable reasons\\" \[]\n },\n {\n \\"line item ref\\" \\"10000002\\",\n \\"title\\" \\"tracksuit pants\\",\n \\"variant\\" \\"large black\\",\n \\"price\\" {\n \\"amount\\" 99 99,\n \\"currency\\" \\"aud\\"\n },\n \\"tax detail\\" {\n \\"tax\\" {\n \\"amount\\" 9 09,\n \\"currency\\" \\"aud\\"\n },\n \\"tax included\\" true\n },\n \\"quantity\\" 1,\n \\"returnable quantity\\" 1,\n \\"discount\\" {\n \\"amount\\" 30,\n \\"currency\\" \\"aud\\"\n },\n \\"image url\\" \\"https //via placeholder com/150\\",\n \\"weight in kilograms\\" 5 3,\n \\"product ref\\" \\"product 2\\",\n \\"variant ref\\" \\"variant 2\\",\n \\"sku\\" \\"sku 2\\",\n \\"categories\\" \[\n \\"pants\\",\n \\"summer\\"\n ],\n \\"non returnable reasons\\" \[\n \\"item already refunded\\"\n ]\n }\n ],\n \\"metafields\\" \[\n {\n \\"value type\\" \\"string\\",\n \\"key\\" \\"loyalty tier\\",\n \\"value\\" \\"gold\\"\n }\n ]\n}" }, { "id" "61wfy aekaaf5oicvzdl4", "language" "404", "customlabel" "order not found", "code" "{ \\"message\\" \\"order not found\\" }" } ], "selectedlanguageid" "61wfy aekaaf5oicvzdl3" }, "request" { "pathparameters" \[], "queryparameters" \[ { "name" "order number", "kind" "optional", "type" "string", "description" "merchant generated customer order number sent (together with email) when refundid looks the order up on the customer's behalf ", "children" \[] }, { "name" "email", "kind" "optional", "type" "string", "description" "customer email always sent together with order number ", "children" \[] }, { "name" "merchant order ref", "kind" "optional", "type" "string", "description" "merchant generated unique order identifier sent instead of order number/email when refundid already knows the order's unique reference ", "children" \[] }, { "name" "key", "kind" "optional", "type" "string", "description" "merchant supplied privacy key for this order, echoed back if one was provided to refundid (e g via a merchant initiated redirect) ", "children" \[] } ], "headerparameters" \[], "formdataparameters" \[], "bodydataparameters" \[] }, "currentnewparameter" { "label" "query parameter", "value" "queryparameters" }, "hastryitout" false, "autogeneratedanchorslug" "order", "legacyhash" "4s3deah fztlov3iagj 4" } return webhook return schema models # this api is only called by refundid with merchants who chose to implement the merchant initiated rma flow for these merchants, refundid will call this api immediately after receiving a redirect to https //portal refundid com/order query?merchant rma ref=merchant rma ref https //portal refundid com/order query?merchant rma ref=merchant rma ref merchants who use only refundid initiated rma flow do not need to implement this api the “get /return” api is called by refundid (as a https get request) to obtain information about an rma generated on the merchant's system and managed by the merchant it is first called upon receiving a redirect https //portal refundid com/order query https //portal refundid com/order query mentioning a merchant's rma id in the "merchant rma ref" url parameter it may be subsequently called by refundid at any time as required to obtain updates to the rma from the merchant on success, the merchant's e commerce system should respond to the request with a json object of a structure shown in the example below each line item specifies a compensation method of refund , exchange or credit , and may carry adjustments positive or negative amounts (e g loyalty bonuses or missing packaging fees) applied on top of the item value the optional return shipping block supplies the return addresses, any existing tracking, and deductions to subtract from the refund for shipping { "name" "return", "method" "get", "url" "https //{{merchant url}}/return", "description" "called by refundid to fetch a merchant managed rma respond with 200 and a rapireturn json body ", "tab" "examples", "examples" { "languages" \[ { "id" "sciwvacvpoav9ot7zflje", "language" "curl", "code" "curl location g request get 'https //{{merchant url}}/return?merchant rma ref=rma123' \\\\\n header 'accept application/json' \\\\\n header 'date mon, 22 jun 2026 01 12 44 gmt'", "customlabel" "" } ], "selectedlanguageid" "sciwvacvpoav9ot7zflje" }, "results" { "languages" \[ { "id" "miaebanlo793t30mvktwb", "language" "200", "customlabel" "", "code" "{\n \\"merchant rma ref\\" \\"rma123\\",\n \\"created at\\" \\"2026 06 20t09 33 50\\",\n \\"line items\\" \[\n {\n \\"merchant order ref\\" \\"5712345678901\\",\n \\"line item ref\\" \\"10000001\\",\n \\"quantity\\" 2,\n \\"return reason\\" \\"wrong size\\",\n \\"child return reason\\" \\"too small\\",\n \\"adjustments\\" \[\n {\n \\"adjustment\\" {\n \\"amount\\" 7,\n \\"currency\\" \\"aud\\"\n },\n \\"description\\" \\"loyalty bonus\\"\n },\n {\n \\"adjustment\\" {\n \\"amount\\" 1,\n \\"currency\\" \\"aud\\"\n },\n \\"description\\" \\"missing packaging fee\\"\n }\n ],\n \\"compensation method\\" \\"refund\\"\n },\n {\n \\"merchant order ref\\" \\"5712345678901\\",\n \\"line item ref\\" \\"10000002\\",\n \\"quantity\\" 1,\n \\"return reason\\" \\"change of mind\\",\n \\"child return reason\\" null,\n \\"adjustments\\" \[],\n \\"compensation method\\" \\"exchange\\"\n }\n ],\n \\"return shipping\\" {\n \\"from address\\" {\n \\"address1\\" \\"89 york street\\",\n \\"address2\\" \\"901\\",\n \\"city\\" \\"sydney\\",\n \\"zip\\" \\"2030\\",\n \\"province\\" \\"new south wales\\",\n \\"country\\" \\"au\\"\n },\n \\"to address\\" {\n \\"address1\\" \\"1 warehouse way\\",\n \\"address2\\" \\"dock 4\\",\n \\"city\\" \\"melbourne\\",\n \\"zip\\" \\"3000\\",\n \\"province\\" \\"victoria\\",\n \\"country\\" \\"au\\"\n },\n \\"tracking\\" {\n \\"carrier\\" \\"australia post\\",\n \\"tracking number\\" \\"sk40010043214\\",\n \\"status\\" null,\n \\"status date\\" null\n },\n \\"deductions\\" {\n \\"amount\\" 10,\n \\"currency\\" \\"aud\\"\n }\n }\n}" } ], "selectedlanguageid" "miaebanlo793t30mvktwb" }, "request" { "pathparameters" \[], "queryparameters" \[ { "name" "merchant rma ref", "kind" "required", "type" "string", "description" "merchant generated unique rma id ", "children" \[] }, { "name" "key", "kind" "optional", "type" "string", "description" "merchant supplied privacy key for this return, echoed back if one was provided to refundid ", "children" \[] } ], "headerparameters" \[], "formdataparameters" \[], "bodydataparameters" \[] }, "currentnewparameter" { "label" "query parameter", "value" "queryparameters" }, "hastryitout" false, "autogeneratedanchorslug" "return", "legacyhash" "ngclparwrch qjpsjos9a" } refundid webhook body schema models # this api should be implemented by all merchants who wish to be notified whenever the status of an instant return has been updated by the refundid platform merchants are not required to implement this api if they do not wish to be notified of these updates currently, refundid invokes this api as an https post request on the following status changes status description refunding issued after refundid has obtained customer's bank account details and verified their identity, and is ready to deposit the refund into the customer's bank account merchant should respond with a 2xx (recommended 201) message to approve the refund, or a 4xx (recommended 403) message to reject it for example, a 4xx response should be used if a refund or exchange has been simultaneously issued to the customer by some other means, such as over the counter if the merchant approves the " refunding " message, they are responsible for not issuing the refund for this rma by any other means unless and until they receive a " closed " or " failed " status update for the same rma rejecting or cancelling the instant refund refundid issued after refundid has transferred funds to the customer's bank account, typically within minutes of the " refunding " message closed issued after the refundid rma has been finalised (accepted, rejected, or cancelled) by merchant, refundid, or customer the payload's " reconciliation breakdown " and per item " resolution " fields are populated at this point failed issued if, after receiving from the merchant a 2xx (approval) response to the " refunding " notification, refundid is unable to proceed with the rma for technical reasons (e g , deposit into the user's account fails ) this notification closes the refund, without issuing a " refundid " and " closed " for the same rma { "name" "refundid", "method" "post", "url" "https //{{merchant url}}/refundid", "description" "called by refundid to notify the merchant of an instant return status change respond with 2xx to acknowledge (or approve, for \\"refunding\\"), or 4xx to veto the body is a rapirefundidorder see the models page for the full field by field breakdown ", "tab" "examples", "examples" { "languages" \[ { "id" "rixgc9x5rnao4unw5l8zc", "language" "curl", "code" "curl location 'https //{{merchant url}}/refundid' \\\\\n header 'content type application/json' \\\\\n header 'date mon, 22 jun 2026 01 12 44 gmt' \\\\\n data '{\n \\"refundid id\\" \\"5175\\",\n \\"rma ref\\" \\"rma7123\\",\n \\"order number\\" \\"#re67803\\",\n \\"created at\\" \\"2026 06 20t09 33 50z\\",\n \\"merchant rma ref\\" null,\n \\"status\\" \\"refundid\\",\n \\"is flagged\\" false,\n \\"line items\\" \[\n {\n \\"merchant order ref\\" \\"7485848158455\\",\n \\"line item ref\\" \\"18984611741943\\",\n \\"quantity\\" 1,\n \\"price\\" {\n \\"amount\\" 295,\n \\"currency\\" \\"aud\\"\n },\n \\"tax detail\\" {\n \\"tax\\" {\n \\"amount\\" 26 82,\n \\"currency\\" \\"aud\\"\n },\n \\"tax included\\" true\n },\n \\"return reason\\" \\"changed of mind\\",\n \\"return reason notes\\" \[],\n \\"sku\\" \\"3i4ijcin\\",\n \\"product ref\\" \\"8123456789012\\",\n \\"variant ref\\" \\"44123456789012\\",\n \\"barcode\\" \\"bar3322\\",\n \\"child return reason\\" null,\n \\"resolution\\" null,\n \\"restock\\" false,\n \\"notes\\" null,\n \\"title\\" \\"anika asymmetrical maxi dress in green\\",\n \\"variant\\" \\"m\\",\n \\"image url\\" \\"https //cdn shopify com/s/files/1/0662/7721/2407/files/ec8042531cn sage 1 700x 7228f001 ad2a 4e55 bab1 3ab62eef4743 webp?v=1749102992\\"\n }\n ],\n \\"refund breakdown\\" {\n \\"subtotal\\" {\n \\"amount\\" 295,\n \\"currency\\" \\"aud\\"\n },\n \\"store return fee\\" {\n \\"amount\\" 0,\n \\"currency\\" \\"aud\\"\n },\n \\"customer shipping cost\\" {\n \\"amount\\" 10,\n \\"currency\\" \\"aud\\"\n },\n \\"total\\" {\n \\"amount\\" 285,\n \\"currency\\" \\"aud\\"\n }\n },\n \\"shipping label\\" {\n \\"tracking\\" {\n \\"carrier\\" \\"australia post\\",\n \\"tracking number\\" \\"111jd857139901000650805\\",\n \\"status\\" null,\n \\"status date\\" null\n },\n \\"purchase price\\" {\n \\"amount\\" 10 11,\n \\"currency\\" \\"aud\\"\n },\n \\"customer price\\" {\n \\"amount\\" 10,\n \\"currency\\" \\"aud\\"\n },\n \\"label url\\" \\"https //easypost files s3 us west 2 amazonaws com/files/postage label/20260320/e89577ac7ea0a548f6bb5afad829208bb4 pdf\\"\n },\n \\"reconciliation breakdown\\" null,\n \\"customer\\" {\n \\"email\\" \\"jane doe\@example com\\"\n }\n}'", "customlabel" "" } ], "selectedlanguageid" "rixgc9x5rnao4unw5l8zc" }, "results" { "languages" \[ { "id" "bnpr1y94outkeg1jmoegm", "language" "200", "customlabel" "", "code" "{\n \\"message\\" \\"success\\"\n}" } ], "selectedlanguageid" "bnpr1y94outkeg1jmoegm" }, "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[], "formdataparameters" \[], "bodydataparameters" \[ { "name" "refundid id", "kind" "required", "type" "string", "description" "the numeric id of the instant return, as a string use this value when calling the refundid provided apis (tracking, close refunds, note, flag) ", "children" \[] }, { "name" "rma ref", "kind" "required", "type" "string", "description" "the refundid rma reference shown in the merchant portal (e g rma7123) ", "children" \[] }, { "name" "order number", "kind" "required", "type" "string", "description" "the order number of the returned order ", "children" \[] }, { "name" "created at", "kind" "required", "type" "string", "description" "when the return was submitted by the customer, as an iso 8601 utc datetime (e g \\"2026 06 20t09 33 50z\\") ", "children" \[] }, { "name" "merchant rma ref", "kind" "optional", "type" "string", "description" "the merchant generated rma reference, if one was supplied for this return ", "children" \[] }, { "name" "status", "kind" "required", "type" "string", "description" "rapirefundidorderstatus one of \\"refunding\\", \\"refundid\\", \\"closed\\", \\"failed\\" (see the status table above) ", "children" \[] }, { "name" "is flagged", "kind" "required", "type" "boolean", "description" "whether the return is currently flagged in the merchant portal ", "children" \[] }, { "name" "line items", "kind" "required", "type" "array", "description" "list of rapirefundidorderlineitem the items being returned each entry carries merchant order ref, line item ref, quantity, price (rapiamount), tax detail, return reason, child return reason, return reason notes, sku, product ref, variant ref, barcode, title, variant, image url, plus resolution / restock / notes which are populated once the return is closed ", "children" \[] }, { "name" "refund breakdown", "kind" "required", "type" "object", "description" "rapirefundidbreakdown subtotal, store return fee, customer shipping cost and total (all rapiamount) the amount instantly refunded to the customer ", "children" \[] }, { "name" "shipping label", "kind" "optional", "type" "object", "description" "rapishippinglabel tracking (carrier, tracking number, status, status date), purchase price, customer price and label url null until a label or tracking is attached ", "children" \[] }, { "name" "reconciliation breakdown", "kind" "optional", "type" "object", "description" "rapireconciliationbreakdown populated on the \\"closed\\" notification describes who pays for the refunded items amount to reconcile from merchant / discounted amount to reconcile from merchant, shipping to reconcile from merchant, merchant advance adjustment, refundid cut / discounted refundid cut, invoice created at, closed by, closed on ", "children" \[] }, { "name" "customer", "kind" "required", "type" "object", "description" "rapicustomer the customer's email ", "children" \[] } ] }, "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" }, "hastryitout" false, "autogeneratedanchorslug" "refundid", "legacyhash" "36nelp1zdtytxsu0tppve" } standard returns webhook body schema models # this api should be implemented by all merchants who wish to be notified whenever the status of a standard returns rma has been updated by the refundid platform merchants are not required to implement this api if they do not wish to be notified of these updates please note, that this webhook will not provide updates on instant refunds as well you'll need to listen to the /refundid webhook above as well currently, refundid invokes this api as an https post request on the following status changes (the status field in the payload is uppercase) status description lodging issued when refundid is trying to lodge the return merchant should respond with a 2xx (recommended 201) message to approve the return lodgement, or a 4xx (recommended 403) message to reject it for example, a 4xx response should be used if a refund or exchange has been simultaneously issued to the customer by some other means, such as over the counter lodged issued after refundid has created the rma and officially lodged the selected items, typically within minutes of the " lodging " message closing issued after the refundid is trying to close the rma merchant should respond with a 2xx (recommended 201) message to approve the closing decision, or a 4xx (recommended 403) message to reject it closed issued after the refundid rma has been finalised (accepted, rejected, or cancelled) by merchant, refundid, or customer the payload's " close breakdown " and per item " resolution " fields are populated at this point failed issued to additional notification webhook endpoints if the standard return cannot be lodged this status is not sent to the primary rapi ecommerce endpoint { "name" "standard return", "method" "post", "url" "https //{{merchant url}}/standard return", "description" "called by refundid to notify the merchant of a standard return status change respond with 2xx to acknowledge (or approve, for \\"lodging\\" / \\"closing\\"), or 4xx to veto the body is a rapistandardreturn see the models page for the full field by field breakdown ", "tab" "examples", "examples" { "languages" \[ { "id" "rixgc9x5rnao4unw5l8zd", "language" "curl", "code" "curl location 'https //{{merchant url}}/standard return' \\\\\n header 'content type application/json' \\\\\n header 'date mon, 22 jun 2026 01 12 44 gmt' \\\\\n data '{\n \\"standard return id\\" \\"1949\\",\n \\"standard return encrypted id\\" \\"gaaaaabmhp ybgcgr 38v8cbhoswij5aliskh2apouen715xvbubc1chdfsnfnnu0vt bszfcxm0x0s5rl ovjccl7b6g lj9g==\\",\n \\"return resolution\\" \\"standard refund\\",\n \\"status\\" \\"lodged\\",\n \\"is flagged\\" false,\n \\"requested refund breakdown\\" {\n \\"subtotal\\" { \\"amount\\" 275 0, \\"currency\\" \\"aud\\" },\n \\"store return fee\\" { \\"amount\\" 0 0, \\"currency\\" \\"aud\\" },\n \\"customer shipping cost\\" { \\"amount\\" 10 0, \\"currency\\" \\"aud\\" },\n \\"total\\" { \\"amount\\" 265 0, \\"currency\\" \\"aud\\" }\n },\n \\"line items\\" \[\n {\n \\"merchant order ref\\" \\"7485848158455\\",\n \\"line item ref\\" \\"18984611709175\\",\n \\"quantity\\" 1,\n \\"price\\" { \\"amount\\" 275 0, \\"currency\\" \\"aud\\" },\n \\"tax detail\\" { \\"tax\\" { \\"amount\\" 25 0, \\"currency\\" \\"aud\\" }, \\"tax included\\" true },\n \\"return reason\\" \\"changed of mind\\",\n \\"return reason notes\\" \[],\n \\"sku\\" \\"42312\\",\n \\"product ref\\" \\"8123456789012\\",\n \\"variant ref\\" \\"44123456789014\\",\n \\"barcode\\" \\"\\",\n \\"child return reason\\" null,\n \\"resolution\\" null,\n \\"restock\\" false,\n \\"notes\\" null,\n \\"title\\" \\"anika asymmetrical maxi dress in green\\",\n \\"variant\\" \\"l\\",\n \\"image url\\" \\"https //cdn shopify com/s/files/1/0662/7721/2407/files/ec8042531cn sage 1 700x 7228f001 ad2a 4e55 bab1 3ab62eef4743 webp?v=1749102992\\"\n }\n ],\n \\"rma ref\\" \\"rma7122\\",\n \\"order number\\" \\"#re67803\\",\n \\"created at\\" \\"2026 06 20t09 33 50z\\",\n \\"estimated order to store currency exchange rate\\" {\n \\"from currency\\" \\"aud\\",\n \\"to currency\\" \\"aud\\",\n \\"exchange rate\\" 1 0\n },\n \\"shipping label\\" {\n \\"tracking\\" {\n \\"carrier\\" \\"australia post\\",\n \\"tracking number\\" \\"111jd857139001000650802\\",\n \\"status\\" null,\n \\"status date\\" null\n },\n \\"purchase price\\" { \\"amount\\" 10 11, \\"currency\\" \\"aud\\" },\n \\"customer price\\" { \\"amount\\" 10 0, \\"currency\\" \\"aud\\" },\n \\"label url\\" \\"https //easypost files s3 us west 2 amazonaws com/files/postage label/20260320/e82625118d342f44369334710f5898fe6b pdf\\"\n },\n \\"close breakdown\\" null,\n \\"exchange\\" null,\n \\"customer\\" {\n \\"email\\" \\"jane doe\@example com\\"\n }\n}'", "customlabel" "" } ], "selectedlanguageid" "rixgc9x5rnao4unw5l8zd" }, "results" { "languages" \[ { "id" "bnpr1y94outkeg1jmoegn", "language" "200", "customlabel" "", "code" "{\n \\"message\\" \\"success\\"\n}" } ], "selectedlanguageid" "bnpr1y94outkeg1jmoegn" }, "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[], "formdataparameters" \[], "bodydataparameters" \[ { "name" "standard return id", "kind" "required", "type" "string", "description" "the numeric id of the standard return, as a string use this value when calling the refundid provided apis (tracking, close refunds, note, flag) ", "children" \[] }, { "name" "standard return encrypted id", "kind" "required", "type" "string", "description" "an encrypted, hard to guess version of the same id, suitable for embedding in customer facing urls ", "children" \[] }, { "name" "return resolution", "kind" "required", "type" "string", "description" "the internal name of the standard resolution the customer selected (e g store credit, standard refund) ", "children" \[] }, { "name" "status", "kind" "required", "type" "string", "description" "rapistandardreturnstatus one of \\"lodging\\", \\"lodged\\", \\"closing\\", \\"closed\\", \\"failed\\" (see the status table above) ", "children" \[] }, { "name" "is flagged", "kind" "required", "type" "boolean", "description" "whether the return is currently flagged in the merchant portal ", "children" \[] }, { "name" "requested refund breakdown", "kind" "required", "type" "object", "description" "rapirefundidbreakdown subtotal, store return fee, customer shipping cost and total (all rapiamount) the refund amount requested by the customer ", "children" \[] }, { "name" "line items", "kind" "required", "type" "array", "description" "list of rapirefundidorderlineitem the items being returned same structure as the /refundid webhook merchant order ref, line item ref, quantity, price, tax detail, return reason, child return reason, return reason notes, sku, product ref, variant ref, barcode, title, variant, image url, plus resolution / restock / notes which are populated once the return is closed ", "children" \[] }, { "name" "rma ref", "kind" "required", "type" "string", "description" "the refundid rma reference shown in the merchant portal (e g rma7122) ", "children" \[] }, { "name" "order number", "kind" "required", "type" "string", "description" "the order number of the returned order ", "children" \[] }, { "name" "created at", "kind" "required", "type" "string", "description" "when the return was submitted by the customer, as an iso 8601 utc datetime (e g \\"2026 06 20t09 33 50z\\") ", "children" \[] }, { "name" "estimated order to store currency exchange rate", "kind" "optional", "type" "object", "description" "rapicurrencyexchangerate from currency, to currency, exchange rate the estimated conversion rate used when the order currency differs from the store's base currency; null otherwise ", "children" \[] }, { "name" "shipping label", "kind" "optional", "type" "object", "description" "rapishippinglabel tracking (carrier, tracking number, status, status date), purchase price, customer price and label url null until a label or tracking is attached ", "children" \[] }, { "name" "close breakdown", "kind" "optional", "type" "object", "description" "rapistandardreturnclosebreakdown populated on the \\"closed\\" notification contains final refund amount, outbound shipping refund amount (the portion of the final refund reimbursing the original order's outbound shipping, when applicable), closed on, closed by (\\"merchant\\" or \\"refundid\\") and refunds (a list of {refund method ref, amount} showing how the refund was paid out) ", "children" \[] }, { "name" "exchange", "kind" "optional", "type" "object", "description" "rapiexchange present when the return includes an exchange / shop now purchase contains purchase request id, status (ready, purchasing, purchased, voided), expected shipping price, purchase request total value, customer invoice amount, the customer's delivery details (fname, lname, email, phone, shipping address), line items (rapiexchangeitem list), draft order ref, shipping rate ref, shipping rate title, and order name / order ref once the exchange order has been purchased see the models page for full details ", "children" \[] }, { "name" "customer", "kind" "required", "type" "object", "description" "rapicustomer the customer's email ", "children" \[] } ] }, "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" }, "hastryitout" false, "autogeneratedanchorslug" "standard return", "legacyhash" "z8enk1bs gnr2ptpqkyra" } shipping webhooks (label provider integrations) the following four webhooks are only relevant for merchants who act as their own shipping label provider i e refundid requests shipping rates and purchases return labels through the merchant's system instead of a refundid managed carrier account most merchants do not need to implement these if you are interested in this integration, please contact integrations\@refundid com mailto\ integrations\@refundid com all four are invoked as https post requests with the standard security headers described above, plus a shared secret passed as a query parameter ( secret for rates, label purchase and tracking status; key for cancellation), configured with refundid during setup shipping rates webhook refundid calls this to fetch available return shipping rates for a parcel before purchasing a label the body contains from address / to address (rapiaddress), sender details / recipient details ({name, email, phone}), parcel ({weight, weight unit (kg|lb|oz|g), length, width, height, dimension unit (cm|in)}), line items the items contained in the parcel (see rapishippinglineitem docid s7ltpxiqkmcxgkxmzpjs ), customer reference , an optional customs declaration for international shipments, settings ({is return, expected label purchase price currency}) and shipper refs the carrier account references to quote against respond with a json array of rates each rate contains purchase price (rapiamount), carrier , service type , shipper ref (the carrier account the rate belongs to), an optional rate id and shipment id (echoed back on purchase), phone number required , and optional pickup options ( {instructions enabled, ranges \[{start, end}]} ) { "name" "shipping rates", "method" "post", "url" "https //{{merchant url}}/shipping rates", "description" "called by refundid to fetch available return shipping rates respond with 200 and a json array of rates ", "tab" "examples", "examples" { "languages" \[ { "id" "shiprateswh0000000001", "language" "curl", "code" "curl location 'https //{{merchant url}}/shipping rates?secret={{shared secret}}' \\\\\n header 'content type application/json' \\\\\n header 'date mon, 22 jun 2026 01 12 44 gmt' \\\\\n data '{\n \\"from address\\" {\n \\"address1\\" \\"89 york street\\",\n \\"address2\\" \\"901\\",\n \\"city\\" \\"sydney\\",\n \\"zip\\" \\"2030\\",\n \\"province\\" \\"nsw\\",\n \\"country\\" \\"australia\\",\n \\"country code\\" \\"au\\"\n },\n \\"to address\\" {\n \\"address1\\" \\"1 warehouse way\\",\n \\"address2\\" null,\n \\"city\\" \\"melbourne\\",\n \\"zip\\" \\"3000\\",\n \\"province\\" \\"vic\\",\n \\"country\\" \\"australia\\",\n \\"country code\\" \\"au\\"\n },\n \\"sender details\\" {\n \\"name\\" \\"jane doe\\",\n \\"email\\" \\"jane doe\@example com\\",\n \\"phone\\" \\"+61400123456\\"\n },\n \\"recipient details\\" {\n \\"name\\" \\"acme apparel returns\\",\n \\"email\\" \\"returns\@acmeapparel com\\",\n \\"phone\\" \\"+61390001111\\"\n },\n \\"parcel\\" {\n \\"weight\\" 1 2,\n \\"weight unit\\" \\"kg\\",\n \\"length\\" 30,\n \\"width\\" 22,\n \\"height\\" 8,\n \\"dimension unit\\" \\"cm\\"\n },\n \\"line items\\" \[\n {\n \\"merchant order ref\\" \\"5678901234567\\",\n \\"line item ref\\" \\"4514319237351\\",\n \\"quantity\\" 1,\n \\"weight\\" 0 25,\n \\"weight unit\\" \\"kg\\",\n \\"title\\" \\"classic crew tee\\",\n \\"variant\\" \\"navy / m\\",\n \\"sku\\" \\"tee nvy m\\",\n \\"product ref\\" \\"7234567890123\\",\n \\"variant ref\\" \\"4514319237351\\",\n \\"barcode\\" \\"9312345678907\\"\n }\n ],\n \\"customer reference\\" \\"rma10425\\",\n \\"customs declaration\\" null,\n \\"settings\\" {\n \\"is return\\" true,\n \\"expected label purchase price currency\\" \\"aud\\"\n },\n \\"shipper refs\\" \[\\"acme auspost 1\\"]\n}'", "customlabel" "" } ], "selectedlanguageid" "shiprateswh0000000001" }, "results" { "languages" \[ { "id" "shiprateswh0000000002", "language" "200", "customlabel" "", "code" "\[\n {\n \\"purchase price\\" { \\"amount\\" 9 5, \\"currency\\" \\"aud\\" },\n \\"carrier\\" \\"australiapost\\",\n \\"service type\\" \\"parcelpost\\",\n \\"shipper ref\\" \\"acme auspost 1\\",\n \\"rate id\\" \\"rate 01hxyz\\",\n \\"shipment id\\" \\"shp 01hxyz\\",\n \\"phone number required\\" false,\n \\"pickup\\" null\n },\n {\n \\"purchase price\\" { \\"amount\\" 13 2, \\"currency\\" \\"aud\\" },\n \\"carrier\\" \\"australiapost\\",\n \\"service type\\" \\"expresspost\\",\n \\"shipper ref\\" \\"acme auspost 1\\",\n \\"rate id\\" \\"rate 01hxza\\",\n \\"shipment id\\" \\"shp 01hxyz\\",\n \\"phone number required\\" false,\n \\"pickup\\" {\n \\"instructions enabled\\" true,\n \\"ranges\\" \[\n { \\"start\\" \\"2026 06 23t09 00 00z\\", \\"end\\" \\"2026 06 23t17 00 00z\\" }\n ]\n }\n }\n]" } ], "selectedlanguageid" "shiprateswh0000000002" }, "request" { "pathparameters" \[], "queryparameters" \[ { "name" "secret", "kind" "required", "type" "string", "description" "the shared secret configured with refundid for this integration ", "children" \[] } ], "headerparameters" \[], "formdataparameters" \[], "bodydataparameters" \[ { "name" "(body)", "kind" "required", "type" "object", "description" "rapishippingratesrequest see the section text above and the models page for the field by field breakdown ", "children" \[] } ] }, "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" }, "hastryitout" false, "autogeneratedanchorslug" "shipping rates", "legacyhash" "7oxefz2fgm0wojv4j5yt " } purchase shipping label webhook refundid calls this to purchase a return shipping label, usually using a rate id / shipment id returned by the shipping rates webhook the body is the same base structure as the rates request plus carrier , service type , shipper ref , rate id , shipment id and an optional pickup request ( {range {start, end}, instructions} ) respond with the purchased label purchase price (rapiamount), label id (your unique reference for the label used for cancellation), label (either {label b64} with a base64 encoded pdf or {label url} with a link to the pdf), tracking number , from location / to location (rapiaddress), carrier , service type , and optionally pickup options ( {pickup id, range, instructions} ), commercial invoice url , from location timezone and barcode url { "name" "shipping label", "method" "post", "url" "https //{{merchant url}}/shipping label", "description" "called by refundid to purchase a return shipping label respond with 200 and the purchased label details ", "tab" "examples", "examples" { "languages" \[ { "id" "shiplabelwh0000000001", "language" "curl", "code" "curl location 'https //{{merchant url}}/shipping label?secret={{shared secret}}' \\\\\n header 'content type application/json' \\\\\n header 'date mon, 22 jun 2026 01 12 44 gmt' \\\\\n data '{\n \\"from address\\" { \\"address1\\" \\"89 york street\\", \\"address2\\" \\"901\\", \\"city\\" \\"sydney\\", \\"zip\\" \\"2030\\", \\"province\\" \\"nsw\\", \\"country\\" \\"australia\\", \\"country code\\" \\"au\\" },\n \\"to address\\" { \\"address1\\" \\"1 warehouse way\\", \\"address2\\" null, \\"city\\" \\"melbourne\\", \\"zip\\" \\"3000\\", \\"province\\" \\"vic\\", \\"country\\" \\"australia\\", \\"country code\\" \\"au\\" },\n \\"sender details\\" { \\"name\\" \\"jane doe\\", \\"email\\" \\"jane doe\@example com\\", \\"phone\\" \\"+61400123456\\" },\n \\"recipient details\\" { \\"name\\" \\"acme apparel returns\\", \\"email\\" \\"returns\@acmeapparel com\\", \\"phone\\" \\"+61390001111\\" },\n \\"parcel\\" { \\"weight\\" 1 2, \\"weight unit\\" \\"kg\\", \\"length\\" 30, \\"width\\" 22, \\"height\\" 8, \\"dimension unit\\" \\"cm\\" },\n \\"line items\\" \[ { \\"merchant order ref\\" \\"5678901234567\\", \\"line item ref\\" \\"4514319237351\\", \\"quantity\\" 1, \\"weight\\" 0 25, \\"weight unit\\" \\"kg\\", \\"title\\" \\"classic crew tee\\", \\"variant\\" \\"navy / m\\", \\"sku\\" \\"tee nvy m\\", \\"product ref\\" \\"7234567890123\\", \\"variant ref\\" \\"4514319237351\\", \\"barcode\\" \\"9312345678907\\" } ],\n \\"customer reference\\" \\"rma10425\\",\n \\"customs declaration\\" null,\n \\"settings\\" { \\"is return\\" true, \\"expected label purchase price currency\\" \\"aud\\" },\n \\"carrier\\" \\"australiapost\\",\n \\"service type\\" \\"parcelpost\\",\n \\"shipper ref\\" \\"acme auspost 1\\",\n \\"rate id\\" \\"rate 01hxyz\\",\n \\"shipment id\\" \\"shp 01hxyz\\",\n \\"pickup request\\" null\n}'", "customlabel" "" } ], "selectedlanguageid" "shiplabelwh0000000001" }, "results" { "languages" \[ { "id" "shiplabelwh0000000002", "language" "200", "customlabel" "", "code" "{\n \\"purchase price\\" { \\"amount\\" 9 5, \\"currency\\" \\"aud\\" },\n \\"label id\\" \\"lbl 01hxyz\\",\n \\"label\\" { \\"label url\\" \\"https //labels acmeapparel com/lbl 01hxyz pdf\\" },\n \\"tracking number\\" \\"33abc1234567\\",\n \\"from location\\" { \\"address1\\" \\"89 york street\\", \\"address2\\" \\"901\\", \\"city\\" \\"sydney\\", \\"zip\\" \\"2030\\", \\"province\\" \\"nsw\\", \\"country\\" \\"australia\\", \\"country code\\" \\"au\\" },\n \\"to location\\" { \\"address1\\" \\"1 warehouse way\\", \\"address2\\" null, \\"city\\" \\"melbourne\\", \\"zip\\" \\"3000\\", \\"province\\" \\"vic\\", \\"country\\" \\"australia\\", \\"country code\\" \\"au\\" },\n \\"carrier\\" \\"australiapost\\",\n \\"service type\\" \\"parcelpost\\",\n \\"pickup options\\" null,\n \\"commercial invoice url\\" null,\n \\"from location timezone\\" \\"australia/sydney\\",\n \\"barcode url\\" null\n}" } ], "selectedlanguageid" "shiplabelwh0000000002" }, "request" { "pathparameters" \[], "queryparameters" \[ { "name" "secret", "kind" "required", "type" "string", "description" "the shared secret configured with refundid for this integration ", "children" \[] } ], "headerparameters" \[], "formdataparameters" \[], "bodydataparameters" \[ { "name" "(body)", "kind" "required", "type" "object", "description" "rapipurchaseshippinglabelrequest see the section text above and the models page for the field by field breakdown ", "children" \[] } ] }, "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" }, "hastryitout" false, "autogeneratedanchorslug" "shipping label", "legacyhash" "rgtzr9a2xe4bc4qapuzaq" } cancel shipping label webhook refundid calls this to cancel a previously purchased label (e g when a return is cancelled before shipment) the body identifies the label by the label id your system returned when the label was purchased respond with any 2xx status to confirm the cancellation { "name" "cancel shipping label", "method" "post", "url" "https //{{merchant url}}/cancel shipping label", "description" "called by refundid to cancel a previously purchased shipping label respond with 2xx to confirm ", "tab" "examples", "examples" { "languages" \[ { "id" "shipcancelwh000000001", "language" "curl", "code" "curl location 'https //{{merchant url}}/cancel shipping label?key={{shared secret}}' \\\\\n header 'content type application/json' \\\\\n header 'date mon, 22 jun 2026 01 12 44 gmt' \\\\\n data '{\n \\"label id\\" \\"lbl 01hxyz\\"\n}'", "customlabel" "" } ], "selectedlanguageid" "shipcancelwh000000001" }, "results" { "languages" \[ { "id" "shipcancelwh000000002", "language" "200", "customlabel" "", "code" "{ \\"message\\" \\"success\\" }" } ], "selectedlanguageid" "shipcancelwh000000002" }, "request" { "pathparameters" \[], "queryparameters" \[ { "name" "key", "kind" "required", "type" "string", "description" "the shared secret configured with refundid for this integration ", "children" \[] } ], "headerparameters" \[], "formdataparameters" \[], "bodydataparameters" \[ { "name" "label id", "kind" "required", "type" "string", "description" "the label id your system returned when the label was purchased ", "children" \[] } ] }, "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" }, "hastryitout" false, "autogeneratedanchorslug" "cancel shipping label", "legacyhash" "4nizrgzzh2fy6lr6obzkv" } shipping tracking status webhook refundid calls this periodically to refresh the tracking status of labels purchased through your system the body is a json array of {tracking number, carrier} pairs respond with a json array of statuses one entry per tracking number you have information for each entry contains tracking number , status (one of not shipped yet, transit, delivered, maybe delivered, failure, unknown), an optional status date , and optional raw carrier fields source status , source substatus and source status details for diagnostics { "name" "shipping tracking status", "method" "post", "url" "https //{{merchant url}}/shipping tracking status", "description" "called by refundid to refresh tracking statuses for labels purchased through your system respond with 200 and a json array of statuses ", "tab" "examples", "examples" { "languages" \[ { "id" "shiptrackwh0000000001", "language" "curl", "code" "curl location 'https //{{merchant url}}/shipping tracking status?secret={{shared secret}}' \\\\\n header 'content type application/json' \\\\\n header 'date mon, 22 jun 2026 01 12 44 gmt' \\\\\n data '\[\n { \\"tracking number\\" \\"33abc1234567\\", \\"carrier\\" \\"australiapost\\" },\n { \\"tracking number\\" \\"33abc7654321\\", \\"carrier\\" \\"australiapost\\" }\n]'", "customlabel" "" } ], "selectedlanguageid" "shiptrackwh0000000001" }, "results" { "languages" \[ { "id" "shiptrackwh0000000002", "language" "200", "customlabel" "", "code" "\[\n {\n \\"tracking number\\" \\"33abc1234567\\",\n \\"status\\" \\"transit\\",\n \\"status date\\" \\"2026 06 22t03 15 00z\\",\n \\"source status\\" \\"in transit\\",\n \\"source substatus\\" null,\n \\"source status details\\" null\n },\n {\n \\"tracking number\\" \\"33abc7654321\\",\n \\"status\\" \\"delivered\\",\n \\"status date\\" \\"2026 06 21t23 40 00z\\",\n \\"source status\\" \\"delivered\\",\n \\"source substatus\\" \\"left in a safe place\\",\n \\"source status details\\" null\n }\n]" } ], "selectedlanguageid" "shiptrackwh0000000002" }, "request" { "pathparameters" \[], "queryparameters" \[ { "name" "secret", "kind" "required", "type" "string", "description" "the shared secret configured with refundid for this integration ", "children" \[] } ], "headerparameters" \[], "formdataparameters" \[], "bodydataparameters" \[ { "name" "(body)", "kind" "required", "type" "array", "description" "a json array of { \\"tracking number\\" string, \\"carrier\\" string } pairs to look up ", "children" \[] } ] }, "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" }, "hastryitout" false, "autogeneratedanchorslug" "shipping tracking status", "legacyhash" "ckzf5zps1xuj9ac5md8el" }