API Documentation

The Faslet API gives you direct access to provide data, without having to go through third party services.

tip

Access to our APIs is available to customers on certain tiers. If you're in doubt, please reach out to your Faslet representative.

API Base Url

The Faslet public API is versioned under

https://api.faslet.net/public

Current versions documented on this page:

https://api.faslet.net/public/v1
https://api.faslet.net/public/v2

If you'd like sandbox/staging environment to test against, please reach out to support, so we can create a test store.

Authorization

Include the custom header faslet-shopid set to your Faslet Shop ID. Your API token can be found in the Faslet Partner Portal. This needs to be included as a Bearer token with the authorization header.

The /public/v2/assistant/context and /public/v2/assistant/size-me endpoints use the same public API authorization middleware as the rest of the public API. The faslet-shopid header is also how the API receives retailer context for these requests.

Endpoints

All formats, request and response are JSON. Be sure to include the application/json content header.

Example headers:

"Content-Type" "application/json",
"faslet-shopid": "MY_SHOP_ID",
"authorization": "Bearer MY_API_TOKEN"

POST /returns

https://api.faslet.net/public/v1/returns

Request Body

An Array of Product Info

Product Info

Field	Required	Type	Description
orderId	YES	string	The identifier of the order
productId	YES	string	The identifier of the product. This should match the product id send to Faslet with the orders and the button
sku	YES	string	The variant SKU
returnDate	YES	string	ISO8601 Date Time
returnReason	YES	string	The return reason value as described below
returnReasonMessage	NO	string	A message for the return reason. This can be the message sent by the customer
externalId	NO	string	The ID of the return in your system

Example Request

[{
        "orderId": "1234",
        "productId": "1234",
        "sku": "1234",
        "returnReason": "1",
        "returnDate": "2022-02-05T18:40:00.000Z",
        "externalId": "o-123"
}, {
        "orderId": "3456",
        "productId": "3456",
        "sku": "3456",
        "returnReason": "3",
        "returnDate": "2022-09-05T18:40:00.000Z",
        "externalId": "o-345"
}]

Return reasons

Reason	Value
Too big	1
Too small	2
Product is damaged	3
Product isn’t as expected	4
Wrong article/ size	5
Color isn’t as expected	6
Quality isn’t as expected	7
Other reason	8
Multiple sizes ordered	9

Response

StatusCodes

Status	Description
202	The request was accepted.

Body

Field	Required	Type
errors	YES	Array of Return Error

Return Error

Field	Type	Description
message	string	The error message

Example Response

{
    "errors": [
        {
            "message": "returnDate is invalid for order 1234"
        }
    ]
}

POST /orders

https://api.faslet.net/public/v1/orders

Request Body

An Order Event

Order Event

Field	Required	Type	Description
customerDataPackage	YES	string	The customer data package obtained from the faslet-orders script
orderId	YES	string	The identifier of the order
paymentStatus	YES	string	The payment status of the order
lineItems	YES	array	Array of Line Items

Line Item

Field	Required	Type	Description
productId	YES	string	The identifier of the product
title	YES	string	The title of the product
variantId	YES	string	The identifier of the variant
sku	YES	string	The SKU of the variant
variant	YES	string	The variant description
quantity	YES	number	The quantity ordered
price	YES	number	The price of the item

Example Request

{
    "orderId": "1234",
    "paymentStatus": "paid",
    "lineItems": [{
        "productId": "1234",
        "title": "Test API Order",
        "variantId": "1234",
        "sku": "1234",
        "variant": "S",
        "quantity": 1,
        "price": 123.45
    }],
  "customerDataPackage": "yX2lkIjoibm8tdXNlci1kYXRhIiwiaGFzVXNlZFdpZGdldCI6ZmFsc2UsInBsYXRmb3JtIjoidW5rbm93biIsImV4cGVyaW1lbnRWYXJpYW50cyI6W119"
}

Getting the Customer Data Package

To obtain the customerDataPackage, include the faslet-orders script somewhere before the end of the checkout flow:

<script src="https://widget.faslet.net/faslet-orders.js"></script> 
<script>
  var fasletCustomerDataPackage = window._faslet_orders.getCustomerDataPackage(MY_SHOP_ID)
  /* Send fasletCustomerDataPackage to your backend to be used in the API request */
