openapi: 3.0.3
info:
  title: 'Metorik API Docs'
  description: 'API documentation for Metorik store products, reports, and Engage endpoints.'
  version: 1.0.0
servers:
  -
    url: 'https://{baseUrl}'
    variables:
      baseUrl:
        default: app.metorik.com
tags:
  -
    name: Store
    description: ''
  -
    name: Search
    description: ''
  -
    name: Segments
    description: ''
  -
    name: Orders
    description: ''
  -
    name: Customers
    description: ''
  -
    name: Subscriptions
    description: ''
  -
    name: Products
    description: ''
  -
    name: Variations
    description: ''
  -
    name: Categories
    description: ''
  -
    name: Brands
    description: ''
  -
    name: Coupons
    description: ''
  -
    name: 'Custom Metrics'
    description: ''
  -
    name: Reports
    description: ''
  -
    name: 'Engage > Profiles'
    description: ''
  -
    name: 'Engage > Unsubscribes'
    description: ''
components:
  securitySchemes:
    default:
      type: http
      scheme: bearer
      description: "Generate a store API key from the store's Metorik API settings in Metorik, and choose the scopes needed for the endpoints you want to call."
security:
  -
    default: {  }
paths:
  /api/v1/store:
    get:
      summary: 'Store details'
      operationId: storeDetails
      description: 'Returns the store name, timezone, currency, platform, and earliest available report date for the authenticated API token.'
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  name: 'Metorik Store'
                  timezone: America/New_York
                  currency: USD
                  platform: woocommerce
                  earliest_date: '2024-01-15'
                properties:
                  name:
                    type: string
                    example: 'Metorik Store'
                  timezone:
                    type: string
                    example: America/New_York
                  currency:
                    type: string
                    example: USD
                  platform:
                    type: string
                    example: woocommerce
                  earliest_date:
                    type: string
                    example: '2024-01-15'
      tags:
        - Store
  /api/v1/store/search:
    get:
      summary: 'Search data'
      operationId: searchData
      description: |-
        Search a single resource using Metorik's existing store search system.
        You must provide both the resource to search and the query string. Any
        returned `*_at` timestamps are in UTC.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: resource
          description: 'Resource to search.'
          example: customers
          required: true
          schema:
            type: string
            description: 'Resource to search.'
            example: customers
            enum:
              - orders
              - customers
              - subscriptions
              - refunds
              - products
              - variations
              - categories
              - coupons
        -
          in: query
          name: query
          description: 'Search query. Minimum 3 characters.'
          example: Jarvis
          required: true
          schema:
            type: string
            description: 'Search query. Minimum 3 characters.'
            example: Jarvis
        -
          in: query
          name: count
          description: 'Number of results to return. Min 1, max 25. Defaults to 10 when omitted.'
          example: null
          required: false
          schema:
            type: integer
            description: 'Number of results to return. Min 1, max 25. Defaults to 10 when omitted.'
            example: null
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: orders
                    type: object
                    example:
                      resource: orders
                      data:
                        -
                          order_id: 5000000000001
                          customer_id: 4821
                          order_number: '#1001'
                          order_name: '#1001'
                          status: completed
                          order_created_at: '2026-03-20T09:15:00.000000Z'
                          order_updated_at: '2026-03-20T09:17:00.000000Z'
                          order_paid_at: '2026-03-20T09:16:00.000000Z'
                          order_completed_at: '2026-03-20T09:17:00.000000Z'
                          currency: USD
                          billing_address_first_name: Taylor
                          billing_address_last_name: Smith
                          billing_address_company: 'Acme Corp'
                          billing_address_phone: '5551234567'
                          billing_address_address_1: '123 Main St'
                          billing_address_address_2: 'Suite 100'
                          billing_address_city: 'Los Angeles'
                          billing_address_state: CA
                          billing_address_postcode: '90001'
                          billing_address_country: US
                          billing_address_email: customer@example.com
                          shipping_address_first_name: Taylor
                          shipping_address_last_name: Smith
                          shipping_address_company: 'Acme Corp'
                          shipping_address_phone: '5551234567'
                          shipping_address_address_1: '123 Main St'
                          shipping_address_address_2: 'Suite 100'
                          shipping_address_city: 'Los Angeles'
                          shipping_address_state: CA
                          shipping_address_postcode: '90001'
                          shipping_address_country: US
                          payment_method: stripe
                          payment_method_title: 'Credit Card (Stripe)'
                          shipping_method_title: 'Flat rate'
                          customer_note: 'Leave at front desk'
                          created_via: checkout
                          total: 120
                          total_items: 3
                          total_refunds: 0
                          net: 110.5
                          net_original: 110.5
                          resource_link: 'https://app.metorik.com/orders/5000000000001'
                          line_items:
                            -
                              line_item_id: 7000000000001
                              name: 'Metorik Hoodie'
                              sku: MTK-HOODIE
                              product_id: 4000000000001
                              variation_id: null
                              quantity: 1
                              tax_class: null
                              price: 120
                              subtotal: 120
                              subtotal_tax: 0
                              total: 120
                              total_tax: 0
                              price_original: 120
                              subtotal_original: 120
                              subtotal_tax_original: 0
                              total_original: 120
                              total_tax_original: 0
                              meta: {  }
                              cogs: 0
                    properties:
                      resource:
                        type: string
                        example: orders
                      data:
                        type: array
                        example:
                          -
                            order_id: 5000000000001
                            customer_id: 4821
                            order_number: '#1001'
                            order_name: '#1001'
                            status: completed
                            order_created_at: '2026-03-20T09:15:00.000000Z'
                            order_updated_at: '2026-03-20T09:17:00.000000Z'
                            order_paid_at: '2026-03-20T09:16:00.000000Z'
                            order_completed_at: '2026-03-20T09:17:00.000000Z'
                            currency: USD
                            billing_address_first_name: Taylor
                            billing_address_last_name: Smith
                            billing_address_company: 'Acme Corp'
                            billing_address_phone: '5551234567'
                            billing_address_address_1: '123 Main St'
                            billing_address_address_2: 'Suite 100'
                            billing_address_city: 'Los Angeles'
                            billing_address_state: CA
                            billing_address_postcode: '90001'
                            billing_address_country: US
                            billing_address_email: customer@example.com
                            shipping_address_first_name: Taylor
                            shipping_address_last_name: Smith
                            shipping_address_company: 'Acme Corp'
                            shipping_address_phone: '5551234567'
                            shipping_address_address_1: '123 Main St'
                            shipping_address_address_2: 'Suite 100'
                            shipping_address_city: 'Los Angeles'
                            shipping_address_state: CA
                            shipping_address_postcode: '90001'
                            shipping_address_country: US
                            payment_method: stripe
                            payment_method_title: 'Credit Card (Stripe)'
                            shipping_method_title: 'Flat rate'
                            customer_note: 'Leave at front desk'
                            created_via: checkout
                            total: 120
                            total_items: 3
                            total_refunds: 0
                            net: 110.5
                            net_original: 110.5
                            resource_link: 'https://app.metorik.com/orders/5000000000001'
                            line_items:
                              -
                                line_item_id: 7000000000001
                                name: 'Metorik Hoodie'
                                sku: MTK-HOODIE
                                product_id: 4000000000001
                                variation_id: null
                                quantity: 1
                                tax_class: null
                                price: 120
                                subtotal: 120
                                subtotal_tax: 0
                                total: 120
                                total_tax: 0
                                price_original: 120
                                subtotal_original: 120
                                subtotal_tax_original: 0
                                total_original: 120
                                total_tax_original: 0
                                meta: {  }
                                cogs: 0
                        items:
                          type: object
                          properties:
                            order_id:
                              type: integer
                              example: 5000000000001
                            customer_id:
                              type: integer
                              example: 4821
                            order_number:
                              type: string
                              example: '#1001'
                            order_name:
                              type: string
                              example: '#1001'
                            status:
                              type: string
                              example: completed
                            order_created_at:
                              type: string
                              example: '2026-03-20T09:15:00.000000Z'
                            order_updated_at:
                              type: string
                              example: '2026-03-20T09:17:00.000000Z'
                            order_paid_at:
                              type: string
                              example: '2026-03-20T09:16:00.000000Z'
                            order_completed_at:
                              type: string
                              example: '2026-03-20T09:17:00.000000Z'
                            currency:
                              type: string
                              example: USD
                            billing_address_first_name:
                              type: string
                              example: Taylor
                            billing_address_last_name:
                              type: string
                              example: Smith
                            billing_address_company:
                              type: string
                              example: 'Acme Corp'
                            billing_address_phone:
                              type: string
                              example: '5551234567'
                            billing_address_address_1:
                              type: string
                              example: '123 Main St'
                            billing_address_address_2:
                              type: string
                              example: 'Suite 100'
                            billing_address_city:
                              type: string
                              example: 'Los Angeles'
                            billing_address_state:
                              type: string
                              example: CA
                            billing_address_postcode:
                              type: string
                              example: '90001'
                            billing_address_country:
                              type: string
                              example: US
                            billing_address_email:
                              type: string
                              example: customer@example.com
                            shipping_address_first_name:
                              type: string
                              example: Taylor
                            shipping_address_last_name:
                              type: string
                              example: Smith
                            shipping_address_company:
                              type: string
                              example: 'Acme Corp'
                            shipping_address_phone:
                              type: string
                              example: '5551234567'
                            shipping_address_address_1:
                              type: string
                              example: '123 Main St'
                            shipping_address_address_2:
                              type: string
                              example: 'Suite 100'
                            shipping_address_city:
                              type: string
                              example: 'Los Angeles'
                            shipping_address_state:
                              type: string
                              example: CA
                            shipping_address_postcode:
                              type: string
                              example: '90001'
                            shipping_address_country:
                              type: string
                              example: US
                            payment_method:
                              type: string
                              example: stripe
                            payment_method_title:
                              type: string
                              example: 'Credit Card (Stripe)'
                            shipping_method_title:
                              type: string
                              example: 'Flat rate'
                            customer_note:
                              type: string
                              example: 'Leave at front desk'
                            created_via:
                              type: string
                              example: checkout
                            total:
                              type: integer
                              example: 120
                            total_items:
                              type: integer
                              example: 3
                            total_refunds:
                              type: integer
                              example: 0
                            net:
                              type: number
                              example: 110.5
                            net_original:
                              type: number
                              example: 110.5
                            resource_link:
                              type: string
                              example: 'https://app.metorik.com/orders/5000000000001'
                            line_items:
                              type: array
                              example:
                                -
                                  line_item_id: 7000000000001
                                  name: 'Metorik Hoodie'
                                  sku: MTK-HOODIE
                                  product_id: 4000000000001
                                  variation_id: null
                                  quantity: 1
                                  tax_class: null
                                  price: 120
                                  subtotal: 120
                                  subtotal_tax: 0
                                  total: 120
                                  total_tax: 0
                                  price_original: 120
                                  subtotal_original: 120
                                  subtotal_tax_original: 0
                                  total_original: 120
                                  total_tax_original: 0
                                  meta: {  }
                                  cogs: 0
                              items:
                                type: object
                                properties:
                                  line_item_id:
                                    type: integer
                                    example: 7000000000001
                                  name:
                                    type: string
                                    example: 'Metorik Hoodie'
                                  sku:
                                    type: string
                                    example: MTK-HOODIE
                                  product_id:
                                    type: integer
                                    example: 4000000000001
                                  variation_id:
                                    type: string
                                    example: null
                                    nullable: true
                                  quantity:
                                    type: integer
                                    example: 1
                                  tax_class:
                                    type: string
                                    example: null
                                    nullable: true
                                  price:
                                    type: integer
                                    example: 120
                                  subtotal:
                                    type: integer
                                    example: 120
                                  subtotal_tax:
                                    type: integer
                                    example: 0
                                  total:
                                    type: integer
                                    example: 120
                                  total_tax:
                                    type: integer
                                    example: 0
                                  price_original:
                                    type: integer
                                    example: 120
                                  subtotal_original:
                                    type: integer
                                    example: 120
                                  subtotal_tax_original:
                                    type: integer
                                    example: 0
                                  total_original:
                                    type: integer
                                    example: 120
                                  total_tax_original:
                                    type: integer
                                    example: 0
                                  meta:
                                    type: array
                                    example: {  }
                                  cogs:
                                    type: integer
                                    example: 0
                  -
                    description: customers
                    type: object
                    example:
                      resource: customers
                      data:
                        -
                          customer_id: 4821
                          full_name: 'Taylor Smith'
                          first_name: Taylor
                          last_name: Smith
                          email: customer@example.com
                          customer_created_at: '2025-10-21T14:00:00.000000Z'
                          customer_updated_at: '2026-03-26T12:30:00.000000Z'
                          billing_address_first_name: Taylor
                          billing_address_last_name: Smith
                          billing_address_company: 'Acme Corp'
                          billing_address_address_1: '123 Main St'
                          billing_address_address_2: 'Suite 100'
                          first_order_date: '2025-11-04T09:15:00.000000Z'
                          last_order_date: '2026-03-25T18:42:00.000000Z'
                          order_count: 6
                          item_count: 14
                          total_spent: 842.5
                          average_order: 140.42
                          subscription_count: 1
                          billing_address_city: 'Los Angeles'
                          billing_address_state: CA
                          billing_address_postcode: '90001'
                          billing_address_country: US
                          billing_address_phone: '5551234567'
                          shipping_address_first_name: Taylor
                          shipping_address_last_name: Smith
                          shipping_address_company: 'Acme Corp'
                          shipping_address_address_1: '123 Main St'
                          shipping_address_address_2: 'Suite 100'
                          shipping_address_city: 'Los Angeles'
                          shipping_address_state: CA
                          shipping_address_postcode: '90001'
                          shipping_address_country: US
                          shipping_address_phone: '5551234567'
                          role: customer
                          metorik_profile: false
                          resource_link: 'https://app.metorik.com/customers/4821'
                    properties:
                      resource:
                        type: string
                        example: customers
                      data:
                        type: array
                        example:
                          -
                            customer_id: 4821
                            full_name: 'Taylor Smith'
                            first_name: Taylor
                            last_name: Smith
                            email: customer@example.com
                            customer_created_at: '2025-10-21T14:00:00.000000Z'
                            customer_updated_at: '2026-03-26T12:30:00.000000Z'
                            billing_address_first_name: Taylor
                            billing_address_last_name: Smith
                            billing_address_company: 'Acme Corp'
                            billing_address_address_1: '123 Main St'
                            billing_address_address_2: 'Suite 100'
                            first_order_date: '2025-11-04T09:15:00.000000Z'
                            last_order_date: '2026-03-25T18:42:00.000000Z'
                            order_count: 6
                            item_count: 14
                            total_spent: 842.5
                            average_order: 140.42
                            subscription_count: 1
                            billing_address_city: 'Los Angeles'
                            billing_address_state: CA
                            billing_address_postcode: '90001'
                            billing_address_country: US
                            billing_address_phone: '5551234567'
                            shipping_address_first_name: Taylor
                            shipping_address_last_name: Smith
                            shipping_address_company: 'Acme Corp'
                            shipping_address_address_1: '123 Main St'
                            shipping_address_address_2: 'Suite 100'
                            shipping_address_city: 'Los Angeles'
                            shipping_address_state: CA
                            shipping_address_postcode: '90001'
                            shipping_address_country: US
                            shipping_address_phone: '5551234567'
                            role: customer
                            metorik_profile: false
                            resource_link: 'https://app.metorik.com/customers/4821'
                        items:
                          type: object
                          properties:
                            customer_id:
                              type: integer
                              example: 4821
                            full_name:
                              type: string
                              example: 'Taylor Smith'
                            first_name:
                              type: string
                              example: Taylor
                            last_name:
                              type: string
                              example: Smith
                            email:
                              type: string
                              example: customer@example.com
                            customer_created_at:
                              type: string
                              example: '2025-10-21T14:00:00.000000Z'
                            customer_updated_at:
                              type: string
                              example: '2026-03-26T12:30:00.000000Z'
                            billing_address_first_name:
                              type: string
                              example: Taylor
                            billing_address_last_name:
                              type: string
                              example: Smith
                            billing_address_company:
                              type: string
                              example: 'Acme Corp'
                            billing_address_address_1:
                              type: string
                              example: '123 Main St'
                            billing_address_address_2:
                              type: string
                              example: 'Suite 100'
                            first_order_date:
                              type: string
                              example: '2025-11-04T09:15:00.000000Z'
                            last_order_date:
                              type: string
                              example: '2026-03-25T18:42:00.000000Z'
                            order_count:
                              type: integer
                              example: 6
                            item_count:
                              type: integer
                              example: 14
                            total_spent:
                              type: number
                              example: 842.5
                            average_order:
                              type: number
                              example: 140.42
                            subscription_count:
                              type: integer
                              example: 1
                            billing_address_city:
                              type: string
                              example: 'Los Angeles'
                            billing_address_state:
                              type: string
                              example: CA
                            billing_address_postcode:
                              type: string
                              example: '90001'
                            billing_address_country:
                              type: string
                              example: US
                            billing_address_phone:
                              type: string
                              example: '5551234567'
                            shipping_address_first_name:
                              type: string
                              example: Taylor
                            shipping_address_last_name:
                              type: string
                              example: Smith
                            shipping_address_company:
                              type: string
                              example: 'Acme Corp'
                            shipping_address_address_1:
                              type: string
                              example: '123 Main St'
                            shipping_address_address_2:
                              type: string
                              example: 'Suite 100'
                            shipping_address_city:
                              type: string
                              example: 'Los Angeles'
                            shipping_address_state:
                              type: string
                              example: CA
                            shipping_address_postcode:
                              type: string
                              example: '90001'
                            shipping_address_country:
                              type: string
                              example: US
                            shipping_address_phone:
                              type: string
                              example: '5551234567'
                            role:
                              type: string
                              example: customer
                            metorik_profile:
                              type: boolean
                              example: false
                            resource_link:
                              type: string
                              example: 'https://app.metorik.com/customers/4821'
                  -
                    description: subscriptions
                    type: object
                    example:
                      resource: subscriptions
                      data:
                        -
                          subscription_id: 99123
                          status: active
                          customer_id: 4821
                          billing_period: month
                          billing_interval: 1
                          start_date: '2026-01-01T00:00:00.000000Z'
                          next_payment_date: '2026-04-01T00:00:00.000000Z'
                          trial_end_date: null
                          end_date: null
                          cancelled_date: null
                          total: 25
                          total_items: 1
                          total_mrr: 25
                          resource_link: 'https://app.metorik.com/subscriptions/99123'
                          requires_manual_renewal: false
                          payment_method: stripe
                          payment_method_title: 'Credit Card (Stripe)'
                    properties:
                      resource:
                        type: string
                        example: subscriptions
                      data:
                        type: array
                        example:
                          -
                            subscription_id: 99123
                            status: active
                            customer_id: 4821
                            billing_period: month
                            billing_interval: 1
                            start_date: '2026-01-01T00:00:00.000000Z'
                            next_payment_date: '2026-04-01T00:00:00.000000Z'
                            trial_end_date: null
                            end_date: null
                            cancelled_date: null
                            total: 25
                            total_items: 1
                            total_mrr: 25
                            resource_link: 'https://app.metorik.com/subscriptions/99123'
                            requires_manual_renewal: false
                            payment_method: stripe
                            payment_method_title: 'Credit Card (Stripe)'
                        items:
                          type: object
                          properties:
                            subscription_id:
                              type: integer
                              example: 99123
                            status:
                              type: string
                              example: active
                            customer_id:
                              type: integer
                              example: 4821
                            billing_period:
                              type: string
                              example: month
                            billing_interval:
                              type: integer
                              example: 1
                            start_date:
                              type: string
                              example: '2026-01-01T00:00:00.000000Z'
                            next_payment_date:
                              type: string
                              example: '2026-04-01T00:00:00.000000Z'
                            trial_end_date:
                              type: string
                              example: null
                              nullable: true
                            end_date:
                              type: string
                              example: null
                              nullable: true
                            cancelled_date:
                              type: string
                              example: null
                              nullable: true
                            total:
                              type: integer
                              example: 25
                            total_items:
                              type: integer
                              example: 1
                            total_mrr:
                              type: integer
                              example: 25
                            resource_link:
                              type: string
                              example: 'https://app.metorik.com/subscriptions/99123'
                            requires_manual_renewal:
                              type: boolean
                              example: false
                            payment_method:
                              type: string
                              example: stripe
                            payment_method_title:
                              type: string
                              example: 'Credit Card (Stripe)'
                  -
                    description: refunds
                    type: object
                    example:
                      resource: refunds
                      data:
                        -
                          refund_id: 88001
                          order_id: 5000000000001
                          refund_created_at: '2026-03-22T12:05:00.000000Z'
                          reason: 'Damaged item'
                          amount: 12.5
                          amount_original: 12.5
                          line_items_total: 10
                          shipping_total: 2
                          total_tax: 0.5
                          resource_link: 'https://app.metorik.com/orders/5000000000001'
                          currency: USD
                          refunded_by: 4821
                          refunded_by_email: staff@example.com
                    properties:
                      resource:
                        type: string
                        example: refunds
                      data:
                        type: array
                        example:
                          -
                            refund_id: 88001
                            order_id: 5000000000001
                            refund_created_at: '2026-03-22T12:05:00.000000Z'
                            reason: 'Damaged item'
                            amount: 12.5
                            amount_original: 12.5
                            line_items_total: 10
                            shipping_total: 2
                            total_tax: 0.5
                            resource_link: 'https://app.metorik.com/orders/5000000000001'
                            currency: USD
                            refunded_by: 4821
                            refunded_by_email: staff@example.com
                        items:
                          type: object
                          properties:
                            refund_id:
                              type: integer
                              example: 88001
                            order_id:
                              type: integer
                              example: 5000000000001
                            refund_created_at:
                              type: string
                              example: '2026-03-22T12:05:00.000000Z'
                            reason:
                              type: string
                              example: 'Damaged item'
                            amount:
                              type: number
                              example: 12.5
                            amount_original:
                              type: number
                              example: 12.5
                            line_items_total:
                              type: integer
                              example: 10
                            shipping_total:
                              type: integer
                              example: 2
                            total_tax:
                              type: number
                              example: 0.5
                            resource_link:
                              type: string
                              example: 'https://app.metorik.com/orders/5000000000001'
                            currency:
                              type: string
                              example: USD
                            refunded_by:
                              type: integer
                              example: 4821
                            refunded_by_email:
                              type: string
                              example: staff@example.com
                  -
                    description: products
                    type: object
                    example:
                      resource: products
                      data:
                        -
                          product_id: 4821
                          title: 'Metorik Hoodie'
                          sku: MTK-HOODIE
                          product_created_at: '2025-09-12T08:00:00.000000Z'
                          product_updated_at: '2026-03-25T13:45:00.000000Z'
                          resource_link: 'https://app.metorik.com/products/4821'
                          type: simple
                          status: publish
                          stock_quantity: 18
                          in_stock: true
                          current_price: 79
                          regular_price: 79
                          sale_price: 0
                          image: 'https://app.metorik.com/images/products/4821.png'
                    properties:
                      resource:
                        type: string
                        example: products
                      data:
                        type: array
                        example:
                          -
                            product_id: 4821
                            title: 'Metorik Hoodie'
                            sku: MTK-HOODIE
                            product_created_at: '2025-09-12T08:00:00.000000Z'
                            product_updated_at: '2026-03-25T13:45:00.000000Z'
                            resource_link: 'https://app.metorik.com/products/4821'
                            type: simple
                            status: publish
                            stock_quantity: 18
                            in_stock: true
                            current_price: 79
                            regular_price: 79
                            sale_price: 0
                            image: 'https://app.metorik.com/images/products/4821.png'
                        items:
                          type: object
                          properties:
                            product_id:
                              type: integer
                              example: 4821
                            title:
                              type: string
                              example: 'Metorik Hoodie'
                            sku:
                              type: string
                              example: MTK-HOODIE
                            product_created_at:
                              type: string
                              example: '2025-09-12T08:00:00.000000Z'
                            product_updated_at:
                              type: string
                              example: '2026-03-25T13:45:00.000000Z'
                            resource_link:
                              type: string
                              example: 'https://app.metorik.com/products/4821'
                            type:
                              type: string
                              example: simple
                            status:
                              type: string
                              example: publish
                            stock_quantity:
                              type: integer
                              example: 18
                            in_stock:
                              type: boolean
                              example: true
                            current_price:
                              type: integer
                              example: 79
                            regular_price:
                              type: integer
                              example: 79
                            sale_price:
                              type: integer
                              example: 0
                            image:
                              type: string
                              example: 'https://app.metorik.com/images/products/4821.png'
                  -
                    description: variations
                    type: object
                    example:
                      resource: variations
                      data:
                        -
                          variation_id: 9912
                          product_id: 4821
                          name: 'Black / Medium'
                          sku: MTK-HOODIE-BLK-M
                          atts:
                            -
                              name: Color
                              option: Black
                            -
                              name: Size
                              option: Medium
                          variation_created_at: '2025-10-01T09:00:00.000000Z'
                          variation_updated_at: '2026-03-18T10:30:00.000000Z'
                          resource_link: 'https://app.metorik.com/products/4821?variation=9912'
                          current_price: 79
                          regular_price: 79
                          sale_price: 0
                          stock_quantity: 9
                          in_stock: true
                          product:
                            product_id: 4821
                            title: 'Metorik Hoodie'
                            sku: MTK-HOODIE
                    properties:
                      resource:
                        type: string
                        example: variations
                      data:
                        type: array
                        example:
                          -
                            variation_id: 9912
                            product_id: 4821
                            name: 'Black / Medium'
                            sku: MTK-HOODIE-BLK-M
                            atts:
                              -
                                name: Color
                                option: Black
                              -
                                name: Size
                                option: Medium
                            variation_created_at: '2025-10-01T09:00:00.000000Z'
                            variation_updated_at: '2026-03-18T10:30:00.000000Z'
                            resource_link: 'https://app.metorik.com/products/4821?variation=9912'
                            current_price: 79
                            regular_price: 79
                            sale_price: 0
                            stock_quantity: 9
                            in_stock: true
                            product:
                              product_id: 4821
                              title: 'Metorik Hoodie'
                              sku: MTK-HOODIE
                        items:
                          type: object
                          properties:
                            variation_id:
                              type: integer
                              example: 9912
                            product_id:
                              type: integer
                              example: 4821
                            name:
                              type: string
                              example: 'Black / Medium'
                            sku:
                              type: string
                              example: MTK-HOODIE-BLK-M
                            atts:
                              type: array
                              example:
                                -
                                  name: Color
                                  option: Black
                                -
                                  name: Size
                                  option: Medium
                              items:
                                type: object
                                properties:
                                  name:
                                    type: string
                                    example: Color
                                  option:
                                    type: string
                                    example: Black
                            variation_created_at:
                              type: string
                              example: '2025-10-01T09:00:00.000000Z'
                            variation_updated_at:
                              type: string
                              example: '2026-03-18T10:30:00.000000Z'
                            resource_link:
                              type: string
                              example: 'https://app.metorik.com/products/4821?variation=9912'
                            current_price:
                              type: integer
                              example: 79
                            regular_price:
                              type: integer
                              example: 79
                            sale_price:
                              type: integer
                              example: 0
                            stock_quantity:
                              type: integer
                              example: 9
                            in_stock:
                              type: boolean
                              example: true
                            product:
                              type: object
                              properties:
                                product_id:
                                  type: integer
                                  example: 4821
                                title:
                                  type: string
                                  example: 'Metorik Hoodie'
                                sku:
                                  type: string
                                  example: MTK-HOODIE
                  -
                    description: categories
                    type: object
                    example:
                      resource: categories
                      data:
                        -
                          category_id: 8801
                          name: Supplements
                          parent_category_id: null
                          slug: supplements
                          resource_link: 'https://app.metorik.com/categories/8801'
                          description: 'Nutritional supplements and vitamins.'
                          products: 24
                          net_items_sold: 481
                          net_sales: 12640.55
                    properties:
                      resource:
                        type: string
                        example: categories
                      data:
                        type: array
                        example:
                          -
                            category_id: 8801
                            name: Supplements
                            parent_category_id: null
                            slug: supplements
                            resource_link: 'https://app.metorik.com/categories/8801'
                            description: 'Nutritional supplements and vitamins.'
                            products: 24
                            net_items_sold: 481
                            net_sales: 12640.55
                        items:
                          type: object
                          properties:
                            category_id:
                              type: integer
                              example: 8801
                            name:
                              type: string
                              example: Supplements
                            parent_category_id:
                              type: string
                              example: null
                              nullable: true
                            slug:
                              type: string
                              example: supplements
                            resource_link:
                              type: string
                              example: 'https://app.metorik.com/categories/8801'
                            description:
                              type: string
                              example: 'Nutritional supplements and vitamins.'
                            products:
                              type: integer
                              example: 24
                            net_items_sold:
                              type: integer
                              example: 481
                            net_sales:
                              type: number
                              example: 12640.55
                  -
                    description: coupons
                    type: object
                    example:
                      resource: coupons
                      data:
                        -
                          coupon_id: 123
                          code: SUMMER10
                          status: publish
                          coupon_created_at: '2025-05-01T11:00:00.000000Z'
                          coupon_updated_at: '2026-03-01T07:30:00.000000Z'
                          resource_link: 'https://app.metorik.com/coupons/123'
                          amount: 10
                          discount_type: percent
                          date_expires: null
                          usage_count: 42
                    properties:
                      resource:
                        type: string
                        example: coupons
                      data:
                        type: array
                        example:
                          -
                            coupon_id: 123
                            code: SUMMER10
                            status: publish
                            coupon_created_at: '2025-05-01T11:00:00.000000Z'
                            coupon_updated_at: '2026-03-01T07:30:00.000000Z'
                            resource_link: 'https://app.metorik.com/coupons/123'
                            amount: 10
                            discount_type: percent
                            date_expires: null
                            usage_count: 42
                        items:
                          type: object
                          properties:
                            coupon_id:
                              type: integer
                              example: 123
                            code:
                              type: string
                              example: SUMMER10
                            status:
                              type: string
                              example: publish
                            coupon_created_at:
                              type: string
                              example: '2025-05-01T11:00:00.000000Z'
                            coupon_updated_at:
                              type: string
                              example: '2026-03-01T07:30:00.000000Z'
                            resource_link:
                              type: string
                              example: 'https://app.metorik.com/coupons/123'
                            amount:
                              type: integer
                              example: 10
                            discount_type:
                              type: string
                              example: percent
                            date_expires:
                              type: string
                              example: null
                              nullable: true
                            usage_count:
                              type: integer
                              example: 42
      tags:
        - Search
  /api/v1/store/segments:
    get:
      summary: Segments
      operationId: segments
      description: 'Returns store-wide saved segments for a store resource.'
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: resource
          description: 'Segment resource.'
          example: orders
          required: true
          schema:
            type: string
            description: 'Segment resource.'
            example: orders
            enum:
              - orders
              - customers
              - subscriptions
              - coupons
              - products
              - variations
              - categories
              - refunds
              - carts
        -
          in: query
          name: page
          description: 'Page number. Min 1.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number. Min 1.'
            example: 1
        -
          in: query
          name: per_page
          description: 'Number of segments per page. Min 1, max 100. Defaults to 50.'
          example: 50
          required: false
          schema:
            type: integer
            description: 'Number of segments per page. Min 1, max 100. Defaults to 50.'
            example: 50
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: 101
                      name: 'High Value Orders'
                      description: null
                      resource: orders
                      match: all
                      filters: {  }
                      store_wide: true
                      is_preset: false
                  pagination:
                    current_page: 1
                    per_page: 50
                    has_more_pages: false
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: 101
                        name: 'High Value Orders'
                        description: null
                        resource: orders
                        match: all
                        filters: {  }
                        store_wide: true
                        is_preset: false
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 101
                        name:
                          type: string
                          example: 'High Value Orders'
                        description:
                          type: string
                          example: null
                          nullable: true
                        resource:
                          type: string
                          example: orders
                        match:
                          type: string
                          example: all
                        filters:
                          type: array
                          example: {  }
                        store_wide:
                          type: boolean
                          example: true
                        is_preset:
                          type: boolean
                          example: false
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 50
                      has_more_pages:
                        type: boolean
                        example: false
      tags:
        - Segments
  /api/v1/store/orders:
    get:
      summary: 'Order data'
      operationId: orderData
      description: |-
        Returns orders from your store together with billing details and order
        totals. All returned `*_at` timestamps are in UTC.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: page
          description: 'Page number for pagination.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number for pagination.'
            example: 1
        -
          in: query
          name: per_page
          description: 'Number of orders per page. Min 1, max 100.'
          example: 10
          required: false
          schema:
            type: integer
            description: 'Number of orders per page. Min 1, max 100.'
            example: 10
        -
          in: query
          name: order_by
          description: 'Sort field.'
          example: order_created_at
          required: false
          schema:
            type: string
            description: 'Sort field.'
            example: order_created_at
            enum:
              - order_created_at
              - order_updated_at
              - order_paid_at
              - order_completed_at
              - order_number
              - total
              - total_items
              - total_refunds
        -
          in: query
          name: order_dir
          description: 'Sort direction.'
          example: desc
          required: false
          schema:
            type: string
            description: 'Sort direction.'
            example: desc
            enum:
              - asc
              - desc
        -
          in: query
          name: search
          description: 'Search term to filter orders.'
          example: '1001'
          required: false
          schema:
            type: string
            description: 'Search term to filter orders.'
            example: '1001'
        -
          in: query
          name: filters
          description: 'Optional JSON-encoded filter array. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference).'
          example: '[{"field":"total","operator":"gte","value":100},{"field":"status","operator":"eq","value":"completed"}]'
          required: false
          schema:
            type: string
            description: 'Optional JSON-encoded filter array. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference).'
            example: '[{"field":"total","operator":"gte","value":100},{"field":"status","operator":"eq","value":"completed"}]'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      order_id: 1001
                      customer_id: 482
                      order_number: '1001'
                      order_name: '#1001'
                      status: completed
                      order_created_at: '2026-03-25T18:42:00Z'
                      order_updated_at: '2026-03-25T18:42:00Z'
                      order_paid_at: '2026-03-25T18:42:00Z'
                      order_completed_at: '2026-03-25T18:42:00Z'
                      currency: USD
                      billing_address_first_name: Tony
                      billing_address_last_name: Stark
                      billing_address_company: 'Stark Industries'
                      billing_address_phone: '5551234567'
                      billing_address_address_1: '10880 Malibu Point'
                      billing_address_address_2: 'Suite 1'
                      billing_address_city: Malibu
                      billing_address_state: CA
                      billing_address_postcode: '90265'
                      billing_address_country: US
                      billing_address_email: tony@example.com
                      shipping_address_first_name: Pepper
                      shipping_address_last_name: Potts
                      shipping_address_company: 'Stark Industries'
                      shipping_address_phone: '5551234567'
                      shipping_address_address_1: '200 Park Ave'
                      shipping_address_address_2: 'Floor 2'
                      shipping_address_city: 'New York'
                      shipping_address_state: NY
                      shipping_address_postcode: '10166'
                      shipping_address_country: US
                      payment_method: stripe
                      payment_method_title: 'Credit Card (Stripe)'
                      shipping_method_title: 'Flat rate'
                      customer_note: 'Leave at front desk'
                      created_via: checkout
                      referer: 'https://google.com/search?q=metorik'
                      landing_path: /products/hoodie
                      utm_campaign: spring-sale
                      utm_medium: cpc
                      utm_source: google
                      utm_term: 'metorik hoodie'
                      utm_content: ad-1
                      utm_id: campaign-123
                      total: 120
                      total_items: 3
                      total_refunds: 15
                      net: 105
                      net_original: 105
                      cogs: 42.5
                      product_cogs: 36.25
                      shipping_cogs: 3.5
                      transaction_cogs: 1.75
                      extra_cogs: 1
                      gross_profit: 77.5
                      resource_link: 'https://app.metorik.com/orders/1001'
                  pagination:
                    current_page: 1
                    per_page: 10
                    has_more_pages: true
                properties:
                  data:
                    type: array
                    example:
                      -
                        order_id: 1001
                        customer_id: 482
                        order_number: '1001'
                        order_name: '#1001'
                        status: completed
                        order_created_at: '2026-03-25T18:42:00Z'
                        order_updated_at: '2026-03-25T18:42:00Z'
                        order_paid_at: '2026-03-25T18:42:00Z'
                        order_completed_at: '2026-03-25T18:42:00Z'
                        currency: USD
                        billing_address_first_name: Tony
                        billing_address_last_name: Stark
                        billing_address_company: 'Stark Industries'
                        billing_address_phone: '5551234567'
                        billing_address_address_1: '10880 Malibu Point'
                        billing_address_address_2: 'Suite 1'
                        billing_address_city: Malibu
                        billing_address_state: CA
                        billing_address_postcode: '90265'
                        billing_address_country: US
                        billing_address_email: tony@example.com
                        shipping_address_first_name: Pepper
                        shipping_address_last_name: Potts
                        shipping_address_company: 'Stark Industries'
                        shipping_address_phone: '5551234567'
                        shipping_address_address_1: '200 Park Ave'
                        shipping_address_address_2: 'Floor 2'
                        shipping_address_city: 'New York'
                        shipping_address_state: NY
                        shipping_address_postcode: '10166'
                        shipping_address_country: US
                        payment_method: stripe
                        payment_method_title: 'Credit Card (Stripe)'
                        shipping_method_title: 'Flat rate'
                        customer_note: 'Leave at front desk'
                        created_via: checkout
                        referer: 'https://google.com/search?q=metorik'
                        landing_path: /products/hoodie
                        utm_campaign: spring-sale
                        utm_medium: cpc
                        utm_source: google
                        utm_term: 'metorik hoodie'
                        utm_content: ad-1
                        utm_id: campaign-123
                        total: 120
                        total_items: 3
                        total_refunds: 15
                        net: 105
                        net_original: 105
                        cogs: 42.5
                        product_cogs: 36.25
                        shipping_cogs: 3.5
                        transaction_cogs: 1.75
                        extra_cogs: 1
                        gross_profit: 77.5
                        resource_link: 'https://app.metorik.com/orders/1001'
                    items:
                      type: object
                      properties:
                        order_id:
                          type: integer
                          example: 1001
                        customer_id:
                          type: integer
                          example: 482
                        order_number:
                          type: string
                          example: '1001'
                        order_name:
                          type: string
                          example: '#1001'
                        status:
                          type: string
                          example: completed
                        order_created_at:
                          type: string
                          example: '2026-03-25T18:42:00Z'
                        order_updated_at:
                          type: string
                          example: '2026-03-25T18:42:00Z'
                        order_paid_at:
                          type: string
                          example: '2026-03-25T18:42:00Z'
                        order_completed_at:
                          type: string
                          example: '2026-03-25T18:42:00Z'
                        currency:
                          type: string
                          example: USD
                        billing_address_first_name:
                          type: string
                          example: Tony
                        billing_address_last_name:
                          type: string
                          example: Stark
                        billing_address_company:
                          type: string
                          example: 'Stark Industries'
                        billing_address_phone:
                          type: string
                          example: '5551234567'
                        billing_address_address_1:
                          type: string
                          example: '10880 Malibu Point'
                        billing_address_address_2:
                          type: string
                          example: 'Suite 1'
                        billing_address_city:
                          type: string
                          example: Malibu
                        billing_address_state:
                          type: string
                          example: CA
                        billing_address_postcode:
                          type: string
                          example: '90265'
                        billing_address_country:
                          type: string
                          example: US
                        billing_address_email:
                          type: string
                          example: tony@example.com
                        shipping_address_first_name:
                          type: string
                          example: Pepper
                        shipping_address_last_name:
                          type: string
                          example: Potts
                        shipping_address_company:
                          type: string
                          example: 'Stark Industries'
                        shipping_address_phone:
                          type: string
                          example: '5551234567'
                        shipping_address_address_1:
                          type: string
                          example: '200 Park Ave'
                        shipping_address_address_2:
                          type: string
                          example: 'Floor 2'
                        shipping_address_city:
                          type: string
                          example: 'New York'
                        shipping_address_state:
                          type: string
                          example: NY
                        shipping_address_postcode:
                          type: string
                          example: '10166'
                        shipping_address_country:
                          type: string
                          example: US
                        payment_method:
                          type: string
                          example: stripe
                        payment_method_title:
                          type: string
                          example: 'Credit Card (Stripe)'
                        shipping_method_title:
                          type: string
                          example: 'Flat rate'
                        customer_note:
                          type: string
                          example: 'Leave at front desk'
                        created_via:
                          type: string
                          example: checkout
                        referer:
                          type: string
                          example: 'https://google.com/search?q=metorik'
                        landing_path:
                          type: string
                          example: /products/hoodie
                        utm_campaign:
                          type: string
                          example: spring-sale
                        utm_medium:
                          type: string
                          example: cpc
                        utm_source:
                          type: string
                          example: google
                        utm_term:
                          type: string
                          example: 'metorik hoodie'
                        utm_content:
                          type: string
                          example: ad-1
                        utm_id:
                          type: string
                          example: campaign-123
                        total:
                          type: integer
                          example: 120
                        total_items:
                          type: integer
                          example: 3
                        total_refunds:
                          type: integer
                          example: 15
                        net:
                          type: integer
                          example: 105
                        net_original:
                          type: integer
                          example: 105
                        cogs:
                          type: number
                          example: 42.5
                        product_cogs:
                          type: number
                          example: 36.25
                        shipping_cogs:
                          type: number
                          example: 3.5
                        transaction_cogs:
                          type: number
                          example: 1.75
                        extra_cogs:
                          type: integer
                          example: 1
                        gross_profit:
                          type: number
                          example: 77.5
                        resource_link:
                          type: string
                          example: 'https://app.metorik.com/orders/1001'
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 10
                      has_more_pages:
                        type: boolean
                        example: true
      tags:
        - Orders
  /api/v1/store/orders/totals:
    get:
      summary: 'Order totals'
      operationId: orderTotals
      description: |-
        Returns summary totals for the same order dataset as the orders list
        endpoint. All returned `*_at` timestamps are in UTC.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: search
          description: 'Search term to filter orders before totaling.'
          example: '1001'
          required: false
          schema:
            type: string
            description: 'Search term to filter orders before totaling.'
            example: '1001'
        -
          in: query
          name: filters
          description: 'Optional JSON-encoded filter array. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference).'
          example: '[{"field":"total","operator":"gte","value":100}]'
          required: false
          schema:
            type: string
            description: 'Optional JSON-encoded filter array. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference).'
            example: '[{"field":"total","operator":"gte","value":100}]'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    count: 712
                    total: 124550.42
                    total_items: 1196
                    average_order_value: 174.9
                    average_order_items: 1.7
                    net: 118420.13
                    unique_customers: 508
                    total_shipping: 5421.1
                    total_discount: 2140.55
                    total_tax: 10334.89
                    total_fees: 882.41
                    total_refunds: 1986.23
                properties:
                  data:
                    type: object
                    properties:
                      count:
                        type: integer
                        example: 712
                      total:
                        type: number
                        example: 124550.42
                      total_items:
                        type: integer
                        example: 1196
                      average_order_value:
                        type: number
                        example: 174.9
                      average_order_items:
                        type: number
                        example: 1.7
                      net:
                        type: number
                        example: 118420.13
                      unique_customers:
                        type: integer
                        example: 508
                      total_shipping:
                        type: number
                        example: 5421.1
                      total_discount:
                        type: number
                        example: 2140.55
                      total_tax:
                        type: number
                        example: 10334.89
                      total_fees:
                        type: number
                        example: 882.41
                      total_refunds:
                        type: number
                        example: 1986.23
      tags:
        - Orders
  /api/v1/store/customers:
    get:
      summary: 'Customer data'
      operationId: customerData
      description: |-
        Returns customers from your store together with all-time customer
        statistics, or period-based customer statistics when `order_start_date`
        and `order_end_date` are provided. All returned `*_at` timestamps are in
        UTC.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: page
          description: 'Page number for pagination.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number for pagination.'
            example: 1
        -
          in: query
          name: per_page
          description: 'Number of customers per page. Min 1, max 100.'
          example: 10
          required: false
          schema:
            type: integer
            description: 'Number of customers per page. Min 1, max 100.'
            example: 10
        -
          in: query
          name: order_by
          description: 'Sort field.'
          example: customer_created_at
          required: false
          schema:
            type: string
            description: 'Sort field.'
            example: customer_created_at
            enum:
              - customer_created_at
              - customer_id
              - full_name
              - email
              - first_order_date
              - last_order_date
              - order_count
              - total_spent
        -
          in: query
          name: order_dir
          description: 'Sort direction.'
          example: desc
          required: false
          schema:
            type: string
            description: 'Sort direction.'
            example: desc
            enum:
              - asc
              - desc
        -
          in: query
          name: search
          description: 'Search term to filter customers.'
          example: jarvis
          required: false
          schema:
            type: string
            description: 'Search term to filter customers.'
            example: jarvis
        -
          in: query
          name: order_start_date
          description: 'Optional start date in the store timezone using YYYY-MM-DD format. Requires `order_end_date`. When provided, customer order stats are calculated for this period.'
          example: '2026-03-01'
          required: false
          schema:
            type: string
            description: 'Optional start date in the store timezone using YYYY-MM-DD format. Requires `order_end_date`. When provided, customer order stats are calculated for this period.'
            example: '2026-03-01'
        -
          in: query
          name: order_end_date
          description: 'Optional end date in the store timezone using YYYY-MM-DD format. Requires `order_start_date`. When provided, customer order stats are calculated for this period.'
          example: '2026-03-31'
          required: false
          schema:
            type: string
            description: 'Optional end date in the store timezone using YYYY-MM-DD format. Requires `order_start_date`. When provided, customer order stats are calculated for this period.'
            example: '2026-03-31'
        -
          in: query
          name: filters
          description: 'Optional JSON-encoded filter array. See [Customer Filters Reference](#customers-GETapi-v1-store-customers-filters-reference).'
          example: '[{"field":"total_spent","operator":"gte","value":100},{"field":"role","operator":"eq","value":"customer"}]'
          required: false
          schema:
            type: string
            description: 'Optional JSON-encoded filter array. See [Customer Filters Reference](#customers-GETapi-v1-store-customers-filters-reference).'
            example: '[{"field":"total_spent","operator":"gte","value":100},{"field":"role","operator":"eq","value":"customer"}]'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      customer_id: 482
                      full_name: 'Tony Stark'
                      first_name: Tony
                      last_name: Stark
                      email: tony@example.com
                      customer_created_at: '2026-03-01T08:00:00Z'
                      customer_updated_at: '2026-03-25T18:42:00Z'
                      billing_address_first_name: Tony
                      billing_address_last_name: Stark
                      billing_address_company: 'Stark Industries'
                      billing_address_address_1: '10880 Malibu Point'
                      billing_address_address_2: 'Suite 1'
                      billing_address_city: Malibu
                      billing_address_state: CA
                      billing_address_postcode: '90265'
                      billing_address_country: US
                      billing_address_phone: '5551234567'
                      shipping_address_first_name: Tony
                      shipping_address_last_name: Stark
                      shipping_address_company: 'Stark Industries'
                      shipping_address_address_1: '10880 Malibu Point'
                      shipping_address_address_2: 'Suite 1'
                      shipping_address_city: Malibu
                      shipping_address_state: CA
                      shipping_address_postcode: '90265'
                      shipping_address_country: US
                      shipping_address_phone: '5551234567'
                      role: customer
                      first_order_date: '2026-03-10T14:15:00Z'
                      last_order_date: '2026-03-25T18:42:00Z'
                      first_order_referer: 'https://google.com/search?q=metorik'
                      first_order_landing_path: /products/hoodie
                      first_order_utm_campaign: spring-sale
                      first_order_utm_medium: cpc
                      first_order_utm_source: google
                      first_order_utm_term: 'metorik hoodie'
                      first_order_utm_content: ad-1
                      first_order_utm_id: campaign-123
                      order_count: 3
                      item_count: 7
                      total_spent: 210.5
                      average_order: 70.17
                      subscription_count: 1
                      metorik_profile: false
                      resource_link: 'https://app.metorik.com/customers/482'
                  pagination:
                    current_page: 1
                    per_page: 10
                    has_more_pages: true
                properties:
                  data:
                    type: array
                    example:
                      -
                        customer_id: 482
                        full_name: 'Tony Stark'
                        first_name: Tony
                        last_name: Stark
                        email: tony@example.com
                        customer_created_at: '2026-03-01T08:00:00Z'
                        customer_updated_at: '2026-03-25T18:42:00Z'
                        billing_address_first_name: Tony
                        billing_address_last_name: Stark
                        billing_address_company: 'Stark Industries'
                        billing_address_address_1: '10880 Malibu Point'
                        billing_address_address_2: 'Suite 1'
                        billing_address_city: Malibu
                        billing_address_state: CA
                        billing_address_postcode: '90265'
                        billing_address_country: US
                        billing_address_phone: '5551234567'
                        shipping_address_first_name: Tony
                        shipping_address_last_name: Stark
                        shipping_address_company: 'Stark Industries'
                        shipping_address_address_1: '10880 Malibu Point'
                        shipping_address_address_2: 'Suite 1'
                        shipping_address_city: Malibu
                        shipping_address_state: CA
                        shipping_address_postcode: '90265'
                        shipping_address_country: US
                        shipping_address_phone: '5551234567'
                        role: customer
                        first_order_date: '2026-03-10T14:15:00Z'
                        last_order_date: '2026-03-25T18:42:00Z'
                        first_order_referer: 'https://google.com/search?q=metorik'
                        first_order_landing_path: /products/hoodie
                        first_order_utm_campaign: spring-sale
                        first_order_utm_medium: cpc
                        first_order_utm_source: google
                        first_order_utm_term: 'metorik hoodie'
                        first_order_utm_content: ad-1
                        first_order_utm_id: campaign-123
                        order_count: 3
                        item_count: 7
                        total_spent: 210.5
                        average_order: 70.17
                        subscription_count: 1
                        metorik_profile: false
                        resource_link: 'https://app.metorik.com/customers/482'
                    items:
                      type: object
                      properties:
                        customer_id:
                          type: integer
                          example: 482
                        full_name:
                          type: string
                          example: 'Tony Stark'
                        first_name:
                          type: string
                          example: Tony
                        last_name:
                          type: string
                          example: Stark
                        email:
                          type: string
                          example: tony@example.com
                        customer_created_at:
                          type: string
                          example: '2026-03-01T08:00:00Z'
                        customer_updated_at:
                          type: string
                          example: '2026-03-25T18:42:00Z'
                        billing_address_first_name:
                          type: string
                          example: Tony
                        billing_address_last_name:
                          type: string
                          example: Stark
                        billing_address_company:
                          type: string
                          example: 'Stark Industries'
                        billing_address_address_1:
                          type: string
                          example: '10880 Malibu Point'
                        billing_address_address_2:
                          type: string
                          example: 'Suite 1'
                        billing_address_city:
                          type: string
                          example: Malibu
                        billing_address_state:
                          type: string
                          example: CA
                        billing_address_postcode:
                          type: string
                          example: '90265'
                        billing_address_country:
                          type: string
                          example: US
                        billing_address_phone:
                          type: string
                          example: '5551234567'
                        shipping_address_first_name:
                          type: string
                          example: Tony
                        shipping_address_last_name:
                          type: string
                          example: Stark
                        shipping_address_company:
                          type: string
                          example: 'Stark Industries'
                        shipping_address_address_1:
                          type: string
                          example: '10880 Malibu Point'
                        shipping_address_address_2:
                          type: string
                          example: 'Suite 1'
                        shipping_address_city:
                          type: string
                          example: Malibu
                        shipping_address_state:
                          type: string
                          example: CA
                        shipping_address_postcode:
                          type: string
                          example: '90265'
                        shipping_address_country:
                          type: string
                          example: US
                        shipping_address_phone:
                          type: string
                          example: '5551234567'
                        role:
                          type: string
                          example: customer
                        first_order_date:
                          type: string
                          example: '2026-03-10T14:15:00Z'
                        last_order_date:
                          type: string
                          example: '2026-03-25T18:42:00Z'
                        first_order_referer:
                          type: string
                          example: 'https://google.com/search?q=metorik'
                        first_order_landing_path:
                          type: string
                          example: /products/hoodie
                        first_order_utm_campaign:
                          type: string
                          example: spring-sale
                        first_order_utm_medium:
                          type: string
                          example: cpc
                        first_order_utm_source:
                          type: string
                          example: google
                        first_order_utm_term:
                          type: string
                          example: 'metorik hoodie'
                        first_order_utm_content:
                          type: string
                          example: ad-1
                        first_order_utm_id:
                          type: string
                          example: campaign-123
                        order_count:
                          type: integer
                          example: 3
                        item_count:
                          type: integer
                          example: 7
                        total_spent:
                          type: number
                          example: 210.5
                        average_order:
                          type: number
                          example: 70.17
                        subscription_count:
                          type: integer
                          example: 1
                        metorik_profile:
                          type: boolean
                          example: false
                        resource_link:
                          type: string
                          example: 'https://app.metorik.com/customers/482'
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 10
                      has_more_pages:
                        type: boolean
                        example: true
      tags:
        - Customers
  /api/v1/store/customers/totals:
    get:
      summary: 'Customer totals'
      operationId: customerTotals
      description: |-
        Returns summary totals for the same customer dataset as the customers
        list endpoint. When `order_start_date` and `order_end_date` are
        provided, customer order stats are calculated for that period. All
        returned `*_at` timestamps are in UTC.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: search
          description: 'Search term to filter customers before totaling.'
          example: jarvis
          required: false
          schema:
            type: string
            description: 'Search term to filter customers before totaling.'
            example: jarvis
        -
          in: query
          name: order_start_date
          description: 'Optional start date in the store timezone using YYYY-MM-DD format. Requires `order_end_date`. When provided, customer order stats are calculated for this period.'
          example: '2026-03-01'
          required: false
          schema:
            type: string
            description: 'Optional start date in the store timezone using YYYY-MM-DD format. Requires `order_end_date`. When provided, customer order stats are calculated for this period.'
            example: '2026-03-01'
        -
          in: query
          name: order_end_date
          description: 'Optional end date in the store timezone using YYYY-MM-DD format. Requires `order_start_date`. When provided, customer order stats are calculated for this period.'
          example: '2026-03-31'
          required: false
          schema:
            type: string
            description: 'Optional end date in the store timezone using YYYY-MM-DD format. Requires `order_start_date`. When provided, customer order stats are calculated for this period.'
            example: '2026-03-31'
        -
          in: query
          name: filters
          description: 'Optional JSON-encoded filter array. See [Customer Filters Reference](#customers-GETapi-v1-store-customers-filters-reference).'
          example: '[{"field":"total_spent","operator":"gte","value":100}]'
          required: false
          schema:
            type: string
            description: 'Optional JSON-encoded filter array. See [Customer Filters Reference](#customers-GETapi-v1-store-customers-filters-reference).'
            example: '[{"field":"total_spent","operator":"gte","value":100}]'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    count: 508
                    total_ltv: 124550.42
                    total_orders: 712
                    total_items: 1196
                    average_ltv: 245.2
                    average_orders: 1.4
                    average_items: 2.4
                    returning_customers: 198
                    returning_customers_rate: 39
                    total_active_subscriptions: 82
                properties:
                  data:
                    type: object
                    properties:
                      count:
                        type: integer
                        example: 508
                      total_ltv:
                        type: number
                        example: 124550.42
                      total_orders:
                        type: integer
                        example: 712
                      total_items:
                        type: integer
                        example: 1196
                      average_ltv:
                        type: number
                        example: 245.2
                      average_orders:
                        type: number
                        example: 1.4
                      average_items:
                        type: number
                        example: 2.4
                      returning_customers:
                        type: integer
                        example: 198
                      returning_customers_rate:
                        type: integer
                        example: 39
                      total_active_subscriptions:
                        type: integer
                        example: 82
      tags:
        - Customers
  /api/v1/store/subscriptions:
    get:
      summary: 'Subscription data'
      operationId: subscriptionData
      description: |-
        Returns subscriptions from your store together with subscription billing
        fields and recurring revenue metrics. All returned `*_date` timestamps are
        in UTC.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: page
          description: 'Page number for pagination.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number for pagination.'
            example: 1
        -
          in: query
          name: per_page
          description: 'Number of subscriptions per page. Min 1, max 100.'
          example: 10
          required: false
          schema:
            type: integer
            description: 'Number of subscriptions per page. Min 1, max 100.'
            example: 10
        -
          in: query
          name: order_by
          description: 'Sort field.'
          example: start_date
          required: false
          schema:
            type: string
            description: 'Sort field.'
            example: start_date
            enum:
              - subscription_id
              - status
              - customer_id
              - billing_period
              - billing_interval
              - start_date
              - next_payment_date
              - trial_end_date
              - end_date
              - cancelled_date
              - total
              - total_items
              - total_mrr
              - renewal_orders_count
              - renewal_orders_total
              - parent_order_total
        -
          in: query
          name: order_dir
          description: 'Sort direction.'
          example: desc
          required: false
          schema:
            type: string
            description: 'Sort direction.'
            example: desc
            enum:
              - asc
              - desc
        -
          in: query
          name: search
          description: 'Search term to filter subscriptions.'
          example: customer@example.com
          required: false
          schema:
            type: string
            description: 'Search term to filter subscriptions.'
            example: customer@example.com
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      subscription_id: 99123
                      status: active
                      customer_id: 6001
                      billing_period: month
                      billing_interval: 1
                      start_date: '2026-01-10T15:00:00.000000Z'
                      next_payment_date: '2026-04-10T15:00:00.000000Z'
                      trial_end_date: null
                      end_date: null
                      cancelled_date: null
                      total: 29
                      total_items: 2
                      total_mrr: 29
                      renewal_orders_count: 3
                      renewal_orders_total: 87
                      parent_order_total: 29
                      days_between_started_and_cancelled: null
                      requires_manual_renewal: false
                      resource_link: 'https://app.metorik.com/subscriptions/99123'
                  pagination:
                    current_page: 1
                    per_page: 10
                    has_more_pages: true
                properties:
                  data:
                    type: array
                    example:
                      -
                        subscription_id: 99123
                        status: active
                        customer_id: 6001
                        billing_period: month
                        billing_interval: 1
                        start_date: '2026-01-10T15:00:00.000000Z'
                        next_payment_date: '2026-04-10T15:00:00.000000Z'
                        trial_end_date: null
                        end_date: null
                        cancelled_date: null
                        total: 29
                        total_items: 2
                        total_mrr: 29
                        renewal_orders_count: 3
                        renewal_orders_total: 87
                        parent_order_total: 29
                        days_between_started_and_cancelled: null
                        requires_manual_renewal: false
                        resource_link: 'https://app.metorik.com/subscriptions/99123'
                    items:
                      type: object
                      properties:
                        subscription_id:
                          type: integer
                          example: 99123
                        status:
                          type: string
                          example: active
                        customer_id:
                          type: integer
                          example: 6001
                        billing_period:
                          type: string
                          example: month
                        billing_interval:
                          type: integer
                          example: 1
                        start_date:
                          type: string
                          example: '2026-01-10T15:00:00.000000Z'
                        next_payment_date:
                          type: string
                          example: '2026-04-10T15:00:00.000000Z'
                        trial_end_date:
                          type: string
                          example: null
                          nullable: true
                        end_date:
                          type: string
                          example: null
                          nullable: true
                        cancelled_date:
                          type: string
                          example: null
                          nullable: true
                        total:
                          type: integer
                          example: 29
                        total_items:
                          type: integer
                          example: 2
                        total_mrr:
                          type: integer
                          example: 29
                        renewal_orders_count:
                          type: integer
                          example: 3
                        renewal_orders_total:
                          type: integer
                          example: 87
                        parent_order_total:
                          type: integer
                          example: 29
                        days_between_started_and_cancelled:
                          type: string
                          example: null
                          nullable: true
                        requires_manual_renewal:
                          type: boolean
                          example: false
                        resource_link:
                          type: string
                          example: 'https://app.metorik.com/subscriptions/99123'
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 10
                      has_more_pages:
                        type: boolean
                        example: true
      tags:
        - Subscriptions
  /api/v1/store/subscriptions/totals:
    get:
      summary: 'Subscription totals'
      operationId: subscriptionTotals
      description: |-
        Returns summary totals for the same subscription dataset as the
        subscriptions list endpoint. All returned `*_date` timestamps are in UTC.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: search
          description: 'Search term to filter subscriptions before totaling.'
          example: customer@example.com
          required: false
          schema:
            type: string
            description: 'Search term to filter subscriptions before totaling.'
            example: customer@example.com
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    count: 12
                    total_items: 19
                    total_mrr: 349.5
                    total_arr: 4194
                    average_subscription_items: 1.6
                properties:
                  data:
                    type: object
                    properties:
                      count:
                        type: integer
                        example: 12
                      total_items:
                        type: integer
                        example: 19
                      total_mrr:
                        type: number
                        example: 349.5
                      total_arr:
                        type: integer
                        example: 4194
                      average_subscription_items:
                        type: number
                        example: 1.6
      tags:
        - Subscriptions
  /api/v1/store/products:
    get:
      summary: 'Product sales'
      operationId: productSales
      description: |-
        Returns products from your store together with product-level sales metrics,
        refunds, and sold date ranges for the selected period.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: page
          description: 'Page number for pagination.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number for pagination.'
            example: 1
        -
          in: query
          name: per_page
          description: 'Number of products per page. Min 1, max 100.'
          example: 10
          required: false
          schema:
            type: integer
            description: 'Number of products per page. Min 1, max 100.'
            example: 10
        -
          in: query
          name: order_by
          description: 'Sort field.'
          example: product_created_at
          required: false
          schema:
            type: string
            description: 'Sort field.'
            example: product_created_at
            enum:
              - title
              - sku
              - product_id
              - product_created_at
              - product_updated_at
              - gross_items_sold
              - items_refunded
              - net_items_sold
              - gross_sales
              - net_orders
              - net_sales
              - first_sold
              - last_sold
        -
          in: query
          name: order_dir
          description: 'Sort direction.'
          example: desc
          required: false
          schema:
            type: string
            description: 'Sort direction.'
            example: desc
            enum:
              - asc
              - desc
        -
          in: query
          name: search
          description: 'Search term to filter products.'
          example: hoodie
          required: false
          schema:
            type: string
            description: 'Search term to filter products.'
            example: hoodie
        -
          in: query
          name: order_filters
          description: 'Optional JSON-encoded array of order-level filters applied before calculating product sales. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference).'
          example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
          required: false
          schema:
            type: string
            description: 'Optional JSON-encoded array of order-level filters applied before calculating product sales. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference).'
            example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      product_id: 4821
                      title: 'Metorik Hoodie'
                      sku: MTK-HOODIE-BLK-M
                      type: simple
                      status: publish
                      current_price: 79
                      regular_price: 79
                      sale_price: 0
                      stock_quantity: 24
                      in_stock: true
                      gross_items_sold: 184
                      items_refunded: 3
                      net_items_sold: 181
                      gross_sales: 14536
                      total_tax: 1211.33
                      total_discounted: 210
                      total_refunds: 237
                      net_orders: 176
                      net_sales: 14089
                      first_sold: '2025-11-04T09:15:00Z'
                      last_sold: '2026-03-25T18:42:00Z'
                      product_created_at: '2025-10-21T14:00:00Z'
                      product_updated_at: '2026-03-12T07:30:00Z'
                  pagination:
                    current_page: 1
                    per_page: 10
                    has_more_pages: true
                properties:
                  data:
                    type: array
                    example:
                      -
                        product_id: 4821
                        title: 'Metorik Hoodie'
                        sku: MTK-HOODIE-BLK-M
                        type: simple
                        status: publish
                        current_price: 79
                        regular_price: 79
                        sale_price: 0
                        stock_quantity: 24
                        in_stock: true
                        gross_items_sold: 184
                        items_refunded: 3
                        net_items_sold: 181
                        gross_sales: 14536
                        total_tax: 1211.33
                        total_discounted: 210
                        total_refunds: 237
                        net_orders: 176
                        net_sales: 14089
                        first_sold: '2025-11-04T09:15:00Z'
                        last_sold: '2026-03-25T18:42:00Z'
                        product_created_at: '2025-10-21T14:00:00Z'
                        product_updated_at: '2026-03-12T07:30:00Z'
                    items:
                      type: object
                      properties:
                        product_id:
                          type: integer
                          example: 4821
                        title:
                          type: string
                          example: 'Metorik Hoodie'
                        sku:
                          type: string
                          example: MTK-HOODIE-BLK-M
                        type:
                          type: string
                          example: simple
                        status:
                          type: string
                          example: publish
                        current_price:
                          type: integer
                          example: 79
                        regular_price:
                          type: integer
                          example: 79
                        sale_price:
                          type: integer
                          example: 0
                        stock_quantity:
                          type: integer
                          example: 24
                        in_stock:
                          type: boolean
                          example: true
                        gross_items_sold:
                          type: integer
                          example: 184
                        items_refunded:
                          type: integer
                          example: 3
                        net_items_sold:
                          type: integer
                          example: 181
                        gross_sales:
                          type: integer
                          example: 14536
                        total_tax:
                          type: number
                          example: 1211.33
                        total_discounted:
                          type: integer
                          example: 210
                        total_refunds:
                          type: integer
                          example: 237
                        net_orders:
                          type: integer
                          example: 176
                        net_sales:
                          type: integer
                          example: 14089
                        first_sold:
                          type: string
                          example: '2025-11-04T09:15:00Z'
                        last_sold:
                          type: string
                          example: '2026-03-25T18:42:00Z'
                        product_created_at:
                          type: string
                          example: '2025-10-21T14:00:00Z'
                        product_updated_at:
                          type: string
                          example: '2026-03-12T07:30:00Z'
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 10
                      has_more_pages:
                        type: boolean
                        example: true
      tags:
        - Products
  '/api/v1/store/products/{product}/by-date':
    get:
      summary: 'Product sales by date'
      operationId: productSalesByDate
      description: |-
        Returns product sales over time for a single product in the selected
        period. Date buckets use the store timezone.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: group_by
          description: 'Time interval for grouping the results.'
          example: day
          required: false
          schema:
            type: string
            description: 'Time interval for grouping the results.'
            example: day
            enum:
              - hour
              - day
              - week
              - month
              - year
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    resource_link: 'https://app.metorik.com/products/4821'
                  resource:
                    product_id: 4821
                    title: 'Metorik Hoodie'
                    sku: MTK-HOODIE
                    resource_link: 'https://app.metorik.com/products/4821'
                  totals:
                    gross_items_sold: 2
                    items_refunded: 0
                    net_items_sold: 2
                    gross_sales: 40
                    total_refunds: 0
                    net_sales: 40
                    orders_count: 1
                    net_orders: 1
                  data:
                    -
                      date: '2026-03-25'
                      label: '25 Mar'
                      gross_items_sold: 2
                      items_refunded: 0
                      net_items_sold: 2
                      gross_sales: 40
                      total_refunds: 0
                      net_sales: 40
                      orders_count: 1
                      net_orders: 1
                properties:
                  meta:
                    type: object
                    properties:
                      resource_link:
                        type: string
                        example: 'https://app.metorik.com/products/4821'
                  resource:
                    type: object
                    properties:
                      product_id:
                        type: integer
                        example: 4821
                      title:
                        type: string
                        example: 'Metorik Hoodie'
                      sku:
                        type: string
                        example: MTK-HOODIE
                      resource_link:
                        type: string
                        example: 'https://app.metorik.com/products/4821'
                  totals:
                    type: object
                    properties:
                      gross_items_sold:
                        type: integer
                        example: 2
                      items_refunded:
                        type: integer
                        example: 0
                      net_items_sold:
                        type: integer
                        example: 2
                      gross_sales:
                        type: integer
                        example: 40
                      total_refunds:
                        type: integer
                        example: 0
                      net_sales:
                        type: integer
                        example: 40
                      orders_count:
                        type: integer
                        example: 1
                      net_orders:
                        type: integer
                        example: 1
                  data:
                    type: array
                    example:
                      -
                        date: '2026-03-25'
                        label: '25 Mar'
                        gross_items_sold: 2
                        items_refunded: 0
                        net_items_sold: 2
                        gross_sales: 40
                        total_refunds: 0
                        net_sales: 40
                        orders_count: 1
                        net_orders: 1
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          example: '2026-03-25'
                        label:
                          type: string
                          example: '25 Mar'
                        gross_items_sold:
                          type: integer
                          example: 2
                        items_refunded:
                          type: integer
                          example: 0
                        net_items_sold:
                          type: integer
                          example: 2
                        gross_sales:
                          type: integer
                          example: 40
                        total_refunds:
                          type: integer
                          example: 0
                        net_sales:
                          type: integer
                          example: 40
                        orders_count:
                          type: integer
                          example: 1
                        net_orders:
                          type: integer
                          example: 1
      tags:
        - Products
    parameters:
      -
        in: path
        name: product
        description: 'The product ID.'
        example: 4821
        required: true
        schema:
          type: integer
  /api/v1/store/variations:
    get:
      summary: 'Variation sales'
      operationId: variationSales
      description: |-
        Returns product variations from your store together with variation-level sales metrics,
        refunds, and sold date ranges for the selected period.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: page
          description: 'Page number for pagination.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number for pagination.'
            example: 1
        -
          in: query
          name: per_page
          description: 'Number of variations per page. Min 1, max 100.'
          example: 10
          required: false
          schema:
            type: integer
            description: 'Number of variations per page. Min 1, max 100.'
            example: 10
        -
          in: query
          name: order_by
          description: 'Sort field.'
          example: variation_created_at
          required: false
          schema:
            type: string
            description: 'Sort field.'
            example: variation_created_at
            enum:
              - sku
              - variation_id
              - variation_created_at
              - variation_updated_at
              - gross_items_sold
              - items_refunded
              - net_items_sold
              - gross_sales
              - net_orders
              - net_sales
              - first_sold
              - last_sold
        -
          in: query
          name: order_dir
          description: 'Sort direction.'
          example: desc
          required: false
          schema:
            type: string
            description: 'Sort direction.'
            example: desc
            enum:
              - asc
              - desc
        -
          in: query
          name: search
          description: 'Search term to filter variations.'
          example: medium
          required: false
          schema:
            type: string
            description: 'Search term to filter variations.'
            example: medium
        -
          in: query
          name: order_filters
          description: 'Optional JSON-encoded array of order-level filters applied before calculating variation sales. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference).'
          example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
          required: false
          schema:
            type: string
            description: 'Optional JSON-encoded array of order-level filters applied before calculating variation sales. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference).'
            example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      variation_id: 9912
                      product_id: 4821
                      sku: MTK-HOODIE-BLK-M
                      name: 'Black - Medium'
                      atts:
                        -
                          name: Color
                          option: Black
                        -
                          name: Size
                          option: Medium
                      current_price: 79
                      regular_price: 79
                      sale_price: 0
                      stock_quantity: 12
                      in_stock: true
                      gross_items_sold: 43
                      items_refunded: 2
                      net_items_sold: 41
                      gross_sales: 3397
                      total_tax: 283.08
                      total_discounted: 91
                      total_refunds: 158
                      net_orders: 39
                      net_sales: 3239
                      first_sold: '2025-12-18T10:30:00Z'
                      last_sold: '2026-03-24T08:12:00Z'
                      variation_created_at: '2025-10-21T14:00:00Z'
                      variation_updated_at: '2026-03-12T07:30:00Z'
                  pagination:
                    current_page: 1
                    per_page: 10
                    has_more_pages: true
                properties:
                  data:
                    type: array
                    example:
                      -
                        variation_id: 9912
                        product_id: 4821
                        sku: MTK-HOODIE-BLK-M
                        name: 'Black - Medium'
                        atts:
                          -
                            name: Color
                            option: Black
                          -
                            name: Size
                            option: Medium
                        current_price: 79
                        regular_price: 79
                        sale_price: 0
                        stock_quantity: 12
                        in_stock: true
                        gross_items_sold: 43
                        items_refunded: 2
                        net_items_sold: 41
                        gross_sales: 3397
                        total_tax: 283.08
                        total_discounted: 91
                        total_refunds: 158
                        net_orders: 39
                        net_sales: 3239
                        first_sold: '2025-12-18T10:30:00Z'
                        last_sold: '2026-03-24T08:12:00Z'
                        variation_created_at: '2025-10-21T14:00:00Z'
                        variation_updated_at: '2026-03-12T07:30:00Z'
                    items:
                      type: object
                      properties:
                        variation_id:
                          type: integer
                          example: 9912
                        product_id:
                          type: integer
                          example: 4821
                        sku:
                          type: string
                          example: MTK-HOODIE-BLK-M
                        name:
                          type: string
                          example: 'Black - Medium'
                        atts:
                          type: array
                          example:
                            -
                              name: Color
                              option: Black
                            -
                              name: Size
                              option: Medium
                          items:
                            type: object
                            properties:
                              name:
                                type: string
                                example: Color
                              option:
                                type: string
                                example: Black
                        current_price:
                          type: integer
                          example: 79
                        regular_price:
                          type: integer
                          example: 79
                        sale_price:
                          type: integer
                          example: 0
                        stock_quantity:
                          type: integer
                          example: 12
                        in_stock:
                          type: boolean
                          example: true
                        gross_items_sold:
                          type: integer
                          example: 43
                        items_refunded:
                          type: integer
                          example: 2
                        net_items_sold:
                          type: integer
                          example: 41
                        gross_sales:
                          type: integer
                          example: 3397
                        total_tax:
                          type: number
                          example: 283.08
                        total_discounted:
                          type: integer
                          example: 91
                        total_refunds:
                          type: integer
                          example: 158
                        net_orders:
                          type: integer
                          example: 39
                        net_sales:
                          type: integer
                          example: 3239
                        first_sold:
                          type: string
                          example: '2025-12-18T10:30:00Z'
                        last_sold:
                          type: string
                          example: '2026-03-24T08:12:00Z'
                        variation_created_at:
                          type: string
                          example: '2025-10-21T14:00:00Z'
                        variation_updated_at:
                          type: string
                          example: '2026-03-12T07:30:00Z'
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 10
                      has_more_pages:
                        type: boolean
                        example: true
      tags:
        - Variations
  '/api/v1/store/variations/{variation}/by-date':
    get:
      summary: 'Variation sales by date'
      operationId: variationSalesByDate
      description: |-
        Returns sales over time for a single variation in the selected period.
        Date buckets use the store timezone.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: group_by
          description: 'Time interval for grouping the results.'
          example: day
          required: false
          schema:
            type: string
            description: 'Time interval for grouping the results.'
            example: day
            enum:
              - hour
              - day
              - week
              - month
              - year
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    resource_link: 'https://app.metorik.com/products/4822'
                  resource:
                    product_id: 4822
                    title: 'Metorik Hoodie'
                    sku: null
                    resource_link: 'https://app.metorik.com/products/4822'
                    variation:
                      variation_id: 9912
                      name: 'Black - Medium'
                      sku: MTK-HOODIE-BLK-M
                  totals:
                    gross_items_sold: 1
                    items_refunded: 0
                    net_items_sold: 1
                    gross_sales: 40
                    total_refunds: 0
                    net_sales: 40
                    orders_count: 1
                    net_orders: 1
                  data:
                    -
                      date: '2026-03-25'
                      label: '25 Mar'
                      gross_items_sold: 1
                      items_refunded: 0
                      net_items_sold: 1
                      gross_sales: 40
                      total_refunds: 0
                      net_sales: 40
                      orders_count: 1
                      net_orders: 1
                properties:
                  meta:
                    type: object
                    properties:
                      resource_link:
                        type: string
                        example: 'https://app.metorik.com/products/4822'
                  resource:
                    type: object
                    properties:
                      product_id:
                        type: integer
                        example: 4822
                      title:
                        type: string
                        example: 'Metorik Hoodie'
                      sku:
                        type: string
                        example: null
                        nullable: true
                      resource_link:
                        type: string
                        example: 'https://app.metorik.com/products/4822'
                      variation:
                        type: object
                        properties:
                          variation_id:
                            type: integer
                            example: 9912
                          name:
                            type: string
                            example: 'Black - Medium'
                          sku:
                            type: string
                            example: MTK-HOODIE-BLK-M
                  totals:
                    type: object
                    properties:
                      gross_items_sold:
                        type: integer
                        example: 1
                      items_refunded:
                        type: integer
                        example: 0
                      net_items_sold:
                        type: integer
                        example: 1
                      gross_sales:
                        type: integer
                        example: 40
                      total_refunds:
                        type: integer
                        example: 0
                      net_sales:
                        type: integer
                        example: 40
                      orders_count:
                        type: integer
                        example: 1
                      net_orders:
                        type: integer
                        example: 1
                  data:
                    type: array
                    example:
                      -
                        date: '2026-03-25'
                        label: '25 Mar'
                        gross_items_sold: 1
                        items_refunded: 0
                        net_items_sold: 1
                        gross_sales: 40
                        total_refunds: 0
                        net_sales: 40
                        orders_count: 1
                        net_orders: 1
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          example: '2026-03-25'
                        label:
                          type: string
                          example: '25 Mar'
                        gross_items_sold:
                          type: integer
                          example: 1
                        items_refunded:
                          type: integer
                          example: 0
                        net_items_sold:
                          type: integer
                          example: 1
                        gross_sales:
                          type: integer
                          example: 40
                        total_refunds:
                          type: integer
                          example: 0
                        net_sales:
                          type: integer
                          example: 40
                        orders_count:
                          type: integer
                          example: 1
                        net_orders:
                          type: integer
                          example: 1
      tags:
        - Variations
    parameters:
      -
        in: path
        name: variation
        description: 'The variation ID.'
        example: 9912
        required: true
        schema:
          type: integer
  /api/v1/store/categories:
    get:
      summary: 'Category sales'
      operationId: categorySales
      description: |-
        Returns product categories from your store together with category-level sales metrics,
        refunds, and order counts for the selected period.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: page
          description: 'Page number for pagination.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number for pagination.'
            example: 1
        -
          in: query
          name: per_page
          description: 'Number of categories per page. Min 1, max 100.'
          example: 10
          required: false
          schema:
            type: integer
            description: 'Number of categories per page. Min 1, max 100.'
            example: 10
        -
          in: query
          name: order_by
          description: 'Sort field.'
          example: name
          required: false
          schema:
            type: string
            description: 'Sort field.'
            example: name
            enum:
              - name
              - category_id
              - products
              - gross_items_sold
              - items_refunded
              - net_items_sold
              - gross_sales
              - net_orders
              - net_sales
        -
          in: query
          name: order_dir
          description: 'Sort direction.'
          example: asc
          required: false
          schema:
            type: string
            description: 'Sort direction.'
            example: asc
            enum:
              - asc
              - desc
        -
          in: query
          name: search
          description: 'Search term to filter categories.'
          example: accessories
          required: false
          schema:
            type: string
            description: 'Search term to filter categories.'
            example: accessories
        -
          in: query
          name: order_filters
          description: 'Optional JSON-encoded array of order-level filters applied before calculating category sales. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference).'
          example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
          required: false
          schema:
            type: string
            description: 'Optional JSON-encoded array of order-level filters applied before calculating category sales. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference).'
            example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      category_id: 221
                      name: Hoodies
                      parent_category_id: null
                      slug: hoodies
                      description: 'Sweatshirts and hoodies.'
                      image: 'https://app.metorik.com/img/products/hoodie-category.png'
                      products: 12
                      gross_items_sold: 184
                      items_refunded: 3
                      net_items_sold: 181
                      gross_sales: 14536
                      total_tax: 1211.33
                      total_discounted: 210
                      total_refunds: 237
                      net_orders: 176
                      net_sales: 14089
                  pagination:
                    current_page: 1
                    per_page: 10
                    has_more_pages: true
                properties:
                  data:
                    type: array
                    example:
                      -
                        category_id: 221
                        name: Hoodies
                        parent_category_id: null
                        slug: hoodies
                        description: 'Sweatshirts and hoodies.'
                        image: 'https://app.metorik.com/img/products/hoodie-category.png'
                        products: 12
                        gross_items_sold: 184
                        items_refunded: 3
                        net_items_sold: 181
                        gross_sales: 14536
                        total_tax: 1211.33
                        total_discounted: 210
                        total_refunds: 237
                        net_orders: 176
                        net_sales: 14089
                    items:
                      type: object
                      properties:
                        category_id:
                          type: integer
                          example: 221
                        name:
                          type: string
                          example: Hoodies
                        parent_category_id:
                          type: string
                          example: null
                          nullable: true
                        slug:
                          type: string
                          example: hoodies
                        description:
                          type: string
                          example: 'Sweatshirts and hoodies.'
                        image:
                          type: string
                          example: 'https://app.metorik.com/img/products/hoodie-category.png'
                        products:
                          type: integer
                          example: 12
                        gross_items_sold:
                          type: integer
                          example: 184
                        items_refunded:
                          type: integer
                          example: 3
                        net_items_sold:
                          type: integer
                          example: 181
                        gross_sales:
                          type: integer
                          example: 14536
                        total_tax:
                          type: number
                          example: 1211.33
                        total_discounted:
                          type: integer
                          example: 210
                        total_refunds:
                          type: integer
                          example: 237
                        net_orders:
                          type: integer
                          example: 176
                        net_sales:
                          type: integer
                          example: 14089
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 10
                      has_more_pages:
                        type: boolean
                        example: true
      tags:
        - Categories
  '/api/v1/store/categories/{category}/by-date':
    get:
      summary: 'Category sales by date'
      operationId: categorySalesByDate
      description: |-
        Returns category sales over time for a single category in the selected
        period. Date buckets use the store timezone.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: group_by
          description: 'Time interval for grouping the results.'
          example: day
          required: false
          schema:
            type: string
            description: 'Time interval for grouping the results.'
            example: day
            enum:
              - hour
              - day
              - week
              - month
              - year
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    resource_link: 'https://app.metorik.com/categories/310'
                  resource:
                    category_id: 310
                    name: 'Prepared Meals'
                    products_count: 1
                    resource_link: 'https://app.metorik.com/categories/310'
                  totals:
                    gross_items_sold: 2
                    items_refunded: 0
                    net_items_sold: 2
                    gross_sales: 40
                    total_refunds: 0
                    net_sales: 40
                    orders_count: 1
                    net_orders: 1
                  data:
                    -
                      date: '2026-03-25'
                      label: '25 Mar'
                      gross_items_sold: 2
                      items_refunded: 0
                      net_items_sold: 2
                      gross_sales: 40
                      total_refunds: 0
                      net_sales: 40
                      orders_count: 1
                      net_orders: 1
                properties:
                  meta:
                    type: object
                    properties:
                      resource_link:
                        type: string
                        example: 'https://app.metorik.com/categories/310'
                  resource:
                    type: object
                    properties:
                      category_id:
                        type: integer
                        example: 310
                      name:
                        type: string
                        example: 'Prepared Meals'
                      products_count:
                        type: integer
                        example: 1
                      resource_link:
                        type: string
                        example: 'https://app.metorik.com/categories/310'
                  totals:
                    type: object
                    properties:
                      gross_items_sold:
                        type: integer
                        example: 2
                      items_refunded:
                        type: integer
                        example: 0
                      net_items_sold:
                        type: integer
                        example: 2
                      gross_sales:
                        type: integer
                        example: 40
                      total_refunds:
                        type: integer
                        example: 0
                      net_sales:
                        type: integer
                        example: 40
                      orders_count:
                        type: integer
                        example: 1
                      net_orders:
                        type: integer
                        example: 1
                  data:
                    type: array
                    example:
                      -
                        date: '2026-03-25'
                        label: '25 Mar'
                        gross_items_sold: 2
                        items_refunded: 0
                        net_items_sold: 2
                        gross_sales: 40
                        total_refunds: 0
                        net_sales: 40
                        orders_count: 1
                        net_orders: 1
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          example: '2026-03-25'
                        label:
                          type: string
                          example: '25 Mar'
                        gross_items_sold:
                          type: integer
                          example: 2
                        items_refunded:
                          type: integer
                          example: 0
                        net_items_sold:
                          type: integer
                          example: 2
                        gross_sales:
                          type: integer
                          example: 40
                        total_refunds:
                          type: integer
                          example: 0
                        net_sales:
                          type: integer
                          example: 40
                        orders_count:
                          type: integer
                          example: 1
                        net_orders:
                          type: integer
                          example: 1
      tags:
        - Categories
    parameters:
      -
        in: path
        name: category
        description: 'The category ID.'
        example: 310
        required: true
        schema:
          type: integer
  /api/v1/store/brands:
    get:
      summary: 'Brand sales'
      operationId: brandSales
      description: |-
        Returns product brands (also known as vendors in some platforms) from your
        store together with brand-level sales metrics for the selected period.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: page
          description: 'Page number for pagination.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number for pagination.'
            example: 1
        -
          in: query
          name: per_page
          description: 'Number of brands per page. Min 1, max 100.'
          example: 10
          required: false
          schema:
            type: integer
            description: 'Number of brands per page. Min 1, max 100.'
            example: 10
        -
          in: query
          name: search
          description: 'Search term to filter brands.'
          example: nike
          required: false
          schema:
            type: string
            description: 'Search term to filter brands.'
            example: nike
        -
          in: query
          name: order_filters
          description: 'Optional JSON-encoded array of order-level filters applied before calculating brand sales. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference).'
          example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
          required: false
          schema:
            type: string
            description: 'Optional JSON-encoded array of order-level filters applied before calculating brand sales. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference).'
            example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      brand: Metorik
                      products: 12
                      gross_items_sold: 184
                      items_refunded: 3
                      net_items_sold: 181
                      gross_sales: 14536
                      total_tax: 1211.33
                      total_discounted: 210
                      total_refunds: 237
                      net_orders: 176
                      net_sales: 14089
                  pagination:
                    current_page: 1
                    per_page: 10
                    has_more_pages: true
                properties:
                  data:
                    type: array
                    example:
                      -
                        brand: Metorik
                        products: 12
                        gross_items_sold: 184
                        items_refunded: 3
                        net_items_sold: 181
                        gross_sales: 14536
                        total_tax: 1211.33
                        total_discounted: 210
                        total_refunds: 237
                        net_orders: 176
                        net_sales: 14089
                    items:
                      type: object
                      properties:
                        brand:
                          type: string
                          example: Metorik
                        products:
                          type: integer
                          example: 12
                        gross_items_sold:
                          type: integer
                          example: 184
                        items_refunded:
                          type: integer
                          example: 3
                        net_items_sold:
                          type: integer
                          example: 181
                        gross_sales:
                          type: integer
                          example: 14536
                        total_tax:
                          type: number
                          example: 1211.33
                        total_discounted:
                          type: integer
                          example: 210
                        total_refunds:
                          type: integer
                          example: 237
                        net_orders:
                          type: integer
                          example: 176
                        net_sales:
                          type: integer
                          example: 14089
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 10
                      has_more_pages:
                        type: boolean
                        example: true
      tags:
        - Brands
  /api/v1/store/coupons:
    get:
      summary: 'Coupon usage'
      operationId: couponUsage
      description: |-
        Returns coupons from your store together with usage and discount totals
        for the selected period.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: page
          description: 'Page number for pagination.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number for pagination.'
            example: 1
        -
          in: query
          name: per_page
          description: 'Number of coupons per page. Min 1, max 100.'
          example: 10
          required: false
          schema:
            type: integer
            description: 'Number of coupons per page. Min 1, max 100.'
            example: 10
        -
          in: query
          name: order_by
          description: 'Sort field.'
          example: coupon_created_at
          required: false
          schema:
            type: string
            description: 'Sort field.'
            example: coupon_created_at
            enum:
              - code
              - coupon_id
              - coupon_created_at
              - coupon_updated_at
              - amount
              - usage_count
              - total_discounted
              - sales_generated
              - sales_generated_gross_profit
              - last_used_at
        -
          in: query
          name: order_dir
          description: 'Sort direction.'
          example: desc
          required: false
          schema:
            type: string
            description: 'Sort direction.'
            example: desc
            enum:
              - asc
              - desc
        -
          in: query
          name: search
          description: 'Search term to filter coupons.'
          example: SUMMER
          required: false
          schema:
            type: string
            description: 'Search term to filter coupons.'
            example: SUMMER
        -
          in: query
          name: has_usage
          description: 'Filter coupons by whether they were used in the selected period.'
          example: true
          required: false
          schema:
            type: boolean
            description: 'Filter coupons by whether they were used in the selected period.'
            example: true
        -
          in: query
          name: order_filters
          description: 'Optional JSON-encoded array of order-level filters applied before calculating coupon usage and sales. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference).'
          example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
          required: false
          schema:
            type: string
            description: 'Optional JSON-encoded array of order-level filters applied before calculating coupon usage and sales. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference).'
            example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      coupon_id: 123
                      code: SUMMER10
                      status: publish
                      coupon_created_at: '2025-05-01T11:00:00Z'
                      coupon_updated_at: '2026-03-01T07:30:00Z'
                      date_expires: null
                      amount: 10
                      discount_type: percent
                      usage_count: 42
                      total_discounted: 416
                      sales_generated: 3186.5
                      sales_generated_cost: 992.2
                      sales_generated_gross_profit: 2194.3
                      last_used_at: '2026-03-25T18:42:00Z'
                      resource_link: 'https://app.metorik.com/coupons/123'
                  pagination:
                    current_page: 1
                    per_page: 10
                    has_more_pages: true
                properties:
                  data:
                    type: array
                    example:
                      -
                        coupon_id: 123
                        code: SUMMER10
                        status: publish
                        coupon_created_at: '2025-05-01T11:00:00Z'
                        coupon_updated_at: '2026-03-01T07:30:00Z'
                        date_expires: null
                        amount: 10
                        discount_type: percent
                        usage_count: 42
                        total_discounted: 416
                        sales_generated: 3186.5
                        sales_generated_cost: 992.2
                        sales_generated_gross_profit: 2194.3
                        last_used_at: '2026-03-25T18:42:00Z'
                        resource_link: 'https://app.metorik.com/coupons/123'
                    items:
                      type: object
                      properties:
                        coupon_id:
                          type: integer
                          example: 123
                        code:
                          type: string
                          example: SUMMER10
                        status:
                          type: string
                          example: publish
                        coupon_created_at:
                          type: string
                          example: '2025-05-01T11:00:00Z'
                        coupon_updated_at:
                          type: string
                          example: '2026-03-01T07:30:00Z'
                        date_expires:
                          type: string
                          example: null
                          nullable: true
                        amount:
                          type: integer
                          example: 10
                        discount_type:
                          type: string
                          example: percent
                        usage_count:
                          type: integer
                          example: 42
                        total_discounted:
                          type: integer
                          example: 416
                        sales_generated:
                          type: number
                          example: 3186.5
                        sales_generated_cost:
                          type: number
                          example: 992.2
                        sales_generated_gross_profit:
                          type: number
                          example: 2194.3
                        last_used_at:
                          type: string
                          example: '2026-03-25T18:42:00Z'
                        resource_link:
                          type: string
                          example: 'https://app.metorik.com/coupons/123'
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 10
                      has_more_pages:
                        type: boolean
                        example: true
      tags:
        - Coupons
  '/api/v1/store/coupons/{coupon}/by-date':
    get:
      summary: 'Coupon usage by date'
      operationId: couponUsageByDate
      description: |-
        Returns coupon usage and discount totals over time for a single coupon in
        the selected period. Date buckets use the store timezone.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: group_by
          description: 'Time interval for grouping the results.'
          example: day
          required: false
          schema:
            type: string
            description: 'Time interval for grouping the results.'
            example: day
            enum:
              - hour
              - day
              - week
              - month
              - year
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    resource_link: 'https://app.metorik.com/coupons/321'
                  resource:
                    coupon_id: 321
                    code: SPRING10
                    resource_link: 'https://app.metorik.com/coupons/321'
                  totals:
                    usage_count: 1
                    total_discounted: 15
                    sales_generated: 120
                    sales_generated_cost: 20
                    sales_generated_gross_profit: 100
                  data:
                    -
                      date: '2026-03-25'
                      label: '25 Mar'
                      usage_count: 1
                      total_discounted: 15
                      sales_generated: 120
                      sales_generated_cost: 20
                      sales_generated_gross_profit: 100
                properties:
                  meta:
                    type: object
                    properties:
                      resource_link:
                        type: string
                        example: 'https://app.metorik.com/coupons/321'
                  resource:
                    type: object
                    properties:
                      coupon_id:
                        type: integer
                        example: 321
                      code:
                        type: string
                        example: SPRING10
                      resource_link:
                        type: string
                        example: 'https://app.metorik.com/coupons/321'
                  totals:
                    type: object
                    properties:
                      usage_count:
                        type: integer
                        example: 1
                      total_discounted:
                        type: integer
                        example: 15
                      sales_generated:
                        type: integer
                        example: 120
                      sales_generated_cost:
                        type: integer
                        example: 20
                      sales_generated_gross_profit:
                        type: integer
                        example: 100
                  data:
                    type: array
                    example:
                      -
                        date: '2026-03-25'
                        label: '25 Mar'
                        usage_count: 1
                        total_discounted: 15
                        sales_generated: 120
                        sales_generated_cost: 20
                        sales_generated_gross_profit: 100
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          example: '2026-03-25'
                        label:
                          type: string
                          example: '25 Mar'
                        usage_count:
                          type: integer
                          example: 1
                        total_discounted:
                          type: integer
                          example: 15
                        sales_generated:
                          type: integer
                          example: 120
                        sales_generated_cost:
                          type: integer
                          example: 20
                        sales_generated_gross_profit:
                          type: integer
                          example: 100
      tags:
        - Coupons
    parameters:
      -
        in: path
        name: coupon
        description: 'The coupon ID or coupon code. Numeric-only values are treated as coupon IDs first, so numeric-only coupon codes may resolve to a coupon ID instead.'
        example: SUMMER10
        required: true
        schema:
          type: string
  /api/v1/store/custom-metrics:
    get:
      summary: 'Custom metrics'
      operationId: customMetrics
      description: |-
        Returns all store-wide custom metrics available to the authenticated API
        key. This endpoint only returns lightweight metric metadata and does not
        calculate values.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: page
          description: 'Page number. Min 1.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number. Min 1.'
            example: 1
        -
          in: query
          name: per_page
          description: 'Number of custom metrics per page. Min 1, max 100. Defaults to 50.'
          example: 50
          required: false
          schema:
            type: integer
            description: 'Number of custom metrics per page. Min 1, max 100. Defaults to 50.'
            example: 50
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: 101
                      name: 'Average Order Value'
                      description: 'A public metric.'
                      format: money
                      decimals: 2
                    -
                      id: 102
                      name: 'Repeat Customer Rate'
                      description: 'Store-wide repeat customer percentage.'
                      format: percent
                      decimals: 1
                  pagination:
                    current_page: 1
                    per_page: 50
                    has_more_pages: false
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: 101
                        name: 'Average Order Value'
                        description: 'A public metric.'
                        format: money
                        decimals: 2
                      -
                        id: 102
                        name: 'Repeat Customer Rate'
                        description: 'Store-wide repeat customer percentage.'
                        format: percent
                        decimals: 1
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 101
                        name:
                          type: string
                          example: 'Average Order Value'
                        description:
                          type: string
                          example: 'A public metric.'
                        format:
                          type: string
                          example: money
                        decimals:
                          type: integer
                          example: 2
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 50
                      has_more_pages:
                        type: boolean
                        example: false
      tags:
        - 'Custom Metrics'
  '/api/v1/store/custom-metrics/{metric}/value':
    get:
      summary: 'Custom metric value'
      operationId: customMetricValue
      description: |-
        Calculates a single store-wide custom metric for the requested date range
        and returns both the raw numeric value and a store-formatted display value.
        Metrics that reference non-store-wide segments are rejected.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 101
                    name: 'Gross Sales Metric'
                    description: 'Public gross sales.'
                    format: money
                    decimals: 2
                    value: 1234.5
                    formatted_value: '$1,234.50'
                  meta:
                    start_date: '2026-02-01'
                    end_date: '2026-02-28'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 101
                      name:
                        type: string
                        example: 'Gross Sales Metric'
                      description:
                        type: string
                        example: 'Public gross sales.'
                      format:
                        type: string
                        example: money
                      decimals:
                        type: integer
                        example: 2
                      value:
                        type: number
                        example: 1234.5
                      formatted_value:
                        type: string
                        example: '$1,234.50'
                  meta:
                    type: object
                    properties:
                      start_date:
                        type: string
                        example: '2026-02-01'
                      end_date:
                        type: string
                        example: '2026-02-28'
      tags:
        - 'Custom Metrics'
    parameters:
      -
        in: path
        name: metric
        description: 'The custom metric ID.'
        example: 101
        required: true
        schema:
          type: integer
  /api/v1/store/reports/customers-by-date:
    get:
      summary: 'Customers by date'
      operationId: customersByDate
      description: |-
        Returns new customers over time together with their related lifetime order
        count, spend, and item totals for each period. Responses are capped at
        1500 time periods.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: group_by
          description: 'Time interval for grouping the results.'
          example: day
          required: false
          schema:
            type: string
            description: 'Time interval for grouping the results.'
            example: day
            enum:
              - hour
              - day
              - week
              - month
              - year
        -
          in: query
          name: segment
          description: 'Optional saved store-wide customer segment ID. You can find the ID on the [customer segments page](https://app.metorik.com/segments/customers).'
          example: 123
          required: false
          schema:
            type: integer
            description: 'Optional saved store-wide customer segment ID. You can find the ID on the [customer segments page](https://app.metorik.com/segments/customers).'
            example: 123
        -
          in: query
          name: customer_filters
          description: 'Optional JSON-encoded array of customer-level filters applied before calculating the report. See [Customer Filters Reference](#customers-GETapi-v1-store-customers-filters-reference). Cannot be combined with `segment`.'
          example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
          required: false
          schema:
            type: string
            description: 'Optional JSON-encoded array of customer-level filters applied before calculating the report. See [Customer Filters Reference](#customers-GETapi-v1-store-customers-filters-reference). Cannot be combined with `segment`.'
            example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    report_link: 'https://app.metorik.com/reports/customers#customers-over-time'
                  totals:
                    gross: 124550.42
                    orders: 712
                    customers: 508
                    items: 1196
                  data:
                    -
                      date: '2026-03-01'
                      customers: 18
                      orders: 26
                      gross: 4420.55
                      items: 39
                    -
                      date: '2026-03-02'
                      customers: 21
                      orders: 30
                      gross: 4988.1
                      items: 44
                properties:
                  meta:
                    type: object
                    properties:
                      report_link:
                        type: string
                        example: 'https://app.metorik.com/reports/customers#customers-over-time'
                  totals:
                    type: object
                    properties:
                      gross:
                        type: number
                        example: 124550.42
                      orders:
                        type: integer
                        example: 712
                      customers:
                        type: integer
                        example: 508
                      items:
                        type: integer
                        example: 1196
                  data:
                    type: array
                    example:
                      -
                        date: '2026-03-01'
                        customers: 18
                        orders: 26
                        gross: 4420.55
                        items: 39
                      -
                        date: '2026-03-02'
                        customers: 21
                        orders: 30
                        gross: 4988.1
                        items: 44
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          example: '2026-03-01'
                        customers:
                          type: integer
                          example: 18
                        orders:
                          type: integer
                          example: 26
                        gross:
                          type: number
                          example: 4420.55
                        items:
                          type: integer
                          example: 39
      tags:
        - Reports
  /api/v1/store/reports/orders-by-date:
    get:
      summary: 'Orders by date'
      operationId: ordersByDate
      description: |-
        Returns order metrics over time for orders placed in the selected period.
        Net values deduct refunds tied to those orders even if the refund happened later,
        giving you order-focused performance rather than refund timing by period.
        Responses are capped at 1500 time periods.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: group_by
          description: 'Time interval for grouping the results.'
          example: day
          required: false
          schema:
            type: string
            description: 'Time interval for grouping the results.'
            example: day
            enum:
              - hour
              - day
              - week
              - month
              - year
        -
          in: query
          name: segment
          description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
          example: 123
          required: false
          schema:
            type: integer
            description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
            example: 123
        -
          in: query
          name: order_filters
          description: 'Optional JSON-encoded array of order-level filters applied before calculating the report. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference). Cannot be combined with `segment`.'
          example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
          required: false
          schema:
            type: string
            description: 'Optional JSON-encoded array of order-level filters applied before calculating the report. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference). Cannot be combined with `segment`.'
            example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    report_link: 'https://app.metorik.com/reports/orders#orders-over-time'
                  totals:
                    gross: 124550.42
                    net: 118420.13
                    orders: 712
                    customers: 508
                    items: 1196
                    aov: 174.93
                    aoi: 1.68
                    discounts: 2140.55
                    refunds: 1986.23
                    taxes: 10334.89
                    shipping: 5421.1
                    fees: 882.41
                  data:
                    -
                      date: '2026-03-01'
                      orders: 26
                      customers: 22
                      gross: 4420.55
                      net: 4201.44
                      items: 39
                      aov: 170.02
                      aoi: 1.5
                      discounts: 88
                      refunds: 41
                      taxes: 366.71
                      shipping: 192.5
                      fees: 31.84
                properties:
                  meta:
                    type: object
                    properties:
                      report_link:
                        type: string
                        example: 'https://app.metorik.com/reports/orders#orders-over-time'
                  totals:
                    type: object
                    properties:
                      gross:
                        type: number
                        example: 124550.42
                      net:
                        type: number
                        example: 118420.13
                      orders:
                        type: integer
                        example: 712
                      customers:
                        type: integer
                        example: 508
                      items:
                        type: integer
                        example: 1196
                      aov:
                        type: number
                        example: 174.93
                      aoi:
                        type: number
                        example: 1.68
                      discounts:
                        type: number
                        example: 2140.55
                      refunds:
                        type: number
                        example: 1986.23
                      taxes:
                        type: number
                        example: 10334.89
                      shipping:
                        type: number
                        example: 5421.1
                      fees:
                        type: number
                        example: 882.41
                  data:
                    type: array
                    example:
                      -
                        date: '2026-03-01'
                        orders: 26
                        customers: 22
                        gross: 4420.55
                        net: 4201.44
                        items: 39
                        aov: 170.02
                        aoi: 1.5
                        discounts: 88
                        refunds: 41
                        taxes: 366.71
                        shipping: 192.5
                        fees: 31.84
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          example: '2026-03-01'
                        orders:
                          type: integer
                          example: 26
                        customers:
                          type: integer
                          example: 22
                        gross:
                          type: number
                          example: 4420.55
                        net:
                          type: number
                          example: 4201.44
                        items:
                          type: integer
                          example: 39
                        aov:
                          type: number
                          example: 170.02
                        aoi:
                          type: number
                          example: 1.5
                        discounts:
                          type: integer
                          example: 88
                        refunds:
                          type: integer
                          example: 41
                        taxes:
                          type: number
                          example: 366.71
                        shipping:
                          type: number
                          example: 192.5
                        fees:
                          type: number
                          example: 31.84
      tags:
        - Reports
  /api/v1/store/reports/revenue-by-date:
    get:
      summary: 'Revenue by date'
      operationId: revenueByDate
      description: |-
        Returns revenue metrics over time for the selected period. Net revenue is calculated
        by deducting refunds when they happen, even if they relate to orders outside this period,
        along with other deductions based on your store settings. Responses are capped at
        1500 time periods.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: group_by
          description: 'Time interval for grouping the results.'
          example: day
          required: false
          schema:
            type: string
            description: 'Time interval for grouping the results.'
            example: day
            enum:
              - hour
              - day
              - week
              - month
              - year
        -
          in: query
          name: segment
          description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
          example: 123
          required: false
          schema:
            type: integer
            description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
            example: 123
        -
          in: query
          name: order_filters
          description: 'Optional JSON-encoded array of order-level filters applied before calculating the report. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference). Cannot be combined with `segment`.'
          example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
          required: false
          schema:
            type: string
            description: 'Optional JSON-encoded array of order-level filters applied before calculating the report. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference). Cannot be combined with `segment`.'
            example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    report_link: 'https://app.metorik.com/reports/revenue#revenue-over-time'
                  totals:
                    gross: 124550.42
                    orders: 712
                    items: 1196
                    discounts: 2140.55
                    refunds: 1986.23
                    refunds_count: 14
                    taxes: 10334.89
                    shipping: 5421.1
                    fees: 882.41
                    net: 118420.13
                  data:
                    -
                      date: '2026-03-01'
                      gross: 4420.55
                      orders: 26
                      items: 39
                      discounts: 88
                      refunds: 41
                      refunds_count: 1
                      taxes: 366.71
                      shipping: 192.5
                      fees: 31.84
                      net: 4201.44
                properties:
                  meta:
                    type: object
                    properties:
                      report_link:
                        type: string
                        example: 'https://app.metorik.com/reports/revenue#revenue-over-time'
                  totals:
                    type: object
                    properties:
                      gross:
                        type: number
                        example: 124550.42
                      orders:
                        type: integer
                        example: 712
                      items:
                        type: integer
                        example: 1196
                      discounts:
                        type: number
                        example: 2140.55
                      refunds:
                        type: number
                        example: 1986.23
                      refunds_count:
                        type: integer
                        example: 14
                      taxes:
                        type: number
                        example: 10334.89
                      shipping:
                        type: number
                        example: 5421.1
                      fees:
                        type: number
                        example: 882.41
                      net:
                        type: number
                        example: 118420.13
                  data:
                    type: array
                    example:
                      -
                        date: '2026-03-01'
                        gross: 4420.55
                        orders: 26
                        items: 39
                        discounts: 88
                        refunds: 41
                        refunds_count: 1
                        taxes: 366.71
                        shipping: 192.5
                        fees: 31.84
                        net: 4201.44
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          example: '2026-03-01'
                        gross:
                          type: number
                          example: 4420.55
                        orders:
                          type: integer
                          example: 26
                        items:
                          type: integer
                          example: 39
                        discounts:
                          type: integer
                          example: 88
                        refunds:
                          type: integer
                          example: 41
                        refunds_count:
                          type: integer
                          example: 1
                        taxes:
                          type: number
                          example: 366.71
                        shipping:
                          type: number
                          example: 192.5
                        fees:
                          type: number
                          example: 31.84
                        net:
                          type: number
                          example: 4201.44
      tags:
        - Reports
  /api/v1/store/reports/profit-by-date:
    get:
      summary: 'Profit by date'
      operationId: profitByDate
      description: |-
        Returns profit metrics over time, including net revenue, costs, profit,
        and margin for each period in the selected date range. Responses are capped at
        1500 time periods.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: group_by
          description: 'Time interval for grouping the results.'
          example: day
          required: false
          schema:
            type: string
            description: 'Time interval for grouping the results.'
            example: day
            enum:
              - hour
              - day
              - week
              - month
              - year
        -
          in: query
          name: segment
          description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
          example: 123
          required: false
          schema:
            type: integer
            description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
            example: 123
        -
          in: query
          name: order_filters
          description: 'Optional JSON-encoded array of order-level filters applied before calculating the report. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference). Cannot be combined with `segment`.'
          example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
          required: false
          schema:
            type: string
            description: 'Optional JSON-encoded array of order-level filters applied before calculating the report. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference). Cannot be combined with `segment`.'
            example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    report_link: 'https://app.metorik.com/reports/profit#profit-costs-over-time'
                  totals:
                    gross: 124550.42
                    net: 118420.13
                    orders: 712
                    items: 1196
                    cogs: 58440.28
                    gross_cogs: 60210.14
                    profit: 59979.85
                    gross_profit: 64340.28
                    margin: 50.65
                    gross_margin: 51.66
                    advertising_cost: 4580.11
                    operational_cost: 1220.5
                    product_cogs: 49210.42
                    shipping_cogs: 3120.14
                    transaction_cogs: 3910.28
                    extra_cogs: 1979.44
                    refunds: 1986.23
                    refunds_count: 14
                    taxes: 10334.89
                    shipping: 5421.1
                  data:
                    -
                      date: '2026-03-01'
                      gross: 4420.55
                      net: 4201.44
                      orders: 26
                      items: 39
                      cogs: 2066.2
                      gross_cogs: 2130.9
                      profit: 2135.24
                      gross_profit: 2289.65
                      margin: 50.82
                      gross_margin: 51.8
                      advertising_cost: 142.8
                      operational_cost: 38.4
                      product_cogs: 1730.5
                      shipping_cogs: 98.2
                      transaction_cogs: 145.6
                      extra_cogs: 53.1
                properties:
                  meta:
                    type: object
                    properties:
                      report_link:
                        type: string
                        example: 'https://app.metorik.com/reports/profit#profit-costs-over-time'
                  totals:
                    type: object
                    properties:
                      gross:
                        type: number
                        example: 124550.42
                      net:
                        type: number
                        example: 118420.13
                      orders:
                        type: integer
                        example: 712
                      items:
                        type: integer
                        example: 1196
                      cogs:
                        type: number
                        example: 58440.28
                      gross_cogs:
                        type: number
                        example: 60210.14
                      profit:
                        type: number
                        example: 59979.85
                      gross_profit:
                        type: number
                        example: 64340.28
                      margin:
                        type: number
                        example: 50.65
                      gross_margin:
                        type: number
                        example: 51.66
                      advertising_cost:
                        type: number
                        example: 4580.11
                      operational_cost:
                        type: number
                        example: 1220.5
                      product_cogs:
                        type: number
                        example: 49210.42
                      shipping_cogs:
                        type: number
                        example: 3120.14
                      transaction_cogs:
                        type: number
                        example: 3910.28
                      extra_cogs:
                        type: number
                        example: 1979.44
                      refunds:
                        type: number
                        example: 1986.23
                      refunds_count:
                        type: integer
                        example: 14
                      taxes:
                        type: number
                        example: 10334.89
                      shipping:
                        type: number
                        example: 5421.1
                  data:
                    type: array
                    example:
                      -
                        date: '2026-03-01'
                        gross: 4420.55
                        net: 4201.44
                        orders: 26
                        items: 39
                        cogs: 2066.2
                        gross_cogs: 2130.9
                        profit: 2135.24
                        gross_profit: 2289.65
                        margin: 50.82
                        gross_margin: 51.8
                        advertising_cost: 142.8
                        operational_cost: 38.4
                        product_cogs: 1730.5
                        shipping_cogs: 98.2
                        transaction_cogs: 145.6
                        extra_cogs: 53.1
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          example: '2026-03-01'
                        gross:
                          type: number
                          example: 4420.55
                        net:
                          type: number
                          example: 4201.44
                        orders:
                          type: integer
                          example: 26
                        items:
                          type: integer
                          example: 39
                        cogs:
                          type: number
                          example: 2066.2
                        gross_cogs:
                          type: number
                          example: 2130.9
                        profit:
                          type: number
                          example: 2135.24
                        gross_profit:
                          type: number
                          example: 2289.65
                        margin:
                          type: number
                          example: 50.82
                        gross_margin:
                          type: number
                          example: 51.8
                        advertising_cost:
                          type: number
                          example: 142.8
                        operational_cost:
                          type: number
                          example: 38.4
                        product_cogs:
                          type: number
                          example: 1730.5
                        shipping_cogs:
                          type: number
                          example: 98.2
                        transaction_cogs:
                          type: number
                          example: 145.6
                        extra_cogs:
                          type: number
                          example: 53.1
      tags:
        - Reports
  /api/v1/store/reports/advertising-costs-by-date:
    get:
      summary: 'Advertising costs by date'
      operationId: advertisingCostsByDate
      description: |-
        Returns advertising cost totals over time, including a breakdown for each
        advertising method recorded in the selected date range. Responses are capped at
        1500 time periods.

        The `meta.methods` object maps each stable method ID used in `totals.methods`
        and `data[].methods` to its display name.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: group_by
          description: 'Time interval for grouping the results.'
          example: day
          required: false
          schema:
            type: string
            description: 'Time interval for grouping the results.'
            example: day
            enum:
              - hour
              - day
              - week
              - month
              - year
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    report_link: 'https://app.metorik.com/reports/profit#advertising-costs-by-date'
                    results_limited: false
                    methods:
                      google: google
                      facebook-123: 'Facebook: Main Account'
                  totals:
                    total: 4580.11
                    methods:
                      google: 3200
                      facebook-123: 1380.11
                  data:
                    -
                      date: '2026-03-01'
                      total: 142.8
                      methods:
                        google: 100
                        facebook-123: 42.8
                properties:
                  meta:
                    type: object
                    properties:
                      report_link:
                        type: string
                        example: 'https://app.metorik.com/reports/profit#advertising-costs-by-date'
                      results_limited:
                        type: boolean
                        example: false
                      methods:
                        type: object
                        properties:
                          google:
                            type: string
                            example: google
                          facebook-123:
                            type: string
                            example: 'Facebook: Main Account'
                  totals:
                    type: object
                    properties:
                      total:
                        type: number
                        example: 4580.11
                      methods:
                        type: object
                        properties:
                          google:
                            type: integer
                            example: 3200
                          facebook-123:
                            type: number
                            example: 1380.11
                  data:
                    type: array
                    example:
                      -
                        date: '2026-03-01'
                        total: 142.8
                        methods:
                          google: 100
                          facebook-123: 42.8
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          example: '2026-03-01'
                        total:
                          type: number
                          example: 142.8
                        methods:
                          type: object
                          properties:
                            google:
                              type: integer
                              example: 100
                            facebook-123:
                              type: number
                              example: 42.8
      tags:
        - Reports
  /api/v1/store/reports/carts-started-by-date:
    get:
      summary: 'Carts started by date'
      operationId: cartsStartedByDate
      description: |-
        Returns cart started, abandoned, placed, and recovered counts and amounts
        over time for the selected period. Responses are capped at 1500 time periods.
        Your store must already have cart tracking/data set up in Metorik for this
        report to return meaningful cart activity.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: group_by
          description: 'Time interval for grouping the results.'
          example: day
          required: false
          schema:
            type: string
            description: 'Time interval for grouping the results.'
            example: day
            enum:
              - hour
              - day
              - week
              - month
              - year
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    report_link: 'https://app.metorik.com/reports/carts'
                    results_limited: false
                    has_active_recovery_emails: true
                  totals:
                    started: 6
                    started_amount: 412.5
                    started_items: 9
                    abandoned: 2
                    abandoned_amount: 145
                    placed: 3
                    placed_amount: 201
                    recovered: 1
                    recovered_amount: 66.5
                  data:
                    -
                      date: '2026-03-01'
                      label: 'Mar 1, 2026'
                      started: 2
                      started_amount: 120
                      started_items: 3
                      abandoned: 1
                      abandoned_amount: 45
                      placed: 1
                      placed_amount: 75
                      recovered: 0
                      recovered_amount: 0
                properties:
                  meta:
                    type: object
                    properties:
                      report_link:
                        type: string
                        example: 'https://app.metorik.com/reports/carts'
                      results_limited:
                        type: boolean
                        example: false
                      has_active_recovery_emails:
                        type: boolean
                        example: true
                  totals:
                    type: object
                    properties:
                      started:
                        type: integer
                        example: 6
                      started_amount:
                        type: number
                        example: 412.5
                      started_items:
                        type: integer
                        example: 9
                      abandoned:
                        type: integer
                        example: 2
                      abandoned_amount:
                        type: integer
                        example: 145
                      placed:
                        type: integer
                        example: 3
                      placed_amount:
                        type: integer
                        example: 201
                      recovered:
                        type: integer
                        example: 1
                      recovered_amount:
                        type: number
                        example: 66.5
                  data:
                    type: array
                    example:
                      -
                        date: '2026-03-01'
                        label: 'Mar 1, 2026'
                        started: 2
                        started_amount: 120
                        started_items: 3
                        abandoned: 1
                        abandoned_amount: 45
                        placed: 1
                        placed_amount: 75
                        recovered: 0
                        recovered_amount: 0
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          example: '2026-03-01'
                        label:
                          type: string
                          example: 'Mar 1, 2026'
                        started:
                          type: integer
                          example: 2
                        started_amount:
                          type: integer
                          example: 120
                        started_items:
                          type: integer
                          example: 3
                        abandoned:
                          type: integer
                          example: 1
                        abandoned_amount:
                          type: integer
                          example: 45
                        placed:
                          type: integer
                          example: 1
                        placed_amount:
                          type: integer
                          example: 75
                        recovered:
                          type: integer
                          example: 0
                        recovered_amount:
                          type: integer
                          example: 0
      tags:
        - Reports
  /api/v1/store/reports/subscriptions-stats:
    get:
      summary: 'Subscriptions stats'
      operationId: subscriptionsStats
      description: |-
        Returns active subscription and MRR stats over time for subscription stores. Responses are capped
        at 1500 time periods.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-03-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-03-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-03-31'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-03-31'
        -
          in: query
          name: group_by
          description: 'Time interval for grouping the results.'
          example: day
          required: false
          schema:
            type: string
            description: 'Time interval for grouping the results.'
            example: day
            enum:
              - day
              - week
              - month
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    report_link: 'https://app.metorik.com/reports/subscriptions'
                  totals:
                    active_subscriptions: 312
                    active_paid_subscriptions: 284
                    active_free_subscriptions: 28
                    mrr: 18450
                    new_subscriptions: 24
                    new_subscriptions_mrr: 1320
                    churned_subscriptions: 8
                    churned_subscriptions_mrr: 410
                  data:
                    -
                      date: '2026-03-01'
                      active_subscriptions: 301
                      active_paid_subscriptions: 274
                      active_free_subscriptions: 27
                      mrr: 17990
                      new_subscriptions: 3
                      new_subscriptions_mrr: 180
                      churned_subscriptions: 1
                      churned_subscriptions_mrr: 45
                properties:
                  meta:
                    type: object
                    properties:
                      report_link:
                        type: string
                        example: 'https://app.metorik.com/reports/subscriptions'
                  totals:
                    type: object
                    properties:
                      active_subscriptions:
                        type: integer
                        example: 312
                      active_paid_subscriptions:
                        type: integer
                        example: 284
                      active_free_subscriptions:
                        type: integer
                        example: 28
                      mrr:
                        type: integer
                        example: 18450
                      new_subscriptions:
                        type: integer
                        example: 24
                      new_subscriptions_mrr:
                        type: integer
                        example: 1320
                      churned_subscriptions:
                        type: integer
                        example: 8
                      churned_subscriptions_mrr:
                        type: integer
                        example: 410
                  data:
                    type: array
                    example:
                      -
                        date: '2026-03-01'
                        active_subscriptions: 301
                        active_paid_subscriptions: 274
                        active_free_subscriptions: 27
                        mrr: 17990
                        new_subscriptions: 3
                        new_subscriptions_mrr: 180
                        churned_subscriptions: 1
                        churned_subscriptions_mrr: 45
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          example: '2026-03-01'
                        active_subscriptions:
                          type: integer
                          example: 301
                        active_paid_subscriptions:
                          type: integer
                          example: 274
                        active_free_subscriptions:
                          type: integer
                          example: 27
                        mrr:
                          type: integer
                          example: 17990
                        new_subscriptions:
                          type: integer
                          example: 3
                        new_subscriptions_mrr:
                          type: integer
                          example: 180
                        churned_subscriptions:
                          type: integer
                          example: 1
                        churned_subscriptions_mrr:
                          type: integer
                          example: 45
      tags:
        - Reports
  /api/v1/store/reports/revenue-grouped-by:
    get:
      summary: 'Revenue grouped by'
      operationId: revenueGroupedBy
      description: |-
        Returns revenue metrics grouped by a chosen store dimension, such as billing country,
        product type, or another supported grouping value. Responses are capped at
        1500 grouped rows.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: grouped_by
          description: 'Dimension to group revenue by.'
          example: billing_address_country
          required: true
          schema:
            type: string
            description: 'Dimension to group revenue by.'
            example: billing_address_country
            enum:
              - billing_address_country
              - billing_address_state
              - billing_address_city
              - billing_address_postcode
              - shipping_address_country
              - shipping_address_state
              - shipping_address_city
              - shipping_address_postcode
              - payment_method
              - payment_method_title
              - shipping_method_id
              - shipping_method_title
              - currency
              - created_via
              - order_type
              - tax_rate_code
              - tax_rate_label
              - tax_rate_id
              - customer_role
              - custom_field
        -
          in: query
          name: custom_field_key
          description: 'Required when grouped_by is custom_field. Custom field key to group orders by.'
          example: sales_channel
          required: false
          schema:
            type: string
            description: 'Required when grouped_by is custom_field. Custom field key to group orders by.'
            example: sales_channel
        -
          in: query
          name: segment
          description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
          example: 123
          required: false
          schema:
            type: integer
            description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
            example: 123
        -
          in: query
          name: order_filters
          description: 'Optional JSON-encoded array of order-level filters applied before calculating the report. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference). Cannot be combined with `segment`.'
          example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
          required: false
          schema:
            type: string
            description: 'Optional JSON-encoded array of order-level filters applied before calculating the report. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference). Cannot be combined with `segment`.'
            example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    report_link: 'https://app.metorik.com/reports/revenue#revenue-grouped-by'
                  totals:
                    gross: 124550.42
                    orders: 712
                    items: 1196
                    discounts: 2140.55
                    refunds: 1986.23
                    taxes: 10334.89
                    shipping: 5421.1
                    fees: 882.41
                    net: 118420.13
                  data:
                    -
                      date: 'United States'
                      gross: 68210.18
                      orders: 392
                      items: 670
                      discounts: 1220.4
                      refunds: 880.2
                      taxes: 5642.81
                      shipping: 3014.2
                      fees: 481.77
                      net: 64985.8
                properties:
                  meta:
                    type: object
                    properties:
                      report_link:
                        type: string
                        example: 'https://app.metorik.com/reports/revenue#revenue-grouped-by'
                  totals:
                    type: object
                    properties:
                      gross:
                        type: number
                        example: 124550.42
                      orders:
                        type: integer
                        example: 712
                      items:
                        type: integer
                        example: 1196
                      discounts:
                        type: number
                        example: 2140.55
                      refunds:
                        type: number
                        example: 1986.23
                      taxes:
                        type: number
                        example: 10334.89
                      shipping:
                        type: number
                        example: 5421.1
                      fees:
                        type: number
                        example: 882.41
                      net:
                        type: number
                        example: 118420.13
                  data:
                    type: array
                    example:
                      -
                        date: 'United States'
                        gross: 68210.18
                        orders: 392
                        items: 670
                        discounts: 1220.4
                        refunds: 880.2
                        taxes: 5642.81
                        shipping: 3014.2
                        fees: 481.77
                        net: 64985.8
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          example: 'United States'
                        gross:
                          type: number
                          example: 68210.18
                        orders:
                          type: integer
                          example: 392
                        items:
                          type: integer
                          example: 670
                        discounts:
                          type: number
                          example: 1220.4
                        refunds:
                          type: number
                          example: 880.2
                        taxes:
                          type: number
                          example: 5642.81
                        shipping:
                          type: number
                          example: 3014.2
                        fees:
                          type: number
                          example: 481.77
                        net:
                          type: number
                          example: 64985.8
      tags:
        - Reports
  /api/v1/store/reports/orders-grouped-by:
    get:
      summary: 'Orders grouped by'
      operationId: ordersGroupedBy
      description: |-
        Returns order metrics grouped by a chosen store dimension, so you can compare
        order performance across segments like country or other supported grouping values.
        Responses are capped at 1500 grouped rows.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: grouped_by
          description: 'Dimension to group orders by.'
          example: billing_address_country
          required: true
          schema:
            type: string
            description: 'Dimension to group orders by.'
            example: billing_address_country
            enum:
              - billing_address_country
              - billing_address_state
              - billing_address_city
              - billing_address_postcode
              - billing_address_company
              - shipping_address_country
              - shipping_address_state
              - shipping_address_city
              - shipping_address_postcode
              - shipping_address_company
              - status
              - customer_role
              - payment_method
              - payment_method_title
              - shipping_method_id
              - shipping_method_title
              - fee_line_title
              - currency
              - created_via
              - order_type
              - custom_field
        -
          in: query
          name: custom_field_key
          description: 'Required when grouped_by is custom_field. Custom field key to group orders by.'
          example: sales_channel
          required: false
          schema:
            type: string
            description: 'Required when grouped_by is custom_field. Custom field key to group orders by.'
            example: sales_channel
        -
          in: query
          name: segment
          description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
          example: 123
          required: false
          schema:
            type: integer
            description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
            example: 123
        -
          in: query
          name: order_filters
          description: 'Optional JSON-encoded array of order-level filters applied before calculating the report. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference). Cannot be combined with `segment`.'
          example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
          required: false
          schema:
            type: string
            description: 'Optional JSON-encoded array of order-level filters applied before calculating the report. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference). Cannot be combined with `segment`.'
            example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    report_link: 'https://app.metorik.com/reports/orders-grouped#orders-grouped-by'
                  totals:
                    gross: 124550.42
                    net: 118420.13
                    orders: 712
                    customers: 508
                    items: 1196
                    aov: 174.93
                    aoi: 1.68
                    discounts: 2140.55
                    refunds: 1986.23
                    taxes: 10334.89
                    shipping: 5421.1
                    fees: 882.41
                  data:
                    -
                      date: 'United States'
                      orders: 392
                      customers: 281
                      gross: 68210.18
                      net: 64985.8
                      items: 670
                      aov: 174.01
                      aoi: 1.71
                      discounts: 1220.4
                      refunds: 880.2
                      taxes: 5642.81
                      shipping: 3014.2
                      fees: 481.77
                properties:
                  meta:
                    type: object
                    properties:
                      report_link:
                        type: string
                        example: 'https://app.metorik.com/reports/orders-grouped#orders-grouped-by'
                  totals:
                    type: object
                    properties:
                      gross:
                        type: number
                        example: 124550.42
                      net:
                        type: number
                        example: 118420.13
                      orders:
                        type: integer
                        example: 712
                      customers:
                        type: integer
                        example: 508
                      items:
                        type: integer
                        example: 1196
                      aov:
                        type: number
                        example: 174.93
                      aoi:
                        type: number
                        example: 1.68
                      discounts:
                        type: number
                        example: 2140.55
                      refunds:
                        type: number
                        example: 1986.23
                      taxes:
                        type: number
                        example: 10334.89
                      shipping:
                        type: number
                        example: 5421.1
                      fees:
                        type: number
                        example: 882.41
                  data:
                    type: array
                    example:
                      -
                        date: 'United States'
                        orders: 392
                        customers: 281
                        gross: 68210.18
                        net: 64985.8
                        items: 670
                        aov: 174.01
                        aoi: 1.71
                        discounts: 1220.4
                        refunds: 880.2
                        taxes: 5642.81
                        shipping: 3014.2
                        fees: 481.77
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          example: 'United States'
                        orders:
                          type: integer
                          example: 392
                        customers:
                          type: integer
                          example: 281
                        gross:
                          type: number
                          example: 68210.18
                        net:
                          type: number
                          example: 64985.8
                        items:
                          type: integer
                          example: 670
                        aov:
                          type: number
                          example: 174.01
                        aoi:
                          type: number
                          example: 1.71
                        discounts:
                          type: number
                          example: 1220.4
                        refunds:
                          type: number
                          example: 880.2
                        taxes:
                          type: number
                          example: 5642.81
                        shipping:
                          type: number
                          example: 3014.2
                        fees:
                          type: number
                          example: 481.77
      tags:
        - Reports
  /api/v1/store/reports/customers-grouped-by:
    get:
      summary: 'Customers grouped by'
      operationId: customersGroupedBy
      description: |-
        Returns customer metrics grouped by a chosen store dimension, helping you compare
        customer activity across segments like billing country or other supported grouping values.
        Responses are capped at 1500 grouped rows.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: grouped_by
          description: 'Dimension to group customers by.'
          example: billing_address_country
          required: true
          schema:
            type: string
            description: 'Dimension to group customers by.'
            example: billing_address_country
            enum:
              - billing_address_country
              - billing_address_state
              - billing_address_city
              - billing_address_postcode
              - billing_address_company
              - shipping_address_country
              - shipping_address_state
              - shipping_address_city
              - shipping_address_postcode
              - shipping_address_company
              - role
              - customer_type
              - custom_field
              - day
              - week
              - month
              - year
              - first_product
              - first_category
              - first_coupon
        -
          in: query
          name: custom_field_key
          description: 'Required when grouped_by is custom_field. Custom field key to group customers by.'
          example: source_label
          required: false
          schema:
            type: string
            description: 'Required when grouped_by is custom_field. Custom field key to group customers by.'
            example: source_label
        -
          in: query
          name: segment
          description: 'Optional saved store-wide customer segment ID. You can find the ID on the [customer segments page](https://app.metorik.com/segments/customers).'
          example: 123
          required: false
          schema:
            type: integer
            description: 'Optional saved store-wide customer segment ID. You can find the ID on the [customer segments page](https://app.metorik.com/segments/customers).'
            example: 123
        -
          in: query
          name: customer_filters
          description: 'Optional JSON-encoded array of customer-level filters applied before calculating the report. See [Customer Filters Reference](#customers-GETapi-v1-store-customers-filters-reference). Cannot be combined with `segment`.'
          example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
          required: false
          schema:
            type: string
            description: 'Optional JSON-encoded array of customer-level filters applied before calculating the report. See [Customer Filters Reference](#customers-GETapi-v1-store-customers-filters-reference). Cannot be combined with `segment`.'
            example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    report_link: 'https://app.metorik.com/reports/customers-grouped'
                  totals:
                    gross: 124550.42
                    orders: 712
                    customers: 508
                    items: 1196
                  data:
                    -
                      date: 'United States'
                      customers: 281
                      orders: 392
                      gross: 68210.18
                      items: 670
                      returning_customers: 214
                      returning_customers_rate: 76.2
                properties:
                  meta:
                    type: object
                    properties:
                      report_link:
                        type: string
                        example: 'https://app.metorik.com/reports/customers-grouped'
                  totals:
                    type: object
                    properties:
                      gross:
                        type: number
                        example: 124550.42
                      orders:
                        type: integer
                        example: 712
                      customers:
                        type: integer
                        example: 508
                      items:
                        type: integer
                        example: 1196
                  data:
                    type: array
                    example:
                      -
                        date: 'United States'
                        customers: 281
                        orders: 392
                        gross: 68210.18
                        items: 670
                        returning_customers: 214
                        returning_customers_rate: 76.2
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          example: 'United States'
                        customers:
                          type: integer
                          example: 281
                        orders:
                          type: integer
                          example: 392
                        gross:
                          type: number
                          example: 68210.18
                        items:
                          type: integer
                          example: 670
                        returning_customers:
                          type: integer
                          example: 214
                        returning_customers_rate:
                          type: number
                          example: 76.2
      tags:
        - Reports
  /api/v1/store/reports/carts-grouped-by:
    get:
      summary: 'Carts grouped by'
      operationId: cartsGroupedBy
      description: |-
        Returns cart counts grouped by a selected cart field, including abandoned,
        placed, and recovered counts and rates. Responses are capped at 1500 grouped rows.
        Your store must already have cart tracking/data set up in Metorik for this
        report to return meaningful cart activity.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: grouped_by
          description: 'Dimension to group carts by.'
          example: billing_address_country
          required: true
          schema:
            type: string
            description: 'Dimension to group carts by.'
            example: billing_address_country
            enum:
              - billing_address_country
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    report_link: 'https://app.metorik.com/reports/carts'
                    results_limited: false
                  data:
                    -
                      grouped_by: US
                      started_count: 4
                      abandoned_count: 1
                      placed_count: 1
                      recovered_count: 1
                      placed_rate: 25
                      abandoned_rate: 25
                      recovered_rate: 25
                    -
                      grouped_by: AU
                      started_count: 1
                      abandoned_count: 0
                      placed_count: 0
                      recovered_count: 0
                      placed_rate: 0
                      abandoned_rate: 0
                      recovered_rate: 0
                properties:
                  meta:
                    type: object
                    properties:
                      report_link:
                        type: string
                        example: 'https://app.metorik.com/reports/carts'
                      results_limited:
                        type: boolean
                        example: false
                  data:
                    type: array
                    example:
                      -
                        grouped_by: US
                        started_count: 4
                        abandoned_count: 1
                        placed_count: 1
                        recovered_count: 1
                        placed_rate: 25
                        abandoned_rate: 25
                        recovered_rate: 25
                      -
                        grouped_by: AU
                        started_count: 1
                        abandoned_count: 0
                        placed_count: 0
                        recovered_count: 0
                        placed_rate: 0
                        abandoned_rate: 0
                        recovered_rate: 0
                    items:
                      type: object
                      properties:
                        grouped_by:
                          type: string
                          example: US
                        started_count:
                          type: integer
                          example: 4
                        abandoned_count:
                          type: integer
                          example: 1
                        placed_count:
                          type: integer
                          example: 1
                        recovered_count:
                          type: integer
                          example: 1
                        placed_rate:
                          type: integer
                          example: 25
                        abandoned_rate:
                          type: integer
                          example: 25
                        recovered_rate:
                          type: integer
                          example: 25
      tags:
        - Reports
  /api/v1/store/reports/sources:
    get:
      summary: 'Sources - referer'
      operationId: sourcesReferer
      description: |-
        Returns order source domain performance for the selected period. Responses are capped
        at 1500 grouped rows.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: specific
          description: 'Optional partial domain filter. Responses are capped at 1500 grouped rows.'
          example: google
          required: false
          schema:
            type: string
            description: 'Optional partial domain filter. Responses are capped at 1500 grouped rows.'
            example: google
        -
          in: query
          name: segment
          description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
          example: 123
          required: false
          schema:
            type: integer
            description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
            example: 123
        -
          in: query
          name: order_filters
          description: 'Optional JSON-encoded array of order-level filters applied before calculating the report. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference). Cannot be combined with `segment`.'
          example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
          required: false
          schema:
            type: string
            description: 'Optional JSON-encoded array of order-level filters applied before calculating the report. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference). Cannot be combined with `segment`.'
            example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    report_link: 'https://app.metorik.com/reports/sources'
                  data:
                    -
                      domain: google.com
                      count: 82
                      total: 12450.5
                      total_refunds: 210
                      total_taxes: 1024.34
                      total_shipping: 531.2
                      total_fees: 88.4
                      average: 151.84
                      net: 11820.9
                      average_net: 144.16
                properties:
                  meta:
                    type: object
                    properties:
                      report_link:
                        type: string
                        example: 'https://app.metorik.com/reports/sources'
                  data:
                    type: array
                    example:
                      -
                        domain: google.com
                        count: 82
                        total: 12450.5
                        total_refunds: 210
                        total_taxes: 1024.34
                        total_shipping: 531.2
                        total_fees: 88.4
                        average: 151.84
                        net: 11820.9
                        average_net: 144.16
                    items:
                      type: object
                      properties:
                        domain:
                          type: string
                          example: google.com
                        count:
                          type: integer
                          example: 82
                        total:
                          type: number
                          example: 12450.5
                        total_refunds:
                          type: integer
                          example: 210
                        total_taxes:
                          type: number
                          example: 1024.34
                        total_shipping:
                          type: number
                          example: 531.2
                        total_fees:
                          type: number
                          example: 88.4
                        average:
                          type: number
                          example: 151.84
                        net:
                          type: number
                          example: 11820.9
                        average_net:
                          type: number
                          example: 144.16
      tags:
        - Reports
  /api/v1/store/reports/sources-landing:
    get:
      summary: 'Sources - landing'
      operationId: sourcesLanding
      description: |-
        Returns landing path performance for orders in the selected period. Responses are capped
        at 1500 grouped rows.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: segment
          description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
          example: 123
          required: false
          schema:
            type: integer
            description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
            example: 123
        -
          in: query
          name: order_filters
          description: 'Optional JSON-encoded array of order-level filters applied before calculating the report. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference). Cannot be combined with `segment`.'
          example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
          required: false
          schema:
            type: string
            description: 'Optional JSON-encoded array of order-level filters applied before calculating the report. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference). Cannot be combined with `segment`.'
            example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    report_link: 'https://app.metorik.com/reports/sources/landing'
                  data:
                    -
                      landing: /products/hoodie
                      count: 58
                      total: 8924.2
                      total_refunds: 120
                      total_taxes: 734.1
                      total_shipping: 402
                      total_fees: 61.8
                      average: 153.87
                      net: 8486.3
                      average_net: 146.32
                properties:
                  meta:
                    type: object
                    properties:
                      report_link:
                        type: string
                        example: 'https://app.metorik.com/reports/sources/landing'
                  data:
                    type: array
                    example:
                      -
                        landing: /products/hoodie
                        count: 58
                        total: 8924.2
                        total_refunds: 120
                        total_taxes: 734.1
                        total_shipping: 402
                        total_fees: 61.8
                        average: 153.87
                        net: 8486.3
                        average_net: 146.32
                    items:
                      type: object
                      properties:
                        landing:
                          type: string
                          example: /products/hoodie
                        count:
                          type: integer
                          example: 58
                        total:
                          type: number
                          example: 8924.2
                        total_refunds:
                          type: integer
                          example: 120
                        total_taxes:
                          type: number
                          example: 734.1
                        total_shipping:
                          type: integer
                          example: 402
                        total_fees:
                          type: number
                          example: 61.8
                        average:
                          type: number
                          example: 153.87
                        net:
                          type: number
                          example: 8486.3
                        average_net:
                          type: number
                          example: 146.32
      tags:
        - Reports
  /api/v1/store/reports/sources-utms:
    get:
      summary: 'Sources - UTM'
      operationId: sourcesUTM
      description: |-
        Returns grouped UTM performance for orders in the selected period. Responses are capped
        at 1500 grouped rows.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: source_type
          description: 'Comma-separated UTM fields to group by. Allowed: utm_campaign, utm_medium, utm_source, utm_term, utm_content, utm_id.'
          example: 'utm_source,utm_campaign'
          required: true
          schema:
            type: string
            description: 'Comma-separated UTM fields to group by. Allowed: utm_campaign, utm_medium, utm_source, utm_term, utm_content, utm_id.'
            example: 'utm_source,utm_campaign'
        -
          in: query
          name: segment
          description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
          example: 123
          required: false
          schema:
            type: integer
            description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
            example: 123
        -
          in: query
          name: order_filters
          description: 'Optional JSON-encoded array of order-level filters applied before calculating the report. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference). Cannot be combined with `segment`.'
          example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
          required: false
          schema:
            type: string
            description: 'Optional JSON-encoded array of order-level filters applied before calculating the report. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference). Cannot be combined with `segment`.'
            example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    report_link: 'https://app.metorik.com/reports/sources/utms'
                  data:
                    -
                      utm_source: google
                      utm_campaign: spring-sale
                      count: 29
                      total: 4310
                      total_refunds: 50
                      total_taxes: 357.44
                      total_shipping: 188
                      total_fees: 24.1
                      average: 148.62
                      net: 4038.46
                      average_net: 139.26
                      source_combined: google-spring-sale
                properties:
                  meta:
                    type: object
                    properties:
                      report_link:
                        type: string
                        example: 'https://app.metorik.com/reports/sources/utms'
                  data:
                    type: array
                    example:
                      -
                        utm_source: google
                        utm_campaign: spring-sale
                        count: 29
                        total: 4310
                        total_refunds: 50
                        total_taxes: 357.44
                        total_shipping: 188
                        total_fees: 24.1
                        average: 148.62
                        net: 4038.46
                        average_net: 139.26
                        source_combined: google-spring-sale
                    items:
                      type: object
                      properties:
                        utm_source:
                          type: string
                          example: google
                        utm_campaign:
                          type: string
                          example: spring-sale
                        count:
                          type: integer
                          example: 29
                        total:
                          type: integer
                          example: 4310
                        total_refunds:
                          type: integer
                          example: 50
                        total_taxes:
                          type: number
                          example: 357.44
                        total_shipping:
                          type: integer
                          example: 188
                        total_fees:
                          type: number
                          example: 24.1
                        average:
                          type: number
                          example: 148.62
                        net:
                          type: number
                          example: 4038.46
                        average_net:
                          type: number
                          example: 139.26
                        source_combined:
                          type: string
                          example: google-spring-sale
      tags:
        - Reports
  /api/v1/store/reports/customer-sources:
    get:
      summary: 'Customer sources - referer'
      operationId: customerSourcesReferer
      description: |-
        Returns customer acquisition source performance for the selected period. Responses are capped
        at 1500 grouped rows.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: segment
          description: 'Optional saved store-wide customer segment ID. You can find the ID on the [customer segments page](https://app.metorik.com/segments/customers).'
          example: 123
          required: false
          schema:
            type: integer
            description: 'Optional saved store-wide customer segment ID. You can find the ID on the [customer segments page](https://app.metorik.com/segments/customers).'
            example: 123
        -
          in: query
          name: customer_filters
          description: 'Optional JSON-encoded array of customer-level filters applied before calculating the report. See [Customer Filters Reference](#customers-GETapi-v1-store-customers-filters-reference). Cannot be combined with `segment`.'
          example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
          required: false
          schema:
            type: string
            description: 'Optional JSON-encoded array of customer-level filters applied before calculating the report. See [Customer Filters Reference](#customers-GETapi-v1-store-customers-filters-reference). Cannot be combined with `segment`.'
            example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    report_link: 'https://app.metorik.com/reports/customer-sources'
                  data:
                    -
                      domain: google.com
                      count: 82
                      returning_customers_count: 24
                      returning_customers_rate: 29.3
                      total_order_count: 146
                      average_order_count: 1.78
                      total_order_gross: 12450.5
                      average_customer_ltv: 151.84
                      total_item_count: 231
                properties:
                  meta:
                    type: object
                    properties:
                      report_link:
                        type: string
                        example: 'https://app.metorik.com/reports/customer-sources'
                  data:
                    type: array
                    example:
                      -
                        domain: google.com
                        count: 82
                        returning_customers_count: 24
                        returning_customers_rate: 29.3
                        total_order_count: 146
                        average_order_count: 1.78
                        total_order_gross: 12450.5
                        average_customer_ltv: 151.84
                        total_item_count: 231
                    items:
                      type: object
                      properties:
                        domain:
                          type: string
                          example: google.com
                        count:
                          type: integer
                          example: 82
                        returning_customers_count:
                          type: integer
                          example: 24
                        returning_customers_rate:
                          type: number
                          example: 29.3
                        total_order_count:
                          type: integer
                          example: 146
                        average_order_count:
                          type: number
                          example: 1.78
                        total_order_gross:
                          type: number
                          example: 12450.5
                        average_customer_ltv:
                          type: number
                          example: 151.84
                        total_item_count:
                          type: integer
                          example: 231
      tags:
        - Reports
  /api/v1/store/reports/customer-sources-landing:
    get:
      summary: 'Customer sources - landing'
      operationId: customerSourcesLanding
      description: |-
        Returns customer acquisition landing path performance for the selected period. Responses are capped
        at 1500 grouped rows.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: segment
          description: 'Optional saved store-wide customer segment ID. You can find the ID on the [customer segments page](https://app.metorik.com/segments/customers).'
          example: 123
          required: false
          schema:
            type: integer
            description: 'Optional saved store-wide customer segment ID. You can find the ID on the [customer segments page](https://app.metorik.com/segments/customers).'
            example: 123
        -
          in: query
          name: customer_filters
          description: 'Optional JSON-encoded array of customer-level filters applied before calculating the report. See [Customer Filters Reference](#customers-GETapi-v1-store-customers-filters-reference). Cannot be combined with `segment`.'
          example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
          required: false
          schema:
            type: string
            description: 'Optional JSON-encoded array of customer-level filters applied before calculating the report. See [Customer Filters Reference](#customers-GETapi-v1-store-customers-filters-reference). Cannot be combined with `segment`.'
            example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    report_link: 'https://app.metorik.com/reports/customer-sources/landing'
                  data:
                    -
                      landing: /products/hoodie
                      count: 58
                      returning_customers_count: 12
                      returning_customers_rate: 20.7
                      total_order_count: 95
                      average_order_count: 1.64
                      total_order_gross: 8924.2
                      average_customer_ltv: 153.87
                      total_item_count: 141
                properties:
                  meta:
                    type: object
                    properties:
                      report_link:
                        type: string
                        example: 'https://app.metorik.com/reports/customer-sources/landing'
                  data:
                    type: array
                    example:
                      -
                        landing: /products/hoodie
                        count: 58
                        returning_customers_count: 12
                        returning_customers_rate: 20.7
                        total_order_count: 95
                        average_order_count: 1.64
                        total_order_gross: 8924.2
                        average_customer_ltv: 153.87
                        total_item_count: 141
                    items:
                      type: object
                      properties:
                        landing:
                          type: string
                          example: /products/hoodie
                        count:
                          type: integer
                          example: 58
                        returning_customers_count:
                          type: integer
                          example: 12
                        returning_customers_rate:
                          type: number
                          example: 20.7
                        total_order_count:
                          type: integer
                          example: 95
                        average_order_count:
                          type: number
                          example: 1.64
                        total_order_gross:
                          type: number
                          example: 8924.2
                        average_customer_ltv:
                          type: number
                          example: 153.87
                        total_item_count:
                          type: integer
                          example: 141
      tags:
        - Reports
  /api/v1/store/reports/customer-sources-utms:
    get:
      summary: 'Customer sources - UTM'
      operationId: customerSourcesUTM
      description: |-
        Returns grouped customer acquisition UTM performance for the selected period. Responses are capped
        at 1500 grouped rows.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-03-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-03-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-03-31'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-03-31'
        -
          in: query
          name: source_type
          description: 'Comma-separated UTM fields to group by. Allowed: utm_campaign, utm_medium, utm_source, utm_term, utm_content, utm_id.'
          example: 'utm_source,utm_campaign'
          required: true
          schema:
            type: string
            description: 'Comma-separated UTM fields to group by. Allowed: utm_campaign, utm_medium, utm_source, utm_term, utm_content, utm_id.'
            example: 'utm_source,utm_campaign'
        -
          in: query
          name: segment
          description: 'Optional saved store-wide customer segment ID. You can find the ID on the [customer segments page](https://app.metorik.com/segments/customers).'
          example: 123
          required: false
          schema:
            type: integer
            description: 'Optional saved store-wide customer segment ID. You can find the ID on the [customer segments page](https://app.metorik.com/segments/customers).'
            example: 123
        -
          in: query
          name: customer_filters
          description: 'Optional JSON-encoded array of customer-level filters applied before calculating the report. See [Customer Filters Reference](#customers-GETapi-v1-store-customers-filters-reference). Cannot be combined with `segment`.'
          example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
          required: false
          schema:
            type: string
            description: 'Optional JSON-encoded array of customer-level filters applied before calculating the report. See [Customer Filters Reference](#customers-GETapi-v1-store-customers-filters-reference). Cannot be combined with `segment`.'
            example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    report_link: 'https://app.metorik.com/reports/customer-sources/utms'
                  data:
                    -
                      utm_source: google
                      utm_campaign: spring-sale
                      count: 29
                      returning_customers_count: 8
                      returning_customers_rate: 27.6
                      total_order_count: 51
                      average_order_count: 1.76
                      total_order_gross: 4310
                      average_customer_ltv: 148.62
                properties:
                  meta:
                    type: object
                    properties:
                      report_link:
                        type: string
                        example: 'https://app.metorik.com/reports/customer-sources/utms'
                  data:
                    type: array
                    example:
                      -
                        utm_source: google
                        utm_campaign: spring-sale
                        count: 29
                        returning_customers_count: 8
                        returning_customers_rate: 27.6
                        total_order_count: 51
                        average_order_count: 1.76
                        total_order_gross: 4310
                        average_customer_ltv: 148.62
                    items:
                      type: object
                      properties:
                        utm_source:
                          type: string
                          example: google
                        utm_campaign:
                          type: string
                          example: spring-sale
                        count:
                          type: integer
                          example: 29
                        returning_customers_count:
                          type: integer
                          example: 8
                        returning_customers_rate:
                          type: number
                          example: 27.6
                        total_order_count:
                          type: integer
                          example: 51
                        average_order_count:
                          type: number
                          example: 1.76
                        total_order_gross:
                          type: integer
                          example: 4310
                        average_customer_ltv:
                          type: number
                          example: 148.62
      tags:
        - Reports
  /api/v1/store/reports/orders-by-hour:
    get:
      summary: 'Orders by hour'
      operationId: ordersByHour
      description: 'Returns order counts and sales totals grouped by hour of day across the selected period.'
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: segment
          description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
          example: 123
          required: false
          schema:
            type: integer
            description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
            example: 123
        -
          in: query
          name: order_filters
          description: 'Optional JSON-encoded array of order-level filters applied before calculating the report. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference). Cannot be combined with `segment`.'
          example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
          required: false
          schema:
            type: string
            description: 'Optional JSON-encoded array of order-level filters applied before calculating the report. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference). Cannot be combined with `segment`.'
            example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    report_link: 'https://app.metorik.com/reports/orders'
                  totals:
                    orders: 82
                    total: 12450.5
                  data:
                    -
                      hour: 0
                      orders: 2
                      total: 150
                    -
                      hour: 14
                      orders: 5
                      total: 845.2
                properties:
                  meta:
                    type: object
                    properties:
                      report_link:
                        type: string
                        example: 'https://app.metorik.com/reports/orders'
                  totals:
                    type: object
                    properties:
                      orders:
                        type: integer
                        example: 82
                      total:
                        type: number
                        example: 12450.5
                  data:
                    type: array
                    example:
                      -
                        hour: 0
                        orders: 2
                        total: 150
                      -
                        hour: 14
                        orders: 5
                        total: 845.2
                    items:
                      type: object
                      properties:
                        hour:
                          type: integer
                          example: 0
                        orders:
                          type: integer
                          example: 2
                        total:
                          type: integer
                          example: 150
      tags:
        - Reports
  /api/v1/store/reports/orders-by-day:
    get:
      summary: 'Orders by day of week'
      operationId: ordersByDayOfWeek
      description: 'Returns order counts and sales totals grouped by weekday across the selected period.'
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: segment
          description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
          example: 123
          required: false
          schema:
            type: integer
            description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
            example: 123
        -
          in: query
          name: order_filters
          description: 'Optional JSON-encoded array of order-level filters applied before calculating the report. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference). Cannot be combined with `segment`.'
          example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
          required: false
          schema:
            type: string
            description: 'Optional JSON-encoded array of order-level filters applied before calculating the report. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference). Cannot be combined with `segment`.'
            example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    report_link: 'https://app.metorik.com/reports/orders'
                  totals:
                    orders: 82
                    total: 12450.5
                  data:
                    -
                      day: Monday
                      orders: 9
                      total: 1320.4
                    -
                      day: Tuesday
                      orders: 12
                      total: 1844.7
                properties:
                  meta:
                    type: object
                    properties:
                      report_link:
                        type: string
                        example: 'https://app.metorik.com/reports/orders'
                  totals:
                    type: object
                    properties:
                      orders:
                        type: integer
                        example: 82
                      total:
                        type: number
                        example: 12450.5
                  data:
                    type: array
                    example:
                      -
                        day: Monday
                        orders: 9
                        total: 1320.4
                      -
                        day: Tuesday
                        orders: 12
                        total: 1844.7
                    items:
                      type: object
                      properties:
                        day:
                          type: string
                          example: Monday
                        orders:
                          type: integer
                          example: 9
                        total:
                          type: number
                          example: 1320.4
      tags:
        - Reports
  /api/v1/store/reports/orders-by-day-hour:
    get:
      summary: 'Orders by day and hour'
      operationId: ordersByDayAndHour
      description: 'Returns order counts, totals, and average order value grouped by weekday and hour across the selected period.'
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: segment
          description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
          example: 123
          required: false
          schema:
            type: integer
            description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
            example: 123
        -
          in: query
          name: order_filters
          description: 'Optional JSON-encoded array of order-level filters applied before calculating the report. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference). Cannot be combined with `segment`.'
          example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
          required: false
          schema:
            type: string
            description: 'Optional JSON-encoded array of order-level filters applied before calculating the report. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference). Cannot be combined with `segment`.'
            example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    report_link: 'https://app.metorik.com/reports/orders'
                  totals:
                    orders: 82
                    total: 12450.5
                  data:
                    Monday:
                      -
                        hour: 0
                        orders: 1
                        total: 90
                        aov: 90
                    Tuesday:
                      -
                        hour: 14
                        orders: 2
                        total: 244.5
                        aov: 122.25
                properties:
                  meta:
                    type: object
                    properties:
                      report_link:
                        type: string
                        example: 'https://app.metorik.com/reports/orders'
                  totals:
                    type: object
                    properties:
                      orders:
                        type: integer
                        example: 82
                      total:
                        type: number
                        example: 12450.5
                  data:
                    type: object
                    properties:
                      Monday:
                        type: array
                        example:
                          -
                            hour: 0
                            orders: 1
                            total: 90
                            aov: 90
                        items:
                          type: object
                          properties:
                            hour:
                              type: integer
                              example: 0
                            orders:
                              type: integer
                              example: 1
                            total:
                              type: integer
                              example: 90
                            aov:
                              type: integer
                              example: 90
                      Tuesday:
                        type: array
                        example:
                          -
                            hour: 14
                            orders: 2
                            total: 244.5
                            aov: 122.25
                        items:
                          type: object
                          properties:
                            hour:
                              type: integer
                              example: 14
                            orders:
                              type: integer
                              example: 2
                            total:
                              type: number
                              example: 244.5
                            aov:
                              type: number
                              example: 122.25
      tags:
        - Reports
  /api/v1/store/reports/orders-devices:
    get:
      summary: 'Orders devices'
      operationId: ordersDevices
      description: 'Returns order counts and sales totals split by device category for the selected period.'
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: segment
          description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
          example: 123
          required: false
          schema:
            type: integer
            description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
            example: 123
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    report_link: 'https://app.metorik.com/reports/devices'
                    has_ga: false
                  totals:
                    count: 58
                    total: 8924.2
                  data:
                    -
                      name: desktop
                      count: 34
                      total: 5210.8
                    -
                      name: mobile
                      count: 24
                      total: 3713.4
                properties:
                  meta:
                    type: object
                    properties:
                      report_link:
                        type: string
                        example: 'https://app.metorik.com/reports/devices'
                      has_ga:
                        type: boolean
                        example: false
                  totals:
                    type: object
                    properties:
                      count:
                        type: integer
                        example: 58
                      total:
                        type: number
                        example: 8924.2
                  data:
                    type: array
                    example:
                      -
                        name: desktop
                        count: 34
                        total: 5210.8
                      -
                        name: mobile
                        count: 24
                        total: 3713.4
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          example: desktop
                        count:
                          type: integer
                          example: 34
                        total:
                          type: number
                          example: 5210.8
      tags:
        - Reports
  /api/v1/store/reports/orders-operating-systems:
    get:
      summary: 'Orders operating systems'
      operationId: ordersOperatingSystems
      description: 'Returns order counts and sales totals split by operating system for the selected period.'
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: segment
          description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
          example: 123
          required: false
          schema:
            type: integer
            description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
            example: 123
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    report_link: 'https://app.metorik.com/reports/devices'
                    has_ga: false
                  totals:
                    count: 63
                    total: 9541.7
                  data:
                    -
                      name: Windows
                      count: 28
                      total: 4388.9
                    -
                      name: iOS
                      count: 19
                      total: 2874.5
                properties:
                  meta:
                    type: object
                    properties:
                      report_link:
                        type: string
                        example: 'https://app.metorik.com/reports/devices'
                      has_ga:
                        type: boolean
                        example: false
                  totals:
                    type: object
                    properties:
                      count:
                        type: integer
                        example: 63
                      total:
                        type: number
                        example: 9541.7
                  data:
                    type: array
                    example:
                      -
                        name: Windows
                        count: 28
                        total: 4388.9
                      -
                        name: iOS
                        count: 19
                        total: 2874.5
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          example: Windows
                        count:
                          type: integer
                          example: 28
                        total:
                          type: number
                          example: 4388.9
      tags:
        - Reports
  /api/v1/store/reports/orders-browsers:
    get:
      summary: 'Orders browsers'
      operationId: ordersBrowsers
      description: 'Returns order counts and sales totals split by browser for the selected period.'
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: segment
          description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
          example: 123
          required: false
          schema:
            type: integer
            description: 'Optional saved store-wide order segment ID. You can find the ID on the [order segments page](https://app.metorik.com/segments/orders).'
            example: 123
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  meta:
                    report_link: 'https://app.metorik.com/reports/devices'
                    has_ga: false
                  totals:
                    count: 71
                    total: 11033.6
                  data:
                    -
                      name: Chrome
                      count: 31
                      total: 4899.1
                    -
                      name: Safari
                      count: 22
                      total: 3412.8
                properties:
                  meta:
                    type: object
                    properties:
                      report_link:
                        type: string
                        example: 'https://app.metorik.com/reports/devices'
                      has_ga:
                        type: boolean
                        example: false
                  totals:
                    type: object
                    properties:
                      count:
                        type: integer
                        example: 71
                      total:
                        type: number
                        example: 11033.6
                  data:
                    type: array
                    example:
                      -
                        name: Chrome
                        count: 31
                        total: 4899.1
                      -
                        name: Safari
                        count: 22
                        total: 3412.8
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          example: Chrome
                        count:
                          type: integer
                          example: 31
                        total:
                          type: number
                          example: 4899.1
      tags:
        - Reports
  /api/v1/store/reports/products-bought-together:
    get:
      summary: 'Products bought together'
      operationId: productsBoughtTogether
      description: |-
        Returns product pairs that were purchased together in the selected period.
        Use `product_id` to limit the response to pairs involving a specific product.
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Start date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-01'
          required: true
          schema:
            type: string
            description: 'Start date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-01'
        -
          in: query
          name: end_date
          description: 'End date in the store timezone using YYYY-MM-DD format.'
          example: '2026-02-28'
          required: true
          schema:
            type: string
            description: 'End date in the store timezone using YYYY-MM-DD format.'
            example: '2026-02-28'
        -
          in: query
          name: page
          description: 'Page number for pagination.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number for pagination.'
            example: 1
        -
          in: query
          name: per_page
          description: 'Number of pairs per page. Min 1, max 100.'
          example: 10
          required: false
          schema:
            type: integer
            description: 'Number of pairs per page. Min 1, max 100.'
            example: 10
        -
          in: query
          name: product_id
          description: 'Limit results to pairs involving this product.'
          example: 4821
          required: false
          schema:
            type: integer
            description: 'Limit results to pairs involving this product.'
            example: 4821
        -
          in: query
          name: variation_id
          description: 'Limit results to pairs involving this variation. Requires `product_id`.'
          example: 9912
          required: false
          schema:
            type: integer
            description: 'Limit results to pairs involving this variation. Requires `product_id`.'
            example: 9912
        -
          in: query
          name: order_filters
          description: 'Optional JSON-encoded array of order-level filters applied before calculating the report. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference).'
          example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
          required: false
          schema:
            type: string
            description: 'Optional JSON-encoded array of order-level filters applied before calculating the report. See [Order Filters Reference](#orders-GETapi-v1-store-orders-filters-reference).'
            example: '[{"field":"billing_address_country","operator":"eq","value":"US"}]'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      times_bought_together: 18
                      product_1:
                        product_id: 4821
                        variation_id: 0
                        title: 'Metorik Hoodie'
                        sku: MTK-HOODIE
                      product_2:
                        product_id: 5199
                        variation_id: 0
                        title: 'Metorik Cap'
                        sku: MTK-CAP
                  pagination:
                    current_page: 1
                    per_page: 10
                    has_more_pages: true
                properties:
                  data:
                    type: array
                    example:
                      -
                        times_bought_together: 18
                        product_1:
                          product_id: 4821
                          variation_id: 0
                          title: 'Metorik Hoodie'
                          sku: MTK-HOODIE
                        product_2:
                          product_id: 5199
                          variation_id: 0
                          title: 'Metorik Cap'
                          sku: MTK-CAP
                    items:
                      type: object
                      properties:
                        times_bought_together:
                          type: integer
                          example: 18
                        product_1:
                          type: object
                          properties:
                            product_id:
                              type: integer
                              example: 4821
                            variation_id:
                              type: integer
                              example: 0
                            title:
                              type: string
                              example: 'Metorik Hoodie'
                            sku:
                              type: string
                              example: MTK-HOODIE
                        product_2:
                          type: object
                          properties:
                            product_id:
                              type: integer
                              example: 5199
                            variation_id:
                              type: integer
                              example: 0
                            title:
                              type: string
                              example: 'Metorik Cap'
                            sku:
                              type: string
                              example: MTK-CAP
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 10
                      has_more_pages:
                        type: boolean
                        example: true
      tags:
        - Reports
  /api/v1/store/engage/profile:
    get:
      summary: 'Get a profile by email'
      operationId: getAProfileByEmail
      description: 'Get a Metorik Engage profile by email for a store.'
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: email
          description: 'Email address for the profile.'
          example: kendall@waystarroyco.com
          required: true
          schema:
            type: string
            description: 'Email address for the profile.'
            example: kendall@waystarroyco.com
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  profile:
                    email: kendall@waystarroyco.com
                    first_name: Kendall
                    last_name: Roy
                    country: US
                    company: 'Waystar Royco'
                    consent: double
                    tags:
                      - VIP
                      - Wholesale
                    created_at: '2026-03-26 12:00:00'
                    updated_at: '2026-03-26 12:00:00'
                properties:
                  profile:
                    type: object
                    properties:
                      email:
                        type: string
                        example: kendall@waystarroyco.com
                      first_name:
                        type: string
                        example: Kendall
                      last_name:
                        type: string
                        example: Roy
                      country:
                        type: string
                        example: US
                      company:
                        type: string
                        example: 'Waystar Royco'
                      consent:
                        type: string
                        example: double
                      tags:
                        type: array
                        example:
                          - VIP
                          - Wholesale
                        items:
                          type: string
                      created_at:
                        type: string
                        example: '2026-03-26 12:00:00'
                      updated_at:
                        type: string
                        example: '2026-03-26 12:00:00'
        403:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example: {  }
                properties: {  }
        404:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: error
                  message: 'Profile not found.'
                properties:
                  status:
                    type: string
                    example: error
                  message:
                    type: string
                    example: 'Profile not found.'
        422:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: error
                  message: 'Invalid email address.'
                properties:
                  status:
                    type: string
                    example: error
                  message:
                    type: string
                    example: 'Invalid email address.'
      tags:
        - 'Engage > Profiles'
  /api/v1/store/engage/profiles:
    post:
      summary: 'Create or update a profile'
      operationId: createOrUpdateAProfile
      description: 'Create or update a Metorik-only Engage profile for a store.'
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  profile:
                    email: kendall@waystarroyco.com
                    first_name: Kendall
                    last_name: Roy
                    country: US
                    company: 'Waystar Royco'
                    consent: double
                    tags:
                      - VIP
                      - Wholesale
                    created_at: '2026-03-26 12:00:00'
                    updated_at: '2026-03-26 12:00:00'
                properties:
                  profile:
                    type: object
                    properties:
                      email:
                        type: string
                        example: kendall@waystarroyco.com
                      first_name:
                        type: string
                        example: Kendall
                      last_name:
                        type: string
                        example: Roy
                      country:
                        type: string
                        example: US
                      company:
                        type: string
                        example: 'Waystar Royco'
                      consent:
                        type: string
                        example: double
                      tags:
                        type: array
                        example:
                          - VIP
                          - Wholesale
                        items:
                          type: string
                      created_at:
                        type: string
                        example: '2026-03-26 12:00:00'
                      updated_at:
                        type: string
                        example: '2026-03-26 12:00:00'
        403:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example: {  }
                properties: {  }
        422:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: error
                  message: 'Invalid email address.'
                properties:
                  status:
                    type: string
                    example: error
                  message:
                    type: string
                    example: 'Invalid email address.'
      tags:
        - 'Engage > Profiles'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: 'Email address for the profile.'
                  example: kendall@waystarroyco.com
                first_name:
                  type: string
                  description: 'First name for the profile.'
                  example: Kendall
                last_name:
                  type: string
                  description: 'Last name for the profile.'
                  example: Roy
                country:
                  type: string
                  description: 'Two-letter country code for the billing country.'
                  example: US
                company:
                  type: string
                  description: 'Company name for the profile.'
                  example: 'Waystar Royco'
                consent:
                  type: string
                  description: 'Consent level to apply.'
                  example: double
                  enum:
                    - single
                    - double
                tags:
                  type: array|string
                  description: 'Tags to set on the profile as either an array of tags or a comma-separated string. When sent, tags replace the existing set.'
                  example: '["VIP", "Wholesale"]'
                add_tags:
                  type: array|string
                  description: 'Tags to add to the profile as either an array of tags or a comma-separated string. Tags are only added if they do not already exist.'
                  example: '["VIP", "Wholesale"]'
                remove_tags:
                  type: array|string
                  description: 'Tags to remove from the profile as either an array of tags or a comma-separated string. Tags are only removed if they currently exist.'
                  example: '["Wholesale"]'
              required:
                - email
    delete:
      summary: 'Delete a profile'
      operationId: deleteAProfile
      description: 'Delete a Metorik-only Engage profile with no orders.'
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  profile_deleted: true
                properties:
                  profile_deleted:
                    type: boolean
                    example: true
        403:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example: {  }
                properties: {  }
        404:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: error
                  message: 'Profile not found.'
                properties:
                  status:
                    type: string
                    example: error
                  message:
                    type: string
                    example: 'Profile not found.'
        422:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: error
                  message: 'Invalid email address.'
                properties:
                  status:
                    type: string
                    example: error
                  message:
                    type: string
                    example: 'Invalid email address.'
      tags:
        - 'Engage > Profiles'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: 'Email address for the profile to delete.'
                  example: kendall@waystarroyco.com
              required:
                - email
  /api/v1/store/engage/unsubscribes:
    get:
      summary: 'List unsubscribes'
      operationId: listUnsubscribes
      description: 'List unsubscribes for a store.'
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: start_date
          description: 'Only return unsubscribes created on or after this datetime. Legacy `after` also works, but is deprecated.'
          example: '2026-03-01 00:00:00'
          required: false
          schema:
            type: string
            description: 'Only return unsubscribes created on or after this datetime. Legacy `after` also works, but is deprecated.'
            example: '2026-03-01 00:00:00'
        -
          in: query
          name: end_date
          description: 'Only return unsubscribes created on or before this datetime. Legacy `before` also works, but is deprecated.'
          example: '2026-03-31 23:59:59'
          required: false
          schema:
            type: string
            description: 'Only return unsubscribes created on or before this datetime. Legacy `before` also works, but is deprecated.'
            example: '2026-03-31 23:59:59'
        -
          in: query
          name: order
          description: 'Sort direction by created date.'
          example: desc
          required: false
          schema:
            type: string
            description: 'Sort direction by created date.'
            example: desc
            enum:
              - asc
              - desc
        -
          in: query
          name: per_page
          description: 'Number of results per page.'
          example: 100
          required: false
          schema:
            type: integer
            description: 'Number of results per page.'
            example: 100
        -
          in: query
          name: page
          description: 'Page number to fetch.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number to fetch.'
            example: 1
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  unsubscribes:
                    current_page: 1
                    data:
                      -
                        email: unsubscribe@example.com
                        created_at: '2026-03-26T12:00:00.000000Z'
                        updated_at: '2026-03-26T12:00:00.000000Z'
                        automation_id: null
                        reason: 'No longer interested'
                    first_page_url: 'https://metorik-app.test/api/v1/store/engage/unsubscribes?page=1'
                    from: 1
                    next_page_url: null
                    path: 'https://metorik-app.test/api/v1/store/engage/unsubscribes'
                    per_page: 100
                    prev_page_url: null
                    to: 1
                properties:
                  unsubscribes:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      data:
                        type: array
                        example:
                          -
                            email: unsubscribe@example.com
                            created_at: '2026-03-26T12:00:00.000000Z'
                            updated_at: '2026-03-26T12:00:00.000000Z'
                            automation_id: null
                            reason: 'No longer interested'
                        items:
                          type: object
                          properties:
                            email:
                              type: string
                              example: unsubscribe@example.com
                            created_at:
                              type: string
                              example: '2026-03-26T12:00:00.000000Z'
                            updated_at:
                              type: string
                              example: '2026-03-26T12:00:00.000000Z'
                            automation_id:
                              type: string
                              example: null
                              nullable: true
                            reason:
                              type: string
                              example: 'No longer interested'
                      first_page_url:
                        type: string
                        example: 'https://metorik-app.test/api/v1/store/engage/unsubscribes?page=1'
                      from:
                        type: integer
                        example: 1
                      next_page_url:
                        type: string
                        example: null
                        nullable: true
                      path:
                        type: string
                        example: 'https://metorik-app.test/api/v1/store/engage/unsubscribes'
                      per_page:
                        type: integer
                        example: 100
                      prev_page_url:
                        type: string
                        example: null
                        nullable: true
                      to:
                        type: integer
                        example: 1
        400:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  error: 'Invalid date format for "start_date" parameter.'
                properties:
                  error:
                    type: string
                    example: 'Invalid date format for "start_date" parameter.'
        403:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example: {  }
                properties: {  }
      tags:
        - 'Engage > Unsubscribes'
    post:
      summary: 'Create or update an unsubscribe'
      operationId: createOrUpdateAnUnsubscribe
      description: 'Create or update an unsubscribe record for an email address.'
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  unsubscribe:
                    email: unsubscribe@example.com
                    created_at: '2026-03-26T12:00:00.000000Z'
                    updated_at: '2026-03-26T12:00:00.000000Z'
                    automation_id: null
                    reason: 'Customer opted out from checkout.'
                properties:
                  unsubscribe:
                    type: object
                    properties:
                      email:
                        type: string
                        example: unsubscribe@example.com
                      created_at:
                        type: string
                        example: '2026-03-26T12:00:00.000000Z'
                      updated_at:
                        type: string
                        example: '2026-03-26T12:00:00.000000Z'
                      automation_id:
                        type: string
                        example: null
                        nullable: true
                      reason:
                        type: string
                        example: 'Customer opted out from checkout.'
        400:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example: {  }
                properties: {  }
        403:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example: {  }
                properties: {  }
      tags:
        - 'Engage > Unsubscribes'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: 'Email address to unsubscribe.'
                  example: unsubscribe@example.com
                reason:
                  type: string
                  description: 'Reason the email address was unsubscribed.'
                  example: 'Customer opted out from checkout.'
              required:
                - email
    delete:
      summary: 'Delete an unsubscribe'
      operationId: deleteAnUnsubscribe
      description: 'Delete an unsubscribe record for an email address.'
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  unsubscribe_deleted: true
                properties:
                  unsubscribe_deleted:
                    type: boolean
                    example: true
        400:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example: {  }
                properties: {  }
        403:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example: {  }
                properties: {  }
        404:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example: {  }
                properties: {  }
      tags:
        - 'Engage > Unsubscribes'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: 'Email address to re-subscribe.'
                  example: unsubscribe@example.com
              required:
                - email
  /api/v1/store/engage/unsubscribe-status:
    get:
      summary: 'Check unsubscribe status'
      operationId: checkUnsubscribeStatus
      description: 'Check whether an email address is unsubscribed.'
      parameters:
        -
          in: header
          name: Accept
          description: 'Response format header.'
          required: true
          schema:
            type: string
            default: application/json
            example: application/json
        -
          in: query
          name: email
          description: 'Email address to check.'
          example: unsubscribe@example.com
          required: true
          schema:
            type: string
            description: 'Email address to check.'
            example: unsubscribe@example.com
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  unsubscribed: true
                properties:
                  unsubscribed:
                    type: boolean
                    example: true
        400:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example: {  }
                properties: {  }
        403:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example: {  }
                properties: {  }
      tags:
        - 'Engage > Unsubscribes'
