Examples

How to perform Metrics API queries on the return resource

Breakdown

Request

The following request performs a breakdown query on the return resource:

curl -g -X POST \
  'https://{{your_domain}}.commercelayer.io/metrics/returns/breakdown' \
  -H 'Accept: application/vnd.api.v1+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -d '{
    "breakdown": {
        "by": "organization.id",
        "field": "return.id",
        "operator": "value_count",
        "sort": "desc",
        "limit": 5,
        "breakdown": {
            "by": "market.id",
            "field": "customer.id",
            "operator": "value_count",
            "sort": "asc",
            "limit": 10
        }
    },
    "filter": {
        "return": {
            "date_from": "2021-05-30T00:00:00Z",
            "date_to": "2022-05-30T23:59:00Z",
            "date_field": "created_at"
        },
        "market": {
          "names": {
            "in": ["USA"]
          }
        }
    }
}'

Response

On success, the API responds with a 200 OK status code, returning the aggregated values in the data object and extra information in the meta object:

{
  "data": {
    "organization.id": [
      {
        "label": "jXbGbFKEBn",
        "value": 2,
        "market.id": [
          {
            "label": "AjRevhvqvo",
            "value": 2
          }
        ]
      },
      {
        "label": "JXgWZFlAZX",
        "value": 1,
        "market.id": [
          {
            "label": "AjRevhvqvo",
            "value": 1
          }
        ]
      },
      {
        "label": "mzRmbZFPyO",
        "value": 1,
        "market.id": [
          {
            "label": "AjRevhvqvo",
            "value": 1
          }
        ]
      }
    ]
  },
  "meta": {
    "type": "breakdown",
    "trace_id": "707f88e4-3584-48a0-96ad-d2e107edf3ef",
    "mode": "test",
    "organization_id": "mzRmbZFPyO",
    "market_ids": [
      "AjRevhvqvo",
      "dlQbPhqGro"
    ]
  }
}

Date breakdown

Request

The following request performs a date breakdown query on the return resource:

curl -g -X POST \
  'https://{{your_domain}}.commercelayer.io/metrics/returns/date_breakdown' \
  -H 'Accept: application/vnd.api.v1+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -d '{
    "date_breakdown": {
        "by": "return.shipped_at",
        "field": "return.skus_count",
        "interval": "year",
        "operator": "stats",
        "breakdown": {
            "by": "origin_address.country_code",
            "field": "origin_address.state_code",
            "operator": "value_count",
            "sort": "desc",
            "limit": 5
        }
    },
    "filter": {
        "return": {
            "date_from": "2021-01-01T00:00:00Z",
            "date_to": "2021-12-30T23:59:00Z"
        },
        "market": {
          "names": {
            "in": ["USA"]
          }
        }
    }
}'

Response

On success, the API responds with a 200 OK status code, returning the aggregated values over the selected time intervals in the data object and extra information in the meta object:

{
  "data": [
    {
      "date": "2021-01-01T00:00:00.000Z",
      "value": {
        "count": 2,
        "min": 1.0,
        "max": 1.0,
        "avg": 1.0,
        "sum": 2.0
      },
      "origin_address.country_code": [
        {
          "label": "IT",
          "value": 2
        }
      ]
    }
  ],
  "meta": {
    "type": "date_breakdown",
    "trace_id": "2e64b0bb-c3b4-47aa-a6c6-21e8fc478609",
    "mode": "test",
    "organization_id": "mzRmbZFPyO",
    "market_ids": [
      "AjRevhvqvo",
      "dlQbPhqGro"
    ]
  }
}

Stats

Request

The following request performs a stats query on the return resource:

curl -g -X POST \
  'https://{{your_domain}}.commercelayer.io/metrics/returns/stats' \
  -H 'Accept: application/vnd.api.v1+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -d '{
    "stats": {
        "field": "return_line_items.quantity",
        "operator": "stats"
    },
    "filter": {
        "return": {
            "date_from": "2021-01-01T00:00:00Z",
            "date_to": "2021-12-31T23:59:00Z"
        },
        "market": {
          "names": {
            "in": ["USA"]
          }
        }
    }
}'

Response

On success, the API responds with a 200 OK status code, returning the computed value in the data object and additional information in the meta object:

{
  "data": {
    "value": {
      "count": 0,
      "min": null,
      "max": null,
      "avg": null,
      "sum": 0.0
    }
  },
  "meta": {
    "type": "stats",
    "trace_id": "5af4be57-a3e4-4875-8f42-694996cb9984",
    "mode": "test",
    "organization_id": "mzRmbZFPyO",
    "market_ids": [
      "AjRevhvqvo",
      "dlQbPhqGro"
    ]
  }
}

Search

Request

The following request performs a search query on the return resource:

curl -g -X POST \
  'https://{{your_domain}}.commercelayer.io/metrics/returns/search' \
  -H 'Accept: application/vnd.api.v1+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -d '{
    "search": {
        "limit": 20,
        "sort": "asc",
        "sort_by": "return.created_at",
        "fields": ["return.id", "return.approved_at", "market.id", "return.status"]
        },
    "filter": {
        "return": {
            "date_from": "2022-01-01T18:36:01Z",
            "date_to": "2022-12-30T18:36:02Z"
        },
        "market": {
          "names": {
            "in": ["USA"]
          }
        }
    }
}'

Response

On success, the API responds with a 200 OK status code, returning the requested fields in the data object and additional information alongside pagination in the meta object:

{
  "data": [
    {
      "id": "nWYGQubnEr",
      "approved_at": "2022-01-11T18:31:37.305Z",
      "status": "received",
      "market": {
        "id": "AjRevhvqvo"
      }
    },
    {
      "id": "QZpXvupjZY",
      "approved_at": "2022-01-12T15:27:34.435Z",
      "status": "received",
      "market": {
        "id": "AjRevhvqvo"
      }
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 2,
      "cursor": null
    },
    "type": "search",
    "trace_id": "df13c031-f7ac-49e7-b182-606413bc9bd3",
    "mode": "test",
    "organization_id": "mzRmbZFPyO",
    "market_ids": [
      "AjRevhvqvo",
      "dlQbPhqGro"
    ]
  }
}