SCAYLE

https://scayle.dev/documentation
Admin
SCAYLE is a full-featured e-commerce platform providing flexible APIs and commerce tools to build...
Tokens:1,728,917
Snippets:27,012
Trust Score:6.5
Update:3 months ago
Show doc for...
Tokens:
Raw
### Updating Category Page Script Setup

Source: https://scayle.dev/documentation/storefront/storefront-application/support-and-resources/upgrade-guides/migrate-to-storefront-v8?sourceText=%25F0%259F%2592%25A5%2520Accessing%2520Basket%2520Data%253A%2520New%2520Response%2520Structure%2520and%2520Error%2520Handling

Example of script setup logic for product and category fetching states.

```typescript
// script setup
const {
    products,
    pagination,
    fetching: productsFetching,
    totalProductsCount,
    paginationOffset,
} = useProductsByCategory(currentCategoryId, route, {

// ...

const {
    data: currentCategory,
    fetching: isCategoryFetching,
    error: categoryError,
} = currentCategoryPromise

const validateCategoryExists = async () => {
    await currentCategoryPromise

    if (categoryError.value || (!isCategoryFetching && !currentCategory.value)) {
        throw createError({ statusCode: HttpStatusCode.NOT_FOUND, fatal: true })
    }
}
```

--------------------------------

### Install Storefront API SDK

Source: https://scayle.dev/documentation/welcome-to-scayle/readme/apis

Install the SDK using package managers.

```bash
npm i @scayle/storefront-api
```

--------------------------------

### Copy Environment Example File

Source: https://scayle.dev/documentation/welcome-to-scayle/quick-start-guide/storefront-setup

Initialize the .env file by copying the provided example template.

```bash
cp .env.example .env
```

--------------------------------

### Install Swagger Client

Source: https://scayle.dev/documentation/welcome-to-scayle/quick-start-guide/importing-product-data?sourceText=Importing%2520Product%2520Data

Install the swagger-client package to interact with the Admin API.

```bash
npm install swagger-client
```

--------------------------------

### Run the setup command

Source: https://scayle.dev/documentation/storefront/storefront-application/storefront-cli/setup

Executes the interactive setup tool requiring tenant space and admin API token arguments.

```bash
$ sfcli setup -t <value> -a <value>
```

--------------------------------

### Verify CLI installation and help

Source: https://scayle.dev/documentation/storefront/storefront-application/storefront-cli?sourceText=SCAYLE%2520Storefront%2520CLI

Checks the installed version and displays help information for the CLI.

```bash
$ sfcli --version
@scayle/storefront-cli/0.13.3 darwin-arm64 node-v22.16.0

$ sfcli --help
USAGE
  $ sfcli COMMAND
...
```

--------------------------------

### Install Storefront API SDK

Source: https://scayle.dev/documentation/welcome-to-scayle/quick-start-guide/storefront-setup

Installs the required backbone dependency via pnpm.

```bash
pnpm install @aboutyou/backbone
```

--------------------------------

### Install Dependencies and Generate SSL

Source: https://scayle.dev/documentation/add-ons/add-on-development/reference-architecture

Prepares the local environment by installing packages and creating required SSL certificates.

```bash
npm ci
npm run generate:ssl
```

--------------------------------

### Start Development Server

Source: https://scayle.dev/documentation/welcome-to-scayle/quick-start-guide/storefront-setup

Launch the Nuxt development server.

```bash
yarn dev
```

--------------------------------

### Install Project Dependencies

Source: https://scayle.dev/documentation/storefront/storefront-application/getting-started/set-up-your-storefront

Install all required dependencies within the project directory.

```bash
# Install all required dependencies
pnpm install
```

--------------------------------

### Install SDK Dependencies

Source: https://scayle.dev/documentation/welcome-to-scayle/readme/apis

Commands to install the swagger-client library using npm or yarn.

```shell
# Install with npm
npm install swagger-client

# Install with yarn
yarn add swagger-client

```

--------------------------------

### Install Storefront CLI globally

Source: https://scayle.dev/documentation/storefront/storefront-application/storefront-cli

Install the package globally to enable the sfcli command alias.

```bash
npm install -g @scayle/storefront-cli
```

--------------------------------

### Deploy command example

Source: https://scayle.dev/documentation/storefront/storefront-application/storefront-cli/deploy

Example execution using pnpm to deploy a specific git revision to a target environment.

```bash
pnpm dlx @scayle/storefront-cli deploy --deploy-token=$DEPLOY_TOKEN --tenant-space=next-qa --shop-key=sb --env-key=dev --git-rev=main
```

--------------------------------

### Install SCAYLE Image Provider

Source: https://scayle.dev/documentation/storefront/storefront-application/support-and-resources/upgrade-guides/migrate-to-scayle-image-provider?sourceText=Migrate%2520to%2520SCAYLE%2520Image%2520Provider

Install the provider package using yarn.

```sh
yarn add @scayle/nuxt-image-provider
```

--------------------------------

### Install Node.js with NVM

Source: https://scayle.dev/documentation/storefront/storefront-application/getting-started/set-up-your-storefront

Use NVM to install and switch to the required Node.js version for the Storefront Application.

```bash
# Option 1: Install the latest LTS version of the v22 release line (Iron)
nvm install lts/iron

# Option 2: Install a specific version
nvm install 22.19.*

# Use the installed version
nvm use lts/iron
# or
nvm use 22.19.*
```

--------------------------------

### Get Basket items with Applicable Promotions

Source: https://scayle.dev/documentation/the-basics/basket-and-wishlist

Example JSON response showing basket items, package details, total costs, and currently applicable promotions.

