openapi: 3.1.0
info:
  title: Pura Vida TLV Storefront & Catalog API
  version: 1.0.0
  description: Pura Vida TLV Storefront & Catalog API v1. Versioning follows URL path
    versioning (/v1/) and semantic versioning. API deprecations are signaled 90 days
    in advance via HTTP Sunset and Deprecation headers per RFC 8594.
  contact:
    name: Pura Vida TLV Engineering & Developer Relations
    url: https://puravidatlv.com/developers
    email: support@puravidatlv.com
  license:
    name: Proprietary Storefront API License
    url: https://puravidatlv.com/policies/terms-of-service
servers:
- url: https://puravidatlv.com/v1
  description: Versioned v1 Storefront API Server
- url: https://puravidatlv.com
  description: Production Storefront API Server
components:
  securitySchemes:
    StorefrontZeroAuth:
      type: http
      scheme: bearer
      description: Public storefront operations require zero authentication.
    AdminOAuth2:
      type: oauth2
      description: Shopify Admin Scoped OAuth 2.0 Client Credentials Grant
      flows:
        clientCredentials:
          tokenUrl: https://25a22e-2.myshopify.com/admin/oauth/access_token
          scopes:
            public_storefront: Public catalog queries and cart operations
            read_products: Read jewelry catalog and inventory levels
            write_products: Manage jewelry listings and pricing
            read_orders: Access order status and tracking details
            write_content: Manage store pages and blog articles
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: Unique UUID v4 string to ensure idempotent execution on retries
      schema:
        type: string
        format: uuid
  schemas:
    ProblemDetails:
      type: object
      required:
      - type
      - title
      - status
      properties:
        type:
          type: string
          format: uri
          description: URI reference identifying error type
        title:
          type: string
          description: Short human-readable summary of problem
        status:
          type: integer
          description: HTTP status code
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence
        instance:
          type: string
          format: uri
          description: URI reference identifying the specific occurrence
    Product:
      type: object
      required:
      - id
      - title
      - handle
      - variants
      properties:
        id:
          type: integer
          description: Unique product ID
        title:
          type: string
          description: Product title in Hebrew/English
        handle:
          type: string
          description: URL handle
        body_html:
          type: string
          description: Product description and specifications
        vendor:
          type: string
          description: Brand vendor (Pura Vida TLV)
        product_type:
          type: string
          description: Jewelry type (Rings, Necklaces, Bracelets, Earrings)
        tags:
          type: array
          items:
            type: string
        variants:
          type: array
          items:
            type: object
            required:
            - id
            - price
            - available
            properties:
              id:
                type: integer
                description: Variant ID
              title:
                type: string
                description: Variant title, e.g. Gold / Size 6
              price:
                type: string
                description: Price in ILS
              available:
                type: boolean
                description: Inventory availability
    Cart:
      type: object
      required:
      - token
      - items
      - item_count
      - total_price
      properties:
        token:
          type: string
          description: Cart session token
        item_count:
          type: integer
          description: Total count of items in cart
        total_price:
          type: integer
          description: Total price in cents (ILS)
        items:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              quantity:
                type: integer
              title:
                type: string
              price:
                type: integer
