Foxway's trade-in solution is designed to seamlessly integrate into your existing systems, whether it's an online store, in-store point of sale (POS), or another business platform. By connecting with the Foxway Vendor API, you can enable a smooth trade-in experience for your customers, from device identification to final registration. This article outlines the key steps and best practices to integrate the Foxway trade-in solution using our Vendor API.
For a more detailed overview of the Vendor API, comprehensive Swagger documentation is available here. If you require any assistance during the integration, please contact your account manager or technical contact.
Integration Steps Overview:
- Obtain API Access
- Device Identification
- Device Condition and Price Lookup
- Due Diligence Checks
- Trade-in Registration
- Campaigns
- Shipping Functions
Integration Steps:
1. Obtain API Access
To begin, you will need the necessary credentials, including the API key and base URL. These will be provided by your assigned technical contact. Both production and development environments are supported, allowing you to test and fine-tune the integration before going live.
2. Device Identification
The first step in the trade-in process is identifying the device the customer wants to trade. The API supports multiple ways of identifying a device:
- IMEI for mobile devices and tablets
- Serial number for products without IMEI
- Search by product name or code (e.g., "iPhone Xs Max")
Once identified, you can use the /api/v2/retail/models endpoint to retrieve the relevant device data, including model information and initial trade-in values. This ensures that the customer is presented with accurate trade-in pricing for their specific device.
Read more about best practices for device identification integration in the Best Practices article.
3. Device Condition and Price Lookup
To determine the trade-in price, you must evaluate the condition of the device. Use the /api/v2/retail/models/{id}/grading-form endpoint to present the customer with a series of condition-related questions (e.g., whether the device turns on, the condition of the screen). Based on the responses, the API will calculate the device's value using the /api/v2/retail/price-quote endpoint.
It's recommended to initially show the customer the maximum possible value for a fully functional device and adjust the pricing based on their inputs regarding the device's condition.
Read more about best practices for device condition and price lookup integration in the Best Practices article.
4. Due Diligence Checks
Before finalizing the trade-in, Foxway performs necessary due diligence checks, including:
- iCloud lock verification for Apple devices
- Blacklist checks to ensure the device is not reported lost or stolen
These checks are handled using the /api/v2/retail/duediligence/check and /api/v2/retail/duediligence/report/{reportId} endpoints. Any issues, such as a failed fraud check, should prevent the trade-in from proceeding.
Read more about best practices for due diligence integration in the Best Practices article.
5. Trade-in Registration
Once the device is identified, graded, and passed due diligence checks, you can register the trade-in using the /api/v2/retail/tradeins endpoint. This step confirms the trade-in and assigns it a unique ID for tracking.
If you offer online trade-ins where the device needs further inspection (e.g., at a central warehouse), you can register a temporary trade-in using the same endpoint with a "temp" parameter. This allows initial value estimation while keeping the final value flexible pending in-person grading.
Read more about best practices for trade-in registration integration in the Best Practices article.
6. Campaigns
Foxway's API supports trade-in campaigns, allowing you to apply promotions or bonuses during the trade-in process. To retrieve active campaigns, use the /api/v2/retail/campaigns/list endpoint, and apply the campaign details when calculating trade-in prices. Only one campaign can be used per trade-in.
Read more about best practices for campaigns integration in the Best Practices article.
7. Shipping Functions
Once the trade-in is registered, the device will need to be sent for processing. You can use the shipping functionality in the API to create packages, shipments, and even generate shipping labels. The /api/v2/retail/packages and /api/v2/retail/shipments endpoints help manage this process, allowing for smooth logistics handling from the customer's location to Foxway's facilities.
Read more about best practices for shipping functions integration in the Best Practices article.