Explain a period total

GET

/periods/{period_id}/totals/{key}/explain

curl --request GET \
  --url https://api.europlaybook.com/v1/periods/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/totals/example/explain \
  --header 'Authorization: Bearer <token>'

• Production

Where a figure comes from: the pack line key (as in declared.lines of the totals) > the ledger entries behind it > products > the packaging lines used (own or inherited, with source and evidence count) + sales facts per month and channel. Recorded at the ledger build; closed periods keep it.

Authorizations

• BearerTokenAuth

Parameters

Path Parameters

period_id

required

Period Id

string format: uuid

key

required

Key

string

Responses

200

OK

Media typeapplication/json

ExplainTotalOut

object

period_id

required

Period Id

string format: uuid

period_status

required

Period Status

string

Allowed values: open review closed filed reopened

line

required

ExplainLineOut

object

key

required

Key

The pack line key, e.g. paper.household.

string

label

required

Label

The line’s label as the scheme calculator names it.

string

value

required

Value

The line’s value as a decimal string.

string

unit

required

Unit

string

Allowed values: kg units parcels

returns_netting

required

Returns Netting

Returns are netted in this scheme (negative entries).

boolean

entry_match

required

Entry Match

How entries were matched to the line: indexes (by the calculator) or material.

string

traced

required

Traced

Lineage was recorded at the build (false: built before; rebuild the period).

boolean

entries

required

Entries

Array<object>

ExplainEntryOut

object

id

required

Id

string format: uuid

kind

required

Kind

string

Allowed values: product packaging parcel_packaging adjustment

fact_kind

required

Fact Kind

string

Allowed values: sale return

product_id

Any of:

string

string format: uuid

null

null

sku

Any of:

string

string

null

null

packaging_item_id

Any of:

string

string format: uuid

null

null

packaging_item_name

Any of:

string

string

null

null

material

Any of:

string

string

null

null

household

required

Household

boolean

in_parcel

required

In Parcel

boolean

channel

Any of:

string

string

null

null

obligated_party

required

Obligated Party

string

exclusion

required

Exclusion

string

size_class

Any of:

string

string

null

null

quantity

required

Quantity

integer

mass_mg

required

Mass Mg

integer

parcels

required

Parcels

integer

packaging_line_ids

Packaging Line Ids

Packaging lines that fed this entry.

Array<string>

default:

sales

Sales

Sales facts per month that fed this entry.

Array<object>

default:

ExplainSalesOut

object

month

Any of:

string

string

null

null

channel

Any of:

string

string

null

null

fact_kind

required

Fact Kind

string

Allowed values: sale return

facts

required

Facts

Sales lines (facts) behind it.

integer

units

required

Units

Sales units behind it.

integer

parcel_facts

Parcel Facts

Parcel facts per month (parcel entries).

Array<object>

default:

ExplainParcelsOut

object

month

Any of:

string

string

null

null

facts

required

Facts

Parcel facts (monthly counts) behind it.

integer

parcels

required

Parcels

integer

parcel_profile_id

Any of:

string

string format: uuid

null

null

parcel_profile_name

Any of:

string

string

null

null

products

required

Products

Products behind the line, largest share first.

Array<object>

ExplainProductOut

object

product_id

required

Product Id

string format: uuid

sku

required

Sku

string

title

required

Title

string

group_id

Any of:

string

string format: uuid

null

null

group_name

Any of:

string

string

null

null

entries

required

Entries

Ledger entries of this product in the line.

integer

mass_mg

required

Mass Mg

This product’s share of the line, milligrams.

integer

packaging_lines

required

Packaging Lines

Array<object>

ExplainPackagingLineOut

object

line_id

required

Line Id

The packaging line that was used (as it was at the ledger build).

string format: uuid

layer

Layer

Sales, grouped or transport.

string

""

quantity

Any of:

string

string

null

null

valid_from

Any of:

string

string format: date

null

null

valid_to

Any of:

string

string format: date

null

null

inherited

required

Inherited

The line is the product group’s (the product had no own line).

boolean

group_id

Any of:

string

string format: uuid

null

null

group_name

Any of:

string

string

null

null

exists

required

Exists

The line still exists (false: deleted after the build).

boolean

item_id

Any of:

string

string format: uuid

null

null

item_name

Any of:

string

string

null

null

state

Any of:

string

string

null

null

source

Any of:

string

string

null

null

source_ref

Any of:

string

string

null

null

evidence_count

Evidence Count

Evidence files on the line and on its packaging item.

integer

0

sales

required

Sales

Sales behind this product’s share, per month/channel.

