Setup return feed for Fit Advisor to integrate with your custom e-comm platform using SFTP
Before you begin
If you are using a 3rd party e-comm platform (Shopify, BigCommerce, etc) then please refers to those docs for setting up your return feed.
Requirements
- Return feed in either JSON (ndjson) or CSV file format
- Ability to push files (daily) over SFTP
SFTP Transfer
- Transfer is expected to be pushed daily with full set of returns (does not need to be a diff of changes).
- We will need a public key and IPs to whitelist
Return feed file formats
Both JSON and CSV file formats are accepted formats to push return feed to Fit Advisor platform. Typically this will depend on how returns are stored in your platform or what available formats are already being exported. The benefit to JSON is that return data can remain structured and does not need to be flattened (denormalized) into variants resulting in a larger amount of data to sync.
Using JSON (preferred)
- Important to note that the expected file format is ndjson where each file line is a json object.
Return format
|
id string |
"id":"1234541223232" Unique identifier for the return for API/backend purposes. |
|
returnCreatedAt string |
"returnCreatedAt":"2012-02-15T15:12:21-05:00" Return created timestamp in ISO 8601 format |
|
returnUpdatedAt string |
"returnUpdatedAt":"2012-02-15T15:12:21-05:00" Return updated timestamp in ISO 8601 format |
|
total number |
"total":85.30 Total price of items being processed for return or exchange |
|
currency string |
"currency":"USD" 3-digit currency code (ISO 4217) |
|
orderId string |
"orderId":"123124121212" Unique identifier for the order being returned. This may be different than the orderId created during the purchase if the return platform is separate from the ecomm platform. |
|
orderName String (optional) |
"orderName":"Order 1234" Human-friendly name for order being returned |
|
providerOrderId string |
"providerOrderId":"14124124124124" Matching identifier used in orderId when order was created |
|
orderNumber string |
"orderNumber":"14232" Matching value using in orderNumber when order was created |
|
returnProductTotal number |
"returnProductTotal":45.50 Total price of items being returned (but not exchanged) |
|
exchangeProductTotal number |
"exchangeProductTotal":10.50 Total price of items being exchanged (but not returned) |
|
refund number |
"refund":5.00 Total amount refunded to shopper including (returned items and/or exchanged for lesser value item) |
Return line item format
|
lineItemId string |
"lineItemId":"1234541223232" Unique identifier for the line item being returned. This may be different than the lineItemId created during the purchase if the return platform is separate from the ecomm platform. |
|
providerLineItemId number |
"providerLineItemId":"4444514242332" Unique identifier for line item that matches lineItemId when order was created |
|
productId string |
"productId":"1124124214124" Matching identifier from product feed for productId |
|
variantId string |
"variantId":"1515252524223" Matching identifier from product feed for variantId |
|
sku string |
"sku":"SHR-L-30-BLK" Matching SKU from product feed |
|
title string |
"title":"Men's Shirt" Title or name of product being processed |
|
price number |
"price":56.00 Subtotal of product being processed |
|
quantity number |
"quantity":3 Number of variant returned |
|
returnedAt string |
"returnedAt":"2012-02-15T15:12:21-05:00" Return completed timestamp in ISO 8601 format. |
|
exchangeVariant string (optional) |
"exchangeVariant":"515224223232" If exchanged, include variantId. Typical when returning for alternate size or color. |
|
returnReason string |
"returnReason":"Return reason" Selected reason for return |
|
parentReturnReason string |
"parentReturnReason":"Parent return reason" Parent return reason for a category of return reasons. I.e. Fit |
Using CSV
- Flat files (denormalized) in csv format using data format below.
- Each row represents a variant. I.e. a return with 10 variants would be represented as 10 rows with returnId repeated in each row.
Return format (return line item variant per row):
|
returnId string |
returnId":"1234541223232" Unique identifier for the return for API/backend purposes. |
|
returnCreatedAt string |
"returnCreatedAt":"2012-02-15T15:12:21-05:00" Return created timestamp in ISO 8601 format |
|
returnUpdatedAt string |
"returnUpdatedAt":"2012-02-15T15:12:21-05:00" Return updated timestamp in ISO 8601 format |
|
total number |
"total":85.30 Total price of items being processed for return or exchange |
|
currency string |
"currency":"USD" 3-digit currency code (ISO 4217) |
|
quantity number |
"quantity":3 Number of variant returned |
|
orderId string |
"orderId":"123124121212" Unique identifier for the order being returned. This may be different than the orderId created during the purchase if the return platform is separate from the ecomm platform. |
|
orderName String (optional) |
"orderName":"Order 1234" Human-friendly name for order being returned |
|
providerOrderId string |
"providerOrderId":"14124124124124" Matching identifier used in orderId when order was created |
|
providerOrderNumber string |
"providerOrderNumber":"14232" Matching value using in orderNumber when order was created |
|
returnProductTotal number |
"returnProductTotal":45.50 Total price of items being returned (but not exchanged) |
|
exchangeProductTotal number |
"exchangeProductTotal":10.50 Total price of items being exchanged (but not returned) |
|
refund number |
"refund":5.00 Total amount refunded to shopper including (returned items and/or exchanged for lesser value item) |
|
lineItemId string |
"lineItemId":"1234541223232" Unique identifier for the line item being returned. This may be different than the lineItemId created during the purchase if the return platform is separate from the ecomm platform. |
|
providerLineItemId number |
"providerLineItemId":"4444514242332" Unique identifier for line item that matches lineItemId when order was created |
|
lineItemProductId string |
"lineItemProductId":"1124124214124" Matching identifier from product feed for productId |
|
lineItemVariantId string |
"lineItemVariantId":"1515252524223" Matching identifier from product feed for variantId |
|
lineItemSku string |
"lineItemSku":"SHR-L-30-BLK" Matching SKU from product feed |
|
lineItemTitle string |
"lineItemTitle":"Men's Shirt" Title or name of product being processed |
|
lineItemPrice number |
"lineItemPrice":56.00 Subtotal of product being processed |
|
lineItemReturnedAt string |
"lineItemReturnedAt":"2012-02-15T15:12:21-05:00" Return completed timestamp in ISO 8601 format. |
|
lineItemExchangeVariant string (optional) |
"lineItemExchangeVariant":"515224223232" If exchanged, include variantId. Typical when returning for alternate size or color. |
|
lineItemReturnReason string |
"lineItemReturnReason":"Return reason" Selected reason for return |
|
lineItemParentReturnReason string |
"lineItemParentReturnReason":"Parent return reason" Parent return reason for a category of return reasons. I.e. Fit |