```json
{
  "key": "myshop_customer_1234",
  "items": [
    {
      "key": "44f364e11b019eb381b86866331a9993",
      "packageId": 2,
      "quantity": 20,
      "status": "available",
      "displayData": {},
      "availableQuantity": 70,
      "customData": {},
      "lowestPriorPrice": {
        "withTax": null,
        "relativeDifferenceToPrice": null
      },
      "price": {
        "total": {
          "currencyCode": "EUR",
          "withTax": 2400,
          "withoutTax": 2020,
          "recommendedRetailPrice": null,
          "tax": {
            "vat": {
              "amount": 380,
              "rate": 0
            }
          },
          "appliedReductions": [
            {
              "category": "promotion",
              "type": "relative",
              "amount": {
                "relative": 0.2,
                "absoluteWithTax": 600,
                "absoluteTax": 100,
                "absoluteWithoutTax": 500
              }
            }
          ]
        },
        "unit": {
          "currencyCode": "EUR",
          "withTax": 120,
          "withoutTax": 101,
          "recommendedRetailPrice": null,
          "tax": {
            "vat": {
              "amount": 19,
              "rate": 0
            }
          },
          "appliedReductions": [
            {
              "category": "promotion",
              "type": "relative",
              "amount": {
                "relative": 0.2,
                "absoluteWithTax": 30,
                "absoluteTax": 5,
                "absoluteWithoutTax": 25
              }
            }
          ]
        }
      },
      "variant": {
        "id": 33378,
        "referenceKey": "default-merchant-fallback-test-v9",
        "firstLiveAt": "2023-11-16T01:04:38+00:00",
        "createdAt": "2023-11-14T11:03:14+00:00",
        "updatedAt": "2023-11-16T01:04:38+00:00",
        "stock": {
          "supplierId": 1,
          "warehouseId": 9,
          "quantity": 70,
          "isSellableWithoutStock": false
        },
        "price": {
          "currencyCode": "EUR",
          "withTax": 150,
          "withoutTax": 126,
          "recommendedRetailPrice": null,
          "tax": {
            "vat": {
              "amount": 24,
              "rate": 0.19
            }
          },
          "appliedReductions": []
        },
        "customData": {
          "subscriptionEligibility": false
        }
      },
      "product": {
        "id": 17381,
        "isActive": true,
        "isSoldOut": false,
        "isNew": true,
        "createdAt": "2023-11-14T10:00:30+00:00",
        "updatedAt": "2023-11-14T10:17:49+00:00",
        "indexedAt": "2023-11-23T10:09:32+00:00",
        "firstLiveAt": "2023-11-16T01:04:38+00:00",
        "masterKey": "default-merchant-fallback-test-m6",
        "referenceKey": "default-merchant-fallback-test-p6",
        "images": [],
        "customData": {}
      },
      "itemGroup": null,
      "promotionId": null,
      "promotion": null
    }
  ],
  "packages": [
    {
      "carrierKey": "zelim-test",
      "deliveryDate": {
        "max": "2023-11-27",
        "min": "2023-11-24"
      },
      "id": 1
    },
    {
      "carrierKey": "zelim-test",
      "deliveryDate": {
        "max": "2023-11-27",
        "min": "2023-11-24"
      },
      "id": 2
    }
  ],
  "cost": {
    "currencyCode": "EUR",
    "withTax": 10400,
    "withoutTax": 8740,
    "recommendedRetailPrice": null,
    "tax": {
      "vat": {
        "amount": 1660,
        "rate": 0
      }
    },
    "appliedReductions": []
  },
  "applicablePromotions": [
    {
      "promotion": {
        "id": "6565fdd53740d2825e72e08f",
        "name": "SAPIQA-B item 155 pId2031 vId17846 EUR G 44390",
        "schedule": {
          "from": "2023-11-28T11:00:00Z",
          "to": "2023-12-09T11:00:00Z"
        },
        "isActive": true,
        "effect": {
          "type": "buy_x_get_y",
          "additionalData": {
            "eligibleItemsQuantity": 2,
            "maxCount": 1,
            "maxCountType": "per_eligible_items_quantity",
            "variantIds": [
              44390
            ]
          }
        },
        "conditions": [
          {
            "level": "item",
            "key": "price==3999",
            "condition": "item.unitPrice.withTax==3999"
          }
        ],
        "customData": {
          "corePanel": {
            "viewType": "advanced"
          }
        },
        "tiers": [
          {
            "id": 1, 
            "name": "Tier 1", 
            "MOV": 10000, 
            "effect": {
              "additionalData": {
                "type": "relative",
                "value": 25
              }
            }
          }
        ]
      },
      "itemId": "e215aa18dc849e9b53c7c90f59d455d5"
    }
  ]
}
```

--------------------------------

### Start Development Server

Source: https://scayle.dev/documentation/storefront/storefront-application/getting-started/set-up-your-storefront

Launches the development server with hot-reloading enabled.

```bash
# Start development server
pnpm dev
```

--------------------------------

### Verify CLI installation

Source: https://scayle.dev/documentation/storefront/storefront-application/storefront-cli

Check the installed version of the CLI.

```bash
sfcli --version
```

--------------------------------

### Install Vercel CLI

Source: https://scayle.dev/documentation/add-ons/add-on-development/deploy-add-on-on-vercel

Global installation of the Vercel command-line interface using yarn.

```bash
yarn global add vercel
```

--------------------------------

### Create a Customer Membership example

Source: https://scayle.dev/documentation/the-basics/customer/manage-customers-via-api/customer-memberships

Example demonstrating the structure of a customer membership object and the API call to create it.

```JavaScript
let customerMembership = {
  "isActive": true,
  "membershipTypeKey": "payback",
  "membershipAccountNumber": "1234567890"
};

let response = await adminApi.apis.Customers.createCustomerMembership({shopKey: 'ms', countryCode: 'DE', customerIdentifier: "key=my-key"}, {requestBody: customerMembership});
customerMembership = response.body;

console.log(customerMembership.id);
```

--------------------------------

### Run Storybook locally

Source: https://scayle.dev/documentation/storefront/storefront-application/integrations/storybook?sourceText=Storybook

Start the Storybook development server.

```bash
pnpm storybook
```

--------------------------------

### Install and run CLI globally

Source: https://scayle.dev/documentation/storefront/storefront-application/storefront-cli?sourceText=SCAYLE%2520Storefront%2520CLI

Installs the package globally to enable the sfcli command alias.

```bash
npm install -g @scayle/storefront-cli
sfcli COMMAND
```

--------------------------------

### Express Checkout Component Implementation

