Returns & Replacements

Overview

The Returns functionality in the POS Portal API is used to manage product returns and replacements. This guide provides an overview of the returns-related resources, including Returns, Return Reasons, Return Items, and Call Tags, as well as important considerations when creating return and replacement orders.

NOTE: Returns are not required to be managed via the API and are independent of the ordering process. In fact, Portal Access is often the preferred method for most clients when submitting returns.

For a quick review of the workflow for submitting a return, please review the image below (click on the image to enlarge it):

Managing Returns and Replacements

Returns management involves creating returns or replacements, identifying the equipment being returned, selecting return reasons, determining how the RMA/Call Tag will be issued, and, when applicable, determining the configuration for a replacement device.

Step 1: Create and Manage Returns or Replacements

To initiate a return or replacement for an order or specific item, use the following endpoint. The {entity} parameter represents the type of entity being returned (e.g., order), and {id} is the identifier for that entity.

• Create a Return

  POST /v2/returns/{entity}/{id}

• Get Return Details

  After creating a return, use the following endpoint to retrieve its details, including the status and items associated with the return.

  GET /v2/returns/{id}

Step 2: Understand Return Reasons

The POS Portal API provides standardized return reasons that can be used when creating a return or replacement.

• Get Return Reasons

  Use the following endpoint to retrieve the available return reasons for the applicable return type.

  GET /v2/returns/reasons/{type}

Step 3: Manage Return Items

Before creating a return or replacement, you may need to identify the items that are eligible to be returned.

• Get Return Items

  Use the following endpoint to retrieve the items available for return for the specified entity.

  GET /v2/returns/{entity}/{id}/items

  The response provides information needed to identify the equipment or products being returned.

  NOTE: If this request returns no items, please check with your POS Portal account manager, as some account configuration may be required for this request to return applicable data.

Step 4: Understanding Returns vs. Replacements

When creating a return, each entry in the returnItems array includes a type that determines whether the device is simply being returned or whether a replacement device should be shipped.

The two primary values are:

• RETURN - The device is being returned and no replacement device is expected to be shipped.
• REPLACEMENT - The device is being returned and POS Portal should send a replacement device.

Returning a Device

For a standard return, identify the deployed equipment being returned using the deployedEquipmentId and set the type to RETURN.

Example:

{
  "returnItems": [
    {
      "type": "RETURN",
      "productType": "SERIALIZED",
      "deployedEquipmentId": 10847806,
      "quantity": 1,
      "problem": "Device no longer needed",
      "reason": {
        "id": 1
      }
    }
  ]
}

Because no replacement device is being shipped, a modernConfiguration would generally not be required for this return item.

Replacing a Device

For a replacement, identify the deployed equipment being replaced using the deployedEquipmentId and set the type to REPLACEMENT.

POS Portal will attempt to replace the returned device using the same order item associated with the original deployed equipment. Because of this, it is generally not necessary to add the replacement device to the top-level items array.

Example:

{
  "returnItems": [
    {
      "type": "REPLACEMENT",
      "productType": "SERIALIZED",
      "deployedEquipmentId": 10847806,
      "quantity": 1,
      "problem": "Bad battery",
      "reason": {
        "id": 1
      },
      "modernConfiguration": {
        "configurations": [
          {
            "id": 100,
            "options": [
              {
                "id": 200,
                "attributes": [
                  {
                    "id": 300,
                    "value": "Example Value"
                  }
                ]
              }
            ]
          }
        ]
      }
    }
  ]
}

The modernConfiguration within the returnItems entry represents the configuration that should be applied to the outgoing replacement device.

Step 5: Configuration Handling for Replacement Devices

When replacing a serialized device, configuration requirements should be evaluated before submitting the return.

The configuration originally assigned to the deployed equipment may still be valid. However, configurations can change over time, so clients should not assume that the original configuration is always available for the replacement device.

Retrieve the Existing Device Configuration

Use the deployed equipment resource to retrieve information about the device being replaced:

GET /v2/deployedequipment/{id}

This can be used to identify the Modern Device Configuration (MDC) associated with the original deployed device.

If the existing configuration is still valid for the replacement device, those configuration values can be submitted within the modernConfiguration object of the applicable returnItems entry.

Retrieve Currently Available Configurations

If the original configuration is no longer available or a different configuration is required, retrieve the currently available configurations for the product:

GET /v2/products/{id}/configurations

Select the appropriate configuration and include it within the modernConfiguration object for the REPLACEMENT return item.

Important: Configuration requirements are associated with the individual device being replaced. If a return contains multiple replacement devices, each returnItems entry can contain the modernConfiguration applicable to that specific replacement.

Step 6: Adding Additional Items to a Return

The top-level items array within the Create Return request can be used when additional items need to be added to the return order.

