Reports

Endpoints related to Reports.

Request a report run.

POST

https://api.cartoncloud.com

/tenants/{tenantId}/report-runs

required permission: EDIT_REPORT_RUN (STOCK_ON_HAND) or EDIT_REPORT_RUN_BULK_CHARGES (BULK_CHARGES)

Create a report run. Report generation is performed asynchronously.

The request body is a report-run object with type and parameters. The returned object may differ from the request: omitted pageSize gets the default; values above 100 are capped at 100; other default parameters may be added; status is IN_PROCESS.

Use the returned id with Get Report Run to poll for completion. After the initial POST, wait about 10 seconds before the first GET, then use exponential back-off (20s, 40s, 80s). Most runs finish in several seconds; if still IN_PROCESS after one minute, send the create request again.

On success status becomes SUCCESS. On failure it becomes FAILED.

parameters is either stock-on-hand or bulk-charges, matching type.

Stock on hand aggregateBy: inboundOrder, location (unlimited-customer clients only), productGroup, productType. productStatus and unitOfMeasure are always applied. Custom product or purchase-order product fields may also be used.

Bulk charges dateFilter: date_added (charge created), date_invoice (invoice dates), date_activity (consignment delivered, manifest added, purchase order allocated, run sheet delivery date, sale order packed, storage period start/end).

Required permission depends on the report type:

STOCK_ON_HAND: EDIT_REPORT_RUN
BULK_CHARGES: EDIT_REPORT_RUN_BULK_CHARGES

Request a report run. › path Parameters

tenantId

string · uuid · required

Tenant ID. Can be found in organisation settings

Request a report run. › Headers

Accept-Version

string · enum · required

All API end points require Accept-Version in the request header.

Failure to provide the header will return a status code of 400, however, an invalid version can return a 404, 406 or 400.

Enum values:

Request a report run. › Request Body

Class AbstractApiEntity

ApiReportRun

type

string · enum · required

Enum values:

BULK_CHARGES

STOCK_ON_HAND

status

string · enum

Enum values:

FAILED

IN_PROCESS

SUCCESS

reportTime

string · date-time

Time the report was generated.

id

UUID · uuid

Request a report run. › Responses

Created. Body is the report-run object (status is IN_PROCESS).

Class AbstractApiEntity

ApiReportRun

type

string · enum · required

Enum values:

BULK_CHARGES

STOCK_ON_HAND

status

string · enum

Enum values:

FAILED

IN_PROCESS

SUCCESS

reportTime

string · date-time

Time the report was generated.

id

UUID · uuid

POST/tenants/{tenantId}/report-runs

curl https://api.cartoncloud.com/tenants/:tenantId/report-runs \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Accept-Version: <string>' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "type": "STOCK_ON_HAND",
  "parameters": {
    "pageSize": 100,
    "warehouse": {
      "id": "93d12a9a-cb7d-11e8-8b31-0260123835bc",
      "name": "Default"
    },
    "customer": {
      "id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
    },
    "aggregateBy": [
      "productType",
      "inboundOrder"
    ]
  }
}'

Example Request Body

{
  "type": "STOCK_ON_HAND",
  "parameters": {
    "pageSize": 100,
    "warehouse": {
      "id": "93d12a9a-cb7d-11e8-8b31-0260123835bc",
      "name": "Default"
    },
    "customer": {
      "id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
    },
    "aggregateBy": [
      "productType",
      "inboundOrder"
    ]
  }
}

json

application/json

Example Responses

{
  "type": "BULK_CHARGES",
  "status": "FAILED",
  "reportTime": "2024-08-25T15:00:00Z",
  "parameters": {
    "chargeClasses": [
      "CONSIGNMENT"
    ],
    "customers": [
      {
        "id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
        "name": "Customer A",
        "references": {
          "code": "C123456"
        }
      }
    ],
    "dateFilter": "date_added",
    "fromDate": "2024-08-25",
    "pageSize": 0,
    "toDate": "2024-08-25"
  },
  "id": "38756e85-d15c-45d9-84fd-1b3e50b73527"
}

json

application/json

Get Report Run

GET

