StylorDocs

The sizes card

post/v1/shoppers/me/size/card

The "Which brands do you wear?" card the Stylor chat widget shows, as data, for your app to draw the same card outside a chat. The widget and this endpoint build it with the same code, so the two always match: the same brands in the same order, the same size chips per brand and garment, the same likely bottoms for each top size.

How the card works

The shopper picks the brands they wear (up to five) from brands, popular ones first (popular: true), searching the rest by name and aliases. Then, for each brand, a size in each garment in garments, from that brand's chips: brands[].sizes is keyed <department>:<garment> (mens:jeans), each entry a size system (letters, numbers, tailored) with its chips. When a brand offers more than one system for a garment, show a switch. Once a top size is picked, brands[].likely["<department>:<top>><bottom>"] names the bottom sizes that usually go with it, to suggest first. Finally, how that size fits them, from fits (tight, right, loose).

Without department the card holds both departments' sizes and should ask womenswear or menswear first; with it, only that one's.

Saving the answer

Send what the shopper picked to remember as sizes, one row per brand and garment, as the card has them: { "brand": "Uniqlo", "garment": "tshirt", "kind": "tops", "label": "M", "fit": "tight" }. From then on size and the chat read them, and this card comes back with them in saved.

Logos

A brand with logo: true has its logo at https://stylor.ai/brand-logos/<slug>.png (the host you call, a public PNG that needs no key). Show logos only when the card's logos is true; otherwise show names.

Store rules

The card is your whole organization's, with no one store in scope, so it is built under the default rules: logos on and no brand left out. A store's own sizing settings (brands it leaves out, logos off) apply in that store's chat and when its products are sized with size, which never reads a size at a brand the product's store left out.

The token is optional: with one, the sizes the profile keeps come back in saved to show already picked. No profile is made.

Public keyapi.v1.shoppersDemo key OK

Headers

1
X-Shopper-Tokenstring

The shopper's profile token, from auth/start, auth/verify or any call that made a profile. Optional here.

Request body

application/json
departmentstringnullable

Whose sizes. Leave it out for a card that asks.

One ofwomensmensnull
garmentsarray<string>nullable

The garments to ask a size in, one card row each, for what the shopper is shopping for: [tshirt, jeans] for everyday, [suit, trousers] for a wedding, [dress]. At most one top, one bottom and one one-piece is kept, in the order sent; menswear is never asked a dress, a skirt or leggings (left out, and the default asked when nothing is left).

One oftshirtshirttopjacketsuitjeanstrousersshortsleggingsskirtdress
default: ["tshirt","jeans"]minItems: 1maxItems: 3
countrystringnullable

The shopper's market, a two-letter ISO 3166 code. Brands' size systems follow it (a UK dress size in GB).

Response

200The card.
ShopperSizesCardrequired

The sizes card, as the Stylor chat widget shows it.

cardIdstringrequired

A new id per card.

titlestringrequired

The card's question, "Which brands do you wear?".

departmentstringnullablerequired

Whose sizes. null, the card asks womenswear or menswear first.

One ofwomensmensnull
kindnullrequired

Always null here (in a chat, the kind of piece the agent asked about).

array<object>required

The rows, one per garment, in order.

array<object>required

Every kind a size can be for, with its label.

array<object>required

How a size fits them, as the card asks it (tight, right, loose).

array<object>required

Every brand the card offers, popular ones first, then by name.

logosbooleanrequired

Whether to show brand logos. Always true here.

array<object>required

The sizes the profile keeps, to show already picked, in the card's words. Empty without a token.

Errors

29

Every error is JSON with a single error string unless noted. Match on the status code; the message is for humans.

400
Request body must be valid JSON.

A body was sent and could not be parsed as JSON.

400
Request body must be a JSON object.

A body was sent and parsed to something other than a JSON object.

401
That shopper token is not valid here. Start a profile or sign in again.

X-Shopper-Token was sent but cannot be opened with this key. Leave it out for a card with nothing saved.

422
department must be womens or mens.

department is another value.

422
garments must be an array.

garments was sent (non-null) but is not an array.

422
garments must not be empty; leave it out for the default.

garments is an empty array.

422
garments can hold at most 3.

garments holds more than 3 entries.