</script>

POST /size-specs

https://api.faslet.net/public/v1/size-specs/MY_BRAND

Request Parameters

Field	Required	Type	Description
brand	YES	string	Then name of the brand for this size specification

Request Body

An Array of Product Size Descriptors

Product Size Descriptor

Field	Required	Type	Description
productName	YES	string	The name or title of the product.
productId	YES	string	The identifier of the product. This should match the product id send to Faslet with the orders and the button
gender	YES	string	The gender of the product. Must be `male`, `female` or `unisex`
productUrl	YES	string	The url of the product as found on the store
sizeChartSpecifications	YES	string	An array of size specifications

Size Chart Specification

Field	Required	Type	Description
sizeLabel	YES	string	The size label of the variant.
useDefaults	NO	boolean	Whether this variant should use default size charts as provided by Faslet.
waist	NO	number	The minimum measurement of the waist for this size label.
hips	NO	number	The minimum measurement of the hips for this size label.
chest	NO	number	The minimum measurement of the chest for this size label.
innerLeg	NO	number	The minimum measurement of the innerLeg for this size label.
length	NO	number	The minimum measurement of the length for this size label.
sleeve	NO	number	The minimum measurement of the sleeve for this size label.
thigh	NO	number	The minimum measurement of the thigh for this size label.
shoulder	NO	number	The minimum measurement of the shoulder for this size label.
waistStretched	NO	number	The maximum measurement of the waist for this size label.
hipsStretched	NO	number	The maximum measurement of the hips for this size label.
chestStretched	NO	number	The maximum measurement of the chest for this size label.

If you choose not to use defaults, please provide as much of this information as possible in order to get the most accurate size charts. Our algorithms will process these and optimize them based on how much information is given.

Example Request

[{
  "productName": "Jacket",
  "productId": "11",
  "gender": "male",
  "productUrl": "https://mywebstore.com/en/jacket.html",
  "sizeChartSpecifications": [{
    "useDefaults": false,
    "waist": 60,
    "waistStretched": 70,
    "hips": 50,
    "hipsStretched": 56,
    "chest": 65,
    "sizeLabel": "S"
  }, {
    "waist": 63,
    "hips": 53,
    "chest": 68,
    "sizeLabel": "M"
  }, {
    "waist": 68,
    "hips": 58,
    "chest": 73,
    "sizeLabel": "XL",
    "useDefaults": false
  }]
}]

Response

StatusCodes

Status	Description
201	New size specifications were created.
200	Existing size specifications were updated.

Body

Field	Required	Type
errors	NO	Array of Return Error. In the case of a 2xx response, with some (or all) size specifications skipped, a list of errors will be provided
error	NO	A Return Error. In the case of a 4xx response, a single error will be returned and nothing will be processed

Return Error

Field	Type	Description
message	string	The error message

Example Response

{
    "errors": [
        {
            "message": "[Item 42] No Product URL, ignoring"
        },
        {
            "message": "[Item 76] No Product ID, ignoring"
        }
    ]
}

info

Errors in individual Size Chart Specifications will not prevent everything from processing. The error will list the index of the descriptor that failed. These will return a 2xx status code and can be safely retried after fixing the errors.

Errors in the Product Size Descriptors will prevent processing and will return a 4xx status code.

POST /assistant/state/

🚧Preview

Note that this API is currently in preview. While we don't expect anything to change, please contact us before using it. We will work together to ensure a smooth transition to the final version.

https://api.faslet.net/public/v1/assistant/state/MY_BRAND

Request Parameters

Field	Required	Type	Description
brand	YES	string	Then name of the brand for this size specification

Query String Parameters

Field	Required	Type	Description
disableTracking	No	boolean	Set this to true if you want to disable all analytics. This will prevent any data from going into the Faslet Partner Portal, and will stop the system from being able to adjust automatically.

Request Body

Field	Required	Type	Description
productId	YES	string	The unique identifier for the product
variants	YES	Array of Variant	List of product variants
productName	NO	string	The name of the product
productUrl	NO	string	The URL of the product
productImage	NO	string	The URL of the product image
userId¹	NO	string	The unique identifier for the user
widgetVersion¹	NO	string	The version of the widget being used
seenExperiments¹	NO	string	The experiments the user has seen
experimentVariants¹	NO	string	The variants of the experiments the user has been exposed to
profile¹	NO	Profile	The profile of the user

