Introduction
Product catalog
1. Create a product catalog
2. Update the product catalog
FTI transaction creation
1. Get residual values
2. Get configured data fields
3. Register an FTI transaction
4. Update the FTI transaction
5. Import FTI transactions
6. Set transactions to the Confirmed status
Return flow
1. Cancel an FTI transaction
2. Get the corresponding grading form
3. Get the price quote
4. Due diligence check
5. Get trade-in data fields
6. Register the trade-in
7. Ship and track the device
Statuses
1. FTI transaction statuses
2. Trade-in device reporting statuses

1 Introduction

The Foxway Vendor API is a traditional RESTful API, designed for ease of implementation and understanding.

Key takeaways:

All timestamps are provided in UTC format
API employs basic authentication (x-apikey), which is obtainable from your Account Manager
- The production base URL, along with the API key, will be provided by the technical contact assigned to you
Both development and production environments are supported
Comprehensive Swagger documentation is available here.

This document outlines best practices for integrating the API into the following workflows:

Product catalogue creation and synchronization
FTI transaction creation and confirmation
FTI transaction updates and cancellation
Device grading, price quotation, and return registration

2 Product catalog

This section describes the API endpoints required to create a product catalog for an FTI implementation.

2.1 Create a product catalog

Before you can call the API endpoint for creating the product catalog, you must first obtain the correct item variant IDs for all models that will be included in the catalog.

The ItemVariantId-s can be retrieved using the GET /api/v2/fti/models endpoint. The endpoint provides several optional query parameters that allow you to filter the results by, for example, ItemGroupId, ManufacturerId, or a search term. Using these filters is highly recommended because, by default, the endpoint returns a maximum of 500 results. Filtering the results helps ensure that you retrieve all required models and improves performance.

Example request:

https://api--uat.qa.rc.foxway.dev/api/v2/retail/models?term=MYED3ZD%2FA

Example response:

{
  "Data": [
    {
      "ItemVariantId": 67911, // Item variant ID
      "ItemName": "iPhone 16",
      "ProductName": "Apple iPhone 16 128GB",
      "ProductCode": "MYED3ZD/A,MYEA3ZD/A,MYE93ZD/A,MYE73ZD/A,MYEC3ZD/A,MYEA3,MYE93,MYE73,3N399,3N398,3N397,3N396,3N395,3N393,3N392,3N391,MYEC3,MYDV3,MYDU3,MYDT3,MYDR3,MYDQ3,3N394,MYED3,3N400,MYAW3LL/A,MYAR3LL/A,MYAQ3LL/A,MYAP3LL/A,MYAT3LL/A,MYDQ3AE/A,MYDQ3AH/A,MYDQ3J/A,MYDR3AE/A,MYDR3AH/A,MYDT3AE/A,MYDT3AH/A,MYDU3AE/A,MYDV3AE/A,MYDV3VC/A,MYE73HN/A,MYE73HX/A,MYE73QL/A,MYE73QN/A,MYE73SX/A,MYE93BR/A,MYE93HN/A,MYE93HX/A,MYE93QL/A,MYE93QN/A,MYE93SX/A,MYEA3HX/A,MYEA3QL/A,MYEA3QN/A,MYEA3SX/A,MYEC3HN/A,MYEC3HX/A,MYEC3PA/A,MYEC3QL/A,MYEC3QN/A,MYEC3SX/A,MYED3HN/A,MYED3HX/A,MYED3QL/A,MYED3QN/A,MYEX3ZA/A,5YE73ZP/A,FYE73ZN/A,MYDT3J/A,MYDU3J/A,MYDV3J/A,MYE73BR/A,MYE73TU/A,MYEA3HN/A,MYEA3ZP/A,MYED3SX/A,NYE73QN/A,NYE73TU/A,NYE73ZD/A,NYEA3ZD/A,NYEC3BE/A,NYEC3ZD/A,NYED3ZD/A",
      "ProductNameShort": "Apple iPhone 16 128GB",
      "ItemGroupId": 1,
      "ManufacturerId": 116,
      "PictureUrl": "https://dcosix8as1189.cloudfront.net/imagestorage/ItemsPicture/Apple%20iPhone%2016.png",
      "Capacity": "128GB",
      "ItemId": 55007
    }
  ],
  "TotalCount": 1
}

For each model in the product catalog, you must also specify the product category to which it belongs. The list of product categories can be retrieved using the GET /api/v2/fti/products/categories endpoint.

Example request:

https://api--uat.qa.rc.foxway.dev/api/v2/fti/products/categories

Example response:

[
  {
    "Id": 7,
    "Name": "iPad"
  },
  {
    "Id": 1,
    "Name": "iPhone"
  },
  {
    "Id": 3,
    "Name": "Watch"
  }
]

To upload the entire product catalog, use the POST /api/v2/fti/product-catalog endpoint. In the request body, include the list of all products that should be part of the product catalog.

Please note that Foxway must have residual value curves configured for all models included in the product catalog. Therefore, please make sure that the required residual value curves have been agreed upon with the Foxway team before uploading the product catalog.

Example request:

{
  "Products": [
    {
      "ItemVariantId": 67911, // from GET /api/v2/fti/models
      "ProductType": 0, // 0 - main, 1 - accessory
      "ProductCategoryId": 1, // from GET /api/v2/fti/products/categories
      "ProductName": "Apple iPhone 16 128GB Teal",
      "Price": 979,
      "Currency": "EUR",
      "SKU": "MYED3ZD/A", // partner SKU
      "IsActive": true,
      "Images": [
        "https://www.google.com" // URL to the image
      ]
    }
  ]
}

2.2. Update the product catalog

Use the PATCH /api/v2/fti/product-catalog/update endpoint to update the product catalog. The request body requires the ProductId for each product to be updated. ProductId-s can be retrieved using the GET /api/v2/fti/products endpoint.

Example request:

