{"openapi":"3.0.0","info":{"title":"Code Returns & Exchanges API","description":"Provides endpoints on which to post status updates towards the Returns & Exchanges app.","termsOfService":"https://apps.support.code.nl/hc/en-us/sections/4958812658833-Code-Returns-Exchanges","version":"0.1.0"},"servers":[{"url":"https://europe-west1-code-rma-app.cloudfunctions.net/api","description":"This instance."}],"components":{"schemas":{"EventOutput":{"description":"Schema of the body for outgoing event webhooks. Contact Code on how to connect to our outgoing webhooks.","type":"object","properties":{"timestamp":{"description":"The time the webhook fired for the first time.","format":"date-time","type":"string"},"rmaReference":{"description":"Name of the RMA.","type":"string"},"rmaProvider":{"description":"Name of the RMA provider if known.","type":"string"},"returnInfo":{"type":"object","properties":{"handler":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"type":"string"},"company":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"type":"string"},"name":{"type":"string"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"postalCode":{"type":"string"},"state":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["handler","addressLine1","addressLine2","city","company","country","name","phone","postalCode","state"]},"type":{"description":"The event this webhook was fired for.","anyOf":[{"description":"The request is submitted to the RMA application.","const":"submitted","type":"string"},{"description":"The shipping provider has received the package from the customer and it's on its way.","const":"shipping","type":"string"},{"description":"An additional payment is awaited.","const":"payment-pending","type":"string"},{"description":"The package has been received by the 3PL.","const":"returned","type":"string"},{"description":"The RMA is processed in the application. Note that there might still be a delayed processing error.","const":"processed","type":"string"},{"description":"A delayed error occurred and the RMA might not be processed properly.","const":"processing-error","type":"string"},{"description":"An exchange is created for the RMA.","const":"exchange-created","type":"string"}]},"customer":{"examples":["Jan Jansen"],"type":"string"},"customerNote":{"examples":["I love your brand!"],"type":"string"},"adminNote":{"examples":["Should send discount code."],"type":"string"},"originalOrder":{"type":"object","properties":{"id":{"description":"The Shopify order number.","type":"number"},"name":{"description":"The Shopify order name.","type":"string"},"shippingCountry":{"description":"A human readable name of the country the order was shipped to.","examples":["The Netherlands"],"type":"string"},"shippingCountryCode":{"description":"The two letter (ISO 3166-1 alpha-2) country code of the country the order was shipped to.","type":"string"}},"required":["id","name","shippingCountry","shippingCountryCode"]},"exchangeOrder":{"type":"object","properties":{"id":{"description":"The Shopify order number.","type":"number"},"name":{"description":"The Shopify order name.","type":"string"},"shippingCountry":{"description":"A human readable name of the country the order was shipped to.","examples":["The Netherlands"],"type":"string"},"shippingCountryCode":{"description":"The two letter (ISO 3166-1 alpha-2) country code of the country the order was shipped to.","type":"string"}},"required":["id","name","shippingCountry","shippingCountryCode"]},"flagReasons":{"type":"array","items":{"type":"string"}},"timeline":{"type":"object","properties":{"orderCreatedAt":{"anyOf":[{"type":"null"},{"type":"string"}]},"rmaSubmittedAt":{"anyOf":[{"type":"null"},{"type":"string"}]},"rmaShippedAt":{"anyOf":[{"type":"null"},{"type":"string"}]},"rmaPaymentPendingAt":{"anyOf":[{"type":"null"},{"type":"string"}]},"rmaReturnedAt":{"anyOf":[{"type":"null"},{"type":"string"}]},"rmaProcessedAt":{"anyOf":[{"type":"null"},{"type":"string"}]}},"required":["orderCreatedAt","rmaSubmittedAt","rmaShippedAt","rmaPaymentPendingAt","rmaReturnedAt","rmaProcessedAt"]},"status":{"type":"object","properties":{"isSubmitted":{"type":"boolean"},"isUnprocessable":{"type":"boolean"},"isShipping":{"type":"boolean"},"isReturned":{"type":"boolean"},"isPaymentPending":{"type":"boolean"},"isProcessed":{"type":"boolean"},"hasError":{"type":"boolean"},"hasFlag":{"type":"boolean"}},"required":["isSubmitted","isUnprocessable","isShipping","isReturned","isPaymentPending","isProcessed","hasError","hasFlag"]},"rmaItems":{"type":"array","items":{"type":"object","properties":{"returned":{"type":"boolean"},"type":{"anyOf":[{"const":"exchange","type":"string"},{"const":"return","type":"string"}]},"returnProduct":{"type":"object","properties":{"lineItemId":{"type":"number"},"productId":{"type":"number"},"productTitle":{"type":"string"},"variantId":{"type":"number"},"variantTitle":{"type":"string"},"sku":{"type":"string"}},"required":["productId","productTitle","variantId","variantTitle","sku"]},"exchangeProduct":{"type":"object","properties":{"productId":{"type":"number"},"productTitle":{"type":"string"},"variantId":{"type":"number"},"variantTitle":{"type":"string"},"sku":{"type":"string"}},"required":["productId","productTitle","variantId","variantTitle","sku"]},"returnCondition":{"type":"string"},"reasons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"}},"required":["id","label"]}}},"required":["returned","type","reasons"]}},"returnHandlerData":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"returnDate":{"description":"The date the item was returned","type":"string"},"externalOrderNumber":{"description":"The ID of the RMA in Returner","type":"string"},"sku":{"type":"string"},"quantity":{"type":"number"},"type":{"type":"string"},"returnReasonId":{"type":"number"},"returnReason":{"type":"string"},"comment":{"type":"string"},"afterCare":{"type":"string"},"porti":{"type":"string"},"reDeliver":{"type":"boolean"},"orderType":{"type":"string"}},"required":["id","returnDate","externalOrderNumber","sku","quantity","type","returnReasonId","returnReason","comment","afterCare","porti","reDeliver","orderType"]}}},"required":["timestamp","rmaReference","type","customer","originalOrder","timeline","status","rmaItems"]}},"requestBodies":{"EventInput":{"type":"object","allOf":[{"type":"object","properties":{"timestamp":{"format":"date-time","type":"string"}},"required":["timestamp"]},{"type":"object","properties":{"type":{"description":"Currently only 'received' is supported.","const":"received","type":"string"},"rmaReference":{"description":"Name of the RMA. Need either `orderName` or this.","type":"string"},"orderName":{"description":"Name of the Order. Need either `rmaReference` or this.","type":"string"},"problem":{"description":"If not empty, this request will be flagged by the application, prohibiting automatic handling.","type":"string"},"returnToSender":{"description":"If true, the item will be marked as 'return to sender'.","type":"boolean"},"rmaRegistered":{"description":"If false, the return was not registered and adjustments still have to be calculated.","anyOf":[{"type":"boolean"},{"type":"null"}]},"flags":{"type":"array","items":{"type":"string"}},"rmaItems":{"type":"array","items":{"type":"object","properties":{"barcode":{"type":"string"},"sku":{"type":"string"},"quantity":{"type":"number"},"comment":{"type":"array","items":{"description":"Comment for this item. Any returns with comments will be flagged.","type":"string"}},"damaged":{"type":"array","items":{"type":"boolean"}},"reasonIds":{"type":"array","items":{"type":"array","items":{"description":"Any reasons this item is being returned that can be determined from the 3PL side, such as return-to-sender and damaged","type":"string"}}}},"required":["quantity"]}},"idsToUnDoAdjustments":{"type":"array","items":{"type":"number"}},"audit":{"type":"object","properties":{"email":{"type":"string"}},"required":["email"]}},"required":["type","rmaItems"]}]}},"securitySchemes":{"jwtAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"ShopDomainAuth":{"type":"apiKey","in":"header","name":"x-shopify-shop-domain","description":"The Shopify store .myshopify.com URL."}}},"security":[{"jwtAuth":[]}],"paths":{"/event":{"post":{"security":[{"jwtAuth":[]}],"description":"Post one of the predefined events to the Code Returns & Exchanges app.","parameters":[{"required":false,"schema":{"description":"The shop this request is for. This is your shopify url, e.g.: 'test.myshopify.com'.","type":"string"},"in":"header","name":"rma-shop-domain"},{"required":false,"schema":{"description":"The HMAC calculated for this request (in hex).","type":"string"},"in":"header","name":"rma-hmac-sha"},{"required":false,"schema":{"description":"The shop this request is for. This is your shopify url, e.g.: 'test.myshopify.com'.","type":"string"},"in":"query","name":"shop"},{"required":false,"schema":{"description":"The HMAC calculated for this request (in hex).","type":"string"},"in":"query","name":"hmac"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/requestBodies/EventInput"}}}},"responses":{"200":{"description":"Successfully processed event!"},"400":{"description":"A validation issue."}}}},"/search":{"get":{"security":[{"jwtAuth":[]}],"description":"Search in your order and RMA combinations.","parameters":[{"required":false,"schema":{"description":"An RMA to search for. This is the RMA number, e.g.: 'CODE-0001-R1'. Exact matching is required.","type":"string"},"in":"query","name":"rma"},{"required":false,"schema":{"description":"An order to search for. This is the Order name, e.g.: 'CODE-0001'. Exact matching is required.","type":"string"},"in":"query","name":"order"},{"required":false,"schema":{"description":"A tracking code to search for. This is the tracking code, e.g.: '3SABCD1234567'. Exact matching is required.","type":"string"},"in":"query","name":"trackingCode"},{"required":false,"schema":{"description":"The shop this request is for. This is your shopify url, e.g.: 'test.myshopify.com'.","type":"string"},"in":"header","name":"rma-shop-domain"},{"required":false,"schema":{"description":"The HMAC calculated for this request (in hex).","type":"string"},"in":"header","name":"rma-hmac-sha"},{"required":false,"schema":{"description":"The shop this request is for. This is your shopify url, e.g.: 'test.myshopify.com'.","type":"string"},"in":"query","name":"shop"},{"required":false,"schema":{"description":"The HMAC calculated for this request (in hex).","type":"string"},"in":"query","name":"hmac"}],"responses":{"200":{"description":"Succesfully found all RMAs and orders!"},"400":{"description":"A validation issue."}}}},"/requests/{rmaRequestId}/handle-and-process":{"post":{"security":[{"jwtAuth":[],"ShopDomainAuth":[]}],"tags":["RMA Requests"],"parameters":[{"in":"path","name":"rmaRequestId","schema":{"type":"string"},"required":true,"description":"ID of the RMA Request that is to be authorized."}],"description":"Authorize a the completion and refund of an RMA.  This is the equivalent of the handle & process button in the admin interface.","responses":{"200":{"description":"Successfully triggered handle and process of RMA request."},"400":{"description":"A validation issue."},"404":{"description":"RMA Request was not found"}}}},"/requests/{rmaRequestId}/mark-processed":{"post":{"security":[{"jwtAuth":[],"ShopDomainAuth":[]}],"tags":["RMA Requests"],"parameters":[{"in":"path","name":"rmaRequestId","schema":{"type":"string"},"required":true,"description":"ID of the RMA Request that should be marked as processed."}],"description":"This is the equivalent of the 'Mark as Processed' button in the admin interface.  Use this when the return is manually handled and you do not wish to issue a refund.","responses":{"200":{"description":"Successfully triggered marked RMA Request as processed."},"400":{"description":"A validation issue."},"404":{"description":"RMA Request was not found"}}}}}}