422
Each garment must be one of tshirt, shirt, top, jacket, suit, jeans, trousers, shorts, leggings, skirt, dress.

An entry of garments is another value.

422
country must be a two-letter ISO 3166 country code, such as 'US'.

country was sent (non-null) but is not two letters.

422
Validation failed.

More than one field is invalid. details lists each, by path.

{
  "error": "Validation failed.",
  "details": [
    {
      "path": "department",
      "message": "department must be womens or mens."
    },
    {
      "path": "garments",
      "message": "Each garment must be one of tshirt, shirt, top, jacket, suit, jeans, trousers, shorts, leggings, skirt, dress."
    }
  ]
}
curl -X POST "https://stylor.ai/api/v1/shoppers/me/size/card" \
  -H "Authorization: Bearer $STYLOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "department": "mens",
  "garments": [
    "tshirt",
    "jeans"
  ],
  "country": "US"
}'
Response · 200
{
  "card": {
    "cardId": "1d7ed9f7-290b-45eb-8ee1-49a010ef61ef",
    "title": "Which brands do you wear?",
    "department": "mens",
    "kind": null,
    "garments": [
      {
        "value": "tshirt",
        "label": "T-shirt",
        "part": "top",
        "kind": "tops"
      },
      {
        "value": "jeans",
        "label": "Jeans",
        "part": "bottom",
        "kind": "jeans"
      }
    ],
    "kinds": [
      {
        "value": "tops",
        "label": "Tops"
      },
      {
        "value": "jeans",
        "label": "Jeans"
      },
      {
        "value": "trousers",
        "label": "Trousers"
      },
      {
        "value": "dresses",
        "label": "Dresses"
      },
      {
        "value": "outerwear",
        "label": "Jackets"
      },
      {
        "value": "suits",
        "label": "Suit jackets"
      }
    ],
    "fits": [
      {
        "value": "tight",
        "label": "Tight"
      },
      {
        "value": "right",
        "label": "Right"
      },
      {
        "value": "loose",
        "label": "Loose"
      }
    ],
    "brands": [
      {
        "slug": "uniqlo",
        "name": "Uniqlo",
        "aliases": [],
        "logo": true,
        "sizes": {
          "mens:tshirt": [
            {
              "id": "letters",
              "name": "Letters",
              "chips": [
                "XXS",
                "XS",
                "S",
                "M",
                "L",
                "XL",
                "XXL",
                "3XL"
              ]
            }
          ],
          "mens:jeans": [
            {
              "id": "numbers",
              "name": "Waist",
              "chips": [
                "27",
                "28",
                "29",
                "30",
                "31",
                "32",
                "33",
                "34",
                "35",
                "36",
                "38",
                "40"
              ]
            }
          ]
        },
        "likely": {
          "mens:tshirt>jeans": {
            "S": [
              "27",
              "28",
              "29"
            ],
            "M": [
              "30",
              "31",
              "32"
            ],
            "L": [
              "34",
              "35",
              "36"
            ]
          }
        },
        "popular": true
      },
      {
        "slug": "levis",
        "name": "Levi's",
        "aliases": [
          "levi",
          "levistrauss",
          "levis501"
        ],
        "logo": true,
        "sizes": {
          "mens:tshirt": [
            {
              "id": "letters",
              "name": "Letters",
              "chips": [
                "XS",
                "S",
                "M",
                "L",
                "XL",
                "XXL",
                "3XL",
                "4XL",
                "5XL"
              ]
            }
          ],
          "mens:jeans": [
            {
              "id": "numbers",
              "name": "Waist",
              "chips": [
                "28",
                "29",
                "30",
                "31",
                "32",
                "33",
                "34",
                "36",
                "38",
                "40"
              ]
            }
          ]
        },
        "likely": {
          "mens:tshirt>jeans": {
            "S": [
              "28",
              "29",
              "30"
            ],
            "M": [
              "31",
              "32",
              "33"
            ],
            "L": [
              "34",
              "35",
              "36"
            ]
          }
        },
        "popular": true
      }
    ],
    "logos": true,
    "saved": [
      {
        "brand": "Uniqlo",
        "kind": "tops",
        "label": "M",
        "fit": "tight"
      },
      {
        "brand": "Levi's",
        "kind": "jeans",
        "label": "32",
        "fit": "loose"
      }
    ]
  }
}