{
  "Products": [
    {
      "ProductId": 76685, // From GET /api/v2/fti/products
      "ItemVariantId": 67911,
      "ProductType": 0,
      "ProductCategoryId": 1,
      "ProductName": "Apple iPhone 16 128GB",
      "Price": 979,
      "Currency": "EUR",
      "SKU": "MYED3ZD/A",
      "IsActive": true,
      "Images": [
        "https://www.google.com"
      ]
    }
  ]
}

3 FTI transaction creation

This section explains which API endpoints are required to register an FTI transaction and the order in which they must be called. It also describes the required request formats and attributes, as well as how to use and interpret the API responses.

3.1 Get residual values

To register an FTI transaction, you must specify the return period. The available return periods (ReturnPeriod), together with their corresponding residual values (Value), can be retrieved using the GET /api/v2/fti/residual endpoint.
You can optionally filter the results by the SKU used in the product catalog, although this is not required. If no filter is specified, the endpoint returns up to 10 results. You can increase this limit, but the maximum number of results that can be returned in a single request is 100.

Example request:

https://api--uat.qa.rc.foxway.dev/api/v2/fti/residual?sku=MYED3ZD%2FA

Example response:

[
  {
    "Sku": "MYED3ZD/A",
    "Price": 979,
    "CurrencyIsoCode": "EUR",
    "ResidualPrices": [
      {
        "ReturnPeriod": 12,
        "Value": 225
      },
      {
        "ReturnPeriod": 24,
        "Value": 147
      }
    ]
  }
]

3.2 Get configured data fields

To collect the customer's personal data required for creating an FTI transaction, we can configure custom data fields according to the integration partner's requirements. The list of configured data fields can be retrieved using the GET /api/v2/fti/configurations/data-fields endpoint. Please note that the FTI transaction registration request requires all mandatory data fields to be included in the request body and populated with valid values.

Example request:

https://api--uat.qa.rc.foxway.dev/api/v2/fti/configurations/data-fields

Example response:

[
  {
    "IsRequired": true,
    "IsActive": true,
    "Label": "Name",
    "SortOrder": 0,
    "DataFieldId": 71, // You need this Id for the registration call
    "DataFieldName": "First name",
    "DataFieldType": "Literal",
    "ListOptions": [],
    "HasEncryption": false,
    "IsGdprCompliant": false
  },
  {
    "IsRequired": true,
    "IsActive": true,
    "Label": "Surname",
    "SortOrder": 0,
    "DataFieldId": 72,
    "DataFieldName": "Last name",
    "DataFieldType": "Literal",
    "ListOptions": [],
    "HasEncryption": false,
    "IsGdprCompliant": false
  }
]

3.3 Register an FTI transaction

To register an FTI transaction, use the POST /api/v2/fti/deal endpoint. The request body must include the product SKU (Sku), product quantity (Quantity), return period (ReturnPeriod), total cart price (CartTotal), and all required customer data fields.

Example request:

{
  "Products": [
    {
      "Sku": "MYED3ZD/A",
      "Quantity": 1
    }
  ],
  "ReturnPeriod": 12,
  "CartTotal": 979,
  "DataFields": [
    {
      "DataFieldId": 71,
      "DataFieldValue": "Mari"
    },
    {
      "DataFieldId": 72,
      "DataFieldValue": "Maasikas"
    }
  ]
}

Example response:

{
  "FpcTransactionId": 1056151
}

3.4 Update the FTI transaction

After registering the FTI transaction, you must associate the correct device identifier with the transaction. Use the IMEI for devices that support it, or the serial number for all other devices. In addition to the FpcTransactionId, this request also requires the FpcTransactionProductId, which can be retrieved using the GET /api/v2/fti/transactions/{ftiTransactionId} endpoint.

Example request:

https://api--uat.qa.rc.foxway.dev/api/v2/fti/transactions/1056151

Example response:

{
  "FpcTransactionId": 1056151,
  "CreateDate": "2026-09-11T09:02:08.7992259Z",
  "Period": 12,
  "User": "API User",
  "Location": "API",
  "ReturnDate": "2027-09-11T09:02:08.7992259Z",
  "Status": "Confirmed",
  "DataFields": [
    {
      "DataFieldId": 231563,
      "DataFieldLabel": "Name",
      "DataFieldValue": "Mari"
    },
    {
      "DataFieldId": 231564,
      "DataFieldLabel": "Surname",
      "DataFieldValue": "Maasikas"
    }
  ],
  "Products": [
    {
      "FpcTransactionProductId": 56472, // You need this to update the transaction
      "ItemVariantId": 67911,
      "ProductName": "Apple iPhone 16 128GB",
      "DeviceIdentifier": "",
      "ProductSKU": "MYED3ZD/A",
      "CurrencyIsoCode": "EUR",
      "ReturnStatus": "Returnable"
    }
  ]
}

Use the PATCH /api/v2/fti/transaction/update endpoint to update the products associated with an FTI transaction.

Example request:

{
  "FpcTransactionId": 1056151,
  "Products": [
    {
      "FpcTransactionProductId": 56472,
      "Identifier": "338743568980997"
    }
  ]
}

3.5 Import FTI transactions

There is also an option to create FTI transactions in bulk by importing an Excel (.xlsx) file. The file can be uploaded using the POST /api/v2/fti/transactions/import endpoint.

Required columns in the import file:

SKU	Product Name	Identifier	Deal Date	Return period	Purchase price (w/o VAT)	Residual value	Data fields
MYED3ZD/A	Apple iPhone 16 128GB Teal	450743604938373	11.09.2026	12	979	225	[{"Id":71,"Value":"Mari"},{"Id":72,"Value":"Maasikas"}]

Example response:

[
  {
    "RowNumber": 1,
    "FpcTransactionId": 1056150,
    "FpcTransactionProductId": 56471,
    "ProductSKU": "MYED3ZD/A",
    "Failed": false
  }
]

3.6 Set transactions to the Confirmed status