Array<object>

ExplainSalesOut

object

month

Any of:

string

string

null

null

channel

Any of:

string

string

null

null

fact_kind

required

Fact Kind

string

Allowed values: sale return

facts

required

Facts

Sales lines (facts) behind it.

integer

units

required

Units

Sales units behind it.

integer

parcels

Parcels

Parcel facts behind parcel packaging entries.

Array<object>

default:

ExplainParcelsOut

object

month

Any of:

string

string

null

null

facts

required

Facts

Parcel facts (monthly counts) behind it.

integer

parcels

required

Parcels

integer

parcel_profile_id

Any of:

string

string format: uuid

null

null

parcel_profile_name

Any of:

string

string

null

null

Example

{
  "period_status": "open",
  "line": {
    "key": "paper.household",
    "value": "27.580",
    "unit": "kg"
  },
  "entries": [
    {
      "kind": "product",
      "fact_kind": "sale",
      "packaging_line_ids": [],
      "sales": [],
      "parcel_facts": []
    }
  ],
  "products": [
    {
      "packaging_lines": [
        {
          "layer": "",
          "evidence_count": 0
        }
      ],
      "sales": [
        {
          "month": "2026-03",
          "fact_kind": "sale"
        }
      ]
    }
  ],
  "parcels": []
}

400

Bad Request

Media typeapplication/json

PublicErrorOut

object

detail

required

Detail

What went wrong, in English, for people and logs.

string

code

required

Code

Stable machine-readable error code; translate and branch on this.

string

params

Any of:

object

object

key

additional properties

any

null

null

Example

{
  "detail": "This API key lacks the scope catalogue:write",
  "code": "insufficient_scope",
  "params": {
    "required_scope": "catalogue:write"
  }
}

401

Unauthorized

Media typeapplication/json

PublicErrorOut

object

detail

required

Detail

What went wrong, in English, for people and logs.

string

code

required

Code

Stable machine-readable error code; translate and branch on this.

string

params

Any of:

object

object

key

additional properties

any

null

null

Example

{
  "detail": "This API key lacks the scope catalogue:write",
  "code": "insufficient_scope",
  "params": {
    "required_scope": "catalogue:write"
  }
}

403

Forbidden

Media typeapplication/json

PublicErrorOut

object

detail

required

Detail

What went wrong, in English, for people and logs.

string

code

required

Code

Stable machine-readable error code; translate and branch on this.

string

params

Any of:

object

object

key

additional properties

any

null

null

Example

{
  "detail": "This API key lacks the scope catalogue:write",
  "code": "insufficient_scope",
  "params": {
    "required_scope": "catalogue:write"
  }
}

404

Not Found

Media typeapplication/json

PublicErrorOut

object

detail

required

Detail

What went wrong, in English, for people and logs.

string

code

required

Code

Stable machine-readable error code; translate and branch on this.

string

params

Any of:

object

object

key

additional properties

any

null

null

Example

{
  "detail": "This API key lacks the scope catalogue:write",
  "code": "insufficient_scope",
  "params": {
    "required_scope": "catalogue:write"
  }
}

409

Conflict

Media typeapplication/json

PublicErrorOut

object

detail

required

Detail

What went wrong, in English, for people and logs.

string

code

required

Code

Stable machine-readable error code; translate and branch on this.

string

params

Any of:

object

object

key

additional properties

any

null

null

Example

{
  "detail": "This API key lacks the scope catalogue:write",
  "code": "insufficient_scope",
  "params": {
    "required_scope": "catalogue:write"
  }
}

422

Unprocessable Content

Media typeapplication/json

PublicValidationErrorOut

object

detail

required

Detail

What went wrong, in English, for people and logs.

string

code

required

Code

Stable machine-readable error code; translate and branch on this.

string

params

Any of:

object

object

key

additional properties

any

null

null

errors

Errors

Per-field problems (pydantic format: loc, msg, type).

Array<object>

default:

object

key

additional properties

any

Example

{
  "detail": "This API key lacks the scope catalogue:write",
  "code": "insufficient_scope",
  "params": {
    "required_scope": "catalogue:write"
  },
  "errors": []
}

429

Too Many Requests

Media typeapplication/json

PublicErrorOut

object

detail

required

Detail

What went wrong, in English, for people and logs.

string

code

required

Code

Stable machine-readable error code; translate and branch on this.

string

params

Any of:

object

object

key

additional properties

any

null

null

Example

{
  "detail": "This API key lacks the scope catalogue:write",
  "code": "insufficient_scope",
  "params": {
    "required_scope": "catalogue:write"
  }
}