Source: https://scayle.dev/documentation/storefront/checkout/express-checkout/setting-up-express-checkout?sourceText=Error%2520messages

Full example of the basket page setup, including the script loader, event listeners for the Express component, and the custom element tag.

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width,initial-scale=1" />
  <title>Basket</title>

  <script
    src="https://${tenant-space}.checkout.api.scayle.cloud/frontend/checkout-wx/js?appId=${shopId}"
    defer>
  </script>
  
  <script>
    ExpressComponent.addEventListener('consent-missing', ({ detail }) => {
      // detail.provider === "paypal" || "klarna"
      const newConsent = { ...currentConsent, [detail.provider]: true };
      ExpressComponent.setAttribute('consent', JSON.stringify(newConsent));
    });

    ExpressComponent.addEventListener('express-checkout-finished', ({ detail }) => {
      // detail.isFinalized === true || false
      // detail.id === transaction id
       
      if (!detail.isFinalized) {
        // Multi-step checkout -> user needs to review order
        // Mount normal Checkout Webcomponent providing transaction-id attribute
        // Checkout's review page will be shown 
      } else {
        // One-step checkout -> order completed -> show OSP
      }
    });

    ExpressComponent.addEventListener('invalid-access-token', ({ detail }) => {
      // access-token is expired/invalid -> update attribute with a fresh one
      ExpressComponent.setAttribute('access-token', newFreshToken);
    });

    ExpressComponent.addEventListener('payment-closed', ({ detail }) => {
      // user closed the payment widget or cancelled the transaction
    });

    ExpressComponent.addEventListener('express-error', ({ detail }) => {
      // express flow errors
    });
  </script>
  
</head>
<body>
...
<scayle-express-checkout
  jwt="${jwt}"
  access-token="${accessToken}"
  origin="web"
  consent="{"paypal":true,"klarna":false"}"
  basket-total="5400"
></scayle-express-checkout>
...
</body>
</html>
```

--------------------------------

### Create a Customer

Source: https://scayle.dev/documentation/the-basics/customer/manage-customers-via-api/create-a-customer

Example of creating a customer with standard profile information.

```javascript
let customer = {
     "firstName": "John",
     "lastName": "Doe",
     "title": "Prof.",
     "gender": "m",
     "birthDate": "1980-01-01",
     "email": "john.doe@scayle.com",
     "phone": "001/21255512345",
     "publicKey": "pubKey-123",
     "referenceKey": "refKey-456"
};

let response = await adminApi.apis.Customers.createCustomer({shopKey: 'ms', countryCode: 'DE'}, {requestBody: customer});
customer = response.body;

console.log(customer.id);
```

--------------------------------

### Run setup with override flag

Source: https://scayle.dev/documentation/storefront/storefront-application/support-and-resources/changelogs/storefront-tooling/scayle-storefront-cli

Executes the setup command with the should-override flag to automatically replace existing configuration files.

```sh
npx @scayle/storefront-cli setup --should-override
```

--------------------------------

### Install Dotenv

Source: https://scayle.dev/documentation/welcome-to-scayle/quick-start-guide/importing-product-data?sourceText=Importing%2520Product%2520Data

Install the dotenv package to manage environment variables.

```bash
npm install dotenv
```

--------------------------------

### Run Contentstack Setup Command

Source: https://scayle.dev/documentation/storefront/storefront-application/integrations/cms/contentstack?sourceText=CMS%2520module%2520README

Executes the CLI setup command to configure Contentstack integration settings.

```bash
pnpx @scayle/storefront-cli setup cms contentstack
```

--------------------------------

### Install test utilities

Source: https://scayle.dev/documentation/add-ons/add-on-development/testing-your-add-on

Install necessary packages for testing Vue components with Vitest.

```sh
npm install -D @vue/test-utils jsdom
```

--------------------------------

### Install Project Dependencies

Source: https://scayle.dev/documentation/welcome-to-scayle/quick-start-guide/storefront-setup

Install the global yarn package manager and project-specific dependencies.

```bash
npm install --global yarn
```

```bash
yarn install
```

--------------------------------

### Product Pricing Response Example

Source: https://scayle.dev/documentation/advanced/pricing-and-promotions/manage-prices

Example JSON response showing product variant pricing, tax details, and applied campaign reductions.

```json
[
  {
    "id": 12784,
    "name": "Premium Running Shoe",
    "variants": [
      {
        "id": 50123,
        "price": {
          "withTax": 8995,
          "withoutTax": 7563,
          "currencyCode": "EUR",
          "tax": {
            "vat": {
              "amount": 1432,
              "rate": 0.19
            }
          },
          "recommendedRetailPrice": 10995,
          "appliedReductions": [
            {
              "category": "campaign",
              "label": "BLACKWEEK",
              "type": "relative",
              "amount": {
                "relative": 0.18
              }
            }
          ],
          "lowestPriorPrice": {
            "withTax": 9595,
            "relativeDifferenceToPrice": 0.0626
          }
        }
      }
    ],
    "priceRange": {
      "min": {
        "withTax": 8995,
        "currencyCode": "EUR"
      },
      "max": {
        "withTax": 9836,
        "currencyCode": "EUR"
      }
    }
  }
]
```

--------------------------------

### Install Vercel CLI

Source: https://scayle.dev/documentation/storefront/storefront-application/deployments/deploying-on-vercel?sourceText=Vercel

Install the Vercel CLI globally based on your Storefront Application version.

```sh
# Starting with Storefront Application v1.11.x
pnpm add --global vercel

