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

# Retrieve sales-by-period performance

> Retrieve aggregated GMV, traffic, and advertising metrics for a merchant over the selected date range, grouped by the requested interval.



## OpenAPI

````yaml /api-reference/openapi.json post /reports/view/salesByPeriod
openapi: 3.0.1
info:
  title: MerchantSpring Public API
  version: 1.0.0
servers:
  - url: https://mm-api.merchantspring.io
    description: Production
  - url: https://mm-api-staging.merchantspring.io
    description: Staging
security: []
tags:
  - name: channel
    x-group: Channel
  - name: content-change
    x-group: Content Change
  - name: custom-group
    x-group: Custom Group
  - name: order
    x-group: Order
  - name: report
    x-group: Report
  - name: tag
    x-group: Tag
  - name: profitability
    x-group: Profitability
paths:
  /reports/view/salesByPeriod:
    post:
      tags:
        - report
      summary: Retrieve sales-by-period performance
      description: >-
        Retrieve aggregated GMV, traffic, and advertising metrics for a merchant
        over the selected date range, grouped by the requested interval.
      operationId: getSalesByPeriodReport
      requestBody:
        description: >-
          Report filters that identify the merchant, time range, and marketplace
          scope to evaluate.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SalesByPeriodRequest'
      responses:
        '200':
          description: Aggregated performance data grouped to match the requested interval.
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalesByPeriodSuccessResponse'
        '400':
          description: Missing or invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalesByPeriodErrorResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalesByPeriodErrorResponse'
      security:
        - api_key: []