It should not be assumed that an items entry is required simply because a replacement device is being shipped.

For example, a replacement may contain only a returnItems entry:

{
  "returnItems": [
    {
      "type": "REPLACEMENT",
      "deployedEquipmentId": 10847806,
      "problem": "Bad battery",
      "reason": {
        "id": 1
      },
      "modernConfiguration": {
        "configurations": [
          {
            "id": 100,
            "options": [
              {
                "id": 200
              }
            ]
          }
        ]
      }
    }
  ]
}

If additional products need to be shipped as part of the return, those products can be included separately within the top-level items array.

Step 7: Determine How the Call Tag/RMA Will Be Issued

The issuedBy field on the Create Return request determines how the Call Tag/RMA is issued and how the return is expected to get back to POS Portal.

The available values are:

• POS
• CLIENT
• ELECTRONIC

issuedBy = POS

Use POS when POS Portal is responsible for issuing the physical RMA/Call Tag.

In this scenario:

• POS Portal creates the Call Tag record.
• POS Portal sends the physical RMA materials needed for the merchant to return the device.
• The Call Tag remains open until the returned equipment is received and processed by POS Portal Operations.

Example:

"issuedBy": "POS"

issuedBy = CLIENT

Use CLIENT when the client is responsible for coordinating and sending the equipment back to POS Portal.

In this scenario:

• POS Portal creates the Call Tag record.
• POS Portal does not send the RMA or return materials to the merchant.
• The client manages the return shipment.
• The Call Tag acts as the expected return record so POS Portal Operations can associate the equipment with the appropriate return when it is received.
• The status of the Call Tag can be viewed through available API resources or reporting.

Example:

"issuedBy": "CLIENT"

issuedBy = ELECTRONIC

An ELECTRONIC Call Tag behaves similarly to a client-issued Call Tag, with one key difference: POS Portal electronically sends the RMA to the merchant.

In this scenario:

• POS Portal creates the Call Tag record.
• POS Portal sends an email containing the RMA for the merchant to print and use when returning the equipment.
• The merchant uses the electronically provided RMA to send the device back to POS Portal.
• The Call Tag remains open until the returned equipment is received and processed.

Example:

"issuedBy": "ELECTRONIC"

Important: ELECTRONIC can only be used when returnItems.type = RETURN. It cannot be used for a REPLACEMENT.

Example: Electronically Issued Return

For an electronically issued RMA, the return item should be submitted as a RETURN and issuedBy should be set to ELECTRONIC.

{
  "issuedBy": "ELECTRONIC",
  "returnItems": [
    {
      "type": "RETURN",
      "productType": "SERIALIZED",
      "deployedEquipmentId": 10847806,
      "quantity": 1,
      "problem": "Device no longer needed",
      "reason": {
        "id": 1
      }
    }
  ]
}

At a high level:

• POS = POS Portal issues the physical return materials.
• CLIENT = The client manages the return shipment; POS Portal creates the Call Tag record only.
• ELECTRONIC = POS Portal creates the Call Tag record and emails the RMA to the merchant for printing.

Step 8: Additional Call Tags

In some cases, an additional Call Tag may need to be issued for an existing return. An additional Call Tag creates a new RMA for equipment that is already expected to be returned to POS Portal.

For example, an additional Call Tag may be needed if the merchant has not returned the equipment within the expected timeframe or needs another RMA to complete the return.

Additional Call Tags can be issued as either:

• CLIENT - The client is responsible for providing the new RMA and coordinating the return with the merchant.
• ELECTRONIC - POS Portal creates the new RMA and emails it to the merchant to print and use for the return.

Issuing an additional Call Tag does not create another return order or change the equipment expected back. It provides an additional RMA for the existing return.

Important: An ELECTRONIC additional Call Tag can only be used for a RETURN, not a REPLACEMENT.

Key Considerations

When integrating with the Returns API, keep the following behaviors in mind:

• returnItems.type = RETURN indicates that the item is being returned without a replacement.
• returnItems.type = REPLACEMENT indicates that a replacement device should be shipped.
• A replacement generally uses the same order item associated with the original deployed equipment.
• The top-level items array is not required simply because a replacement device is being shipped.
• For a REPLACEMENT, returnItems.modernConfiguration identifies the configuration to apply to the outgoing replacement device.
• Configurations should be evaluated when the replacement is created because the original device configuration may no longer be valid.
• Multiple devices can be returned or replaced within the same return request, with configuration information associated independently with each applicable returnItems entry.
• The issuedBy field determines how the Call Tag/RMA is issued.
• ELECTRONIC can only be used with a RETURN; it cannot be used for a REPLACEMENT.
• Additional Call Tags can be used to issue a new RMA for equipment that is already expected to be returned.

For more detailed information on the Returns endpoint and its parameters, please refer to the POS Portal API Documentation.