# Until Storefront Application v1.10.x
yarn global add vercel
```

--------------------------------

### Get All Brands Response

Source: https://scayle.dev/documentation/the-basics/products/manage-products-via-api/manage-brands

Example JSON response structure for a collection of brands.

```json
{
    "pagination": { "current": 4, "total": 4, "perPage": 100, "page": 1, "first": 1, "prev": 1, "next": 1, "last": 1 },
    "entities": [
        {
            "id": 10,
            "slug": "tommy-hilfiger",
            "name": "Tommy Hilfiger",
            "externalReference": "",
            "group": "",
            "isActive": true,
            "logoHash": "",
            "createdAt": "2023-06-12T14:05:34+00:00",
            "updatedAt": "2023-06-12T14:05:34+00:00",
            "indexedAt": "2023-07-01T09:12:24+00:00",
            "customData": {}
        },
        {
            "id": 44,
            "slug": "tom-tailor",
            "name": "Tom Tailor",
            "externalReference": "",
            "group": "",
            "isActive": true,
            "logoHash": "",
            "createdAt": "2023-06-12T14:05:43+00:00",
            "updatedAt": "2023-06-12T14:05:43+00:00",
            "indexedAt": "2023-07-01T09:12:24+00:00",
            "customData": {}
        },
        {
            "id": 52,
            "slug": "lewis",
            "name": "Lewis",
            "externalReference": "",
            "group": "",
            "isActive": true,
            "logoHash": "",
            "createdAt": "2023-06-12T14:05:49+00:00",
            "updatedAt": "2023-06-12T14:05:49+00:00",
            "indexedAt": "2023-07-01T09:12:24+00:00",
            "customData": {}
        },
        {
            "id": 78,
            "slug": "liu-jo",
            "name": "Liu Jo",
            "externalReference": "",
            "group": "",
            "isActive": true,
            "logoHash": "",
            "createdAt": "2023-06-12T14:06:03+00:00",
            "updatedAt": "2023-06-12T14:06:03+00:00",
            "indexedAt": "2023-07-01T09:12:24+00:00",
            "customData": {}
        }
    ]
}
```

--------------------------------

### Initialize BapiClient and Fetch Products

Source: https://scayle.dev/documentation/welcome-to-scayle/quick-start-guide/storefront-setup

Demonstrates how to configure the BapiClient using environment variables and perform a product query.

```javascript
const backbone = require("@aboutyou/backbone");
require("dotenv").config();

async function fetchProducts() {
  const client = new backbone.BapiClient({
    host: `https://${process.env.TENANT_SPACE}.storefront.api.scayle.cloud/v1/`,
    shopId: process.env.SHOP_ID,
    auth: {
      type: "token",
      token: process.env.STOREFRONT_API_TOKEN,
    },
  });
  try {
    const products = await client.products.query();
    console.log("Fetched products", products);
  } catch (error) {
    console.error("Unable to fetch products", error);
  }
}

fetchProducts();
```

--------------------------------

### Get Specific Image Attribute

Source: https://scayle.dev/documentation/the-basics/products/manage-products-via-api/manage-media-assets

Example of retrieving a specific image attribute by name.

```javascript
let response = await adminApi.apis.Attributes.getProductImageAttribute({
  productIdentifier: 1,
  imageIdentifier: 2,
  attributeGroupName: "material"
});

let imageAttribute = response.body;
```

--------------------------------

### Run Storefront CLI Setup

Source: https://scayle.dev/documentation/storefront/storefront-application/getting-started/set-up-your-storefront

Initialize the application configuration by fetching shop data from the SCAYLE Admin API.

```bash
# Run setup with your Admin API token and tenant space
pnpm dlx @scayle/storefront-cli setup --admin-api-token=<YOUR_TOKEN> --tenant-space=<TENANT_SPACE>
```

--------------------------------

### Requesting Code Explanations

Source: https://scayle.dev/documentation/storefront/storefront-application/getting-started/ai-development

Examples of how to ask for specific architectural or implementation details.

```text
How does this work?
```

```text
Explain how the RPC method pattern works in this codebase, specifically:
- How defineRpcHandler utility is used to create RPC methods
- How session data is passed to RPC methods
- How caching is implemented for RPC responses
- How error handling is standardized across RPC methods

Reference the implementation in rpcMethods/getProduct.ts as an example.
```

```text
In the useProductFilters composable, I see both ref() and reactive() being used.
Explain the difference between these two approaches in this specific context:
- Why is ref() used for the loading state?
- Why is reactive() used for the filters object?
- What are the performance implications of each choice?
- When should I use one over the other in similar scenarios?
```

--------------------------------

### Product API Response Example

Source: https://scayle.dev/documentation/the-basics/products/manage-products-via-api/stock

Example JSON response showing product details including the visibleWithoutStock attribute.

```json
{
  "id": 215370,
  "isActive": true,
  "isSoldOut": false,
  "isNew": true,
  "createdAt": "2026-01-28T13:04:20+00:00",
  "updatedAt": "2026-01-28T13:40:13+00:00",
  "indexedAt": "2026-02-06T15:05:15+00:00",
  "firstLiveAt": "2026-01-28T13:04:31+00:00",
  "masterKey": "SAPI",
  "referenceKey": "SAPI",
  "attributes": {
    "visibleWithoutStock": {
      "id": 559,
      "key": "visibleWithoutStock",
      "label": "visibleWithoutStock",
      "type": "",
      "multiSelect": false,
      "values": {
        "id": 4519,
        "label": "true",
        "value": "true"
      }
    }
  },
  "images": [
    {
      "hash": "images/4f0d3ee1e253de584e802e10604d53f0.jpg",
      "customData": {}
    }
  ],
  "customData": {}
}
```

--------------------------------

### Get a Brand by Slug Response

Source: https://scayle.dev/documentation/the-basics/products/manage-products-via-api/manage-brands

Example JSON response for a brand lookup by slug.

```json
{
  "id": 44,
  "slug": "tom-tailor",
  "name": "Tom Tailor",
  "externalReference": "",
  "group": "",
  "isActive": true,
  "logoHash": "",
  "createdAt": "2023-06-12T14:05:43+00:00",
  "updatedAt": "2023-06-12T14:05:43+00:00",
  "indexedAt": "2023-07-01T09:12:24+00:00",
  "customData": {}
},
{
"id": 673,
"slug": "700",
"name": "700",
"externalReference": "",
"group": "",
"isActive": true,
"logoHash": "",
"createdAt": "2021-12-14T10:29:56+00:00",
"updatedAt": "2021-12-14T10:29:56+00:00",
"indexedAt": "2023-12-27T14:42:49+00:00",
"customData": {}
}
```

--------------------------------

### Build and Preview Production-Like Environment

Source: https://scayle.dev/documentation/storefront/storefront-application/getting-started/set-up-your-storefront

Compiles the application and starts a preview server to simulate production behavior.

```bash
# Build the application
pnpm build