¹obtained from the Faslet Javascript onDataChanged callback

Variant

Field	Required	Type	Description
sizeLabel	YES	string	The label of the size for this variant
available	YES	boolean	Indicates if the variant is available for purchase/in stock
variantId	YES	string	The unique identifier for this variant

Example Requests

An initial request before getting user data from the assistant may look like this:

{
  "productId": "11",
  "variants": [{
    "sizeLabel": "S",
    "available": true,
    "variantId": "1234"
  }, {
    "sizeLabel": "M",
    "available": true,
    "variantId": "5678"
  }]
}

Subsequent requests after getting user data from the assistant may look like this:

{
  "productId": "11",
  "variants": [{
    "sizeLabel": "S",
    "available": true,
    "variantId": "1234"
  }, {
    "sizeLabel": "M",
    "available": true,
    "variantId": "5678"
  }],
  "userId": "1234",
  "widgetVersion": "v35.0.3",
  "seenExperiments": "exp1,exp2",
  "experimentVariants": "exp1_variant1,exp2_variant2",
  "profile": {
    "gender": "male",
    "height": 180,
    "weight": 85,
    "age": 29   
    ...
  }
}

Response

StatusCodes

Status	Description
200	The endpoint returned a state result

Body

Field	Required	Type	Description
state	YES	string	The state of the assistant. Can be `hidden`, `default` or `result`
data	YES	object	When the state is `result`, the data contains the recommened size label as a field called `result`. This also contains a userId which should be used in the widget initialization

Example Response

When a product is not available:

{
    "state": "hidden",
    "data": {
        "userId" "123-456-789"
    }
}

When a product is available:

{
    "state": "default",
    "data": {
        "userId" "123-456-789"
    }
}

When a product is available and a result is available:

{
    "state": "result",
    "data": {
        "result": "M",
        "userId" "123-456-789"
    }
}

Assistant API v2

The Assistant API v2 endpoints support public-facing assistant flows where clients first resolve product and shopper context, then request a size recommendation when the sizeMe capability is available and all required inputs are present.

These endpoints are both POST endpoints under /public/v2:

/assistant/context
/assistant/size-me

Shared request body

Both endpoints use the same request body shape.

https://api.faslet.net/public/v2

Authentication and retailer context

Authenticate with authorization: Bearer MY_API_TOKEN
Provide retailer context with faslet-shopid: MY_SHOP_ID
Send JSON with Content-Type: application/json

Example request

{
  "userId": "user-123",
  "product": {
    "productUrl": "https://shop.example.com/products/example-product",
    "productIdentifier": "sku-123",
    "brand": "Nike",
    "productName": "Example Product",
    "sizeLabels": ["S", "M", "L"]
  },
  "profile": {
    "gender": "female",
    "height": 180,
    "weight": 75,
    "age": 30,
    "hasMadeOrders": false,
    "hasUsedAssistant": true,
    "referenceItems": [],
    "measurements": {
      "fit": 2,
      "waist": 2,
      "hips": 2,
      "chest": 2,
      "footWidth": 2,
      "braCupSize": "C",
      "braBandSize": 75,
      "relativeSizingPreference": 2
    }
  },
  "experiments": {
    "device": "mobile",
    "experimentVariants": "variant-a",
    "seenExperiments": "1,2",
    "newDevice": "newDevice"
  }
}

Top-level fields

Field	Required	Type	Description
userId	NO	string	Optional shopper identifier. If omitted, the backend generates one and returns it in the response.
product	YES	object	Product context used to resolve the assistant state for a product. The `product` object is required and must include at least one product locator.
profile	NO	object	Optional shopper profile data used for capability resolution and sizing.
experiments	NO	object	Optional experiment metadata used for the assistant flow.

`product`

The product object is required, and at least one product locator must be provided:

product.productUrl?: string
product.productIdentifier?: string

Additional supported fields:

brand?: string
productName?: string
sizeLabels?: string[]

Field	Required	Type	Description
productUrl	NO*	string	Product URL used to resolve the product context.
productIdentifier	NO*	string	Product identifier used to resolve the product context.
brand	NO	string	Brand name for the product.
productName	NO	string	Product name or title.
sizeLabels	NO	string[]	Available size labels for the product.