All newly created FTI transactions are initially assigned the Pending status. This status is intended to cover the remorse return period, during which the transaction can still be canceled. Once the remorse return period has ended, the transaction must be moved to the Confirmed status to indicate that it can no longer be canceled. To confirm an FTI transaction, use the PATCH /api/v2/fti/transactions/{ftiTransactionId}/confirm endpoint.

Example request:

https://api--uat.qa.rc.foxway.dev/api/v2/fti/transactions/1056150/confirm

You can check the status using the GET /api/v2/fti/transactions/{ftiTransactionId} endpoint.

{
  "FpcTransactionId": 1056150,
  "CreateDate": "2026-09-11T00:00:00Z",
  "Period": 12,
  "User": "API User",
  "Location": "API",
  "ReturnDate": "2027-09-11T00:00:00Z",
  "Status": "Confirmed", // The status to check
  "DataFields": [
    {
      "DataFieldId": 231561,
      "DataFieldLabel": "Name",
      "DataFieldValue": "Mari"
    },
    {
      "DataFieldId": 231562,
      "DataFieldLabel": "Surname",
      "DataFieldValue": "Maasikas"
    }
  ],
  "Products": [
    {
      "FpcTransactionProductId": 56471,
      "ItemVariantId": 67911,
      "ProductName": "Apple iPhone 16 128GB",
      "DeviceIdentifier": "11542344586944",
      "ProductSKU": "MYED3ZD/A",
      "CurrencyIsoCode": "EUR",
      "ReturnStatus": "Returnable"
    }
  ]
}

4 Return flow

4.1 Cancel an FTI transaction

An FTI transaction can be canceled if it was registered by mistake or if the customer exercises their right to return the product during the remorse return period. Please note that an FTI transaction can only be canceled while it is in the Pending status. To cancel an FTI transaction, use the PATCH /api/v2/fti/cancel endpoint.

Example request:

https://api--uat.qa.rc.foxway.dev/api/v2/fti/cancel?ftiTransactionId=1056151&keepTradeIn=false

