---
title: "Configuring warranty information"
slug: "configuring-warranty-information"
updated: 2026-05-04T16:52:31Z
published: 2026-05-04T16:52:31Z
canonical: "docs.newstore.com/configuring-warranty-information"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newstore.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuring warranty information

Configure NewStore Associate App to show warranty information for a product during the return process. This information can be used by associates in your business to decide if a product can be returned by the customer and if any refunds have to be provided for such returns.

## Enabling warranty information

The warranty information products are only displayed after you enable this feature for NewStore Associate App:

1. Use the [Update app configuration](https://docs.newstore.net/api/configuration/apps/associate-app-config-api_config#operation/putConfig) method.
2. In `commerceComponents` > `warrantyLambdaUrl`, specify the URL that returns warranty information given an order ID.

## Setting up the warranty information

To display warranty information for a product in NewStore Associate App, you have to first set up a service at the provided URL that accepts the order ID as part of the path and responds with warranty details. The response format is detailed below.

To enable it:

1. Configure the warranty base URL in the existing Associate App configuration service.
2. Implement an endpoint at that URL that returns warranty information for a given order.

> [!TIP]
> Note
> 
> If no warranty URL is configured, the app does not attempt any warranty lookup. The app displays that no warranty information is available to store associates.

### Your responsibilities

As an integrator for your business or for the retailer, you are responsible for:

- Setting the warranty endpoint URL in the configuration service
- Building and operating the warranty endpoint behind that URL (despite the configuration name, the warranty endpoint does not have to be a lambda function)
- Returning warranty data in the expected format
- Ensuring the returned item identifiers can be matched to order items shown in the app

You are not responsible for building the Associate App configuration service itself. NewStore is responsible for the app configuration.

## Configuring the app to set up warranty information

The Associate App configuration must include a warranty base URL.

Conceptually, the configuration looks like the example here:

```json
{
  "commerce_components": {
    "warranty_lambda_url": "https://your-domain.example.com/warranty"
  }
}
```

When the URL value is provided, the app calls your endpoint whenever it needs to display warranty information.

### Contract for the warranty URL

Your system must expose an HTTP GET endpoint using this pattern:

```plaintext
GET {warranty_lambda_url}/{orderId}
```

See the example:

```plaintext
GET https://your-domain.example.com/warranty/external_order_id
```

The `{orderId}` path parameter is supplied by the app and identifies the order for which warranty data is requested.

### Request behavior

When the app calls your endpoint, it includes standard request headers used across the platform, including:

- Authorization
- Accept-Language
- User-Agent
- Tracing headers

Your system should be prepared to accept authenticated requests. Ensure no additional request body or query parameters are required for the standard integration.

### Response format

Your system must return a JSON payload describing warranty information for the order and items included in the order. See an example for the response payload:

```json
{
  "order_id": "external_order_id",
  "items": [
    {
      "item_id": "itemId1",
      "product_id": "origin333", // optional
      "external_identifiers": {
        "serial_number": "SN123456" // optional
      },
      "warranty": {
        "warranty_end_date": "2026-12-31T00:00:00Z",
        "covered_by_warranty": true,
        "additional_data": [
          { "label": "Type of warranty", "value": "Extended" },
          { "label": "Provider", "value": "Acme Warranty" }
        ]
      }
    }
  ]
}
```

### Required fields

The response payload must include the:

- `order_id`
- `items`

For each item, the response must include:

- `item_id`
- `warranty.warranty_end_date`
- `warranty.covered_by_warranty`

### Optional fields

These fields are optional but supported:

- `product_id`
- `external_identifiers`
- `warranty.additional_data`

`additional_data` can be used to display extra warranty details as label or value pairs, such as:

- Warranty type
- Coverage tier
- Provider
- Redemption limit

## Setting up identifier matching requirements

> [!NOTE]
> Important
> 
> This section is crucial to set up your warranty integration. **If the mapping of identifiers is wrong or incomplete, the warranty data may exist but will not appear in the UI.**

The app matches warranty records to order items using item-level identifiers. In different screens, the app may use different order item identifiers to match.

To make the integration reliable, your system should:

- Accept the order ID provided by the app, even if your internal systems distinguish between external and canonical order IDs
- Return the `item_id` , whenever possible
- Populate those fields with values that correspond to identifiers present on the order items returned to the app

In practice, this means your warranty endpoint should be tolerant of identifier variations. It should also provide enough item-level data for the app to match the correct warranty record to each item.

## Displaying the warranty information

When a matching warranty record is returned, the app displays:

- Whether the item is covered by warranty
- The warranty expiration date
- Any additional warranty attributes you provide

This information is displayed to store associates in relevant order and return flows. At present, warranty information is only informative. It is intended to help associates understand item coverage during order review and return handling.

## Handling errors and troubleshooting

Your system should follow these behaviors:

- Return `200 OK` with the response body when warranty data is available
- Return `404 Not Found` when no warranty information exists for the requested order
- Return other error codes only for genuine service or processing failures

A `404` error is treated as a `no warranty information available` situation instead of a broken experience.

## Data format guidelines

Use these conventions when formatting the data:

- Return JSON
- Use `snake_case` field names
- Provide `warranty_end_date` as a valid `ISO 8601` timestamp
- Keep `additional_data` values short and suitable for display in the app UI