Return feed setup - Custom platform

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