# Run production preview
pnpm preview
```

--------------------------------

### Get a shop country example

Source: https://scayle.dev/documentation/advanced/internationalization/manage-countries-via-api

Retrieves a specific shop country and logs its URL.

```javascript
let response = await adminApi.apis.Shops.getShopCountry({shopKey: "ms", countryCode: "DE"});
let shopCountry = response.body;

console.log(shopCountry.url);
```

--------------------------------

### Install mkcert Root Certificate

Source: https://scayle.dev/documentation/storefront/storefront-application/getting-started/set-up-your-storefront?sourceText=Storefront%2520Project%2520Setup%2520Guide

Install the local certificate authority to resolve HTTPS trust issues.

```bash
mkcert -install
```

--------------------------------

### Create Customer with Groups

Source: https://scayle.dev/documentation/the-basics/customer/manage-customers-via-api/create-a-customer

Example of creating a customer and assigning them to specific groups.

```javascript
let customer = {
  "firstName": "John",
  "lastName": "Doe",
  "title": "Prof.",
  "gender": "m",
  "birthDate": "1980-01-01",
  "email": "john.doe@scayle.com",
  "phone": "001/21255512345",
  "publicKey": "customer-1234",
  "groups": [
    "employee"
  ]
};

let response = await adminApi.apis.Customers.createCustomer({shopKey: 'ms', countryCode: 'DE'}, {requestBody: customer});
customer = response.body;

console.log(customer.id);
```

--------------------------------

### Create a Complete Product

Source: https://scayle.dev/documentation/the-basics/products/manage-products-via-api/import-products?sourceText=Admin%2520API

Example demonstrating the creation of a product with variants, attributes, images, and custom data.

```javascript
let newProduct = {
    referenceKey: "myReferenceKey",
    name: {
        "de_DE": "Mein Produkt",
        "en_GB": "My Product"
    },
    state: "live",
    master: {
        referenceKey: "myMasterReferenceKey",
        categories: {
            paths: [
                [
                    "Fashion",
                    "Women",
                    "Shirts"
                ]
            ]
        }
    },
    attributes: [
        {
            name: "color",
            type: "localizedStringList",
            value: [
                {
                    de_DE: "rot",
                    en_GB: "red"
                },
                {
                    de_DE: "blau",
                    en_GB: "blue"
                }
            ]
        }
    ],
    variants: [
        {
            referenceKey: "myVariantKey",
            attributes: [
                {
                    name: "size",
                    type: "simple",
                    value: "M"
                }
            ],
            prices: [
                {
                    price: 2499,
                    tax: 19,
                    currencyCode: "EUR",
                    countryCode: "DE",
                }
            ]
        }
    ],
    images: [
        {
            source: {
                url: "https://example.com/image.jpg"
            }
        }
    ],
    customData: {
        "additionalDetails": "details"
    },
    merchantReferenceKeys: ["merchant-1", "merchant-2"]
};

let response = await adminApi.apis.Products.createProduct({}, {requestBody: newProduct});
let createdProduct = response.body;
```

--------------------------------

### Get a Voucher by ID Example

Source: https://scayle.dev/documentation/advanced/pricing-and-promotions/discounts-and-offers/vouchers

Retrieves and logs the name of a voucher using its unique ID.

```JavaScript
response = await adminApi.apis.Vouchers.getVoucher({shopKey: 'ms', countryCode: 'DE', voucherId: 1});
let voucher = response.body;

console.log(voucher.name);
```

--------------------------------

### Install KV Store Drivers

Source: https://scayle.dev/documentation/storefront/storefront-hosting/getting-started/migrate-existing-storefronts

Install the required SCAYLE KV store drivers to enable caching functionality.

```bash
pnpm add @scayle/unstorage-compression-driver
pnpm add @scayle/unstorage-scayle-kv-driver
```

--------------------------------

### Get a collection of shop countries example

Source: https://scayle.dev/documentation/advanced/internationalization/manage-countries-via-api

Retrieves a collection of shop countries and logs their country codes.

```javascript
let response = await adminApi.apis.Shops.getShopCountries({shopKey: "ms"});
let shopCountries = response.body.entities;

