> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cartble.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add and manage your product catalog in Cartble

> Learn how to create and manage resources — Cartble's universal term for products, items, and services — across Retail, On-Demand, and Booking stores.

Every sellable thing in your store is called a **resource**. Regardless of whether you run a retail shop, a food-delivery operation, or a booking-based service, the same catalog system powers your listings. Cartble adapts the terminology and available fields to match your industry: resources appear as "products" in Retail, "items" in On-Demand, and "services" in Booking.

## Resource types

<CardGroup cols={2}>
  <Card title="Physical" icon="box">
    Tangible goods that require shipping. Supports SKU, weight, and dimensions via the logistics bundle.
  </Card>

  <Card title="Digital" icon="download">
    Files or links delivered after purchase. Set a download limit and an optional link expiration period.
  </Card>

  <Card title="Service" icon="calendar">
    Bookable appointments or sessions. Uses the scheduling bundle for duration, staff, and buffer time.
  </Card>

  <Card title="Subscription" icon="repeat">
    Recurring-billing products. Configure the billing period and an optional free trial via the subscription bundle.
  </Card>
</CardGroup>

## Creating a resource

Navigate to **Admin → Resources → All Products** and click **New Resource**.

<Steps>
  <Step title="Fill in the basics">
    Enter a **name**, **description**, and set the **price**. Prices are stored in cents — entering `1999` with currency `USD` represents \$19.99. You can optionally set a **compare-at price** (the original price shown as crossed out) and a **cost per item** for margin tracking.
  </Step>

  <Step title="Add images">
    Upload one or more images. The first image becomes the cover image shown in listings. You can also set a dedicated `coverImage` separately.
  </Step>

  <Step title="Set stock">
    Enter the available quantity. For services, stock represents capacity (number of available slots).
  </Step>

  <Step title="Assign categories and collections">
    Select one or more **categories** for internal taxonomy and optionally assign the resource to one or more **collections** for storefront grouping.
  </Step>

  <Step title="Set status">
    Choose the initial **status**:

    * `draft` — not visible to customers
    * `active` — live on the storefront
    * `archived` — hidden and no longer purchasable

    You can also mark a resource as **featured** to promote it in themed storefront sections.
  </Step>
</Steps>

## Variants

Enable **Has Variations** when a resource comes in multiple options (for example, Size and Color for a T-shirt).

<Steps>
  <Step title="Define variation groups">
    Add one or more **variation groups**, each with a name (e.g., "Size") and a list of options (e.g., "S", "M", "L", "XL").
  </Step>

  <Step title="Configure variation items">
    Cartble generates a **variation item** for each combination of options. For each item you can set:

    * Individual **price** and optional **compare-at price**
    * **Stock** quantity
    * **SKU**
    * Optional **weight** and **dimensions** (length, width, height)
  </Step>
</Steps>

<Note>
  Variation items override the base resource price and stock. The base price is used only when no variations are defined.
</Note>

## Industry-specific fields

<Tabs>
  <Tab title="Retail (Physical)">
    Physical resources support a **logistics bundle** for shipping and tax:

    | Field        | Description                                   |
    | ------------ | --------------------------------------------- |
    | `sku`        | Stock keeping unit identifier                 |
    | `baseSku`    | Base SKU shared across variants               |
    | `ncm`        | Fiscal classification code (used in Brazil)   |
    | `weight`     | Item weight in grams                          |
    | `dimensions` | Length, width, and height in your chosen unit |
    | `chargeTax`  | Whether tax is applied at checkout            |
  </Tab>

  <Tab title="On-Demand / Food">
    Food and on-demand items support a **gastronomy bundle**:

    | Field            | Description                             |
    | ---------------- | --------------------------------------- |
    | `prepTime`       | Kitchen preparation time in minutes     |
    | `nutritionInfo`  | Free-text nutrition or ingredient notes |
    | `modifierGroups` | Add-on option groups (see below)        |

    **Modifier groups** let customers customize their order. Each group has a `name`, a `minSelection`, and a `maxSelection`. Within each group you define individual **modifiers**, each with a name and an additional price.

    *Example:* An "Extras" group with `minSelection: 0` and `maxSelection: 3` lets customers pick up to three toppings at extra cost.
  </Tab>

  <Tab title="Booking (Service)">
    Bookable services support a **scheduling bundle**:

    | Field          | Description                                       |
    | -------------- | ------------------------------------------------- |
    | `duration`     | Session duration in minutes                       |
    | `staffMembers` | List of staff (id, name, optional role and image) |
    | `bufferTime`   | Break time in minutes added after each booking    |
    | `policy`       | Free-text cancellation or rescheduling policy     |
  </Tab>

  <Tab title="Digital">
    Digital resources support the following delivery fields:

    | Field                  | Description                                   |
    | ---------------------- | --------------------------------------------- |
    | `digitalFileUrl`       | URL of the hosted file                        |
    | `digitalLinkExternal`  | External URL to redirect to after purchase    |
    | `downloadLimit`        | Maximum number of download attempts           |
    | `linkExpirationDays`   | Number of days before the access link expires |
    | `deliveryInstructions` | Custom message shown to buyers after purchase |
  </Tab>

  <Tab title="Subscription">
    Subscription resources use a **subscription bundle**:

    | Field             | Description                                                              |
    | ----------------- | ------------------------------------------------------------------------ |
    | `billingPeriod`   | Recurring interval: `monthly`, `quarterly`, `semi_annually`, or `yearly` |
    | `trialPeriodDays` | Number of free trial days before the first charge                        |
  </Tab>
</Tabs>

## Custom attributes and metafields

Resources support two ways to store extra data:

* **Attributes** (`attributes[]`) — structured key/value pairs with a display label and a visibility toggle. Use these for product specifications shown on the storefront.
* **Metafields** (`metafields`) — a free-form key/value map for custom data that does not need a defined schema. Manage reusable metafield definitions in **Admin → Attribute Library**.

## SEO fields

Each resource has optional SEO fields:

| Field             | Description                                                        |
| ----------------- | ------------------------------------------------------------------ |
| `metaTitle`       | Custom page title for search engines (overrides the resource name) |
| `metaDescription` | Page description shown in search results                           |

<Tip>
  If you leave SEO fields blank, Cartble falls back to the resource name and description automatically.
</Tip>