Commerce Layer

Commerce Layer returns API

resource type

Documentation GitHub OpenAPI

Operations 10

GET /returns List all returns #

POST /returns Create a return #

GET /returns/{returnId} Retrieve a return #

PATCH /returns/{returnId} Update a return #

DELETE /returns/{returnId} Delete a return #

POST /returns/breakdown Query breakdown on returns #

POST /returns/date_breakdown Query date_breakdown on returns #

POST /returns/stats Query stats on returns #

POST /returns/search Query search on returns #

POST /returns/export Query export on returns #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/commerce-layer-returns-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no email required.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Commerce Layer Returns API
  contact:
    name: API Support
    url: https://commercelayer.io
    email: support@commercelayer.io
  version: '1.0'
  description: 'Operations tagged returns across 2 of this provider''s published API definitions: commerce-layer-core-api-openapi.json, commerce-layer-metrics-api-openapi.json. Each path carries the servers of the definition it was published in.'
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
- url: https://{your-domain}.commercelayer.io/metrics
  description: Commerce Layer Metrics API
- url: https://docs.commercelayer.io/metrics-api
  description: API reference
security:
- bearerAuth: []
tags:
- name: returns
  description: resource type
paths:
  /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'
    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
  /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
    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
  /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.\n\n### Nesting breakdowns\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.\n\nSingle breakdown request\n\n`{\n\t\"breakdown\": {\n\t  \"by\": \"organization.id\",\n     \"field\": \"order.id\",\n     \"operator\": \"value_count\",\n     \"sort\": \"desc\",\n     \"limit\": 5\n\t}\n}`\n  \n  \n Nested breakdown request\n \n` {\n\t\"breakdown\": {\n        \"by\": \"organization.id\",\n        \"field\": \"order.id\",\n        \"operator\": \"value_count\",\n        \"sort\": \"desc\",\n        \"limit\": 5,\n        \"breakdown\": {\n            \"by\": \"line_items.name\",\n            \"field\": \"line_items.id\",\n            \"operator\": \"value_count\",\n            \"sort\": \"desc\",\n            \"limit\": 20\n        }\n    }\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:
                                      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.city:
                          type: array
                          it

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

Commerce Layer returns API

Operations 10

Documentation

Specifications

Schemas & Data

Other Resources