shopCountries.forEach(
    shopCountry => console.log(shopCountry.countryCode)
);
```

--------------------------------

### Admin API Get Customer Response

Source: https://scayle.dev/documentation/advanced/customize-and-extend/custom-data?sourceText=Custom%2520Data%2520page

Example JSON structure for a customer object returned by the Admin API.

```js
{
  "id": 456,
  "isGuestCustomer": false,
  "groups": ["employee"]
}
```

--------------------------------

### Run Contentful Setup Command

Source: https://scayle.dev/documentation/storefront/storefront-application/integrations/cms/contentful?sourceText=Contentful

Use the SCAYLE Storefront CLI to initialize the Contentful integration in your project.

```bash
pnpx @scayle/storefront-cli setup cms contentful
```

--------------------------------

### Storefront API Get Category Response

Source: https://scayle.dev/documentation/advanced/customize-and-extend/custom-data?sourceText=Custom%2520Data%2520page

Example JSON structure for a category object returned by the Storefront API.

```json
{
  "id": 1,
  "name": "Example Category",
  "customData": {
    "seoTitle": "Custom SEO Title",
    "metaDescription": "Custom meta description",
    "allowIndexing": true
  }
}
```

--------------------------------

### Single Product Pricing Response Example

Source: https://scayle.dev/documentation/advanced/pricing-and-promotions/manage-prices

Example JSON response for a single product containing multiple variants with individual pricing and campaign reductions.

```json
{
  "id": 12784,
  "name": "Premium Running Shoe",
  "variants": [
    {
      "id": 50123,
      "price": {
        "withTax": 8995,
        "withoutTax": 7563,
        "currencyCode": "EUR",
        "tax": {
          "vat": {
            "amount": 1432,
            "rate": 0.19
          }
        },
        "recommendedRetailPrice": 10995,
        "appliedReductions": [
          {
            "category": "campaign",
            "label": "BLACKWEEK",
            "type": "relative",
            "amount": {
              "relative": 0.18
            }
          }
        ],
        "lowestPriorPrice": {
          "withTax": 9595,
          "relativeDifferenceToPrice": 0.0626
        }
      }
    },
    {
      "id": 50124,
      "price": {
        "withTax": 9836,
        "withoutTax": 8266,
        "currencyCode": "EUR",
        "tax": {
          "vat": {
            "amount": 1570,
            "rate": 0.19
          }
        },
        "recommendedRetailPrice": 11995,
        "appliedReductions": [
          {
            "category": "campaign",
            "label": "BLACKWEEK",
            "type": "relative",
            "amount": {
              "relative": 0.18
            }
          }
        ],
        "lowestPriorPrice": {
          "withTax": 10995,
          "relativeDifferenceToPrice": 0.1048
        }
      }
    }
  ],
  "priceRange": {
    "min": {
      "withTax": 8995,
      "currencyCode": "EUR"
    },
    "max": {
      "withTax": 9836,
      "currencyCode": "EUR"
    }
  }
}
```

--------------------------------

### Storefront API Get Campaign by ID Response

Source: https://scayle.dev/documentation/advanced/customize-and-extend/custom-data?sourceText=Custom%2520Data%2520page

Example JSON structure for a campaign object returned by the Storefront API.

```json
{
  "id": 123,
  "name": "Summer Sale",
  "customData": {
    "sortingKey": "summer-sorting-key"
  }
}
```

--------------------------------

### Create a Basic Product

Source: https://scayle.dev/documentation/the-basics/products/manage-products-via-api/import-products?sourceText=Admin%2520API

Minimal example for creating a product using the Admin API client.

```javascript
let newProduct = {
    referenceKey: "myReferenceKey",
    master: {
        referenceKey: "myMasterReferenceKey",
        categories: {
            paths: [
                [
                    "Fashion",
                    "Women",
                    "Shirts"
                ]
            ]
        }
    },
    name: {
        de_DE: "Mein Produkt",
        en_GB: "My Product"
    },
    state: "draft"
};

let response = await adminApi.apis.Products.createProduct({}, {requestBody: newProduct});
let createdProduct = response.body;
```

--------------------------------

### Create stock reservations example

Source: https://scayle.dev/documentation/the-basics/products/manage-products-via-api/stock

Constructs a reservation array and submits it to the API.

```javascript
const reservations = [];

const reservation1 = {
  referenceKey: 'order4711-item3',
  warehouseReferenceKey: 'myWarehouse',
  variant: {
    id: 123,
    merchantReferenceKey: 'merchant-1',
  }
};

const reservation2 = {
  referenceKey: 'order4711-item4',
  warehouseReferenceKey: 'myWarehouse',
  variant: {
    referenceKey: 'foo-456789',
    merchantReferenceKey: 'merchant-1',
  }
};

reservations.push(reservation1);
reservations.push(reservation2);

const result = await client.apis.Reservations.createReservations({}, {requestBody: newProduct});
```

--------------------------------

### Initialize Project Directory

Source: https://scayle.dev/documentation/welcome-to-scayle/quick-start-guide/project-setup

Commands to create and enter the project directory.

```bash
mkdir academy-getting-started
cd academy-getting-started
```

--------------------------------

### Retrieve Customer Group Information

Source: https://scayle.dev/documentation/advanced/customize-and-extend/custom-data?sourceText=Custom%2520Data%2520Guideline

Example response from the Admin API Get Customer endpoint showing group membership and guest status.

```json
...
"groups": [
    "employee"
  ],
  "status": {
    "isActive": true,
    "isGuestCustomer": false
  },
  ...
```

--------------------------------

### Retrieve sorted products via Storefront API

Source: https://scayle.dev/documentation/the-basics/products/sorting/how-to-integrate-a-custom-product-sorting

Examples of GET requests to the products endpoint using different sorting keys and shop IDs.

```json
[{
        "id": 5
        "referenceKey": "product5"
            ...
    },
    {
        "id": 3,
        "referenceKey": "product3"
            ...
    },
    {
        "id": 2,
        "referenceKey": "product2"
            ...
    },
    {
        "id": 1,
        "referenceKey": "product1"
            ...
    },
    {
        "id": 4,
        "referenceKey": "product4"
            ...
    }
]
```

```json
[{
        "id": 5
        "referenceKey": "product5"
            ...
    },
    {
        "id": 2,
        "referenceKey": "product2"
            ...
    },
    {
        "id": 1,
        "referenceKey": "product1"
            ...
    },
    {
        "id": 3,
        "referenceKey": "product3"
            ...
    },
    {
        "id": 4,
        "referenceKey": "product4"
            ...
    }
]
```

```json
[{
        "id": 1
        "referenceKey": "product1"
            ...
    },
    {
        "id": 4,
        "referenceKey": "product4"
            ...
    },
    {
        "id": 2,
        "referenceKey": "product2"
            ...
    },
    {
        "id": 5,
        "referenceKey": "product5"
            ...
    },
    {
        "id": 3,
        "referenceKey": "product3"
            ...
    }
]
```

--------------------------------

### Update a customer's membership example

Source: https://scayle.dev/documentation/the-basics/customer/manage-customers-via-api/customer-memberships

Example showing how to update membership fields like status, type, and account number.

```JavaScript
let customerMembership = {
  "isActive": true,
  "membershipTypeKey": "payback",
  "membershipAccountNumber": "1234567890"
};

let response = await client.apis.Customers.updateCustomerMembership({shopKey: 'ms', countryCode: 'DE', membershipId: 123}, {requestBody: customerMembership});
customerMembership = response.body;

console.log(customerMembership.id);
```

--------------------------------

### Create a basic product in JavaScript

Source: https://scayle.dev/documentation/the-basics/products/manage-products-via-api/manage-products?sourceText=Creating%2520Products

Initializes a product object with a reference key, master category path, and localized names, then sends it to the API.

```javascript
let newProduct = {
  referenceKey: "myReferenceKey",
  master: {
    referenceKey: "myMasterReferenceKey",
    categories: {
      paths: [
        [
          "Fashion",
          "Women",
          "Shirts"
        ]
      ]
    }
  },
  name: {
    de_DE: "Mein Produkt",
    en_GB: "My Product"
  },
  state: "draft"
};