* At least one of productUrl or productIdentifier must be present.

If neither productUrl nor productIdentifier is provided, the API returns:

{
  "status": "invalid_input",
  "message": "product.productUrl or product.productIdentifier is required"
}

`profile`

The current profile.gender contract accepts male and female.

Field	Required	Type	Description
gender	NO	one of: `male`, `female`	Shopper gender, if known.
height	NO	number	Shopper height in centimeters.
weight	NO	number	Shopper weight in kilograms.
age	NO	number	Shopper age in years.
hasMadeOrders	NO	boolean	Whether the shopper has previously placed orders with the store.
hasUsedAssistant	NO	boolean	Whether the shopper has previously used the sizing assistant.
referenceItems	NO	`ReferenceItem[]`	Optional list of items the shopper already wears and knows the size of.
measurements	NO	`AssistantContextMeasurementsInput`	Optional body-shape and sizing-preference inputs.

`profile.referenceItems`

Optional list of known items the shopper already wears.

Field	Required	Type	Description
brand	NO	string	Brand of the reference item.
model	NO	string	Model or product name of the reference item.
size	NO	string	Shopper’s known size in that item.
gender	NO	string	Gender or category of the reference item.

`profile.measurements`

These values are normalized assistant profile inputs, not raw centimeter measurements. Most numeric fields here are small qualitative scales used to describe body shape or fit preference. For the ordinal numeric fields, use values like 1, 2, and 3, where 2 is the average/default value and lower or higher values represent smaller/tighter versus larger/looser selections.

Field	Required	Type	Description
fit	NO	number	Fit preference scale, for example `1`, `2`, `3`, from tighter to looser fit.
waist	NO	number	Waist shape scale, not waist circumference, for example `1`, `2`, `3`, from flatter to rounder waist shape.
hips	NO	number	Hip width scale, not hip circumference, for example `1`, `2`, `3`, from narrower to wider hips.
chest	NO	number	Chest width scale, not chest circumference, for example `1`, `2`, `3`, from narrower to wider chest shape.
footWidth	NO	number	Foot width scale, not a physical width measurement, for example `1`, `2`, `3`, from narrower to wider feet.
braCupSize	NO	string	Bra cup size, for example `B`, `C`, or `D`.
braBandSize	NO	number	Bra band size, for example `75`, `80`, `34`, or `36`, depending on the sizing system used.
relativeSizingPreference	NO	number	Signed sizing preference value. Expected values are typically `-2`, `-1`, `0`, `1`, or `2`, where `0` is neutral. Unlike `waist`, `hips`, `chest`, and similar fields, this is not a body-shape scale.

Guidance for API consumers:

Send height in centimeters and weight in kilograms.
Treat fit, waist, hips, chest, and footWidth as qualitative scales, not exact measurements.
If a field is not known, omit it rather than guessing.
braCupSize and braBandSize are optional and only relevant when bra sizing information is available.

`experiments`

Field	Required	Type	Description
device	NO	one of: `all`, `mobile`, `desktopTablet`	Device bucket used for experiment targeting.
experimentVariants	NO	string	Comma-separated or serialized experiment variant data.
seenExperiments	NO	string	Previously seen experiments.
newDevice	NO	one of: `all`, `newDevice`, `returningDevice`	Whether this device is new or returning.

POST /assistant/context

https://api.faslet.net/public/v2/assistant/context

Purpose

Resolve assistant context for a product and return:

normalized product context
widget configuration
capabilities
experiment metadata

Clients can use /assistant/context to drive UI decisions:

which assistant actions are available
which profile or product inputs still need to be collected
whether virtual try-on can be offered

nextRequiredInputs is intended for progressive input collection flows.

Success response

{
  "status": "resolved",
  "userId": "user-123",
  "productContext": {
    "shopId": "shop-1",
    "brand": "Nike",
    "productIdentifier": "sku-123",
    "productName": "Example Product",
    "productUrl": "https://shop.example.com/products/example-product",
    "virtualTryOnImageUrl": "https://cdn.example.com/image.jpg"
  },
  "widgetConfiguration": {
    "locale": "en",
    "buttonBackgroundColor": "#000000",
    "virtualTryOn": {
      "enabled": true
    }
  },
  "capabilities": {
    "sizeMe": {
      "name": "sizeMe",
      "available": true,
      "requiredInputs": [
        {
          "name": "height",
          "source": "profile",
          "required": true
        }
      ],
      "nextRequiredInputs": []
    },
    "tryOn": {
      "name": "tryOn",
      "available": true,
      "requiredInputs": [
        {
          "name": "userPhoto",
          "source": "profile",
          "required": true
        }
      ],
      "nextRequiredInputs": [
        "userPhoto"
      ]
    }
  },
  "experiments": {
    "activeVariants": [],
    "seenExperiments": []
  }
}

