🚧

Commerce: Refunds - Beta testing

Please note, this feature is in beta testing. We encourage you to provide any feedback you have on the product by selecting Submit idea here on our roadmap.

The Refunds endpoint retrieves the number and total value of refunds, and the refund rate for a specific company's commerce connection, over one or more periods of time.

Refer to the Assess reporting structure page for more detail on reports in Assess.

For Refunds, these are the dimensions and measures:

Dimensions

  • Period
  • Refund metrics

Measures

  • Count
  • Value
  • Percentage

Report Data

  • Is structured based on dimension (index =“0”), i.e. Period.
  • The endpoint will return the number of refunds, value of refunds and refund rate for each period.

View the Refunds formulas.

The endpoint is available in Swagger under Assess.

GET ​/data​/companies​/{companyId}​/connections​/{connectionId}​/assess​/commerceMetrics​/refunds

Parameters

Parameter

Type

Description

Required

reportDate

string
See Date

YYYY-MM-DD

Datetime or Date (inclusive of the whole day).

Required

periodUnit

string

The period unit of time returned, and it can be: “Day”, “Week”, “Month”, “Year”.

Required

periodLength

integer

Based on the period unit provided.

It must be positive, not zero and an integer.

Required

numberOfPeriods

integer

The number of periods to return.

It must be positive, not zero and an integer.

Required

includeDisplayNames

boolean

Shows the dimensionDisplayName and itemDisplayName in measures to make the report data human-readable.

Default is false.

Optional

Data model

The response structure is split into four areas: Report info, Dimensions, Measures and Report data.

Report info

Field

Type

Description

name

string

"refunds"

displayName

string

"Refunds"

Dimensions

Refunds consists of these dimensions: Period and Refund metrics.

Dimension (index = “0”): Period

Field

Type

Description

displayName

string

"Period"

type

string

"datespan"

items

array
See Dimension (index = “0”) items

Returns an array of “Period”. This is driven by the query parameter values.

Ordered by latest to earliest periods.

Dimension (index = “0”) items

Field

Type

Description

displayName

string

"Period n"

start

string
See Date

YYYY-MM-DD

Date in which the period begins (inclusive).

end

string
See Date

YYYY-MM-DD

Date in which the period ends (inclusive).

Dimension (index = “1”): Refund metrics

Field

Type

Description

displayName

string

"Refund metrics"

type

string

"string"

items

array
See Dimension (index = “1”) items

Returns an array of refund metrics.

Dimension (index = “1”) items

Field

Type

Description

value

string

  • “Number of refunds”
  • “Value of refunds”
  • "Refund rate"

These will always show for any response in this report. The dimension values are not dependent on the user’s query parameters.

Measures

Measures provide information about the measures contained in the report data.

The three measures for this report are as follows:

Index “0” - Count

Field

Type

Description

displayName

string

"Count"

type

number

"int"

Index “1” - Value

Field

Type

Description

displayName

string

“Value”

units

string

The base currency of the company’s commerce connection.

type

string

“currency”

Index “2” - Percentage

Field

Type

Description

displayName

string

“Percentage”

units

string

"%"

type

string

“percentage”

Report data

The report data combines multiple reporting dimensions and outputs the value of each combination. Each dimension reference is specified.

Since the report data is reflective of two dimensions and their measures, the tables below represent each component grouping.

Each object is grouped by dimension (index=“0”) which is the number of periods specified by the user in the query parameters.

Each period will be broken down into Refund metrics.

Components structure

Field

Type

Description

dimension

number

Index 1

dimensionDisplayName

string

Shows when includeDisplayNames is set to true.

item

number

itemDisplayName

string

Shows when includeDisplayNames is set to true.

measures

See Measures in components

All components have the structure described in the Measures in components data model below.

Measures in components

Index "0" - Count

Field

Type

Description

measureDisplayName

string

"Count"

value

number

Index “1” - Value

Field

Type

Description

measureDisplayName

string

“Value"

value

string

Index “2” - Refund rate

Field

Type

Description

measureDisplayName

string

“Percentage"

value

string

Example data

{
    "reportInfo": {
        "name": "refunds",
        "displayName": "Refunds"
    },
    "dimensions": [
        {
            "index": 0,
            "displayName": "Period",
            "type": "datespan",
            "items": [
                {
                    "index": 0,
                    "displayName": "Period 0",
                    "start": "2021-03-30",
                    "end": "2021-04-30"
                },
                {
                    "index": 1,
                    "displayName": "Period 1",
                    "start": "2021-04-30",
                    "end": "2021-05-31"
                }
            ]
        },
        {
            "index": 1,
            "displayName": "Refund metrics",
            "type": "string",
            "items": [
                {
                    "index": 0,
                    "value": "Number of refunds"
                },
                {
                    "index": 1,
                    "value": "Value of refunds"
                },
                {
                    "index": 2,
                    "value": "Refund rate"
                }
            ]
        }
    ],
    "measures": [
        {
            "displayName": "Count",
            "index": 0,
            "type": "int"
        },
        {
            "displayName": "Value",
            "units": "GBP",
            "index": 1,
            "type": "currency"
        },
        {
            "displayName": "Percentage",
            "units": "%",
            "index": 2,
            "type": "percentage"
        }
    ],
    "reportData": [
        {
            "dimension": 0,
            "dimensionDisplayName": "Period",
            "item": 0,
            "itemDisplayName": "Period 0",
            "components": [
                {
                    "dimension": 1,
                    "dimensionDisplayName": "Refund metrics",
                    "item": 0,
                    "itemDisplayName": "Number of refunds",
                    "measures": [
                        {
                            "index": 0,
                            "measureDisplayName": "Count",
                            "value": 6
                        }
                    ]
                },
                {
                    "dimension": 1,
                    "dimensionDisplayName": "Refund metrics",
                    "item": 1,
                    "itemDisplayName": "Value of refunds",
                    "measures": [
                        {
                            "index": 1,
                            "measureDisplayName": "Value",
                            "value": 131.92
                        }
                    ]
                },
                {
                    "dimension": 1,
                    "dimensionDisplayName": "Refund metrics",
                    "item": 2,
                    "itemDisplayName": "Refund rate",
                    "measures": [
                        {
                            "index": 2,
                            "measureDisplayName": "Percentage",
                            "value": 0.75
                        }
                    ]
                }
            ]
        },
        {
            "dimension": 0,
            "dimensionDisplayName": "Period",
            "item": 1,
            "itemDisplayName": "Period 1",
            "components": [
                {
                    "dimension": 1,
                    "dimensionDisplayName": "Refund metrics",
                    "item": 0,
                    "itemDisplayName": "Number of refunds",
                    "measures": [
                        {
                            "index": 0,
                            "measureDisplayName": "Count",
                            "value": 4
                        }
                    ]
                },
                {
                    "dimension": 1,
                    "dimensionDisplayName": "Refund metrics",
                    "item": 1,
                    "itemDisplayName": "Value of refunds",
                    "measures": [
                        {
                            "index": 1,
                            "measureDisplayName": "Value",
                            "value": 95.14
                        }
                    ]
                },
                {
                    "dimension": 1,
                    "dimensionDisplayName": "Refund metrics",
                    "item": 2,
                    "itemDisplayName": "Refund rate",
                    "measures": [
                        {
                            "index": 2,
                            "measureDisplayName": "Percentage",
                            "value": 0.40
                        }
                    ]
                }
            ]
        }
    ]
}

Did this page help you?