Returns

## Sections
• [Introduction](https://app.theneo.io/nshiftone/returns/getting-started.md): Welcome to the nShift Returns API documentation. This guide will help you integrate with nShift Returns. The Returns API allows you to automate and control the full returns lifecycle - from creating return requests to monitoring their status and outcomes. With the API, you can streamline returns operations, reduce manual handling, and keep your systems in sync with real-time return data. In this documentation, you’ll learn how to authenticate, make API requests, create and manage returns. Using the API Swagger specification We provide HTTP endpoints with Swagger documentation, available for both Production and Staging. Production | Staging Environments We provide a Staging an Production environment. The nShift Returns API is organized around REST and designed to integrate seamlessly with your existing systems. All endpoints are accessible only via HTTPS. Documentation This technical documentation is intended for developers. For user guides and instructions on how to configure and use the product, see the nShift Help Center – Returns .
  • [Sign-Up](https://app.theneo.io/nshiftone/returns/getting-started/data-types-and-formats-copy.md): To start using nShift Returns, submit a request through our contact form . A member of the nShift team will get in touch with you to guide you through the next steps. Once your account has been set up, you will receive access to the nShift Returns Portal , where you can configure and manage your returns.
  • [Authentication](https://app.theneo.io/nshiftone/returns/getting-started/authentication.md): Authenication in nShift Returns uses Basic Authentication using a username and password. You create and manage your API keys in the nShift Returns admin. Multiple API keys can be created as needed, making it easy to separate access across environments or integrations Important: Keep API-keys confidential. Never embed them in client-side code. Generate API-keys 1 Log into nShift Returns Admin 2 Go to Settings → Credentials → Create Credentials 3 Enter a username → Create The username needs to be unique within your account. 4 Credentials created A password will be created for you. Please make sure to copy and save it, as you will not be able to see or retrieve it again. You will be able to click Close after you have copied the password. 5 Overview You will now see the user on the list. You can create as many users as you need. If you forget a user's password, you can simply delete that user and create a new one. Delete keys In addition to creating API keys, you can also delete them from this view. Please note that deleted keys are permanently removed and cannot be recovered. Using the API-key Authentication credentials are sent with every request and are validated by the server. If the credentials are missing or invalid, the API will respond with a 401 Unauthorized status code.
  • [Data Types and Formats](https://app.theneo.io/nshiftone/returns/getting-started/data-types-and-formats.md): If not specified in the different services, refer to this table Date & Time Timestamps use ISO 8601 extended format. Example : 202x-xx-xxT00:00:00Z Locale Locales should be formatted as IETF BCP 47 language tags = ISO-639 language code + ISO-3166-1 alpha-2 country code (e.g. en-US , fr-FR , ja-JP ). Plain text "locale": "sv-SE", Country Country code = Standard ISO-3166-1 alpha-2 (e.g. US , FR , JP ). Currency Code We use the Standard ISO-4217 standard for defining currencies. Plain text "currency": "SEK", Amount Numeric value represented as a decimal number . Plain text "amount": 8.5
• [Order - PUSH API](https://app.theneo.io/nshiftone/returns/api-v-3-push-api-controller.md): Our Order endpoints are used to push order data towards our API. We support the following methods: Consolidated Data Submission With the Store Orders Consolidated option, all related data such as customers, products, and orders is submitted in a single request. This method is our recommended approach. Individual Data Submission Alternatively, data can be submitted through separate endpoints: Store orders Store customers Store products Orders act as the connecting element, linking products to their respective customers. Choose the submission method that best fits your workflow and integration needs.
  • [Store orders consolidated](https://app.theneo.io/nshiftone/returns/api-v-3-push-api-controller/store-orders-consolidated.md): This endpoint lets you push orders together with customer and product information in a single request.
  • [Individual data submission](https://app.theneo.io/nshiftone/returns/api-v-3-push-api-controller/individual-data-submission.md): Individual Data Submission is used to: Store customers Creates or updates a customer record. Orders reference this record using customerId or customerEmail . Store orders Creates or updates an order that links a customer to one or more product or variant lines. Each line represents a purchased item. Store products Creates or updates a product with one or more variants. Order items reference either productVariantId or productId from this catalog. The calls are made separately and handled individually.
• [PULL API](https://app.theneo.io/nshiftone/returns/api-v-3-returns-controller.md): Our Pull API is used to retrieve return data from nShift Returns. We support the following methods: Get return summaries Returns a list of summarized return data for a given period. Get returns Returns complete return orders within a date range. Get return order by return order id Returns detailed information about a single return order. Choose the method that best fits your workflow.
  • [Get return summaries](https://app.theneo.io/nshiftone/returns/api-v-3-returns-controller/get-return-summaries.md): The Get return summaries endpoint provides a lightweight way to retrieve return activity within a specific period. It returns records that include order and customer identifiers, product references, returned quantities, refund values, reason codes, and the current processing state. Because it focuses on summarized data, this endpoint is well suited for reporting, tracking return trends, or monitoring activity without pulling full order details. Filtering is done with periodStart , periodEnd , and optionally by marketCode , and results can be paginated with pageSize and pageNumber .
  • [Get return orders](https://app.theneo.io/nshiftone/returns/api-v-3-returns-controller/get-return-orders.md): The Get returns endpoint delivers complete return order data. It allows filtering by creation or update date ranges using createdAfter , createdBefore , updatedAfter , and updatedBefore . The response includes everything related to a return order: identifiers, status, totals for amounts and fees, detailed line items with refund values and reasons, reconversion items for exchanges, applied fees, and shipment and tracking information.
  • [Get return order by return order id](https://app.theneo.io/nshiftone/returns/api-v-3-returns-controller/get-return-order-by-return-order-id.md): This endpoint retrieves detailed information about a single return order by its unique returnOrderId . The response includes the main return order data such as identifiers, status, totals, and customer reference, along with item details, fees, and shipment information. Use this endpoint when you need the full return order object for a specific case.
• [Process Returns](https://app.theneo.io/nshiftone/returns/api-v-3-wms-controller.md): The Returns section of our API allows users to retrieve information related to returns processed within our warehouse management system. With this section, users can access data on returned items, reasons for return, and status updates, enabling them to efficiently manage returns and track their progress.
  • [Create/Process/Update Return](https://app.theneo.io/nshiftone/returns/api-v-3-wms-controller/process-wms-update.md): Summary: Create, process, or update a return order Description : A single endpoint handles three distinct operations depending on what you send. Title Description Goal What to send Create a new return orderId (or alternative) + items with status Process a return returnId returnItemId on each item status Update a return item returnId returnItemId corrected fields No return needs to exist yet when creating. When processing or updating, include returnItemId on every item - this is how the endpoint identifies which return item to act on. Create a return Process a return Update a return Create a return Plain text "returns": [ { "orderId": "ORD-10023", "items": [ { "productVariantSku": "SHOE-BLK-42", "quantity": 1, "status": "ARRIVED" } ] } ] } "returns": [ { "orderId": "ORD-10023", "items": [ { "productVariantSku": "SHOE-BLK-42", "quantity": 1, "status": "ARRIVED" } ] } ] } Process a return JSON { "returns": [ { "returnId": "4521", "items": [ { "returnItemId": "8801", "quantity": 1, "status": "APPROVED" } ] } ] } Update a return Plain text { "returns": [ { "returnId": "4521", "items": [ { "returnItemId": "8801", "quantity": 1, "status": "REMOVED" } ] } ] } { "returns": [ { "returnId": "4521", "items": [ { "returnItemId": "8801", "quantity": 1, "status": "REMOVED" } ] } ] }
• [Update return order refund status by return order id](https://app.theneo.io/nshiftone/returns/update-order/update-return-order-refund-status-by-return-order-id.md): This endpoint is used to update the refund status of a return order , identified by its return order ID . It lets you signal whether the refund was successful or not, and optionally provide error details if it failed