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

# Products

> Get a paginated list of all products with filtering and sorting options. Returns product details including pricing and availability.



## OpenAPI

````yaml api-reference/openapi.json get /products
openapi: 3.0.0
info:
  title: Marzipan API
  version: 1.0.0
servers:
  - url: https://api.marzipan.co/v1
security:
  - tenantAuth: []
tags:
  - name: Account
    description: >-
      Account management endpoints including registration, login, and user
      details
  - name: Carts
    description: Shopping cart management endpoints
  - name: Products
    description: Product catalog and search endpoints
  - name: Subscriptions
    description: Subscription management and renewal endpoints
  - name: CMS
    description: Content management system endpoints
  - name: Messaging
    description: Message and communication endpoints
  - name: Search
    description: Search functionality endpoints
paths:
  /products:
    parameters: []
    get:
      tags:
        - Products
      summary: Products
      description: >-
        Get a paginated list of all products with filtering and sorting options.
        Returns product details including pricing and availability.
      parameters:
        - name: collection
          in: query
          required: false
          description: >-
            Filter products by collection slug or name. Products will be ordered
            by their position in the collection.
          schema:
            type: string
          example: featured-products
        - name: attr
          in: query
          required: false
          description: >-
            Filter products by attributes using deep object notation. Each
            attribute filter accepts comma-separated values for OR matching.


            Format: attr[attribute_slug]=value1,value2


            Example: attr[color]=red,blue&attr[size]=large

            This returns products that are (red OR blue) AND large.
          schema:
            type: object
            additionalProperties:
              type: string
          style: deepObject
          explode: true
          example:
            color: red,blue
            size: large
        - name: sort
          in: query
          required: false
          description: >-
            Sort products by field and direction. Format: field.direction (e.g.,
            price.asc, name.desc). Multiple sort options can be comma-separated.
          schema:
            type: string
          example: price.asc,name.desc
        - name: limit
          in: query
          required: false
          description: Limit the number of results returned. Maximum 50 per page.
          schema:
            type: integer
            minimum: 1
            maximum: 50
          example: 10
        - name: page
          in: query
          required: false
          description: Page number for pagination.
          schema:
            type: integer
            minimum: 1
          example: 1
        - name: per_page
          in: query
          required: false
          description: Number of items per page. Default is 50.
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 50
        - name: include
          in: query
          required: false
          description: >-
            Comma-separated list of related resources to include in the
            response.

             Available options: linkedSubscriptions (includes full subscription details for products with linked subscriptions).
          schema:
            type: string
            enum:
              - linkedSubscriptions
          example: linkedSubscriptions
      responses:
        '200':
          description: products
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        format: uri
                      last:
                        type: string
                        format: uri
                        nullable: true
                      prev:
                        type: string
                        format: uri
                        nullable: true
                      next:
                        type: string
                        format: uri
                        nullable: true
                  meta:
                    type: object
                    properties:
                      currentPage:
                        type: integer
                      from:
                        type: integer
                      path:
                        type: string
                        format: uri
                      perPage:
                        type: integer
                      to:
                        type: integer
              example:
                data:
                  - id: 2e2805a1-738e-4118-8a8b-f9431f0e210c
                    name: Cellar Selection Malbec
                    slug: cellar-selection-malbec-2015
                    description: >-
                      Id laboris ad aliqua exercitation dolore. Ad, aliqua
                      exercitation dolore est culpa. Dolore est culpa id duis
                      duis labore dolore do ex.
                    productType: physical
                    sku: CSMALBC2015
                    collection: Store
                    status: active
                    image:
                      id: 0736c529-a33d-4b8c-8126-eb69779dcdad
                      path: 1/0736c529-a33d-4b8c-8126-eb69779dcdad.jpg
                      src: >-
                        https://marzipan-cloud-dev.b-cdn.net/1/0736c529-a33d-4b8c-8126-eb69779dcdad.jpg
                      alt: Cellar Selection Malbec 2015 bottle
                      mimeType: image/jpeg
                      filename: 0736c529-a33d-4b8c-8126-eb69779dcdad.jpg
                    price: £24.99
                    salePrice: null
                    subscriberPrice: null
                    createdAt: '2024-02-05T23:22:56.000000Z'
                    updatedAt: '2024-02-05T23:22:56.000000Z'
                    storeSlug: store
                    subscriptionsSlug: null
                    availability: all
                    upsellProducts: []
                  - id: df0d13db-1332-4461-b3d1-b2774d47ff5f
                    name: Chardonnay
                    slug: chardonnay-2015
                    description: >-
                      Lorem sed id, culpa. Culpa id duis duis labore dolore do
                      ex. Duis duis labore, dolore.
                    productType: physical
                    sku: CHARD2015
                    collection: Store
                    status: active
                    image:
                      id: 1b978a90-3ecb-4f37-b480-9fb81882176e
                      path: 1/1b978a90-3ecb-4f37-b480-9fb81882176e.jpg
                      src: >-
                        https://marzipan-cloud-dev.b-cdn.net/1/1b978a90-3ecb-4f37-b480-9fb81882176e.jpg
                      alt: Chardonnay 2015 bottle
                      mimeType: image/jpeg
                      filename: 1b978a90-3ecb-4f37-b480-9fb81882176e.jpg
                    price: £23.99
                    salePrice: null
                    subscriberPrice: null
                    createdAt: '2024-02-05T23:22:56.000000Z'
                    updatedAt: '2024-02-05T23:22:56.000000Z'
                    storeSlug: store
                    subscriptionsSlug: null
                    availability: all
                    upsellProducts: []
                  - id: 084b80ef-d16d-4531-a25f-40b7ff4c744b
                    name: Discovery Club
                    slug: discovery-club
                    description: >-
                      Laborum adipiscing, tempor cillum. Cillum exercitation sed
                      officia mollit do dolore.
                    productType: subscription
                    sku: DISCCLUB
                    collection: Club
                    status: active
                    image:
                      id: bc1a0d61-e7f9-44d3-ae53-1475b5f9395d
                      path: 1/bc1a0d61-e7f9-44d3-ae53-1475b5f9395d.jpg
                      src: >-
                        https://marzipan-cloud-dev.b-cdn.net/1/bc1a0d61-e7f9-44d3-ae53-1475b5f9395d.jpg
                      alt: Discovery Club subscription box
                      mimeType: image/jpeg
                      filename: bc1a0d61-e7f9-44d3-ae53-1475b5f9395d.jpg
                    price: from £0.00
                    salePrice: null
                    subscriberPrice: null
                    createdAt: '2024-02-05T23:22:56.000000Z'
                    updatedAt: '2024-02-05T23:22:56.000000Z'
                    storeSlug: null
                    subscriptionsSlug: club
                    availability: all
                    upsellProducts: []
                    billing_frequency: 6
                    pricing_type: per_item
                links:
                  first: https://api.marzipan.co/v1/products?page=1
                  last: https://api.marzipan.co/v1/products?page=5
                  prev: null
                  next: https://api.marzipan.co/v1/products?page=2
                meta:
                  currentPage: 1
                  from: 1
                  path: https://api.marzipan.co/v1/products
                  perPage: 15
                  to: 15