components:
  schemas:
    SalesByPeriodRequest:
      type: object
      description: Payload used to request the sales-by-period view report.
      properties:
        merchantId:
          type: string
          description: >-
            MerchantSpring merchant identifier for the account whose performance
            should be returned.
        channelId:
          type: string
          description: >-
            MerchantSpring channel identifier for the account whose performance
            should be returned.
        reportOptions:
          allOf:
            - $ref: '#/components/schemas/SalesByPeriodReportOptions'
          description: >-
            Defines the reporting window and comparison period that should be
            analysed.
        includeTax:
          type: boolean
          description: >-
            True by default. When true, gross sales figures include tax; when
            false, results are reported net of tax.
        sellerSkus:
          type: array
          description: >-
            Optional list of seller SKUs to restrict the dataset to specific
            products.
          items:
            type: string
      required:
        - merchantId
        - channelId
        - reportOptions
    SalesByPeriodSuccessResponse:
      type: object
      description: Successful response returned by the sales-by-period report endpoint.
      properties:
        status:
          type: string
          enum:
            - success
          description: Indicates that the request completed successfully.
        currency:
          type: string
          description: Currency code associated with the returned metrics.
        formattedChartData:
          type: array
          description: >-
            Display-ready metrics including formatted strings and comparison
            values for each interval.
          items:
            $ref: '#/components/schemas/FormattedSalesByPeriodChartData'
      required:
        - status
        - currency
        - chartData
        - formattedChartData
    SalesByPeriodErrorResponse:
      type: object
      description: >-
        Error payload returned when the sales-by-period request cannot be
        processed.
      properties:
        status:
          type: string
          enum:
            - error
          description: Identifies the response as an error.
        error:
          type: string
          description: Human-readable explanation of what went wrong.
      required:
        - status
        - error
    SalesByPeriodReportOptions:
      allOf:
        - $ref: '#/components/schemas/CommonReportOptions'
        - type: object
          description: >-
            Defines the principal and comparison date windows for the report and
            how results should be bucketed.
          properties:
            interval:
              type: string
              enum:
                - 'y'
                - Q
                - M
                - w
                - d
                - h
              description: >-
                Interval code that controls how results are bucketed (y=year,
                Q=quarter, M=month, w=week, d=day, h=hour).
          required:
            - fromDate
            - toDate
            - priorFromDate
            - priorToDate
            - timezone
            - interval
    FormattedSalesByPeriodChartData:
      type: object
      description: >-
        Human-readable metrics pre-formatted using the requested currency and
        timezone.
      properties:
        startTime:
          type: string
          description: >-
            Formatted start timestamp for the time bucket (respecting the
            requested interval and timezone).
        endTime:
          type: string
          description: >-
            Formatted end timestamp for the time bucket (respecting the
            requested interval and timezone).
        sales:
          type: string
          description: >-
            Current-period gross merchandise value formatted in the requested
            currency.
        priorSales:
          type: string
          description: >-
            Prior-period gross merchandise value formatted in the requested
            currency.
        unitsSold:
          type: integer
          format: int32
          description: Units sold during the current period.
        priorUnitsSold:
          type: integer
          format: int32
          description: Units sold during the comparison period.
        lineItemCount:
          type: integer
          format: int32
          description: Order line items recorded in the current period.
        priorLineItemCount:
          type: integer
          format: int32
          description: Order line items recorded in the comparison period.
        avgLineItemValue:
          type: string
          description: >-
            Average value per order line item in the current period, formatted
            in the requested currency.
        priorAvgLineItemValue:
          type: string
          description: >-
            Average value per order line item in the comparison period,
            formatted in the requested currency.
        pageViews:
          type: integer
          format: int32
          description: Product detail page views during the current period.
        priorPageViews:
          type: integer
          format: int32
          description: Product detail page views during the comparison period.
        pageViewsConversions:
          type: string
          description: Current-period units per view ratio formatted to one decimal place.
        priorPageViewsConversions:
          type: string
          description: >-
            Comparison-period units per view ratio formatted to one decimal
            place.
        totalSessions:
          type: integer
          format: int32
          description: Shopping sessions during the current period.
        priorTotalSessions:
          type: integer
          format: int32
          description: Shopping sessions during the comparison period.
        sessionConversions:
          type: string
          description: >-
            Current-period units per session ratio formatted to one decimal
            place.
        priorSessionConversions:
          type: string
          description: >-
            Comparison-period units per session ratio formatted to one decimal
            place.
        buyboxWinPercentage:
          type: string
          description: Current-period Buy Box win rate formatted to one decimal place.
        priorBuyboxWinPercentage:
          type: string
          description: Comparison-period Buy Box win rate formatted to one decimal place.
        adSpend:
          type: string
          description: >-
            Current-period advertising spend formatted in the requested
            currency.
        priorAdSpend:
          type: string
          description: >-
            Comparison-period advertising spend formatted in the requested
            currency.
        adSales:
          type: string
          description: >-
            Current-period attributed ad sales formatted in the requested
            currency.
        priorAdSales:
          type: string
          description: >-
            Comparison-period attributed ad sales formatted in the requested
            currency.
        impressions:
          type: integer
          format: int32
          description: Advertising impressions served during the current period.
        priorImpressions:
          type: integer
          format: int32
          description: Advertising impressions served during the comparison period.
        clickThroughRate:
          type: string
          description: Current-period ad click-through rate formatted to one decimal place.
        priorClickThroughRate:
          type: string
          description: >-
            Comparison-period ad click-through rate formatted to one decimal
            place.
        acos:
          type: string
          description: >-
            Current-period advertising cost of sales formatted to one decimal
            place.
        priorAcos:
          type: string
          description: >-
            Comparison-period advertising cost of sales formatted to one decimal
            place.
        tacos:
          type: string
          description: >-
            Current-period total advertising cost of sales formatted to one
            decimal place.
        priorTacos:
          type: string
          description: >-
            Comparison-period total advertising cost of sales formatted to one
            decimal place.
        currency:
          type: string
          description: Currency code used when formatting the monetary totals.
    CommonReportOptions:
      type: object
      properties:
        fromDate:
          type: number
          description: >-
            Unix epoch time (seconds) representing the start of the reporting
            period
        toDate:
          type: number
          description: >-
            Unix epoch time (seconds) representing the end of the reporting
            period
        priorFromDate:
          type: number
          description: >-
            Unix epoch time (seconds) representing the start of the comparison
            period
        priorToDate:
          type: number
          description: >-
            Unix epoch time (seconds) representing the end of the comparison
            period
        timezone:
          type: string
          description: >-
            The timezone string you wish to see the report in (e.g.
            'America/Los_Angeles') see
            https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header

````