openapi: 3.1.0
info:
  title: Corksy API
  description: >
    API for retrieving orders, customers, inventory, wine-club data, and
    products.


    ## Authentication


    This API uses a two-step authentication process:


    ### Step 1: Generate API Key

    First, generate your API key from the Admin Settings API page:

    - Go to: https://admin.corksy.io/settings/apiaccess

    - Create a new API key for your application


    ### Step 2: Obtain Bearer Token

    Use your API key to obtain a bearer token by making a POST request to the
    authentication endpoint:


    **Production:**

    ```bash

    curl --location 'https://connect-api.corksy.io/v1/auth/public/login' \

    --header 'Content-Type: application/json' \

    --data '{
        "apiKey": "your-api-key-here"
    }'

    ```


    **Staging:**

    ```bash

    curl --location
    'https://staging.corksy.io/connect-api/v1/v1/auth/public/login' \

    --header 'Content-Type: application/json' \

    --data '{
        "apiKey": "your-api-key-here"
    }'

    ```


    **Response:**

    ```json

    {
        "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "expiresIn": 1800000
    }

    ```


    ### Step 3: Use Bearer Token

    Use the `accessToken` from the response as a Bearer token in the
    Authorization header for all subsequent API requests:


    **Example Requests:**


    **Get Orders:**

    ```bash

    curl --location
    'https://connect-api.corksy.io/v1/orders?modifiedFromDate=2025-05-01&modifiedToDate=2025-05-31'
    \

    --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

    ```


    **Get Customers:**

    ```bash

    curl --location 'https://connect-api.corksy.io/v1/customers' \

    --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

    ```


    **Get Inventory:**

    ```bash

    curl --location 'https://connect-api.corksy.io/v1/inventory' \

    --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

    ```


    **Get Wine Clubs:**

    ```bash

    curl --location 'https://connect-api.corksy.io/v1/wine-clubs' \

    --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

    ```


    **Get Wine Club Members:**

    ```bash

    curl --location 'https://connect-api.corksy.io/v1/wine-club-members' \

    --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

    ```


    **Get Products:**

    ```bash

    curl --location
    'https://connect-api.corksy.io/v1/products?modifiedFromDate=2025-05-01&modifiedToDate=2025-05-31'
    \

    --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

    ```


    **Note:** The bearer token expires after 30 minutes (1,800,000
    microseconds). You'll need to obtain a new token when it expires.


    ## Pagination


    All list endpoints support pagination to handle large datasets efficiently.
    The API uses offset-based pagination with the following parameters:


    ### Pagination Parameters


    - **`offset`** (optional): Number of records to skip. Default: `0`

    - **`pageSize`** (optional): Number of records to return per page. Default:
    `1000`, Maximum: `1000`


    ### Pagination Response


    Each paginated response includes a `pagination` object with the following
    information:


    ```json

    {
      "data": [...],
      "pagination": {
        "current_offset": 0,
        "page_size": 50,
        "total_records": 1250,
        "total_pages": 25,
        "current_page": 1,
        "pages_remaining": 24,
        "has_next_page": true,
        "has_previous_page": false
      }
    }

    ```


    ### Pagination Examples


    **First Page (Default):**

    ```bash

    curl --location
    'https://connect-api.corksy.io/v1/orders?modifiedFromDate=2025-05-01&modifiedToDate=2025-05-31'
    \

    --header 'Authorization: Bearer YOUR_TOKEN'

    ```


    **Second Page (50 records per page):**

    ```bash

    curl --location
    'https://connect-api.corksy.io/v1/orders?modifiedFromDate=2025-05-01&modifiedToDate=2025-05-31&offset=50&pageSize=50'
    \

    --header 'Authorization: Bearer YOUR_TOKEN'

    ```


    **Custom Page Size:**

    ```bash

    curl --location
    'https://connect-api.corksy.io/v1/orders?modifiedFromDate=2025-05-01&modifiedToDate=2025-05-31&pageSize=100'
    \

    --header 'Authorization: Bearer YOUR_TOKEN'

    ```


    ### Best Practices


    1. **Start with the first page** (no parameters or `offset=0`)

    2. **Use `has_next_page`** to determine if more pages exist

    3. **Increment `offset` by `page_size`** to get the next page

    4. **Choose appropriate `page_size`** based on your needs. 

    5. **Handle rate limits** - each page request counts toward your rate limit
  version: 1.2.0