Since an FTI transaction can include a trade-in of an old device (currently, it's not supported via the API), this cancellation endpoint allows you to specify whether the associated trade-in should also be canceled.

keepTradeIn: false - the associated trade-in will be canceled

keepTradeIn: true - the associated trade-in will remain active and will be processed

4.2 Get the corresponding grading form

The first step in the return flow is to retrieve the correct grading form for the returnable device. To retrieve the grading form, you must first obtain the ItemVariantId. The ItemVariantId can be retrieved from the FTI transaction details using the GET /api/v2/fti/transactions/{ftiTransactionId} endpoint. See the example below.

Example request:

https://api--uat.qa.rc.foxway.dev/api/v2/fti/transactions/1056150

Example response:

{
  "FpcTransactionId": 1056150,
  "CreateDate": "2026-09-11T00:00:00Z",
  "Period": 12,
  "User": "API User",
  "Location": "API",
  "ReturnDate": "2027-09-11T00:00:00Z",
  "Status": "Confirmed",
  "DataFields": [
    {
      "DataFieldId": 231561,
      "DataFieldLabel": "Name",
      "DataFieldValue": "Mari"
    },
    {
      "DataFieldId": 231562,
      "DataFieldLabel": "Surname",
      "DataFieldValue": "Maasikas"
    }
  ],
  "Products": [
    {
      "FpcTransactionProductId": 56471, // you need this Id to get the price quote for the returnable device
      "ItemVariantId": 67911, // you need this Id for requesting the correct grading form
      "ProductName": "Apple iPhone 16 128GB",
      "DeviceIdentifier": "11542344586944", // you need this Id to get the price quote for the returnable device
      "ProductSKU": "MYED3ZD/A",
      "CurrencyIsoCode": "EUR",
      "ReturnStatus": "Returnable"
    }
  ]
}

Once you have the ItemVariantId, use the GET /api/v2/fti/return/grading-form endpoint to retrieve the correct grading form for the returnable device.

Example request:

https://api--uat.qa.rc.foxway.dev/api/v2/fti/return/grading-form?itemVariantId=67911

Example response:

{
  "Id": 8,
  "Name": "!Mobiles / Tablets / iPods (No Premium)",
  "Questions": [
    {
      "Id": 0,
      "Name": "Does the device turn on and stay on without a charger?",
      "Label": "Power",
      "Info": "<p>&nbsp;</p>",
      "InfoCards": [
        {
          "Id": 0,
          "Label": "Info card 209",
          "Text": "<p><strong><span>All criteria must be met before selecting &quot;YES&quot;!</span></strong></p><ul><li><span>Device can be turned on and off</span></li><li><span>Charging port is without visual damage</span></li><li><span>Device starts charging with charger connected</span></li><li><span>Device can be used without charger connected</span></li><li><span>Device is not heavily deformed</span></li><li><span>Device is intact&nbsp;</span></li></ul><p><br></p><p><strong><span style=\"color: rgb(184, 49, 47);\">Devices with visually swollen or damaged batteries pose safety risks, including overheating or fire hazards, and are therefore strictly prohibited from trade-in.</span></strong></p>",
          "Images": [
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/80781556-3c29-4268-aa7c-e7070e6629d0.jpg",
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/a940ca9d-ce59-47bd-829b-62aecc35b6d6.jpg",
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/7bde3429-dc91-4f57-9b5f-702ec1673923.jpg",
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/0866a614-a255-4e21-bc2f-40c6d63fd8e2.jpg",
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/b1c87c1d-1ee4-4761-85d0-08fd062c1030.jpg"
          ]
        }
      ],
      "Answers": [
        {
          "Id": 0,
          "Name": "Yes",
          "Score": 100,
          "InfoCards": [],
          "IsVendorSelected": false,
          "IsPartnerSelected": false,
          "IsAffiliateSelected": false
        },
        {
          "Id": 1,
          "Name": "No",
          "Score": 5,
          "InfoCards": [],
          "IsVendorSelected": false,
          "IsPartnerSelected": false,
          "IsAffiliateSelected": false
        }
      ]
    },
    {
      "Id": 1,
      "Name": "Is LCD working and without physical damage?",
      "Label": "LCD",
      "Info": "<p>&nbsp;</p>",
      "InfoCards": [
        {
          "Id": 0,
          "Label": "Info card 213",
          "Text": "<p><strong>All criteria must be met before selecting &quot;YES&quot;</strong></p><p><br></p><ul><li>LCD is without any clear signs of discoloration (screenburn, dead pixels, spots)</li><li>Touchscreen is fully working (check edges of the screen)</li><li>Glass covering the LCD is without any missing pieces (it can be cracked)<br><br><span>Additional criteria for foldable device:</span></li><li>If device has more than one screen, all screens are without LCD defects&nbsp;</li><li><span>No light cutting lines on the folding area&nbsp;</span><br><br><em><span>Please do not remove factory installed screen protection film from Samsung Flip/Fold devices</span></em></li></ul>",
          "Images": [
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/e8bcc976-d36b-4451-beec-2386ced73dee.jpg",
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/58906a0b-a726-4866-b1c4-2be96a6fe7a6.jpg",
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/1d38bb67-aca6-4f02-9997-5757d891bf9c.jpg",
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/455ec633-2871-4464-80a9-d166157182f9.jpg",
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/23a97d9c-2c9d-4d7a-9fe0-96d29b4f70e1.jpg",
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/ac2f8849-a9b0-45bf-955e-afc1439f9c6d.jpg",
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/c4473aea-647f-4874-b2f2-09018a61cc4f.jpg",
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/1fa3ec4a-f3ce-427b-ab33-3211becf10f1.jpg"
          ]
        }
      ],
      "Answers": [
        {
          "Id": 0,
          "Name": "Yes",
          "Score": 100,
          "InfoCards": [],
          "IsVendorSelected": false,
          "IsPartnerSelected": false,
          "IsAffiliateSelected": false
        },
        {
          "Id": 1,
          "Name": "No",
          "Score": 30,
          "InfoCards": [],
          "IsVendorSelected": false,
          "IsPartnerSelected": false,
          "IsAffiliateSelected": false
        }
      ]
    },
    {
      "Id": 2,
      "Name": "Are front, frame and back cover in good condition (general wear is acceptable)?",
      "Label": "Body",
      "Info": "<p>&nbsp;</p>",
      "InfoCards": [
        {
          "Id": 0,
          "Label": "Info card 218",
          "Text": "<p><strong>All criteria must be met before selecting &quot;YES&quot;</strong></p><ul><li>Display glass is without cracks or chips (check also on edges)&nbsp;</li><li>There are no cracks, splits or fractures on the frame or back cover</li><li>There is no gap between backcover / screen and frame</li><li>The frame of the device is not bent</li><li>Camera glass is not cracked&nbsp;</li><li>No parts are missing (battery, backcover, port cover, screws, sim tray)&nbsp;</li><li>Screen is not visibly loose (can see under the screen)</li><li>No apparent modifications have been used&nbsp;</li></ul><p><br></p><p><span>Additional criteria for foldable devices:</span></p><ul><li>Foldable devices goes fully flat when opened</li></ul><p><br></p><p><em><span>Please do not remove factory installed screen protection film from Samsung Flip/Fold devices</span></em></p>",
          "Images": [
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/de59018f-0399-438e-84bd-e134f46e08b3.jpg",
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/8ccd0bbc-0424-4ac2-ace0-bad7305ae354.jpg",
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/ef71f0f7-19e7-4d85-8037-dabe0d78a46e.jpg",
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/efc38215-ddd6-4f75-a4f3-54e15b1cfec0.jpg",
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/4397dbbd-cbbb-4adf-92ef-a4421d2a7901.jpg",
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/5cb6e9cb-9592-4af5-ad41-cabaf6bafae7.jpg",
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/d25ad3cb-7cdf-49ac-a17e-70c4dd88b46d.jpg",
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/dfda681c-1f1b-4470-88a3-3febd9b05b00.jpg",
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/9fda9868-4efe-48f4-8aea-fef337d1c28d.jpg",
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/97ca233c-71ee-4a01-b921-a7707026eda4.jpg",
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/f305931e-758c-4271-b4a2-c30638a8b298.jpg",
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/764cbe57-ce90-4515-b136-87205d2ee708.jpg",
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/26072600-b339-45dd-a802-5e569ba76412.jpg",
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/0235cbcb-66c4-4633-8d1c-29e3e8cdf039.jpg",
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/45121399-221c-472e-8642-feac8963e6fb.jpg",
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/651a42f3-84e2-449a-9acf-a2f7726f6fce.jpg"
          ]
        }
      ],
      "Answers": [
        {
          "Id": 0,
          "Name": "Yes",
          "Score": 100,
          "InfoCards": [],
          "IsVendorSelected": false,
          "IsPartnerSelected": false,
          "IsAffiliateSelected": false
        },
        {
          "Id": 1,
          "Name": "No",
          "Score": 70,
          "InfoCards": [],
          "IsVendorSelected": false,
          "IsPartnerSelected": false,
          "IsAffiliateSelected": false
        }
      ]
    },
    {
      "Id": 3,
      "Name": "Are all buttons present and working?",
      "Label": "Buttons",
      "Info": "<p>&nbsp;</p>",
      "InfoCards": [
        {
          "Id": 0,
          "Label": "Info card 226",
          "Text": "<p><strong>All criteria must be met before selecting &quot;YES&quot;</strong></p><ul><li><span>All buttons work easily (Home, Power, Volume and Mute), no &nbsp; &nbsp; &nbsp;excessive force is needed</span></li><li><span>No unoriginal parts or modifications have been used for buttons</span></li></ul>",
          "Images": [
            "https://d33jui1kdiur6e.cloudfront.net/imagestorage/GradingFormInfoCardImage/ec795b22-da42-424d-ab25-82239a95e4da.jpg"
          ]
        }
      ],
      "Answers": [
        {
          "Id": 0,
          "Name": "Yes",
          "Score": 100,
          "InfoCards": [],
          "IsVendorSelected": false,
          "IsPartnerSelected": false,
          "IsAffiliateSelected": false
        },
        {
          "Id": 1,
          "Name": "No",
          "Score": 80,
          "InfoCards": [],
          "IsVendorSelected": false,
          "IsPartnerSelected": false,
          "IsAffiliateSelected": false
        }
      ]
    }
  ],
  "Extras": [],
  "SystemExtras": [
    {
      "Id": 1,
      "IsVendorSelected": false,
      "IsPartnerSelected": false,
      "IsAffiliateSelected": false
    }
  ],
  "ScoringType": 2
}

4.3 Get the price quote

To retrieve a price quote for the returnable device, you need the FpcTransactionProductId and ItemIdentifier. Both values can be retrieved from the FTI transaction details using the GET /api/v2/fti/transactions/{ftiTransactionId endpoint (see the example in the previous section).
Once you have these values, use the POST /api/v2/fti/return/price-quote endpoint to request the price quote.

Please note that the LocationId and AgentId attributes are optional and do not need to be included in the request body. If they are omitted, the system automatically uses the values associated with the API key.

Example request:

{
  "FpcTransactionProductId": 56471,
  "ItemIdentifier": "11542344586944",
  "GradingForm": {
    "Answers": {
      "0": [
        0
      ],
      "1": [
        0
      ],
      "2": [
        0
      ],
      "3": [
        0
      ]
    },
    "Extras": [
      0
    ],
    "SystemExtras": [
      1
    ]
  },
  "LocationId": 29135, // Get the correct Id from GET /api/v2/locations
  "AgentId": "2a51ef0e-5be7-4568-8c85-a897d67decbc" // Get the correct Id from GET /api/v2/users
}

Example response:

{
  "PriceQuoteId": "4a9565e7-fc49-4ae6-a368-a700fd563e0f", // you need this Id for the registration step
  "ItemIdentifier": "11542344586944",
  "Grade": "Working",
  "OfferedPrice": 40,
  "CurrencyIsoCode": "EUR",
  "CurrencySymbol": "€",
  "ExchangeRate": 1,
  "TradeInType": 3,
  "ModelName": "iPhone 16 128GB",
  "ItemVariantId": 67911,
  "IdentifierSuitable": true,
  "IsAgreedCondition": false,
  "MonthsPassed": 0,
  "IsLatestProduct": false
}

4.4 Due diligence check (if applicable)

By default, this option is not allowed on public websites unless all relevant details, including costs, are covered in the contract between Foxway and the integration partner. If this option is not applicable for you, proceed with the next step.

To perform the due diligence check, use the POST /api/v2/retail/duediligence/check endpoint. Please note that this feature must first be enabled by Foxway before it can be used.

Example request:

{
 "ModelId": 67911,
 "ItemIdentifier": "11542344586944"
}

Example response:

"83aa5baa-d993-4c8e-89ef-32c6d4b405a4" // Use it to get the due diligence report

To check the results, use GET /api/v2/retail/duediligence/report/{reportId}.

Example request:

https://api--uat.qa.rc.foxway.dev/api/v2/retail/duediligence/report/83aa5baa-d993-4c8e-89ef-32c6d4b405a4

Example response:

{
  "FraudCheckResults": [
    {
      "Provider": "CheckmendDeviceBlackListProvider",
      "CertId": "8-10466A038E08-465:A072ACE1",
      "Result": "Passed",
      "ResultId": 1,
      "Timestamp": "2026-09-15T08:33:57.6758881+00:00"
    }
  ],
  "FmipCheckResults": [
    {
      "Provider": "CheckmendFmipProvider",
      "CertId": "8-10466A039657-575:0B36A206",
      "Result": "Passed",
      "ResultId": 1,
      "Timestamp": "2026-09-15T08:33:57.6758881+00:00"
    }
  ]
}

4.5 Get configured data fields

Since the device return flow may require additional customer information, the required data fields are configured separately. To retrieve the list of configured data fields for the returnable device, use the GET /api/v2/retail/configurations/data-fields endpoint.

Example request:

https://api--uat.qa.rc.foxway.dev/api/v2/retail/configurations/data-fields

Example response:

[
  {
    "IsRequired": true,
    "IsVisible": true,
    "Scope": "Corporate, Private",
    "Label": "ClientPhone",
    "SortOrder": 0,
    "DataFieldId": 25,
    "DataFieldName": "ClientPhone",
    "DataFieldTemplateType": "Text",
    "DataFieldType": "Literal",
    "IsCampaignField": false,
    "DefaultValue": "",
    "ListOptions": []
  },
  {
    "IsRequired": true,
    "IsVisible": true,
    "Scope": "Corporate, Private",
    "Label": "Email Address",
    "SortOrder": 0,
    "DataFieldId": 26,
    "DataFieldName": "ClientEmail",
    "DataFieldTemplateType": "Text",
    "DataFieldType": "Literal",
    "IsCampaignField": false,
    "ListOptions": []
  },
  {
    "IsRequired": false,
    "IsVisible": true,
    "Scope": "Corporate",
    "Label": "Organization name",
    "SortOrder": 0,
    "DataFieldId": 70,
    "DataFieldName": "Organization name",
    "DataFieldTemplateType": "Text",
    "DataFieldType": "Literal",
    "IsCampaignField": false,
    "ListOptions": []
  },
  {
    "IsRequired": true,
    "IsVisible": true,
    "Scope": "Corporate, Private",
    "Label": "First Name",
    "SortOrder": 0,
    "DataFieldId": 71,
    "DataFieldName": "First name",
    "DataFieldTemplateType": "Text",
    "DataFieldType": "Literal",
    "IsCampaignField": false,
    "ListOptions": []
  },
  {
    "IsRequired": true,
    "IsVisible": true,
    "Scope": "Corporate, Private",
    "Label": "Last Name",
    "SortOrder": 0,
    "DataFieldId": 72,
    "DataFieldName": "Last name",
    "DataFieldTemplateType": "Text",
    "DataFieldType": "Literal",
    "IsCampaignField": false,
    "ListOptions": []
  },
  {
    "IsRequired": true,
    "IsVisible": true,
    "Scope": "Corporate, Private",
    "Label": "Address",
    "SortOrder": 0,
    "DataFieldId": 79,
    "DataFieldName": "Customer Address",
    "DataFieldTemplateType": "Text",
    "DataFieldType": "Literal",
    "IsCampaignField": false,
    "ListOptions": []
  },
  {
    "IsRequired": true,
    "IsVisible": true,
    "Scope": "Corporate, Private",
    "Label": "Postal Code",
    "SortOrder": 0,
    "DataFieldId": 80,
    "DataFieldName": "Customer Postal Code",
    "DataFieldTemplateType": "Text",
    "DataFieldType": "Literal",
    "IsCampaignField": false,
    "ListOptions": []
  },
  {
    "IsRequired": true,
    "IsVisible": true,
    "Scope": "Corporate, Private",
    "Label": "City",
    "SortOrder": 0,
    "DataFieldId": 81,
    "DataFieldName": "Customer City",
    "DataFieldTemplateType": "Text",
    "DataFieldType": "Literal",
    "IsCampaignField": false,
    "ListOptions": []
  }
]

4.6 Register the trade-in

To register an FTI device return, use the POST /api/v2/fti/return/register-trade-in endpoint. The request body must include the FpcTransactionProductId, the PriceQuoteId obtained in Section 4.3, the DeviceIdentifier, and all required customer data fields.

Example request:

{
  "FpcTransactionProductId": 56471, // from GET /api/v2/fti/transactions/{ftiTransactionId}
  "PriceQuoteId": "4a9565e7-fc49-4ae6-a368-a700fd563e0f",
  "DeviceIdentifier": "11542344586944", // GET /api/v2/fti/transactions/{ftiTransactionId}
  "CustomDataFields": [
    {
      "DataFieldId": 71,
      "DataFieldValue": "Mari"
    },
    {
      "DataFieldId": 72,
      "DataFieldValue": "Maasikas"
    },
    {
      "DataFieldId": 25,
      "DataFieldValue": "12345678"
    },
    {
      "DataFieldId": 26,
      "DataFieldValue": "test@test.test"
    },
    {
      "DataFieldId": 80,
      "DataFieldValue": "60534"
    },
    {
      "DataFieldId": 79,
      "DataFieldValue": "Killustiku põik 1"
    },
    {
      "DataFieldId": 81,
      "DataFieldValue": "Tartu"
    }
  ],
  "IsCorporate": false,
  "AgentId": "string", // Optional
  "AgentRef": "string", // Optional
  "LocationId": 0, // Optional
  "LocationRef": "string", // Optional
  "TradeInRef": "string", // Optional
  "ClientSignature": "string", // Optional
  "AgentSignature": "string" // Optional
}

Example response:

{
  "Id": 9282001, // You need this for creating shipment
  "CreatedDate": "2026-09-15T08:42:13.9632748Z",
  "TradeInDevices": [
    {
      "IsAgreedCondition": false,
      "MonthsPassed": 0,
      "IsLatestProduct": false,
      "TradeInDeviceId": 9282002,
      "DeviceIdentifier": "11542344586944",
      "PriceQuoteId": "4a9565e7-fc49-4ae6-a368-a700fd563e0f",
      "ProductName": "Apple iPhone 16 128GB",
      "Grade": "Working",
      "Price": 40,
      "CurrencyIsoCode": "EUR",
      "CurrencySymbol": "€",
      "ExchangeRate": 1
    }
  ],
  "Status": "Registered",
  "CustomDataFields": [
    {
      "DataFieldId": 71,
      "DataFieldValue": "Mari"
    },
    {
      "DataFieldId": 72,
      "DataFieldValue": "Maasikas"
    }
  ]
}

4.7 Shipping and tracking

There are two options for creating the shipment and shipping label:

Automatic creation – Foxway configures the integration so that the shipment and shipping label are created automatically when the returnable device is registered.
Manual creation – The integration partner creates the shipment and shipping label by calling the required API endpoints.

4.7.1 Shipment creation

If you choose the second option, use the POST /api/v2/retail/shipments/tradein/{tradeInId} endpoint to create the shipment for the returnable device. This request requires the tradeInId, which is returned in the response from the previous step.

Example request (1):

{
  "PackageName": "Test package", // Optional
  "ShipmentName": "Test shipment", // Optional
  "PackageIdentifier": "123456", // Optional
  "TrackingNumber": "Track12345", // Optional
  "AgentId": "2a51ef0e-5be7-4568-8c85-a897d67decbc", // Optional
  "AgentRef": "API", // Optional
  "LocationId": 29135, // Optional
  "LocationRef": "API" // Optional
}

Example request (2):

{} // If the request body is empty, the system takes the data assigned to the API key in use

Example response:

{
  "PackageId": 2058177, 
  "ShipmentId": 1928482 // You need this for shipping label creation
}

4.7.2 Shipping label creation

Once the shipment has been created, use the POST /api/v2/retail/shipments/{shipmentId}/label endpoint to generate the shipping label. This request requires the ShipmentId returned by the shipment creation endpoint.

Example request:

https://api--uat.qa.rc.foxway.dev/api/v2/retail/shipments/1928482/label

Example request body (1):

{
  "LocationId": 29135, // Optional
  "LocationAddress": { // Optional
    "CountryCode": "EE",
    "City": "Tartu",
    "PostCode": "60534",
    "Street1": "Killustiku Põik 1",
    "PhoneNumber": "12345678"
  },
  "PickupDate": "2026-09-16T07:36:05.336Z" // Optional
}

Example request body (1):

{}

Example response:

{
  "DownloadUrl": "/api/v2/retail/shipments/1928482/label"
}

To download the label, use the GET /api/v2/retail/shipments/{shipmentId}/label endpoint.

Example request:

https://api--uat.qa.rc.foxway.dev/api/v2/retail/shipments/1928482/label

4.7.3 Shipment details

Use the GET /api/v2/retail/shipments/{shipmentId} endpoint to retrieve additional information about the shipment, such as the tracking number, shipment status, and other shipment details.

Example request:

https://api--uat.qa.rc.foxway.dev/api/v2/retail/shipments/1928482

Example response:

{
  "Id": 1928482,
  "Name": "Test shipment",
  "Identifier": "SALWQERGX4S",
  "TrackingNumber": "00370733748785620611",
  "Location": "API",
  "LocationId": 29135,
  "LocationRef": "API",
  "AgentName": "API User",
  "AgentId": "2a51ef0e-5be7-4568-8c85-a897d67decbc",
  "AgentRef": "API",
  "CreatedDate": "2026-09-16T07:31:47.4490895Z",
  "Status": "Ready",
  "Packages": [
    {
      "Id": 2058177,
      "Name": "Test package",
      "Identifier": "123456",
      "Location": "API",
      "LocationId": 29135,
      "LocationRef": "API",
      "AgentName": "API User",
      "AgentRef": "API",
      "AgentId": "2a51ef0e-5be7-4568-8c85-a897d67decbc",
      "CreatedDate": "2026-09-16T07:31:47.3738338Z",
      "Status": "Packed",
      "Content": [
        {
          "TradeInDeviceId": 9282002,
          "DeviceIdentifier": "11542344586944",
          "ProductName": "Apple iPhone 16 128GB",
          "Grade": "Working",
          "Price": 40,
          "CurrencyIsoCode": "EUR",
          "CurrencySymbol": "€",
          "ExchangeRate": 1,
          "Status": "Shipment Created",
          "TradeInId": 9282001,
          "TradeInDate": "2026-09-15T08:42:13.9632748Z",
          "AgentName": "API User",
          "LocationId": 29135,
          "Location": "API",
          "ReportingStatusId": 50
        }
      ]
    }
  ]
}

4.7.4 Returned device details

Use the GET /api/v2/retail/tradeins/{tradeInId} endpoint to retrieve the details of the returned device. The tradeInId is required for this request.

Example request:

https://api--uat.qa.rc.foxway.dev/api/v2/retail/tradeins/9282001

Example response:

{
  "Id": 9282001,
  "TradeInRef": "",
  "IsCorporate": false,
  "CustomerName": "Mari Maasikas",
  "CampaignOfferAdjustment": 0,
  "CustomDataFields": [
    {
      "DataFieldId": 71,
      "DataFieldValue": "Mari"
    },
    {
      "DataFieldId": 72,
      "DataFieldValue": "Maasikas"
    }
  ],
  "TradeInDevices": [
    {
      "Id": 9282002, // Use this for GET /api/v2/retail/tradeins/devices to get more details
      "DeviceIdentifier": "11542344586944",
      "ProductName": "Apple iPhone 16 128GB",
      "Grade": "Working",
      "Price": 40,
      "ManufacturerId": 116,
      "ManufacturerName": "Apple",
      "PriceWithVAT": 40,
      "CurrencyIsoCode": "EUR",
      "CurrencySymbol": "€",
      "ExchangeRate": 1,
      "Status": "Registered",
      "ReportingStatus": "Shipment Created", // The status to track the device
      "ReportingStatusId": 50,
      "PackageId": 2058177,
      "PackageIdentifier": "123456",
      "ShipmentId": 1928482,
      "ShipmentIdentifier": "SALWQERGX4S",
      "GradingFormJson": "{\"GradingFormVersion\":5792,\"MappingId\":14700,\"Vendor\":{\"GradingDifferenceImages\":{\"0\":[],\"1\":[],\"2\":[],\"3\":[]},\"GradingDiscrepancyReasonId\":null,\"Answers\":{\"0\":[0],\"1\":[0],\"2\":[0],\"3\":[0]},\"Extras\":[],\"SystemExtras\":[1]},\"Partner\":null,\"Affiliate\":null}",
      "VendorGradingDifferenceImages": [],
      "ItemVariantId": 67911,
      "ItemGroupId": 1,
      "SavedCO2": 49
    }
  ],
  "LocationId": 29135,
  "AgentId": "2a51ef0e-5be7-4568-8c85-a897d67decbc",
  "AgentName": "API User",
  "CreatedDate": "2026-09-15T08:42:13.9632748Z",
  "Status": "Registered",
  "TotalVATPrice": 40,
  "TradeInTypeId": 3
}

To retrieve more detailed information about the returned device, including the Foxway evaluation results, use the GET /api/v2/retail/tradeins/devices endpoint. This request should be filtered using the trade-in device Id (see the previous example).

Example request:

https://api--uat.qa.rc.foxway.dev/api/v2/retail/tradeins/devices?id=9282002&limit=500

Example response:

{
  "Data": [
    {
      "TradeInDeviceId": 9282002,
      "CurrencyIsoCode": "EUR",
      "ExchangeRate": 1,
      "ReportingStatus": "Processed", // Use this status for tracking
      "VendorDeviceInfo": {
        "DeviceIdentifier": "11542344586944",
        "ProductName": "Apple iPhone 16 128GB",
        "CP": 40,
        "CP_WithVAT": 40,
        "CBP": 396,
        "VEP": 40,
        "VBP": 440,
        "Grade": "Working",
        "ManufacturerId": 116,
        "ManufacturerName": "Apple",
        "ItemVariantId": 67911,
        "ItemGroupId": 1
      },
      "PartnerDeviceInfo": { // Appears after Foxway has evaluated the device
        "DeviceIdentifier": "505056749189850",
        "ProductName": "Apple iPhone 16 128GB",
        "CP": 40,
        "CP_WithVAT": 40,
        "CBP": 396,
        "VEP": 40,
        "VBP": 440,
        "Grade": "Faulty",
        "ManufacturerId": 116,
        "ManufacturerName": "Apple",
        "ItemVariantId": 67911,
        "ItemGroupId": 1
      },
      "Status": 55,
      "StatusTimestamp": "0001-01-01T00:00:00",
      "TradeInId": 9282001,
      "TradeInDate": "2026-09-15T08:42:13.9632748Z",
      "AgentName": "API User",
      "LocationId": 29135,
      "Location": "API",
      "DataFields": [],
      "PackageId": 2058177,
      "PackageIdentifier": "123456",
      "ShipmentId": 1928482,
      "ShipmentIdentifier": "SALWQERGX4S",
      "GradingFormJson": "{\"GradingFormVersion\":5792,\"MappingId\":14700,\"Vendor\":{\"GradingDifferenceImages\":{\"0\":[],\"1\":[],\"2\":[],\"3\":[]},\"GradingDiscrepancyReasonId\":null,\"Answers\":{\"0\":[0],\"1\":[0],\"2\":[0],\"3\":[0]},\"Extras\":[],\"SystemExtras\":[1]},\"Partner\":{\"GradingDifferenceImages\":{\"0\":[],\"1\":[],\"2\":[\"https://cdn-test.uat.rc.foxway.dev/imagestorage/GradingDifferenceImage/f0d78892-09ee-4818-81d3-598bb2ee2a96.jpg\"]},\"GradingDiscrepancyReasonId\":null,\"Answers\":{\"0\":[0],\"1\":[0],\"2\":[1]},\"Extras\":[],\"SystemExtras\":[]},\"Affiliate\":null}",
      "VendorGradingDifferenceImages": [],
      "PartnerGradingDifferenceImages": [
        "https://cdn-test.uat.rc.foxway.dev/imagestorage/GradingDifferenceImage/f0d78892-09ee-4818-81d3-598bb2ee2a96.jpg"
      ],
      "PurchaseOrderId": 648198
    }
  ]
}

5 Statuses

This section describes the statuses used throughout the FTI transaction and device return process. Please note that not all statuses are currently used, and additional statuses may be introduced or existing ones may change in future releases.

5.1 FTI transaction statuses (will be modified)

Pending – The initial status assigned to newly created transactions. It remains active during the remorse return period, during which the transaction can still be canceled. Transactions created via the API are initially assigned this status.

Confirmed – Assigned once the remorse return period has ended. This status indicates that the transaction can no longer be canceled. The transition to this status can be automated.

Canceled – Indicates that the transaction has been canceled, either because it was registered by mistake or because the customer exercised their right to return the product during the remorse return period.

Returned – Indicates that the FTI product has been returned after the minimum return period and the associated trade-in has been registered. (Not yet available.)

Expired – Indicates that the maximum return period has elapsed without the product being returned. The rented device can now be traded in through any supported channel or partner. (Not yet available.)

5.2 Trade-in device reporting statuses

ReportingStatus	Explanation
Registered	Trade In has been registered
Packed	Trade In device has been added to package in retail tool
Shipment Created	Package that contains trade in device has been added to shipment
Shipped	Shipment has been handed over to courier, devices in transit
Delivered	Trade In device has reached its final destination according to tracking number
Processed	Trade in device has been regraded by Foxway with expected (or higher) results
Processed/OnHold	Trade in device has been regraded by Foxway with worse results, customer is notified via email and expected to take action (confirm/decline new offer)
Processed/Confirmed	User confirms the new price offer
Processed/Declined	User declines the new price offer
Returned	Trade in device is returned to the customer, e/g after customer has declined the new price offer
Expired	Trade in device has not been sent to Foxway within time period (configurable)
Canceled	Trade in has been canceled
Processed/WaitingForReturn	Trade in device has been regraded in Luna, but for some reason is waiting to be returned to customer

Online FTI API best practices

Table of contents

1 Introduction

2 Product catalog

2.1 Create a product catalog

2.2. Update the product catalog

3 FTI transaction creation

3.1 Get residual values

3.2 Get configured data fields

3.3 Register an FTI transaction

3.4 Update the FTI transaction

3.5 Import FTI transactions

3.6 Set transactions to the Confirmed status

4 Return flow

4.1 Cancel an FTI transaction

4.2 Get the corresponding grading form

4.3 Get the price quote

4.4 Due diligence check (if applicable)

4.5 Get configured data fields

4.6 Register the trade-in

4.7 Shipping and tracking

4.7.1 Shipment creation

4.7.2 Shipping label creation

4.7.3 Shipment details

4.7.4 Returned device details

5 Statuses

5.1 FTI transaction statuses (will be modified)

5.2 Trade-in device reporting statuses

Search

Table of contents

1 Introduction

2 Product catalog

2.1 Create a product catalog

2.2. Update the product catalog

3 FTI transaction creation

3.1 Get residual values

3.2 Get configured data fields

3.3 Register an FTI transaction

3.4 Update the FTI transaction

3.5 Import FTI transactions

3.6 Set transactions to the Confirmed status

4 Return flow

4.1 Cancel an FTI transaction

4.2 Get the corresponding grading form

4.3 Get the price quote

4.4 Due diligence check (if applicable)

4.5 Get configured data fields

4.6 Register the trade-in

4.7 Shipping and tracking

4.7.1 Shipment creation

4.7.2 Shipping label creation

4.7.3 Shipment details

4.7.4 Returned device details

5 Statuses

5.1 FTI transaction statuses (will be modified)

5.2 Trade-in device reporting statuses