let response = await adminApi.apis.Products.createProduct({}, {requestBody: newProduct});
let createdProduct = response.body;
```

--------------------------------

### Retrieve Category Custom Data

Source: https://scayle.dev/documentation/advanced/customize-and-extend/custom-data?sourceText=Custom%2520Data%2520Guideline

Example response from the Storefront API Get Category endpoint showing custom data fields at the country level.

```json
{
    "id": 12,
    ...
    "countryLevelCustomData": {
        "vip-customer": true
    }
}
```

--------------------------------

### Storefront API Get Category Response for Customer Groups

Source: https://scayle.dev/documentation/advanced/customize-and-extend/custom-data?sourceText=Custom%2520Data%2520page

Example JSON structure for a category object including custom data for visibility control.

```js
{
  "id": 1,
  "name": "VIP Category",
  "customData": {
    "vip-customer": true
  }
}
```

--------------------------------

### Run Storyblok Setup Command

Source: https://scayle.dev/documentation/storefront/storefront-application/integrations/cms/storyblok

Execute the SCAYLE Storefront CLI command to initialize the Storyblok integration.

```sh
pnpx @scayle/storefront-cli setup cms storyblok
```

--------------------------------

### Retrieve Shops List

Source: https://scayle.dev/documentation/welcome-to-scayle/readme/apis

Example of testing the connection by fetching all shops from the API.

```javascript
const response = await adminApi.apis.Shops.getShops();
const shops = response.body.entities;
console.log(shops.length);
```

--------------------------------

### Install Dependencies

Source: https://scayle.dev/documentation/welcome-to-scayle/quick-start-guide/importing-product-data?sourceText=Importing%2520Product%2520Data

Installs the papaparse library for CSV parsing.

```actionscript
pnpm install papaparse
```

--------------------------------

### Configure Preview URLs

Source: https://scayle.dev/documentation/storefront/storefront-application/integrations/cms/contentstack?sourceText=CMS%2520module%2520README

Example preview URL configurations for different SHOP_SELECTOR_MODE settings in Contentstack.

```bash
# Preview URLs for SHOP_SELECTOR_MODE = 'path' or 'path_or_default'
https://your-domain.com/en
https://your-domain.com/de

# Preview URLs for SHOP_SELECTOR_MODE = 'domain'
https://en.your-domain.com
https://de.your-domain.com
```

--------------------------------

### Install Vitest

Source: https://scayle.dev/documentation/add-ons/add-on-development/testing-your-add-on

Command to install Vitest as a development dependency.

```sh
npm install -D vitest
```

--------------------------------

### Full product import implementation

Source: https://scayle.dev/documentation/welcome-to-scayle/quick-start-guide/importing-product-data?sourceText=Importing%2520Product%2520Data

Complete script for initializing the Swagger client, parsing a CSV file, and creating products in SCAYLE.

```javascript
const SwaggerClient = require("swagger-client");
require("dotenv").config();

const Papa = require("papaparse");
const fs = require("fs");

// Create a product according to the documentation found here: /en/api-guides/admin-api/admin-api/resources/products/create-a-product
// Learn more about the product structure here: https://scayle.dev/en/dev/admin-api/product-overview
async function createProduct(client, data) {
  const newProduct = {
    referenceKey: data.referenceKey,
    name: {
      de_DE: data.name, // We assume here that the name will work for all languages
      en_GB: data.name,
    },
    state: data.state, // live or draft
    master: {
      referenceKey: `${data.referenceKey}-master`, // Usually we would receive a master key and not set it like this
      categories: {
        paths: [data.categories.split(",")], // These categories need to be defined beforehand
      },
    },
    attributes: [
      {
        name: "color", // This attribute group needs to be present
        type: "localizedString",
        value: {
          de_DE: data.color, // these attribute values will automatically be created if they don't exist
          en_GB: data.color,
        },
      },
    ],
    images: data.imageSource.split(",").map((imageSource) => {
      return {
        source: {
          url: imageSource.trim(), // Make sure that the URL contains the filetype ({filename}.png/jpg)
        },
      };
    }),
    // Usually you would set prices and stock at a later point. They also might differ between
    // variants and not on product level like in the CSV.
    variants: data.size.split(",").map((size) => {
      return {
        referenceKey: `${data.referenceKey}-${size}`,
        attributes: [
          {
            name: "size",
            type: "localizedString",
            value: {
              de_DE: size,
              en_GB: size,
            },
          },
        ],
        prices: [
          {
            price: parseInt(data.price), // Make sure to pass decimals like 3900 (39,00 EUR)
            tax: parseInt(data.tax),
            currencyCode: data.currencyCode,
            countryCode: data.countryCode,
          },
        ],
        stocks: [
          {
            quantity: parseInt(data.quantity),
            warehouseReferenceKey: data.warehouse,
            changedAt: "2024-01-26T00:00:00+00:00",
            merchantReferenceKey: "default",
          },
        ],
      };
    }),
  };

  try {
    let response = await client.apis.Products.createProduct(
      {},
      { requestBody: newProduct }
    );
    let createdProduct = response.body;
    console.log("Created Product:", createdProduct);
  } catch (error) {
    console.error("Unable to create product", error.response.body.errors);
  }
}

// Import products from our products.csv file
// The CSV is simplified. In a production import you would probably have a different way of importing the data from your system.
// This is a general demonstration on how to use the Admin API to create products in SCAYLE.
async function importProducts() {
  const client = await new SwaggerClient({
    url: `https://${process.env.TENANT_SPACE}.admin.api.scayle.cloud/api/admin/v1/admin-api.json`,
    authorizations: {
      accessToken: {
        value: process.env.ADMIN_API_TOKEN,
      },
    },
  });
  fs.readFile("./data/products.csv", "utf8", function (err, data) {
    if (err) {
      console.error("Error reading the CSV file:", err);
      return;
    }

    Papa.parse(data, {
      // Makes sure that we get the data as an array of objects
      // in the format {referenceKey: "THS1234", name: "Hilfiger Shirt", ...}
      header: true,
      complete: function (results) {
        for (const product of results.data) {
          createProduct(client, product);
        }
      },
      error: function (error) {
        console.log("Unable to parse products.csv", error);
      },
    });
  });
}