Response fields

`status`

Assistant context execution status. Successful context resolution returns:

resolved

`productContext`

Normalized product context:

Field	Required	Type	Description
shopId	YES	string	Faslet shop identifier.
brand	NO	string	Normalized product brand.
productIdentifier	NO	string	Normalized product identifier.
productName	NO	string	Normalized product name.
productUrl	NO	string	Normalized product URL.
virtualTryOnImageUrl	NO	string	Product image used for virtual try-on.

`widgetConfiguration`

The backend returns a partial widget configuration object for the assistant experience. Supported exposed keys include:

locale
localizationOverrides
buttonBackgroundColor
buttonHeight
buttonFillParent
buttonAlignmentInParent
buttonContentAlignment
fontColor
bodyFontColor
headerFontColor
secondaryFontColor
borderRadius
popupBorderRadius
disableIcon
customIcon
disableBorder
disableUiShadows
disableBackgroundBlur
headerImage
virtualTryOn

`capabilities`

The backend returns capability objects in:

capabilities.sizeMe
capabilities.tryOn

Each capability has this shape:

Field	Required	Type	Description
name	YES	string	Capability name.
available	YES	boolean	Whether the capability can currently be used.
requiredInputs	YES	array	Full list of `AssistantInputRequirement` objects for the capability.
nextRequiredInputs	YES	string[]	Inputs that are still missing in the current request.
reason	NO	string	Human-readable reason when the capability is unavailable.

`AssistantInputRequirement`

{
  "name": "height",
  "source": "profile",
  "required": true
}

Field	Required	Type	Description
name	YES	string	Input name.
source	YES	one of: `profile`, `product`	Where the missing or required input should come from.
required	YES	boolean	Whether the input is required.

Capability semantics

`sizeMe`

Describes whether size recommendation is available for the current product context.

Field	Required	Type	Description
name	YES	`'sizeMe'`	Capability identifier.
available	YES	boolean	`false` when the product does not support Size Me.
requiredInputs	YES	array	Full set of inputs needed to size.
nextRequiredInputs	YES	string[]	Missing inputs for the current request.
reason	NO	string	Example: `Size Me unavailable for this product`.

Behavior:

available is false when the product does not support Size Me
requiredInputs lists the full set of profile inputs needed to size
nextRequiredInputs lists which inputs are still missing for the current request

`tryOn`

Describes whether virtual try-on is available.

Field	Required	Type	Description
name	YES	`'tryOn'`	Capability identifier.
available	YES	boolean	Whether virtual try-on is available.
requiredInputs	YES	array	Full set of inputs needed for try-on.
nextRequiredInputs	YES	string[]	Missing inputs for the current request.
reason	NO	string	Example: `Try-On unavailable for this product`.

Behavior:

a profile photo input is always required for try-on; use requiredInputs and nextRequiredInputs to determine the exact input(s) still needed for the current request
if the product has no virtualTryOnImageUrl, then productImage is also required as a product input

Error cases

Documented non-success cases include:

400 invalid_input when a product locator is missing
widget or product lookup failures mapped from the widget info layer
missing or invalid retailer context

Treat any response where status !== 'resolved' as a non-success result and inspect message plus any returned details.

POST /assistant/size-me

https://api.faslet.net/public/v2/assistant/size-me

Purpose

Generate a size recommendation using the same request body shape as /assistant/context, after product and profile context has been resolved.

Success response

{
  "status": "resolved",
  "userId": "user-123",
  "productContext": {
    "shopId": "shop-1",
    "brand": "Nike",
    "productIdentifier": "sku-123",
    "productName": "Example Product",
    "productUrl": "https://shop.example.com/products/example-product"
  },
  "recommendation": {
    "size": "M"
  }
}

