Commerce Layer returns API

openapi: 3.1.0
info:
  title: Commerce Layer addresses returns API
  version: 7.10.1
  contact:
    name: API Support
    url: https://commercelayer.io
    email: support@commercelayer.io
  description: Headless Commerce for Global Brands.
servers:
- url: https://{your_organization_slug}.commercelayer.io/api
  description: API
- url: https://core.commercelayer.io/users/sign_in
  description: Sign in
- url: https://docs.commercelayer.io/api
  description: API reference
security:
- bearerAuth: []
tags:
- name: returns
  description: resource type
paths:
  /captures/{captureId}/return:
    get:
      operationId: GET/captureId/return
      summary: Retrieve the return associated to the capture
      description: Retrieve the return associated to the capture
      tags:
      - returns
      parameters:
      - name: captureId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The return associated to the capture
  /customers/{customerId}/returns:
    get:
      operationId: GET/customerId/returns
      summary: Retrieve the returns associated to the customer
      description: Retrieve the returns associated to the customer
      tags:
      - returns
      parameters:
      - name: customerId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The returns associated to the customer
  /orders/{orderId}/returns:
    get:
      operationId: GET/orderId/returns
      summary: Retrieve the returns associated to the order
      description: Retrieve the returns associated to the order
      tags:
      - returns
      parameters:
      - name: orderId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The returns associated to the order
  /refunds/{refundId}/return:
    get:
      operationId: GET/refundId/return
      summary: Retrieve the return associated to the refund
      description: Retrieve the return associated to the refund
      tags:
      - returns
      parameters:
      - name: refundId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The return associated to the refund
  /return_line_items/{returnLineItemId}/return:
    get:
      operationId: GET/returnLineItemId/return
      summary: Retrieve the return associated to the return line item
      description: Retrieve the return associated to the return line item
      tags:
      - returns
      parameters:
      - name: returnLineItemId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The return associated to the return line item
  /returns:
    get:
      operationId: GET/returns
      summary: List all returns
      description: List all returns
      tags:
      - returns
      responses:
        '200':
          description: A list of return objects
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/returnResponseList'
    post:
      operationId: POST/returns
      summary: Create a return
      description: Create a return
      tags:
      - returns
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/returnCreate'
      responses:
        '201':
          description: The created return object
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/returnResponse'
  /returns/{returnId}:
    get:
      operationId: GET/returns/returnId
      summary: Retrieve a return
      description: Retrieve a return
      tags:
      - returns
      parameters:
      - name: returnId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The return object
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/returnResponse'
    patch:
      operationId: PATCH/returns/returnId
      summary: Update a return
      description: Update a return
      tags:
      - returns
      parameters:
      - name: returnId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/returnUpdate'
      responses:
        '200':
          description: The updated return object
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/returnResponse'
    delete:
      operationId: DELETE/returns/returnId
      summary: Delete a return
      description: Delete a return
      tags:
      - returns
      parameters:
      - name: returnId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '204':
          description: No content
  /returns/breakdown:
    post:
      operationId: POST/returns/breakdown
      summary: Query breakdown on returns
      description: "Breakdowns are aggregations that summarize your data as metrics (based on specific operators) or statistics, computed on field values. When performing a breakdown query on the Metrics API endpoint you get in the response the value of the computation (based on the selected operator) on the selected field, aggregated by another field.\r\n\r\n### Nesting breakdowns\r\nBreakdowns can be nested recursively one into the other, up to one level (see example). The valid values allowed for the by key of the nested breakdown are strictly dependent on the value you specified in the by key of the parent breakdown. Hence, they are different for each resource you’re doing statistics on (see orders, returns, and carts for the related lists).You cannot group the nested breakdown by the same field by which you’re already grouping the parent breakdown.\r\n\r\nSingle breakdown request\r\n\r\n`{\r\n\t\"breakdown\": {\r\n\t  \"by\": \"organization.id\",\r\n     \"field\": \"order.id\",\r\n     \"operator\": \"value_count\",\r\n     \"sort\": \"desc\",\r\n     \"limit\": 5\r\n\t}\r\n}`\r\n  \r\n  \r\n Nested breakdown request\r\n \r\n` {\r\n\t\"breakdown\": {\r\n        \"by\": \"organization.id\",\r\n        \"field\": \"order.id\",\r\n        \"operator\": \"value_count\",\r\n        \"sort\": \"desc\",\r\n        \"limit\": 5,\r\n        \"breakdown\": {\r\n            \"by\": \"line_items.name\",\r\n            \"field\": \"line_items.id\",\r\n            \"operator\": \"value_count\",\r\n            \"sort\": \"desc\",\r\n            \"limit\": 20\r\n        }\r\n    }\r\n  }`"
      tags:
      - returns
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/returns_breakdown_request'
      responses:
        '200':
          description: The breakdown result from returns
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    oneOf:
                    - type: object
                      properties:
                        customer.email:
                          type: array
                          items:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                oneOf:
                                - type: number
                                  example: 8
                                - type: string
                                - type: object
                                  properties:
                                    count:
                                      type: number
                                      example: 8
                                    min:
                                      type: number
                                      example: 8
                                    max:
                                      type: number
                                      example: 8
                                    avg:
                                      type: number
                                      example: 8
                                    sum:
                                      type: number
                                      example: 8
                            additionalProperties:
                              type: object
                              properties:
                                label:
                                  type: string
                                value:
                                  oneOf:
                                  - type: number
                                    example: 8
                                  - type: string
                                  - type: object
                                    properties:
                                      count:
                                        type: number
                                        example: 8
                                      min:
                                        type: number
                                        example: 8
                                      max:
                                        type: number
                                        example: 8
                                      avg:
                                        type: number
                                        example: 8
                                      sum:
                                        type: number
                                        example: 8
                    - type: object
                      properties:
                        customer.group_name:
                          type: array
                          items:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                oneOf:
                                - type: number
                                  example: 8
                                - type: string
                                - type: object
                                  properties:
                                    count:
                                      type: number
                                      example: 8
                                    min:
                                      type: number
                                      example: 8
                                    max:
                                      type: number
                                      example: 8
                                    avg:
                                      type: number
                                      example: 8
                                    sum:
                                      type: number
                                      example: 8
                            additionalProperties:
                              type: object
                              properties:
                                label:
                                  type: string
                                value:
                                  oneOf:
                                  - type: number
                                    example: 8
                                  - type: string
                                  - type: object
                                    properties:
                                      count:
                                        type: number
                                        example: 8
                                      min:
                                        type: number
                                        example: 8
                                      max:
                                        type: number
                                        example: 8
                                      avg:
                                        type: number
                                        example: 8
                                      sum:
                                        type: number
                                        example: 8
                    - type: object
                      properties:
                        destination_address.business:
                          type: array
                          items:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                oneOf:
                                - type: number
                                  example: 8
                                - type: string
                                - type: object
                                  properties:
                                    count:
                                      type: number
                                      example: 8
                                    min:
                                      type: number
                                      example: 8
                                    max:
                                      type: number
                                      example: 8
                                    avg:
                                      type: number
                                      example: 8
                                    sum:
                                      type: number
                                      example: 8
                            additionalProperties:
                              type: object
                              properties:
                                label:
                                  type: string
                                value:
                                  oneOf:
                                  - type: number
                                    example: 8
                                  - type: string
                                  - type: object
                                    properties:
                                      count:
                                        type: number
                                        example: 8
                                      min:
                                        type: number
                                        example: 8
                                      max:
                                        type: number
                                        example: 8
                                      avg:
                                        type: number
                                        example: 8
                                      sum:
                                        type: number
                                        example: 8
                    - type: object
                      properties:
                        destination_address.city:
                          type: array
                          items:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                oneOf:
                                - type: number
                                  example: 8
                                - type: string
                                - type: object
                                  properties:
                                    count:
                                      type: number
                                      example: 8
                                    min:
                                      type: number
                                      example: 8
                                    max:
                                      type: number
                                      example: 8
                                    avg:
                                      type: number
                                      example: 8
                                    sum:
                                      type: number
                                      example: 8
                            additionalProperties:
                              type: object
                              properties:
                                label:
                                  type: string
                                value:
                                  oneOf:
                                  - type: number
                                    example: 8
                                  - type: string
                                  - type: object
                                    properties:
                                      count:
                                        type: number
                                        example: 8
                                      min:
                                        type: number
                                        example: 8
                                      max:
                                        type: number
                                        example: 8
                                      avg:
                                        type: number
                                        example: 8
                                      sum:
                                        type: number
                                        example: 8
                    - type: object
                      properties:
                        destination_address.country_code:
                          type: array
                          items:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                oneOf:
                                - type: number
                                  example: 8
                                - type: string
                                - type: object
                                  properties:
                                    count:
                                      type: number
                                      example: 8
                                    min:
                                      type: number
                                      example: 8
                                    max:
                                      type: number
                                      example: 8
                                    avg:
                                      type: number
                                      example: 8
                                    sum:
                                      type: number
                                      example: 8
                            additionalProperties:
                              type: object
                              properties:
                                label:
                                  type: string
                                value:
                                  oneOf:
                                  - type: number
                                    example: 8
                                  - type: string
                                  - type: object
                                    properties:
                                      count:
                                        type: number
                                        example: 8
                                      min:
                                        type: number
                                        example: 8
                                      max:
                                        type: number
                                        example: 8
                                      avg:
                                        type: number
                                        example: 8
                                      sum:
                                        type: number
                                        example: 8
                    - type: object
                      properties:
                        destination_address.geocoded:
                          type: array
                          items:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                oneOf:
                                - type: number
                                  example: 8
                                - type: string
                                - type: object
                                  properties:
                                    count:
                                      type: number
                                      example: 8
                                    min:
                                      type: number
                                      example: 8
                                    max:
                                      type: number
                                      example: 8
                                    avg:
                                      type: number
                                      example: 8
                                    sum:
                                      type: number
                                      example: 8
                            additionalProperties:
                              type: object
                              properties:
                                label:
                                  type: string
                                value:
                                  oneOf:
                                  - type: number
                                    example: 8
                                  - type: string
                                  - type: object
                                    properties:
                                      count:
                                        type: number
                                        example: 8
                                      min:
                                        type: number
                                        example: 8
                                      max:
                                        type: number
                                        example: 8
                                      avg:
                                        type: number
                                        example: 8
                                      sum:
                                        type: number
                                        example: 8
                    - type: object
                      properties:
                        destination_address.localized:
                          type: array
                          items:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                oneOf:
                                - type: number
                                  example: 8
                                - type: string
                                - type: object
                                  properties:
                                    count:
                                      type: number
                                      example: 8
                                    min:
                                      type: number
                                      example: 8
                                    max:
                                      type: number
                                      example: 8
                                    avg:
                                      type: number
                                      example: 8
                                    sum:
                                      type: number
                                      example: 8
                            additionalProperties:
                              type: object
                              properties:
                                label:
                                  type: string
                                value:
                                  oneOf:
                                  - type: number
                                    example: 8
                                  - type: string
                                  - type: object
                                    properties:
                                      count:
                                        type: number
                                        example: 8
                                      min:
                                        type: number
                                        example: 8
                                      max:
                                        type: number
                                        example: 8
                                      avg:
                                        type: number
                                        example: 8
                                      sum:
                                        type: number
                                        example: 8
                    - type: object
                      properties:
                        destination_address.state_code:
                          type: array
                          items:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                oneOf:
                                - type: number
                                  example: 8
                                - type: string
                                - type: object
                                  properties:
                                    count:
                                      type: number
                                      example: 8
                                    min:
                                      type: number
                                      example: 8
                                    max:
                                      type: number
                                      example: 8
                                    avg:
                                      type: number
                                      example: 8
                                    sum:
                                      type: number
                                      example: 8
                            additionalProperties:
                              type: object
                              properties:
                                label:
                                  type: string
                                value:
                                  oneOf:
                                  - type: number
                                    example: 8
                                  - type: string
                                  - type: object
                                    properties:
                                      count:
                                        type: number
                                        example: 8
                                      min:
                                        type: number
                                        example: 8
                                      max:
                                        type: number
                                        example: 8
                                      avg:
                                        type: number
                                        example: 8
                                      sum:
                                        type: number
                                        example: 8
                    - type: object
                      properties:
                        destination_address.zip_code:
                          type: array
                          items:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                oneOf:
                                - type: number
                                  example: 8
                                - type: string
                                - type: object
                                  properties:
                                    count:
                                      type: number
                                      example: 8
                                    min:
                                      type: number
                                      example: 8
                                    max:
                                      type: number
                                      example: 8
                                    avg:
                                      type: number
                                      example: 8
                                    sum:
                                      type: number
                                      example: 8
                            additionalProperties:
                              type: object
                              properties:
                                label:
                                  type: string
                                value:
                                  oneOf:
                                  - type: number
                                    example: 8
                                  - type: string
                                  - type: object
                                    properties:
                                      count:
                                        type: number
                                        example: 8
                                      min:
                                        type: number
                                        example: 8
                                      max:
                                        type: number
                                        example: 8
                                      avg:
                                        type: number
                                        example: 8
                                      sum:
                                        type: number
                                        example: 8
                    - type: object
                      properties:
                        origin_address.business:
                          type: array
                          items:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                oneOf:
                                - type: number
                                  example: 8
                                - type: string
                                - type: object
                                  properties:
                                    count:
                                      type: number
                                      example: 8
                                    min:
                                      type: number
                                      example: 8
                                    max:
                                      type: number
                                      example: 8
                                    avg:
                       

# --- truncated at 32 KB (332 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/commerce-layer/refs/heads/main/openapi/commerce-layer-returns-api-openapi.yml