https://api.cartoncloud.com

/tenants/{tenantId}/report-runs/{reportRunId}

required permission: VIEW_REPORT_RUN (STOCK_ON_HAND) or VIEW_REPORT_RUN_BULK_CHARGES (BULK_CHARGES)

Retrieve the report run and, when complete, its result rows.

A successful HTTP status is 200 OK in all of these cases:

SUCCESS — items is the current page of rows (may be empty). Use pagination headers to iterate pages (see Pagination).
FAILED — failureDetails describes the error. HTTP status remains 200 OK.
IN_PROCESS — generation is still running; poll again.

Report data is retained for 7 days from processing. Older runs return 404 Not Found.

Required permission depends on the report type:

STOCK_ON_HAND: VIEW_REPORT_RUN
BULK_CHARGES: VIEW_REPORT_RUN_BULK_CHARGES

Get Report Run › path Parameters

tenantId

string · uuid · required

Tenant ID. Can be found in organisation settings

reportRunId

UUID · uuid · required

Report run ID

Example: 38756e85-d15c-45d9-84fd-1b3e50b73527

Get Report Run › query Parameters

page

integer

The page number to return results for

Get Report Run › Headers

Accept-Version

string · enum · required

All API end points require Accept-Version in the request header.

Failure to provide the header will return a status code of 400, however, an invalid version can return a 404, 406 or 400.

Enum values:

Get Report Run › Responses

Report run. Choose the schema variant that matches type and status.

SUCCESS includes items (the current page of rows; may be empty). FAILED includes failureDetails and not items. IN_PROCESS includes neither.

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: type, items
	type = object · requires: type, items
	type = object · requires: type, failureDetails

Properties for Stock on hand (SUCCESS):

Class AbstractApiEntity

StockOnHandReportRunView

type

string · enum · const · required

Const value: STOCK_ON_HAND

Enum values:

BULK_CHARGES

STOCK_ON_HAND

StockOnHandReportItem[] · required

Stock rows. Present when status is SUCCESS.

status

string · enum · const

Const value: SUCCESS

Enum values:

FAILED

IN_PROCESS

SUCCESS

reportTime

string · date-time

Time the report was generated.

id

UUID · uuid

GET/tenants/{tenantId}/report-runs/{reportRunId}

curl https://api.cartoncloud.com/tenants/:tenantId/report-runs/:reportRunId \
  --header 'Accept-Version: <string>' \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "id": "8d0ada6a-9414-4cfe-83b6-ac09689373cd",
  "type": "STOCK_ON_HAND",
  "status": "SUCCESS",
  "reportTime": "2021-07-16T14:15:16Z",
  "parameters": {
    "pageSize": 100,
    "warehouse": {
      "id": "93d12a9a-cb7d-11e8-8b31-0260123835bc",
      "name": "Default"
    },
    "customer": {
      "id": "791a3061-383d-4759-a3b4-0bc89d48608d"
    },
    "aggregateBy": [
      "productType",
      "inboundOrder",
      "unitOfMeasure",
      "productStatus"
    ]
  },
  "items": [
    {
      "type": "ITEM",
      "details": {
        "product": {
          "id": "089c89d4-0080-4fe9-855b-8ccf29d5ebf8",
          "name": "Dark Chocolate Cookies",
          "customer": {
            "id": "791a3061-383d-4759-a3b4-0bc89d48608d"
          },
          "references": {
            "code": "COOKIES123"
          }
        },
        "unitOfMeasure": {
          "type": "UNIT",
          "name": "UNIT"
        }
      },
      "measures": {
        "quantity": 7140,
        "quantityFree": 7100,
        "quantityIncoming": 0,
        "quantityAllocated": 40,
        "quantitySellable": 6800
      },
      "properties": {
        "productType": "General",
        "inboundOrder": {
          "id": "b51c26f7-59d9-49cc-924f-d47a481d3468"
        },
        "unitOfMeasure": {
          "type": "UNIT",
          "name": "UNIT"
        },
        "productStatus": "OK"
      }
    }
  ]
}

json

application/json

Outbound Orders (Sale Orders)Transport Products