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:

Use the Update app configuration method.
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:

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

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:

{
  "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:

GET {warranty_lambda_url}/{orderId}

See the example:

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:

{
  "order_id": "external_order_id",
  "items": [
    {
      "item_id": "itemId1",
      "product_id": "origin333",
      "external_identifiers": {
        "serial_number": "SN123456"
      },
      "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
product_id
warranty.warranty_end_date
warranty.covered_by_warranty

Optional fields

These fields are optional but supported:

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

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 both item_id and product_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