components:
  schemas:
    Product:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the product
        name:
          type: string
          description: Product name
        slug:
          type: string
          description: URL-friendly product identifier
        url:
          type: string
          description: Full URL to the product page
        description:
          type: string
          description: Product description
        product_type:
          type: string
          enum:
            - physical
            - event
            - subscription
            - bundle
          description: Type of product
        subscription_type:
          type: string
          enum:
            - picknmix
            - variable
          description: Type of subscription. Only present for subscription products
        sku:
          type: string
          description: Stock Keeping Unit
        collections:
          type: array
          items:
            $ref: '#/components/schemas/Collection'
          description: Collections this product belongs to
        status:
          type: string
          enum:
            - active
            - inactive
            - out_of_stock
          description: >-
            Product status - automatically set to out_of_stock when quantity is
            0
        images:
          type: object
          properties:
            product:
              type: array
              items:
                $ref: '#/components/schemas/ProductImage'
              description: Main product images
            labels:
              type: object
              properties:
                front:
                  type: array
                  items:
                    $ref: '#/components/schemas/ProductImage'
                  description: Front label images
                back:
                  type: array
                  items:
                    $ref: '#/components/schemas/ProductImage'
                  description: Back label images
          description: Product images organized by type
        primaryImage:
          $ref: '#/components/schemas/ProductImage'
          description: Primary product image
        price:
          type: string
          description: >-
            Formatted price (e.g., £10.00). For pick-and-mix subscriptions with
            per-item pricing, may show 'from £X.XX'
        salePrice:
          type: string
          nullable: true
          description: Formatted sale price if on sale
        subscriberPrice:
          type: string
          nullable: true
          description: Special price for subscribers. Not shown for subscription products
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp
        store_slug:
          type: string
          description: Store URL slug
        subscriptions_slug:
          type: string
          description: Subscriptions URL slug
        availability:
          type: string
          enum:
            - all
            - subscribers
          description: Product availability
        upsell_products:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Product ID
              name:
                type: string
                description: Product name
              sku:
                type: string
                description: Product SKU
              price:
                type: string
                description: Formatted price
              sale_price:
                type: string
                nullable: true
                description: Formatted sale price
              subscriber_price:
                type: string
                nullable: true
                description: Formatted subscriber price
          description: Upsell products with simplified data
        linkedSubscriptions:
          type: array
          items:
            $ref: '#/components/schemas/LinkedSubscription'
          description: >-
            Full details of linked subscriptions. Only included when requested
            via the include query parameter.
        billing_frequency:
          type: integer
          description: Billing frequency in months. Only present for subscription products
        billing_frequencies:
          type: array
          items:
            type: integer
          description: >-
            Available billing frequencies. Only present for subscription
            products
        pricing_type:
          type: string
          enum:
            - fixed
            - per_item
          description: >-
            Pricing type for subscriptions. Only present for subscription
            products
        bundle_items:
          type: array
          items:
            type: object
          description: Items included in bundle. Only present for bundle products
        attributes:
          type: array
          items:
            type: object
          description: Product attributes like color, size, etc.
        options:
          type: array
          items:
            type: object
          description: Product options with their possible values
        related_products:
          type: array
          items:
            type: object
          description: Related products
        awards:
          type: array
          items:
            type: object
          description: Product awards
        reviews:
          type: array
          items:
            type: object
          description: Product reviews
        meta_title:
          type: string
          description: SEO meta title
        meta_description:
          type: string
          description: SEO meta description
        meta_image:
          type: string
          nullable: true
          description: SEO meta image URL (1200x630)
        linked_subscription:
          type: boolean
          description: >-
            Whether product has linked subscriptions. Only present if product
            has linked subscriptions
        store_name:
          type: string
          description: Store name
    Collection:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the collection
        name:
          type: string
          description: Collection name
        description:
          type: string
          description: Collection description
        slug:
          type: string
          description: URL-friendly collection identifier
        attributes:
          type: array
          items:
            type: object
          description: Collection attributes
    ProductImage:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the image
        path:
          type: string
          description: Relative path to the image file
        src:
          type: string
          format: uri
          description: Full URL to access the image
        alt:
          type: string
          nullable: true
          description: Alternative text for accessibility
        mimeType:
          type: string
          description: MIME type of the image (e.g., image/jpeg, image/png)
        filename:
          type: string
          description: Original filename of the uploaded image
    LinkedSubscription:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Subscription ID
        name:
          type: string
          description: Subscription name
        options:
          type: object
          description: Subscription options
        status:
          type: string
          description: Subscription status
        start_date:
          type: string
          format: date
          description: Subscription start date
        end_date:
          type: string
          format: date
          description: Subscription end date
        next_billing_date:
          type: string
          format: date
          description: Next billing date
        billing_interval:
          type: integer
          description: Billing interval in months
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
  securitySchemes:
    tenantAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer authentication header of the form `Bearer <token>`, where
        `<token>` is your API token.
      bearerFormat: JWT

````