paths:
  /products.json:
    get:
      summary: List jewelry products
      description: Returns a paginated list of jewelry products with cursor-based
        and page-based pagination.
      operationId: listProducts
      security:
      - StorefrontZeroAuth: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          maximum: 250
        description: Number of products to return
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
        description: Page number
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: Cursor pagination token
      responses:
        '200':
          description: Products retrieved successfully
          headers: &id001
            RateLimit-Limit: &id003
              description: The maximum number of allowed requests in the current time
                window
              schema:
                type: integer
            RateLimit-Remaining: &id004
              description: The number of remaining requests allowed in the current
                time window
              schema:
                type: integer
            RateLimit-Reset: &id005
              description: Number of seconds until the current rate limit window resets
              schema:
                type: integer
            Retry-After: &id006
              description: Number of seconds to wait before retrying after a 429 response
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                required:
                - products
                properties:
                  products:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'
                  page_info:
                    type: object
                    properties:
                      has_next_page:
                        type: boolean
                      end_cursor:
                        type: string
        '400': &id002
          description: Standard Problem Details error response per RFC 9457
          headers: *id001
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401': *id002
        '403': *id002
        '404': *id002
        '422': *id002
        '429': *id002
        '500': *id002
  /products/{handle}.json:
    get:
      summary: Get product details by handle
      description: Retrieve comprehensive details, pricing, and variants for a single
        product.
      operationId: getProductByHandle
      security:
      - StorefrontZeroAuth: []
      parameters:
      - name: handle
        in: path
        required: true
        schema:
          type: string
        description: Product URL handle
      responses:
        '200':
          description: Product details retrieved
          headers: *id001
          content:
            application/json:
              schema:
                type: object
                required:
                - product
                properties:
                  product:
                    $ref: '#/components/schemas/Product'
        '400': *id002
        '401': *id002
        '403': *id002
        '404': *id002
        '422': *id002
        '429': *id002
        '500': *id002
  /collections.json:
    get:
      summary: List collections
      description: Retrieve jewelry collections (Rings, Necklaces, Bracelets, Earrings,
        Sets).
      operationId: listCollections
      security:
      - StorefrontZeroAuth: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Collections retrieved
          headers: *id001
          content:
            application/json:
              schema:
                type: object
                properties:
                  collections:
                    type: array
                    items:
                      type: object
        '400': *id002
        '401': *id002
        '403': *id002
        '404': *id002
        '422': *id002
        '429': *id002
        '500': *id002
  /collections/{handle}/products.json:
    get:
      summary: List products in collection
      description: Retrieve all jewelry items categorized under a specific collection.
      operationId: getCollectionProducts
      security:
      - StorefrontZeroAuth: []
      parameters:
      - name: handle
        in: path
        required: true
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Collection products retrieved
          headers: *id001
          content:
            application/json:
              schema:
                type: object
                properties:
                  products:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'
        '400': *id002
        '401': *id002
        '403': *id002
        '404': *id002
        '422': *id002
        '429': *id002
        '500': *id002
  /search/suggest.json:
    get:
      summary: Search jewelry catalog
      description: Search product titles, tags, and descriptions with instant suggestions.
      operationId: searchCatalog
      security:
      - StorefrontZeroAuth: []
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
        description: Query term
      - name: resources[type]
        in: query
        required: false
        schema:
          type: string
          default: product
      responses:
        '200':
          description: Search suggestions retrieved
          headers: *id001
          content:
            application/json:
              schema:
                type: object
                properties:
                  resources:
                    type: object
        '400': *id002
        '401': *id002
        '403': *id002
        '404': *id002
        '422': *id002
        '429': *id002
        '500': *id002
  /cart.json:
    get:
      summary: Get current shopping cart
      description: Inspect active session shopping cart items and checkout URL.
      operationId: getCart
      security:
      - StorefrontZeroAuth: []
      responses:
        '200':
          description: Cart contents retrieved
          headers: *id001
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
        '400': *id002
        '401': *id002
        '403': *id002
        '404': *id002
        '422': *id002
        '429': *id002
        '500': *id002
  /cart/add.json:
    post:
      summary: Add product variant to cart
      description: Add an item to the buyer session cart. Supports Idempotency-Key
        for network retries.
      operationId: addItemToCart
      security:
      - StorefrontZeroAuth: []
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: integer
                  description: Product variant ID
                quantity:
                  type: integer
                  default: 1
                  description: Quantity to add
      responses:
        '200':
          description: Item added to cart
          headers: *id001
          content:
            application/json:
              schema:
                type: object
        '400': *id002
        '401': *id002
        '403': *id002
        '404': *id002
        '422': *id002
        '429': *id002
        '500': *id002
  /cart/batch.json:
    post:
      summary: Batch add multiple items to cart (Bulk endpoint)
      description: Accepts an array of line items to add to the cart in a single atomic
        bulk operation.
      operationId: batchAddItemsToCart
      security:
      - StorefrontZeroAuth: []
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - items
              properties:
                items:
                  type: array
                  description: Array of item variants and quantities to add
                  items:
                    type: object
                    required:
                    - id
                    - quantity
                    properties:
                      id:
                        type: integer
                        description: Product variant ID
                      quantity:
                        type: integer
                        default: 1
      responses:
        '200':
          description: Items added to cart in bulk
          headers: *id001
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
        '400': *id002
        '401': *id002
        '403': *id002
        '404': *id002
        '422': *id002
        '429': *id002
        '500': *id002
  /cart/clear.json:
    post:
      summary: Clear shopping cart
      description: Empties all line items from the current cart session.
      operationId: clearCart
      security:
      - StorefrontZeroAuth: []
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: Cart cleared
          headers: *id001
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
        '400': *id002
        '401': *id002
        '403': *id002
        '404': *id002
        '422': *id002
        '429': *id002
        '500': *id002
  /v1/jobs/catalog-export:
    post:
      summary: Initiate async bulk catalog export job
      description: Starts an asynchronous background job to export full product catalog
        data.
      operationId: createCatalogExportJob
      security:
      - StorefrontZeroAuth: []
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '202':
          description: Job accepted and processing asynchronously
          headers:
            Location:
              description: URL to poll for job status
              schema:
                type: string
            RateLimit-Limit: *id003
            RateLimit-Remaining: *id004
            RateLimit-Reset: *id005
            Retry-After: *id006
          content:
            application/json:
              schema:
                type: object
                required:
                - job_id
                - status
                - poll_url
                properties:
                  job_id:
                    type: string
                  status:
                    type: string
                    enum:
                    - queued
                    - processing
                    - completed
                    - failed
                  poll_url:
                    type: string
        '400': *id002
        '401': *id002
        '403': *id002
        '404': *id002
        '422': *id002
        '429': *id002
        '500': *id002
  /v1/jobs/{job_id}:
    get:
      summary: Check async job status
      description: Poll status and progress of an asynchronous job.
      operationId: getCatalogExportJobStatus
      security:
      - StorefrontZeroAuth: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Current job status
          headers: *id001
          content:
            application/json:
              schema:
                type: object
                required:
                - job_id
                - status
                properties:
                  job_id:
                    type: string
                  status:
                    type: string
                    enum:
                    - queued
                    - processing
                    - completed
                    - failed
                  result_url:
                    type: string
                    nullable: true
        '400': *id002
        '401': *id002
        '403': *id002
        '404': *id002
        '422': *id002
        '429': *id002
        '500': *id002