importProducts();
```

--------------------------------

### Initialize product search with useFacet

Source: https://scayle.dev/documentation/welcome-to-scayle/onboarding-guide/onboarding-frontend/products-query

Example of using the useFacet composable to manage product state and fetch data with specific attribute requirements.

```javascript
const {
      products,
      fetchingProducts,
      pagination,
      filters,
      fetchProducts: _fetchProducts,
      fetchingProductCount,
      fetchProductCount,
      productCountData,
    } = useFacet('useSearchFacet', {
      with: {
        product: {
          attributes: {
            withKey: [
              'color',
              'brand',
              'name',
              'geschlecht',
              'jerseyVariant',
              'kaeufergruppe',
              'neuManuellGruppiert',
              'sustainability',
              'sustainabilityCertificates',
              'sustainabilityIcons',
              'sustainabilityMaterials',
              'nachhaltigkeit',
              'jerseyModell',
              'sourceProduct',
            ],
          },
          advancedAttributes: {
            withKey: ['customizableProduct'],
          },
          variants: {
            attributes: {
              withKey: ['price'],
            },
          },
          images: {
            attributes: {
              withKey: [
                'imageType',
                'imageView',
                'imageBackground',
                'imageKind',
              ],
            },
          },
          priceRange: true,
          lowestPriorPrice: true,
        },
      },
    })
```

--------------------------------

### Install Dependencies

Source: https://scayle.dev/documentation/welcome-to-scayle/quick-start-guide/storefront-setup

Install project dependencies using Yarn to resolve undefined errors.

```bash
yarn install
```

--------------------------------

### Full Shop Creation Implementation

Source: https://scayle.dev/documentation/welcome-to-scayle/quick-start-guide/importing-product-data?sourceText=Importing%2520Product%2520Data

Complete script combining client initialization, shop definition, and API execution.

```javascript
const SwaggerClient = require("swagger-client");
require("dotenv").config();

async function addShop() {
  const client = await new SwaggerClient({
    url: `https://${process.env.TENANT_SPACE}.admin.api.scayle.cloud/api/admin/v1/admin-api.json`,
    authorizations: {
      accessToken: {
        value: process.env.ADMIN_API_TOKEN,
      },
    },
  });
  const shop = {
    name: "The Kernel Kiosk 2",
    key: "k2", // Must be 2 chars long
    countries: [
      {
        countryCode: "de", // en, gb, de, fr, es
        defaultLanguageCode: "en_GB", // en_GB, en_US, de_DE, fr_FR, es_ES
        currencyCode: "EUR", // USD, EUR, GBP, JPY, CHF
        url: "http://www.kernel_kiosk.com",
      },
    ],
  };
  try {
    let response = await client.apis.Shops.createShop(
      {},
      { requestBody: shop }
    );
    let createdShop = response.body;
    console.log("Created Shop", createdShop);
  } catch (error) {
    console.error("Errors", error.response.body.errors);
  }
}

addShop();
```

--------------------------------

### Create a shop country with configuration

Source: https://scayle.dev/documentation/advanced/internationalization/manage-countries-via-api

Example of creating a shop country with specific country code, currency, and language settings.

```JavaScript
let newShopCountry = {
    countryCode: "DE",
    currencyCode: "EUR",
    defaultLanguageCode: "de_DE",
    supportedLanguageCodes: ["de_DE", "en_GB"],
    url: "https://ms.de"
};

let response = await adminApi.apis.Shops.createShopCountry({shopKey: "ms"}, {requestBody: newShopCountry});
let createdShopCountry = response.body;
```

--------------------------------

### Initialize Swagger Client

Source: https://scayle.dev/documentation/welcome-to-scayle/quick-start-guide/importing-product-data?sourceText=Importing%2520Product%2520Data

Sets up the Swagger client using environment variables for the tenant space and API token.

```javascript
const SwaggerClient = require("swagger-client");
require("dotenv").config();

async function addShop() {
  const client = await new SwaggerClient({
    url: `https://${process.env.TENANT_SPACE}.admin.api.scayle.cloud/api/admin/v1/admin-api.json`,
    authorizations: {
      accessToken: {
        value: process.env.ADMIN_API_TOKEN,
      },
    },
  });
}

addShop();
```

--------------------------------

### Delete stock reservation example

Source: https://scayle.dev/documentation/the-basics/products/manage-products-via-api/stock

Example call to delete a specific stock reservation.

```javascript
client.apis.Reservations.deleteReservation({reservationIdentifier: "key=my-key"});
```

--------------------------------

### Generated TypeScript Interface Example

Source: https://scayle.dev/documentation/storefront/storefront-application/integrations/cms/contentful?sourceText=Contentful

Example of the auto-generated TypeScript interface for a Contentful component.

```typescript
// Auto-generated by cms:sync
export interface TypeMyBannerComponentWithoutUnresolvableLinksResponse {
  sys: { id: string; [key: string]: any }
  fields: {
    title?: string
    description?: string
    // ... all fields from your Contentful content type
  }
}
```

--------------------------------

### Install Playwright Dependencies

Source: https://scayle.dev/documentation/storefront/storefront-application/testing/end-to-end-testing?sourceText=End-to-End%2520Testing

Commands to install Playwright dependencies based on the Storefront Application version.

```sh
# Starting with Storefront Application v1.11.x
pnpm playwright install

# Until Storefront Application v1.10.x
yarn playwright install
```

--------------------------------

### Organize with parameters in separate files

Source: https://scayle.dev/documentation/welcome-to-scayle/onboarding-guide/onboarding-frontend/understanding-the-with-parameter

Recommended pattern for managing complex 'with' configurations by exporting them as constants.

```javascript
export const BASKET_WITH = {
 items: {
   variants: 'all',
   ...
 }
}

export const WISHLIST_WITH = {...}
```
Tokens:
Raw