Success response fields

Field	Required	Type	Description
status	YES	`'resolved'`	Successful sizing result.
userId	YES	string	Shopper identifier returned by the backend.
productContext	YES	object	Resolved product context for the sizing request.
recommendation	YES	object	Public sizing response payload.

`recommendation`

Field	Required	Type	Description
size	YES	string	Recommended size label returned by the sizing service.

Failure response

{
  "status": "invalid_input",
  "message": "Missing required profile inputs for size-me",
  "userId": "user-123",
  "productContext": {
    "shopId": "shop-1",
    "brand": "Nike",
    "productIdentifier": "sku-123"
  },
  "requiredInputs": [
    {
      "name": "height",
      "source": "profile",
      "required": true
    }
  ],
  "nextRequiredInputs": ["height"]
}

Failure response fields

Field	Required	Type	Description
status	YES	string	Any non-`resolved` assistant execution status.
message	NO	string	Human-readable error or availability message.
userId	NO	string	Shopper identifier.
productContext	NO	object	Resolved product context when available.
requiredInputs	NO	array	Full list of required inputs for the sizing attempt.
nextRequiredInputs	NO	string[]	Missing inputs for the current request.
details	NO	object	Optional public sizing failure details returned by the backend.

Failure semantics

`invalid_input`

Returned when the request does not contain enough profile information to produce a size recommendation.

Example message:

Missing required profile inputs for size-me

The response includes:

requiredInputs: all inputs needed
nextRequiredInputs: the currently missing ones

`unavailable`

Returned when the product does not support Size Me.

Example message:

Size Me unavailable for this product

Additional non-resolved statuses may be surfaced from downstream widget or sizing failure mappings. Clients should treat any status other than resolved as a non-success result and use message, requiredInputs, nextRequiredInputs, and details to decide how to continue the flow.

Help

In case of any questions, please don’t hesitate to contact us on support@faslet.me

API Base Url​

Authorization​

Endpoints​

Example headers:​

POST /returns​

Request Body​

Product Info​

Example Request​

Return reasons​

Response​

StatusCodes​

Body​

Return Error​

Example Response​

POST /orders​

Request Body​

Order Event​

Line Item​

Example Request​

POST /size-specs​

Request Parameters​

Request Body​

Product Size Descriptor​

Size Chart Specification​

Example Request​

Response​

StatusCodes​

Body​

Return Error​

Example Response​

POST /assistant/state/​

Request Parameters​

Query String Parameters​

Request Body​

Variant​

Example Requests​

Response​

StatusCodes​

Body​

Example Response​

Assistant API v2​

Shared request body​

Authentication and retailer context​

Example request​

Top-level fields​

product​

profile​

profile.referenceItems​

profile.measurements​

experiments​

POST /assistant/context​

Purpose​

Success response​

Response fields​

status​

productContext​

widgetConfiguration​

capabilities​

AssistantInputRequirement​

Capability semantics​

sizeMe​

tryOn​

Error cases​

POST /assistant/size-me​

Purpose​

Success response​

Success response fields​

recommendation​

Failure response​

Failure response fields​

Failure semantics​

invalid_input​

unavailable​

Help​

API Base Url

Authorization

Endpoints

Example headers:

POST /returns

Request Body

Product Info

Example Request

Return reasons

Response

StatusCodes

Body

Return Error

Example Response

POST /orders

Request Body

Order Event

Line Item

Example Request

POST /size-specs

Request Parameters

Request Body

Product Size Descriptor

Size Chart Specification

Example Request

Response

StatusCodes

Body

Return Error

Example Response

POST /assistant/state/

Request Parameters

Query String Parameters

Request Body

Variant

Example Requests

Response

StatusCodes

Body

Example Response

Assistant API v2

Shared request body

Authentication and retailer context

Example request

Top-level fields

`product`

`profile`

`profile.referenceItems`

`profile.measurements`

`experiments`

POST /assistant/context

Purpose

Success response

Response fields

`status`

`productContext`

`widgetConfiguration`

`capabilities`

`AssistantInputRequirement`

Capability semantics

`sizeMe`

`tryOn`

Error cases

POST /assistant/size-me

Purpose

Success response

Success response fields

`recommendation`

Failure response

Failure response fields

Failure semantics

`invalid_input`

`unavailable`

Help