servers:
  - url: https://staging.corksy.io/connect-api/v1
    description: Staging Environment
  - url: https://connect-api.corksy.io
    description: Production Environment
tags:
  - name: Authentication
    description: Endpoints related to authentication and authorization
  - name: Orders
    description: Endpoints related to orders
  - name: Customers
    description: Endpoints related to customers
  - name: Inventory
    description: Endpoints related to inventory
  - name: Wine Clubs
    description: Endpoints related to wine clubs
  - name: Wine Club Members
    description: Endpoints related to wine-club members
  - name: Products
    description: Endpoints related to products
paths:
  /v1/auth/public/login:
    post:
      summary: Authenticate with API key to obtain bearer token
      description: >
        Authenticate using your API key to obtain a JWT bearer token for
        accessing protected endpoints.


        **Rate Limit:** 10 requests / minute


        **Note:** The returned token expires after 30 minutes. You'll need to
        call this endpoint again to get a new token.
      operationId: authenticate
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - apiKey
              properties:
                apiKey:
                  type: string
                  description: Your API key obtained from the Admin Settings API page
                  example: your-api-key-here
            example:
              apiKey: your-api-key-here
      responses:
        '200':
          description: Authentication successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  accessToken:
                    type: string
                    description: JWT bearer token for API access
                    example: >-
                      eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
                  expiresIn:
                    type: integer
                    description: Token expiration time in microseconds
                    example: 1800000
                required:
                  - accessToken
                  - expiresIn
        '400':
          description: Invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 'cipher: message authentication failed'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Rate limit exceeded. Please try again later.
  /orders:
    get:
      summary: Retrieve a list of orders within a date range
      description: '🚦 **Rate Limit**: 100 requests / minute'
      operationId: getOrders
      tags:
        - Orders
      security:
        - BearerAuth: []
      parameters:
        - name: modifiedFromDate
          in: query
          required: false
          schema:
            type: string
            format: date-time
            example: '2025-05-01T00:00:00Z'
          description: >-
            Filter orders modified from this date (ISO 8601 format). If
            specified without modifiedToDate, current date will be used as end
            date.
        - name: modifiedToDate
          in: query
          required: false
          schema:
            type: string
            format: date-time
            example: '2025-05-31T23:59:59Z'
          description: >-
            Filter orders modified up to this date (ISO 8601 format). Cannot be
            specified without modifiedFromDate.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            example: 0
          description: 'Number of records to skip for pagination (default: 0)'
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            example: 50
          description: 'Number of records to return per page (default: 1000, max: 1000)'
      responses:
        '200':
          description: A list of orders within the specified date range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
  /customers:
    get:
      summary: Retrieve a list of customers
      description: '🚦 **Rate Limit**: 100 requests / minute'
      operationId: getCustomers
      tags:
        - Customers
      security:
        - BearerAuth: []
      parameters:
        - name: modifiedFromDate
          in: query
          required: false
          schema:
            type: string
            format: date-time
            example: '2025-05-01T00:00:00Z'
          description: >-
            Filter customers modified from this date (ISO 8601 format). Optional
            - if not provided, no date filtering is applied.
        - name: modifiedToDate
          in: query
          required: false
          schema:
            type: string
            format: date-time
            example: '2025-05-31T23:59:59Z'
          description: >-
            Filter customers modified up to this date (ISO 8601 format). Cannot
            be specified without modifiedFromDate.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            example: 0
          description: 'Number of records to skip for pagination (default: 0)'
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            example: 50
          description: 'Number of records to return per page (default: 1000, max: 1000)'
      responses:
        '200':
          description: A list of customers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerResponse'
  /inventory:
    get:
      summary: Retrieve a list of inventory items
      description: '🚦 **Rate Limit**: 100 requests / minute'
      operationId: getInventory
      tags:
        - Inventory
      security:
        - BearerAuth: []
      parameters:
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            example: 0
          description: 'Number of records to skip for pagination (default: 0)'
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            example: 50
          description: 'Number of records to return per page (default: 1000, max: 1000)'
      responses:
        '200':
          description: A list of inventory items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryResponse'
  /wine-clubs:
    get:
      summary: Retrieve a list of wine clubs
      description: '🚦 **Rate Limit**: 100 requests / minute'
      operationId: getWineClubs
      tags:
        - Wine Clubs
      security:
        - BearerAuth: []
      parameters:
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            example: 0
          description: 'Number of records to skip for pagination (default: 0)'
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            example: 50
          description: 'Number of records to return per page (default: 1000, max: 1000)'
      responses:
        '200':
          description: A list of wine clubs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WineClubResponse'
  /wine-club-members:
    get:
      summary: Retrieve a list of wine-club members
      description: '🚦 **Rate Limit**: 100 requests / minute'
      operationId: getWineClubMembers
      tags:
        - Wine Club Members
      security:
        - BearerAuth: []
      parameters:
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            example: 0
          description: 'Number of records to skip for pagination (default: 0)'
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            example: 50
          description: 'Number of records to return per page (default: 1000, max: 1000)'
      responses:
        '200':
          description: A list of wine-club members
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WineClubMemberResponse'
  /products:
    get:
      summary: Retrieve a list of products
      description: '🚦 **Rate Limit**: 100 requests / minute'
      operationId: getProducts
      tags:
        - Products
      security:
        - BearerAuth: []
      parameters:
        - name: modifiedFromDate
          in: query
          required: false
          schema:
            type: string
            format: date-time
            example: '2025-05-01T00:00:00Z'
          description: >-
            Filter products modified from this date (ISO 8601 format). Optional
            - if not provided, no date filtering is applied.
        - name: modifiedToDate
          in: query
          required: false
          schema:
            type: string
            format: date-time
            example: '2025-05-31T23:59:59Z'
          description: >-
            Filter products modified up to this date (ISO 8601 format). Cannot
            be specified without modifiedFromDate.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            example: 0
          description: 'Number of records to skip for pagination (default: 0)'
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            example: 50
          description: 'Number of records to return per page (default: 1000, max: 1000)'
      responses:
        '200':
          description: A list of products
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductResponse'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Bearer token obtained from the authentication endpoint.


        **Token Format:** JWT (JSON Web Token)

        **Expiration:** 30 minutes (1,800,000 microseconds)

        **Header Format:** `Authorization: Bearer <token>`


        **Example:**

        ```

        Authorization: Bearer
        eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

        ```
  schemas:
    PaginationInfo:
      type: object
      properties:
        current_offset:
          type: integer
          example: 0
        page_size:
          type: integer
          example: 50
        total_records:
          type: integer
          example: 1250
        total_pages:
          type: integer
          example: 25
        current_page:
          type: integer
          example: 1
        pages_remaining:
          type: integer
          example: 24
        has_next_page:
          type: boolean
          example: true
        has_previous_page:
          type: boolean
          example: false
    Customer:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: f4a71b9d-17a9-4100-8110-46e133d6fc1b
        first_name:
          type: string
          example: Dale
        last_name:
          type: string
          example: Cooper
        email:
          type: string
          example: dcooper@fbi.gov
        phone:
          type: string
          example: +1-202-555-0123
        shipping_preference_company:
          type: string
          example: USPS
        total_orders:
          type: string
          example: '23'
        total_spent:
          type: number
          example: 2847.85
        average_order_value:
          type: number
          example: 123.82
        date_of_birth:
          type: string
          example: '1960-04-19'
        created_at:
          type: string
          format: date-time
          example: '2023-01-15T10:30:00Z'
        customer_type:
          type: string
          example: club_member
        customer_tags:
          type: string
          example: VIP,Black Lodge
        class:
          type: string
          example: Platinum
        primary_card_expiry_date:
          type: string
          example: 12/26
        memberships:
          type: string
          example: Reserve Reds,White Lodge
        has_password:
          type: string
          example: 'true'
        accepts_marketing:
          type: string
          example: 'true'
        note:
          type: string
          example: Prefers cherry pie with orders
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/Address'
        payment_methods:
          type: array
          items:
            $ref: '#/components/schemas/PaymentMethod'
    Address:
      type: object
      properties:
        first_name:
          type: string
          example: Dale
        last_name:
          type: string
          example: Cooper
        address_line1:
          type: string
          example: 123 Twin Peaks Way
        address_line2:
          type: string
          example: Apt 302
        city:
          type: string
          example: Twin Peaks
        state_name:
          type: string
          example: Washington
        state_code:
          type: string
          example: WA
        country_name:
          type: string
          example: United States
        country_code:
          type: string
          example: US
        zip_code:
          type: string
          example: '98065'
        is_primary:
          type: boolean
          example: true
    PaymentMethod:
      type: object
      properties:
        last4:
          type: string
          example: '1234'
        brand:
          type: string
          example: Visa
        exp_month:
          type: string
          example: '12'
        exp_year:
          type: string
          example: '2026'
        is_primary:
          type: boolean
          example: true
        billing_address:
          type: object
          properties:
            first_name:
              type: string
              example: Dale
            last_name:
              type: string
              example: Cooper
            address_line1:
              type: string
              example: 123 Twin Peaks Way
            address_line2:
              type: string
              example: Apt 302
            city:
              type: string
              example: Twin Peaks
            state:
              type: string
              example: Washington
            state_code:
              type: string
              example: WA
            country:
              type: string
              example: United States
            country_code:
              type: string
              example: US
            zip_code:
              type: string
              example: '98065'
            is_primary:
              type: boolean
              example: true
    CustomerResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Customer'
        pagination:
          $ref: '#/components/schemas/PaginationInfo'
    Order:
      type: object
      properties:
        order_number:
          type: integer
          example: 87452
        created_at:
          type: string
          format: date-time
          example: '2025-05-12T18:32:44Z'
        updated_at:
          type: string
          format: date-time
          example: '2025-05-12T18:32:44Z'
        order_date:
          type: string
          example: '2025-05-12T18:32:44Z'
        first_name:
          type: string
          example: Dale
        last_name:
          type: string
          example: Cooper
        date_of_birth:
          type: string
          example: '1960-04-19'
        phone:
          type: string
          example: +1-202-555-0123
        email:
          type: string
          example: dcooper@fbi.gov
        subtotal_price:
          type: number
          example: 245
        total_discounts:
          type: number
          example: 25
        shipping_price:
          type: number
          example: 18.5
        sales_tax:
          type: number
          example: 19.85
        crv:
          type: number
          example: 1.2
        total_tax:
          type: number
          example: 21.05
        total_price:
          type: number
          example: 259.55
        tip:
          type: number
          example: 10
        delivery_preference:
          type: string
          example: shipping
        order_type:
          type: string
          example: ecommerce
        order_subtype:
          type: string
          example: wine_club
        payment_status:
          type: string
          example: paid
        fulfillment_status:
          type: string
          example: fulfilled
        item_count:
          type: integer
          example: 4
        order_items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
          description: Array of order line items
          example:
            - product_name: Black Lodge Chardonnay 2022
              variant_name: 750 ml Bottle
              sku: BL-CHA-2022-750
              quantity: 2
              price: 38
              product_type: Wine
            - product_name: Twin Peaks Merlot 2021
              variant_name: 750 ml Bottle
              sku: TP-MER-2021-750
              quantity: 1
              price: 42
              product_type: Wine
        order_discounts:
          $ref: '#/components/schemas/OrderDiscounts'
          description: Object containing applied discounts
          example:
            auto_discount: 15
            promocode_discount: 10
            pos_discount: null
            custom_discount: null
        shipping_first_name:
          type: string
          example: Dale
        shipping_last_name:
          type: string
          example: Cooper
        shipping_birth_date:
          type: string
          example: '1960-04-19'
        shipping_phone:
          type: string
          example: +1-202-555-0123
        shipping_address_line1:
          type: string
          example: 123 Twin Peaks Way
        shipping_address_line2:
          type: string
          example: Apt 302
        shipping_address_city:
          type: string
          example: Twin Peaks
        shipping_address_state:
          type: string
          example: Washington
        shipping_address_zip_code:
          type: string
          example: '98065'
        billing_first_name:
          type: string
          example: Dale
        billing_last_name:
          type: string
          example: Cooper
        billing_birth_date:
          type: string
          example: '1960-04-19'
        billing_phone:
          type: string
          example: +1-202-555-0123
        billing_address_line1:
          type: string
          example: 123 Twin Peaks Way
        billing_address_line2:
          type: string
          example: Apt 302
        billing_address_city:
          type: string
          example: Twin Peaks
        billing_address_state:
          type: string
          example: Washington
        billing_address_zip_code:
          type: string
          example: '98065'
        customer_type:
          type: string
          example: club_member
        customer_tags:
          type: array
          items:
            type: string
          example:
            - VIP
            - Black Lodge
        class:
          type: string
          example: Platinum
        notes:
          type: string
          example: Leave with doorman at Great Northern Hotel
        payment_type:
          type: string
          example: credit_card
        order_edit:
          type: array
          items:
            $ref: '#/components/schemas/OrderEdit'
          description: Array of order edit records if applicable
          example:
            - order_number: 87452
              created_at: '2025-05-12T18:32:44Z'
              current_operation:
                newItems: '0'
                deletedItems: '1'
                updatedItems: '0'
              summary: {}
              custom_refund_amount: 25
              order_delivery_method: shipping
              order_edit_type: refund
              status: completed
              activity: Order refunded due to customer request
              notes: Customer requested refund for damaged item
        club_package_info:
          $ref: '#/components/schemas/ClubPackageInfo'
          description: Wine club package details if applicable
          example:
            wine_club_name: Black Lodge Reserve
            subscription_package_type: quarterly
            package_number: 2025001
            package_type: red_wine
            package_status: active
            payment_date: '2025-01-15T00:00:00Z'
            open_at: '2025-01-01T00:00:00Z'
            closed_at: '2025-01-31T23:59:59Z'
            customer_package_status: selection_completed
            opened_date: '2025-01-01T00:00:00Z'
            closed_date: '2025-01-31T23:59:59Z'
            package_message: Your wine selection has been confirmed
            is_selection_completed: true
            wine_club_order_status: fulfilled
            compliance_status: compliant
            wine_club_message: Package shipped successfully
        fulfillment_info:
          type: array
          items:
            $ref: '#/components/schemas/FulfillmentInfo'
          description: Array of fulfillment tracking and shipping details
          example:
            - fulfillment_id: ful_123456789
              fulfillment_number: FUL-2025-001
              status: fulfilled
              shipment_status: delivered
              service: FedEx Ground
              created_at: '2025-05-12T18:32:44Z'
              updated_at: '2025-05-13T10:15:30Z'
              tracking:
                company_name: FedEx
                tracking_number: '123456789012'
                tracking_numbers:
                  - '123456789012'
                  - '123456789013'
                tracking_url: >-
                  https://www.fedex.com/tracking?action=track&tracknumbers=123456789012
                tracking_urls:
                  - >-
                    https://www.fedex.com/tracking?action=track&tracknumbers=123456789012
                  - >-
                    https://www.fedex.com/tracking?action=track&tracknumbers=123456789013
              shipping_price: 18.5
              fulfillment_type: shipping
              package_slip: 'true'
              notify_customer: true
              history_created_at: '2025-05-12T18:32:44Z'
        tender_info:
          type: array
          items:
            $ref: '#/components/schemas/TenderInfo'
          description: Array of payment tender records
          example:
            - payment_type: credit_card
              card_type: Visa
              amount: 259.55
              created_at: '2025-05-12T18:32:44Z'
              status: paid
              last_four: '4242'
              card_brand: Visa
              card_expiry:
                month: '12'
                year: '2026'
    OrderResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Order'
        pagination:
          $ref: '#/components/schemas/PaginationInfo'
    OrderItem:
      type: object
      properties:
        product_name:
          type: string
          example: Black Lodge Chardonnay 2022
        variant_name:
          type: string
          example: 750 ml Bottle
        sku:
          type: string
          example: BL-CHA-2022-750
        quantity:
          type: integer
          example: 2
        price:
          type: number
          example: 38
        product_type:
          type: string
          example: Wine
    OrderDiscounts:
      type: object
      properties:
        auto_discount:
          type: number
          example: 15
          description: Wine club automatic discount amount
        promocode_discount:
          type: number
          example: 10
          description: Promotional code discount amount
        pos_discount:
          type: number
          example: 5
          description: Point of sale discount amount
        custom_discount:
          type: number
          example: 8.5
          description: Custom discount amount
    OrderEditCurrentOperation:
      type: object
      properties:
        newItems:
          type: string
          example: '0'
          description: Number of new items added to the order
        deletedItems:
          type: string
          example: '0'
          description: Number of items removed from the order
        updatedItems:
          type: string
          example: '0'
          description: Number of items modified in the order
    OrderEdit:
      type: object
      properties:
        order_number:
          type: integer
          example: 87452
        created_at:
          type: string
          format: date-time
          example: '2025-05-12T18:32:44Z'
        current_operation:
          $ref: '#/components/schemas/OrderEditCurrentOperation'
        summary:
          type: object
          additionalProperties: true
          description: Summary of the order edit operation (JSON raw message)
        custom_refund_amount:
          type: number
          example: 25
        order_delivery_method:
          type: string
          example: shipping
        order_edit_type:
          type: string
          example: refund
        status:
          type: string
          example: completed
        activity:
          type: string
          example: Order refunded due to customer request
        notes:
          type: string
          description: String containing order edit notes
          example: Customer requested refund for damaged item
    ClubPackageInfo:
      type: object
      properties:
        wine_club_name:
          type: string
          example: Black Lodge Reserve
        subscription_package_type:
          type: string
          example: quarterly
        package_number:
          type: integer
          format: int64
          example: 2025001
        package_type:
          type: string
          example: red_wine
        package_status:
          type: string
          example: active
        payment_date:
          type: string
          format: date-time
          example: '2025-01-15T00:00:00Z'
        open_at:
          type: string
          format: date-time
          example: '2025-01-01T00:00:00Z'
        closed_at:
          type: string
          format: date-time
          example: '2025-01-31T23:59:59Z'
        customer_package_status:
          type: string
          example: selection_completed
        opened_date:
          type: string
          format: date-time
          example: '2025-01-01T00:00:00Z'
        closed_date:
          type: string
          format: date-time
          example: '2025-01-31T23:59:59Z'
        package_message:
          type: string
          example: Your wine selection has been confirmed
        is_selection_completed:
          type: boolean
          example: true
        wine_club_order_status:
          type: string
          example: fulfilled
        compliance_status:
          type: string
          example: compliant
        wine_club_message:
          type: string
          example: Package shipped successfully
    CardExpiry:
      type: object
      properties:
        month:
          type: string
          example: '12'
        year:
          type: string
          example: '2026'
    TenderInfo:
      type: object
      properties:
        payment_type:
          type: string
          example: credit_card
        card_type:
          type: string
          example: Visa
        amount:
          type: number
          example: 259.55
        created_at:
          type: string
          format: date-time
          example: '2025-05-12T18:32:44Z'
        status:
          type: string
          example: paid
        last_four:
          type: string
          example: '4242'
        card_brand:
          type: string
          example: Visa
        card_expiry:
          $ref: '#/components/schemas/CardExpiry'
    FulfillmentTracking:
      type: object
      properties:
        company_name:
          type: string
          example: FedEx
        tracking_number:
          type: string
          example: '123456789012'
        tracking_numbers:
          type: array
          items:
            type: string
          example:
            - '123456789012'
            - '123456789013'
        tracking_url:
          type: string
          example: >-
            https://www.fedex.com/tracking?action=track&tracknumbers=123456789012
        tracking_urls:
          type: array
          items:
            type: string
          example:
            - >-
              https://www.fedex.com/tracking?action=track&tracknumbers=123456789012
            - >-
              https://www.fedex.com/tracking?action=track&tracknumbers=123456789013
    FulfillmentInfo:
      type: object
      properties:
        fulfillment_id:
          type: string
          example: ful_123456789
        fulfillment_number:
          type: string
          example: FUL-2025-001
        status:
          type: string
          example: fulfilled
        shipment_status:
          type: string
          example: delivered
        service:
          type: string
          example: FedEx Ground
        created_at:
          type: string
          format: date-time
          example: '2025-05-12T18:32:44Z'
        updated_at:
          type: string
          format: date-time
          example: '2025-05-13T10:15:30Z'
        tracking:
          $ref: '#/components/schemas/FulfillmentTracking'
        shipping_price:
          type: number
          example: 18.5
        fulfillment_type:
          type: string
          example: shipping
        notify_customer:
          type: boolean
          example: true
        history_created_at:
          type: string
          format: date-time
          example: '2025-05-12T18:32:44Z'
    Weight:
      type: object
      properties:
        value:
          type: number
          example: 1.4
        units:
          type: string
          example: kg
    Inventory:
      type: object
      properties:
        product_name:
          type: string
          example: Black Lodge Chardonnay 2022
        variant_name:
          type: string
          example: 750 ml Bottle
        sku:
          type: string
          example: BL-CHA-2022-750
        product_type:
          type: string
          example: Wine
        price:
          type: number
          example: 38
        discount_price:
          type: number
          example: 34
        cost:
          type: number
          example: 18.75
        upc:
          type: string
          example: '012345678905'
        weight:
          $ref: '#/components/schemas/Weight'
        available:
          type: number
          example: 298
        available_by_locations:
          type: object
          additionalProperties: true
          description: JSON object containing inventory levels by location
    InventoryResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Inventory'
        pagination:
          $ref: '#/components/schemas/PaginationInfo'
    WineClubProduct:
      type: object
      properties:
        variant_id:
          type: string
          format: uuid
          example: f4a71b9d-17a9-4100-8110-46e133d6fc1b
        product_name:
          type: string
          example: Black Lodge Chardonnay 2022
        sku:
          type: string
          example: BL-CHA-2022-750
        default_quantity:
          type: integer
          example: 2
        min_quantity:
          type: integer
          example: 1
        max_quantity:
          type: integer
          example: 6
    Package:
      type: object
      properties:
        package_id:
          type: string
          format: uuid
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        package_number:
          type: integer
          example: 2025001
        package_type:
          type: string
          example: red_wine
        status:
          type: string
          example: active
        payment_date:
          type: string
          example: '2025-01-15T00:00:00Z'
        opened_at:
          type: string
          example: '2025-01-01T00:00:00Z'
        closed_at:
          type: string
          example: '2025-01-31T23:59:59Z'
        products:
          type: array
          items:
            $ref: '#/components/schemas/WineClubProduct'
    WineClub:
      type: object
      properties:
        wine_club_name:
          type: string
          example: Black Lodge Reserve
        short_description:
          type: string
          example: >-
            Exclusive, limited-release wines from the mysterious Black Lodge
            collection.
        long_description:
          type: string
          example: >-
            Members receive carefully curated wines from our most enigmatic
            vineyards—each bottle tells a story of the supernatural and the
            sublime. Includes exclusive tasting notes and pairing suggestions.
        number_of_shipment:
          type: string
          example: '4'
        frequency:
          type: string
          example: quarterly
        open_before_n_days:
          type: integer
          example: 21
        close_after_n_days:
          type: integer
          example: 7
        price_range:
          type: string
          example: $220 – $280
        status:
          type: string
          example: active
        publish_date:
          type: string
          example: '2024-11-01T00:00:00Z'
        created_at:
          type: string
          example: '2023-08-15T10:21:37Z'
        default_shipping_rate:
          type: number
          example: 28
        active_members:
          type: integer
          example: 156
        paused_members:
          type: integer
          example: 12
        cancelled_members:
          type: integer
          example: 23
        packages:
          type: array
          items:
            $ref: '#/components/schemas/Package'
    WineClubResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/WineClub'
        pagination:
          $ref: '#/components/schemas/PaginationInfo'
    WineClubPackageProduct:
      type: object
      properties:
        variant_id:
          type: string
          format: uuid
          example: f4a71b9d-17a9-4100-8110-46e133d6fc1b
        variant_name:
          type: string
          example: 750 ml Bottle
        product_id:
          type: string
          format: uuid
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        product_name:
          type: string
          example: Black Lodge Chardonnay 2022
        quantity:
          type: integer
          example: 2
        sku:
          type: string
          example: BL-CHA-2022-750
    PackageDetails:
      type: object
      properties:
        package_id:
          type: string
          format: uuid
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        package_number:
          type: integer
          example: 2025001
        package_type:
          type: string
          example: red_wine
        status:
          type: string
          example: active
        opened_date:
          type: string
          example: '2025-01-01'
        canceled_date:
          type: string
          example: '2025-01-01'
        hold_date:
          type: string
          example: '2025-01-01'
        skipped_date:
          type: string
          example: '2025-01-01'
        is_selection_completed:
          type: boolean
          example: true
        delivery_status:
          type: string
          example: shipped
        financial_status:
          type: string
          example: paid
        products:
          type: array
          items:
            $ref: '#/components/schemas/WineClubPackageProduct'
    WineClubMember:
      type: object
      properties:
        customer_id:
          type: string
          format: uuid
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        member_id:
          type: integer
          format: int64
          example: 1001
        first_name:
          type: string
          example: Audrey
        last_name:
          type: string
          example: Horne
        email:
          type: string
          example: audrey.horne@horneindustries.com
        phone:
          type: string
          example: +1-509-555-0198
        date_of_birth:
          type: string
          example: '1973-08-15'
        club_details:
          type: object
          additionalProperties: true
          description: JSON object containing wine club membership details
        billing_address:
          type: object
          additionalProperties: true
          description: JSON object containing billing address information
        shipping_address:
          type: object
          additionalProperties: true
          description: JSON object containing shipping address information
        payment_method:
          type: object
          additionalProperties: true
          description: JSON object containing payment method details
        spouse_details:
          type: object
          additionalProperties: true
          description: JSON object containing spouse information if applicable
        status:
          type: string
          example: active
        order_delivery_method:
          type: string
          example: shipping
        location_details:
          type: object
          additionalProperties: true
          description: JSON object containing location-specific details
        package_type:
          type: string
          example: 6 bottles
        associate:
          type: string
          example: ''
        created_at:
          type: string
          example: '2023-09-03T14:57:02Z'
        signup_date:
          type: string
          example: '2023-09-01'
        cancel_date:
          type: string
          example: '2025-01-01'
        cancellation_reason:
          type: string
          example: Customer requested cancellation
        hold_date:
          type: string
          example: '2025-01-01'
        package_details:
          type: array
          items:
            $ref: '#/components/schemas/PackageDetails'
    WineClubMemberResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/WineClubMember'
        pagination:
          $ref: '#/components/schemas/PaginationInfo'
    Bundle:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: f4a71b9d-17a9-4100-8110-46e133d6fc1b
        quantity:
          type: integer
          example: 2
        variants:
          type: array
          items:
            $ref: '#/components/schemas/Variant'
    Variant:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: f4a71b9d-17a9-4100-8110-46e133d6fc1b
        name:
          type: string
          example: 750ml Bottle
        sku:
          type: string
          example: BL-PN-2021-750
        price:
          type: number
          format: float
          example: 42
    Size:
      type: object
      properties:
        size:
          type: string
          example: '750'
        unit:
          type: string
          example: ml
    Image:
      type: object
      properties:
        src:
          type: string
          example: https://example.com/images/product.jpg
    Product:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: f4a71b9d-17a9-4100-8110-46e133d6fc1b
        product_name:
          type: string
          example: Black Lodge Pinot Noir 2021
        created_at:
          type: string
          format: date-time
          example: '2024-08-20T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2024-09-10T14:22:00Z'
        last_modified_at:
          type: string
          format: date-time
          example: '2024-09-10T14:22:00Z'
        product_description:
          type: string
          example: >-
            Elegant aromas of cherry, raspberry, and subtle oak with notes of
            the supernatural. Aged in the mystical cellars of Twin Peaks.
        tags:
          type: array
          items:
            type: string
          example:
            - limited_release
            - black_lodge
        status:
          type: string
          example: active
        published_status:
          type: string
          example: published
        published_at_date:
          type: string
          example: '2024-09-10'
        published:
          type: string
          example: 'true'
        alcohol_by_volume:
          type: number
          format: float
          example: 14.2
        vintage:
          type: string
          example: '2021'
        varietal:
          type: string
          example: Pinot Noir
        harvest_date:
          type: string
          example: '2021-09-27'
        acid:
          type: string
          example: 5.8 g/L
        bottle_date:
          type: string
          example: '2023-02-07'
        pairing_notes:
          type: string
          example: Cherry pie, wild mushroom risotto, grilled salmon
        tasting_notes:
          type: string
          example: >-
            Velvety texture, bright red-fruit flavors, subtle spice finish with
            hints of the cherry
        min_inventory:
          type: integer
          example: 25
        page_title:
          type: string
          example: Black Lodge Pinot Noir 2021 | Corksy Wines
        meta_description:
          type: string
          example: >-
            Discover our award-winning Black Lodge Pinot Noir 2021, crafted from
            premium Twin Peaks vineyards.
        url_handle:
          type: string
          example: black-lodge-pinot-noir-2021
        wine_making_notes:
          type: string
          example: >-
            Fermented in small open-top tanks; 18 months in French oak (30%
            new). Aged in the mystical cellars of Twin Peaks.
        vintage_notes:
          type: string
          example: >-
            Cool spring and warm summer resulted in balanced acidity and
            supernatural complexity.
        is_available_for_pos:
          type: boolean
          example: true
        is_available_for_online_store:
          type: boolean
          example: true
        exclusive_for_wine_club:
          type: boolean
          example: false
        pos_title:
          type: string
          example: BL PN 2021
        upc_code:
          type: string
          example: '012345678912'
        product_type_name:
          type: string
          example: Wine
        brand_name:
          type: string
          example: Corksy
        product_variants:
          type: object
          additionalProperties: true
          description: JSON object containing product variant information
        inventory_items:
          type: object
          additionalProperties: true
          description: JSON object containing inventory item information
        bundles:
          type: array
          items:
            $ref: '#/components/schemas/Bundle'
          description: Array of product bundles
        appellation:
          type: string
          example: Willamette Valley AVA
        sizes:
          type: array
          items:
            $ref: '#/components/schemas/Size'
          description: Array of available sizes
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
          description: Array of product images
    ProductResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Product'
        pagination:
          $ref: '#/components/schemas/PaginationInfo'
