Finance

Metering and billing keyed to the same product identifier every endpoint definition carries.

Finance meters each invocation against the product API it called, using the identifier already present in that endpoint's definition. There is no separate billing catalogue to keep in step with the API catalogue, because they are the same identifier.

Price revisions are versioned per API, and vendor cost is reported alongside what was charged.

How it works

Metered units can be negative. That is what expresses a charge reversed when a call returned nothing usable — a credit rather than a suppressed record, so the ledger still shows the attempt.

Keeping the attempt visible matters for the waterfall: a vendor tried and returning nothing is exactly the event the ordering is tuned on.

Operations

Metrics

POST /metrics

Create Finance Metrics

createFinanceMetric

Create Finance Metric

This service enables storing finance metrics. The unit value is a required field that can be either positive or negative according to the direction of the transaction.

Request

application/json

{
  "product_api_identifier": "product_api_identifier_2",
  "product_price_identifier": "product_price_identifier_2",
  "product_identifier": "c5b45e21-6946-4110-bf83-8ca90fac5493",
  "transaction_id": "01G0KZARZ46W8KZ81277V5C0HA",
  "request_collection_id": "2I8JNKZARZ46W8KZ81277V5CASD",
  "response_collection_id": "328JNKZARZ46W8KZ81277V5SKDS",
  "company_name": "customer_comp",
  "price_unit_type": "transaction",
  "price_timing_type": "completion",
  "price_amount": 10,
  "price_amount_unit_type": "cents"
}

Response

application/json

Success response.

{
  "message": "metric created"
}

Parameters

Parameter	Type	Example	Description
`x-api-key` required	`string` header	`<redacted>`	API key

Request body`application/json`

11 fields

Field	Type	Description
`product_api_identifier`required	`string`	Unique identifier for payable unitExample `product_api_identifier_1`
`product_price_identifier`required	`string`	Unique identifier for priceExample `product_price_identifier_1`
`transaction_id`	`string`	Transactions in Staircase are containers for all the data related to an instance of a transaction type. They enable you to correlate the output of various products to a single transaction type, where the transaction type depends on your line of business. A transaction_id, when used properly, gives you a holistic view of the data related to the transaction you’ve assembled.Example `01G0KZARZ46W8KZ81277V5C0HA`
`request_collection_id`	`string`	Unique identifier for Staircase request collectionExample `2I8JNKZARZ46W8KZ81277V5CASD`
`response_collection_id`	`string`	Unique identifier for Staircase response collectionExample `328JNKZARZ46W8KZ81277V5SKDS`
`company_name`	`string`	Company nameExample `comp_name`
`price_unit_type`required	`string`	The unit of the platform where the price evaluation can be determined as relevant`api_calldatapointdocumentenvironmenthourimagepagepersonperson-hourpmpm-hourproductseatsubscriptiontransaction`Example `product`
`price_timing_type`required	`string`	Price is included into billing based on this defined schedule.`completionmonthly`Example `completion`
`product_identifier`required	`string`	Unique identifier for productExample `c5b45e21-6946-4110-bf83-8ca90fac5493`
`price_amount`required	`number`	Value of the unit in selected unit price. This value can be negative or positive.Example `95`
`price_amount_unit_type`required	`string`	Unit of the price`cents`Example `cents`

Response `201application/json`

1 fields

Success response.

Field	Type	Description
`message`	`string`	Message response

Response `400application/json`

1 fields

Error Response.

Field	Type	Description
`message`	`string`	Error message

Response `403application/json`

1 fields

Bad request syntax or forbidden request

Field	Type	Description
`message`	`string`	Error message

Response `404application/json`

1 fields

Not found.

Field	Type	Description
`message`	`string`	Error message

Response `422application/json`

2 fields

Forbidden

Field	Type	Description
`message`	`string`	Error message
`error`	`string`	Error

POST /products/finance-service/custom_endpoint/create-finance-metric

Create Finance Metric

createFinanceMetric

Create finance metric

Create finance metric. Results will be saved in the output collection. Remember transaction_id and response_collection_id from the response to get the collection data from Persistence API: Retrieve Collection

Response collection example

{
 "metadata": {
 "version": 2,
 "validation": true,
 "product_name": "finance-service"
 },
 "transaction_id": "01GME0M8HH3TXS0STWANH32VRC",
 "collection_id": "01GME0M8KYYBNYQSEVB7MXKVXW",
 "data": {
 "finance_metrics": [
 {
 "@id": "01GQJPZJAFSMTB9EDYKGQ85VKK",
 "@type": "finance_metric",
 "has_finance_metrShow the rest

ic_identifier": {
 "has_value": "01GQJPZJAFSMTB9EDYKGQ85VKK"
 },
 "has_collection_id": {
 "has_value": ""
 },
 "has_organization_id": {
 "has_value": "john.doe@test.co"
 },
 "has_produce_identifier": {
 "has_value": "customer"
 },
 "has_product_api_identifier": {
 "has_value": "active"
 },
 "has_transaction_id": {
 "has_value": "test-co-1"
 }
 }
 ]
 }
 }
}

Request

application/json

{
  "request_data": {
    "finance_metrics": [
      {
        "has_transaction_id": {
          "has_value": "test-co-1"
        },
        "has_collection_id": {
          "has_value": "https://test-co-1.com"
        },
        "has_organization_id": {
          "has_value": "john.doe@test.co"
        },
        "has_produce_identifier": {
          "has_value": "customer"
        },
        "has_product_api_identifier": {
          "has_value": "product-api-identifier"
        }
      }
    ]
  }
}

Response

application/json

Successfully started flow invocation.

{
  "invocation_id": "9aefb465-90fb-4d50-8ae6-2df2b58373f4",
  "invocation_status": "STARTED",
  "product_flow_name": "product_flow_name_example",
  "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4",
  "request_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK",
  "response_collection_id": "01F6NAQ4894HPMCBGB4P0G78HG",
  "options": {
    "dry_run": false
  },
  "tags": [
    "manual verification"
  ],
  "widget_url": "https://product-dev-productsbucket-1j472c4onqkxw.s3.amazonaws.com/widgets/063f5f"
}

Parameters

Parameter	Type	Example	Description
`x-api-key` required	`string` header	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`	Environment API Key.

Request body`application/json`

2 fields

Field	Type	Description
`callback_url`	`string (uri)`	Callback URL.
`request_data`required	`object`	Request JSON body.
`finance_metrics`	`object[]`	Finance metric filter
`has_transaction_id`	`object`	Transaction ID
`has_value`	`string`	Transaction IDExample `01GQJPZG07MMFTF6ZZ3BVK1ZFP`
`has_collection_id`	`object`	Collection ID
`has_value`	`string`	Collection IDExample `01GQJPZFXPRR8QMR31CG92J27D`
`has_organization_id`	`object`	Organization ID
`has_value`	`string`	Organization IDExample `test-co-1@gmail.com`
`has_produce_identifier`	`object`	Product Identifier
`has_value`	`string`	Product IdentifierExample `customer`
`has_product_api_identifier`	`object`	Product API Identifier
`has_value`	`string`	Product API IdentifierExample `62f5691e-7fd0-4728-ac3c-977dea07f338`

Response `201application/json`

12 fields

Successfully started flow invocation.

Field	Type	Description
`invocation_id`required	`string`	Invocation ID.
`invocation_status`required	`string`	The status of the invocation.`STARTED`
`transaction_id`required	`string`	Transaction ID.
`request_collection_id`required	`string`	Request collection ID.
`response_collection_id`required	`string`	Response collection ID.
`product_flow_name`	`string`	Product flow name.
`metadata`	`object`	The metadata of the invoked product flow.
`callback_url`	`string`	Callback URL.
`request_data`	`object`	The data for the request collection.
`tags`	`string[]`	List of tags.
`options`	`object`	Additional information that should be passed to the connector but not be added to the request collection.
`widget_url`	`string`	Product widget_url listening on the connector widget_url

Response `400application/json`

1 fields

Bad request

Field	Type	Description
`message`	`one of`	Either message or object with additional properties.

Response `403application/json`

2 fields

Forbidden

Field	Type	Description
`message`	`string`	Request forbidden -- authorization will not help
`url`	`string (url)`	Indicates at which url the error occurs

Response `404application/json`

1 fields

Partner, flow or execution not found

Field	Type	Description
`message`	`string`	Nothing matches the given URI

POST /metrics/query

Create Asynchronous Metric Query

create_async_query_execution

Create Asynchronous Query Execution

The service creates asynchronous query execution to retrieves a list of metrics given one or multiple filters. To retrieve all results, send the request with the same query parameters and next_token provided on the previous call until next_token does not appear in the response.

Request

application/json

Create asynchronous query execution

{
  "product_api_identifier": "c4c7a50e-ef10-4885-9a9d-2c04d7410084",
  "product_price_identifier": "ecb11b04-e99c-4610-8db1-990367c25883",
  "transaction_id": "01F2Q6WJXF5DK3ERTZ18JHSNE8",
  "start_date": "2022-04-11",
  "end_date": "2022-04-15"
}

Response

application/json

Ok.

{
  "query_id": "c62a1228-fae7-44c8-aebe-8706ecfb9fc4",
  "status": "IN_PROGRESS"
}

Parameters

Parameter	Type	Example	Description
`x-api-key` required	`string` header	`<redacted>`	API key

Request body`application/json`

11 fields

Field	Type	Description
`product_api_identifier`	`string`	Unique identifier for payable unitExample `product_api_identifier_1`
`product_price_identifier`	`string`	Unique identifier for priceExample `product_price_identifier_1`
`transaction_id`	`string`	Transactions in Staircase are containers for all the data related to an instance of a transaction type. They enable you to correlate the output of various products to a single transaction type, where the transaction type depends on your line of business. A transaction_id, when used properly, gives you a holistic view of the data related to the transaction you’ve assembled.Example `01G0KZARZ46W8KZ81277V5C0HA`
`request_collection_id`	`string`	Unique identifier for Staircase request collectionExample `2I8JNKZARZ46W8KZ81277V5CASD`
`response_collection_id`	`string`	Unique identifier for Staircase response collectionExample `328JNKZARZ46W8KZ81277V5SKDS`
`company_name`	`string`	Company nameExample `comp_name`
`price_unit_type`	`string`	The unit of the platform where the price evaluation can be determined as relevant`api_calldatapointdocumentenvironmenthourimagepagepersonperson-hourpmpm-hourproductseatsubscriptiontransaction`Example `product`
`price_timing_type`	`string`	Price is included into billing based on this defined schedule.`completionmonthly`Example `completion`
`product_identifier`	`string`	Unique identifier for the productExample `3f312801-e3bb-49c2-a59b-8e2c05958c1b`
`start_date`required	`string`	If provided, filters by start_date it must be used together with the end_date. Date must be in ISO8601 format.Example `2021-04-13`
`end_date`required	`string`	If provided, filters by end_date it must be used together with the start_date. Date must be in ISO8601 format.Example `2021-04-16`

Response `201application/json`

2 fields

Ok.

Field	Type	Description
`query_id`	`string`	Unique identifier for running query execution
`status`	`string`	Status of the query execution

Response `400application/json`

1 fields

Failed Creation.

Field	Type	Description
`message`	`string`	Message reason why the creation has failed

Response `403application/json`

1 fields

Bad request syntax or forbidden request

Field	Type	Description
`message`	`string`	Error message

Response `422application/json`

2 fields

Forbidden

Field	Type	Description
`message`	`string`	Error message
`error`	`string`	Error

GET /metrics/query/{query_id}

Get Asynchronous Query Result

get_async_query_result

The service retrieves a list of metrics by given query id. To retrieve all results, send the next_token provided on the previous call until next_token does not appear in the response.

Response

application/json

Ok.

{
  "query_id": "fd99d4de-1632-487f-8576-2ee064e75b51",
  "status": "SUCCEEDED",
  "result_csv_file": "https://finance-athena-result-795294970345.s3.amazonaws.com/fd99d4de-1632-487f-8576-2ee064e75b51.csv&Expires=1659342953",
  "data": {
    "metrics": [
      {
        "product_api_identifier": "c4c7a50e-ef10-4885-9a9d-2c04d7410084",
        "product_price_identifier": "ecb11b04-e99c-4610-8db1-990367c25883",
        "transaction_id": "da2dbe64-33c0-4de2-b5a4-745f0b60ee4c",
        "host_environment": "documentation.staircaseapi.com",
        "date": "2022-08-01 03:32:42.000",
        "company_name": "bohr",
        "price_unit_type": "subscription",
        "price_timing_type": "monthly",
        "price_amount": "10000.0",
        "price_amount_unit_type": "cents"
      },
      {
        "product_api_identifier": "df7d610c-0e6e-4bbd-86c0-7de39e29dd8a",
        "product_price_identifier": "6c58cf4d-0d97-49dd-8d1a-fd44387734e4",
        "transaction_id": "aaa55ebb-43e8-4722-96cd-050bf2b5c29c",
        "host_environment": "documentation.staircaseapi.com",
        "date": "2022-08-01 03:32:20.000",
        "company_name": "bohr",
        "price_unit_type": "subscription",
        "price_timing_type": "monthly",
        "price_amount": "50000.0",
        "price_amount_unit_type": "cents"
      },
      {
        "product_api_identifier": "6ee48f0c-7bd8-43de-9bf9-afce5e85bd08",
        "product_price_identifier": "4159a209-bc65-48eb-8735-7cb3600d7fa0",
        "transaction_id": "2c71d744-9589-4812-a373-e4bcec7df5c5",
        "host_environment": "documentation.staircaseapi.com",
        "date": "2022-08-01 03:28:51.000",
        "company_name": "bohr",
        "price_unit_type": "subscription",
        "price_timing_type": "monthly",
        "price_amount": "100000.0",
        "price_amount_unit_type": "cents"
      }
    ]
  }
}

application/json

Error Response.

{
  "response": {
    "value": {
      "message": "Filters not allowed ",
      "allowed filters": [
        "product_name",
        "status",
        "partner_name",
        "metric_type",
        "operation_status",
        "product_name and severity",
        "product_name and status",
        "operation_stauts and partner_name",
        "start_date and end_date can be combined with every filter"
      ]
    }
  }
}

Parameters

Parameter	Type	Example	Description
`query_id` required	`string` path	`1fc23e2-b13e-405a-a3de-a5228950e3b8`	Unique query execution id
`x-api-key` required	`string` header	`<redacted>`	API key
`limit`	`integer` query	`150`	The number of results to return in this request.
`next_token`	`string` query	`000000000000`	The token for the next set of items to return. (You received this token from a previous call. If you have reached the end of the stream, the returned token is null.)

Response `200application/json`

3 fields

Ok.

Field	Type	Description
`status`	`string`	Status of the query execution
`result_csv_file`	`string`	URL for query result in CSV format
`metrics`	`object[]`	Metrics
`host_environment`	`string`	Environment host where the product is deployed.
`product_api_identifier`	`string`	Unique identifier for payable unit
`product_price_identifier`	`string`	Unique identifier for price
`transaction_id`	`string`	Transaction ID
`request_collection_id`	`string`	Unique identifier for Staircase request collection
`response_collection_id`	`string`	Unique identifier for Staircase response collection
`company_name`	`string`	Company name
`price_unit_type`	`string`	The unit of the platform where the price evaluation can be determined as relevant
`price_timing_type`	`string`	Price is included into billing based on this defined schedule.
`price_amount`	`string`	Value of the unit in selected unit price. This value can be negative or positive.
`price_amount_unit_type`	`string`	Unit of the price

Response `400application/json`

1 fields

Error Response.

Field	Type	Description
`message`	`string`	Error message

Response `403application/json`

1 fields

Bad request syntax or forbidden request

Field	Type	Description
`message`	`string`	Error message

Response `404application/json`

1 fields

Not found.

Field	Type	Description
`message`	`string`	Error message

Response `504application/json`

1 fields

504 Timeout response.

Field	Type	Description
`message`	`string`	Endpoint request timed out

Aggregated Metric Migrations

POST /migrations

Create Aggregated Finance Metric Migration Configurations

createFinanceMigrationConfigurations

Create Finance Migration Configurations

This service creates migration configurations to allow migrating aggregated finance data to another environment. Aggregated finance data is needed for generating finance reports from them.

Request

application/json

{
  "migration_configuration_name": "test_name",
  "target_environment_api_key": "apikey",
  "target_environment_domain": "documentation.staircaseapi.com"
}

Response

application/json

Success response.

{
  "message": "migration configuration created"
}

Parameters

Parameter	Type	Example	Description
`x-api-key` required	`string` header	`<redacted>`	API key

Request body`application/json`

3 fields

Field	Type	Description
`migration_configuration_name`required	`string`	Migration configuration nameExample `test-migration`
`target_environment_domain`required	`string`	Domain of target environmentExample `documentation.staircaseapi.com`
`target_environment_api_key`required	`string`	API key of given target environmentExample `1111111-22222-333333`

Response `201application/json`

1 fields

Success response.

Field	Type	Description
`message`	`string`	Message response

Response `400application/json`

1 fields

Error Response.

Field	Type	Description
`message`	`string`	Error message

Response `403application/json`

1 fields

Bad request syntax or forbidden request

Field	Type	Description
`message`	`string`	Error message

Response `404application/json`

1 fields

Not found.

Field	Type	Description
`message`	`string`	Error message

Response `422application/json`

2 fields

Forbidden

Field	Type	Description
`message`	`string`	Error message
`error`	`string`	Error

GET /migrations

List Aggregated Finance Metric Migration Configurations

listFinanceMigrationConfigurations

List Finance Migration Configurations

This service allows retrieving Finance product migration configuration

Response

application/json

Ok.

{
  "migration_configurations": [
    {
      "migration_configuration_name": "test_name",
      "target_environment_api_key": "apikey",
      "target_environment_domain": "template.staircaseapi.com"
    }
  ]
}

Parameters

Parameter	Type	Example	Description
`x-api-key` required	`string` header	`<redacted>`	API key

Response `200application/json`

1 fields

Ok.

Field	Type	Description
`migration_configurations`	`object[]`	Configurations
`migration_configuration_name`	`string`	Unique configuration nameExample `test_configuration`
`target_environment_api_key`	`string`	Target environment API keyExample `111111-222222-333333`
`target_environment_domain`	`string`	Target environment domainExample `documentation.staircaseapi.com`

Response `400application/json`

1 fields

Error response example

Field	Type	Description
`Error`	`string`	Error

Response `403application/json`

1 fields

Bad request syntax or forbidden request

Field	Type	Description
`message`	`string`	Error message

Response `404application/json`

1 fields

Not found.

Field	Type	Description
`message`	`string`	Error message

Response `422application/json`

2 fields

Forbidden

Field	Type	Description
`message`	`string`	Error message
`error`	`string`	Error

PUT /migrations/{migration_configuration_name}

Update Aggregated Finance Metric Migration Configurations

updateFinanceMigrationConfigurations

Update Finance Migration Configurations

This service updates migration configuration.

Request

application/json

{
  "target_environment_api_key": "apikey",
  "target_environment_domain": "documentation.staircaseapi.com"
}

Response

application/json

Success response.

{
  "message": "migration configuration updated"
}

Parameters

Parameter	Type	Example	Description
`x-api-key` required	`string` header	`<redacted>`	API key
`migration_configuration_name` required	`string` path	`test_configuration_name`	Unique configuration name
`x-api-key` required	`string` header	`<redacted>`	API key

Request body`application/json`

2 fields

Field	Type	Description
`target_environment_domain`required	`string`	Domain of target environmentExample `documentation.staircaseapi.com`
`target_environment_api_key`required	`string`	API key of given target environmentExample `1111111-22222-333333`

Response `201application/json`

1 fields

Success response.

Field	Type	Description
`message`	`string`	Message response

Response `400application/json`

1 fields

Error Response.

Field	Type	Description
`message`	`string`	Error message

Response `403application/json`

1 fields

Bad request syntax or forbidden request

Field	Type	Description
`message`	`string`	Error message

Response `404application/json`

1 fields

Not found.

Field	Type	Description
`message`	`string`	Error message

Response `422application/json`

2 fields

Forbidden

Field	Type	Description
`message`	`string`	Error message
`error`	`string`	Error

GET /migrations/{migration_configuration_name}

Get Aggregated Finance Metric Migration Configurations

getFinanceMigrationConfigurations

Get Finance Migration Configurations

This service allows retrieving Finance product migration configuration

Response

application/json

Ok.

{
  "migration_configuration_name": "test_name",
  "target_environment_api_key": "apikey",
  "target_environment_domain": "documentation.staircaseapi.com"
}

Parameters

Parameter	Type	Example	Description
`x-api-key` required	`string` header	`<redacted>`	API key
`migration_configuration_name` required	`string` path	`test_configuration_name`	Unique configuration name
`x-api-key` required	`string` header	`<redacted>`	API key

Response `200application/json`

3 fields

Ok.

Field	Type	Description
`migration_configuration_name`	`string`	Unique configuration nameExample `test_configuration`
`target_environment_api_key`	`string`	Target environment API keyExample `111111-222222-333333`
`target_environment_domain`	`string`	Target environment domainExample `documentation.staircaseapi.com`

Response `400application/json`

1 fields

Error response example

Field	Type	Description
`Error`	`string`	Error

Response `403application/json`

1 fields

Bad request syntax or forbidden request

Field	Type	Description
`message`	`string`	Error message

Response `404application/json`

1 fields

Not found.

Field	Type	Description
`message`	`string`	Error message

Response `422application/json`

2 fields

Forbidden

Field	Type	Description
`message`	`string`	Error message
`error`	`string`	Error

DELETE /migrations/{migration_configuration_name}

Delete Aggregated Finance Metric Migration Configurations

deleteFinanceConfigurations

Delete Finance Configurations

This service allows deleting Finance product configuration

Response

application/json

Ok.

{
  "message": "migration configuration deleted"
}

Parameters

Parameter	Type	Example	Description
`x-api-key` required	`string` header	`<redacted>`	API key
`migration_configuration_name` required	`string` path	`test_configuration_name`	Unique configuration name
`x-api-key` required	`string` header	`<redacted>`	API key

Response `200application/json`

1 fields

Ok.

Field	Type	Description
`message`	`string`	Unique configuration nameExample `test_configuration`

Response `400application/json`

1 fields

Error response example

Field	Type	Description
`Error`	`string`	Error

Response `403application/json`

1 fields

Bad request syntax or forbidden request

Field	Type	Description
`message`	`string`	Error message

Response `404application/json`

1 fields

Not found.

Field	Type	Description
`message`	`string`	Error message

Response `422application/json`

2 fields

Forbidden

Field	Type	Description
`message`	`string`	Error message
`error`	`string`	Error

Reports

POST /reports/finance

Create Finance Metric Reports

createFinanceMetricReport

Create Finance Metric Report

This service allows the creation of financial reports for given dates. Request body allows filtering reports by some fields. This service starts asynchronous report execution and returns a unique report ID for checking report execution status and getting report results if report execution is finished.

Request

application/json

{
  "product_api_identifiers": [
    "id_1",
    "id_2"
  ],
  "product_price_identifiers": [
    "product_price_identifier_1",
    "product_price_identifier_2"
  ],
  "start_date": "2021-04-13",
  "end_date": "2021-05-13"
}

Response

application/json

Report execution started

{
  "report_id": "9a6aa8-4f2-400d-9451-e1e127485"
}

Parameters

Parameter	Type	Example	Description
`x-api-key` required	`string` header	`<redacted>`	API key

Request body`application/json`

5 fields

Field	Type	Description
`product_api_identifiers`	`array`	List of API ID
`product_price_identifiers`	`array`	List of product price identifier
`price_amount_unit_type`	`string`	Price unit`cents`Example `cents`
`start_date`required	`string`	Start date in ISO8601 formatExample `2021-04-13`
`end_date`required	`string`	End date in ISO8601 formatExample `2021-05-13`

Response `202application/json`

1 fields

Report execution started

Field	Type	Description
`report_id`	`string`	Report ID

Response `400application/json`

1 fields

Bad request syntax or missed a required field

Field	Type	Description
`message`	`string`	Error message

Response `401application/json`

1 fields

Unauthorized, Bad credentials.

Field	Type	Description
`message`	`string`	Error message

Response `403application/json`

1 fields

Bad request syntax or forbidden request

Field	Type	Description
`message`	`string`	Error message

Response `404application/json`

1 fields

Not found.

Field	Type	Description
`message`	`string`	Error message

Response `405application/json`

1 fields

Method not allowed.

Field	Type	Description
`message`	`string`	Error message

Other responses

422

POST /reports/finance/aggregated

Create Aggregated Finance Metric Reports

createAggregatedFinanceMetricReport

Create Aggregated Finance Metric Report

This service allows the creation of financial reports from aggregated metric data for given dates. In order to get a finance report for multiple environments, please have a look at the migrations(/migrations) service for migrating aggregated finance metrics. Request body allows filtering reports by some fields. This service starts asynchronous report execution and returns a unique report ID for checking report execution status and getting report results if report execution is finished. There is no retention period for aggregated finance metrics.

Request

application/json

{
  "product_api_identifiers": [
    "id_1",
    "id_2"
  ],
  "environments": [
    "documentation.staircaseapi.com"
  ],
  "product_price_identifiers": [
    "product_price_identifier_1",
    "product_price_identifier_2"
  ],
  "start_date": "2021-04-13",
  "end_date": "2021-05-13"
}

Response

application/json

Report execution started

{
  "report_id": "9a6aa8-4f2-400d-9451-e1e127485"
}

Parameters

Parameter	Type	Example	Description
`x-api-key` required	`string` header	`<redacted>`	API key

Request body`application/json`

6 fields

Field	Type	Description
`product_api_identifiers`	`array`	List of API ID
`environments`	`array`	List of environment names
`product_price_identifiers`	`array`	List of product price identifier
`price_amount_unit_type`	`string`	Price unit`cents`Example `cents`
`start_date`required	`string`	Start date in ISO8601 formatExample `2021-04-13`
`end_date`required	`string`	End date in ISO8601 formatExample `2021-05-13`

Response `202application/json`

1 fields

Report execution started

Field	Type	Description
`report_id`	`string`	Report ID

Response `400application/json`

1 fields

Bad request syntax or missed a required field

Field	Type	Description
`message`	`string`	Error message

Response `401application/json`

1 fields

Unauthorized, Bad credentials.

Field	Type	Description
`message`	`string`	Error message

Response `403application/json`

1 fields

Bad request syntax or forbidden request

Field	Type	Description
`message`	`string`	Error message

Response `404application/json`

1 fields

Not found.

Field	Type	Description
`message`	`string`	Error message

Response `405application/json`

1 fields

Method not allowed.

Field	Type	Description
`message`	`string`	Error message

Other responses

422

GET /reports/{report_id}

Get Finance Report Result

getFinanceReportResult

This service retrieves the status of a Report Execution for a given report_id. Status = IN_PROGRESS, SUCCEEDED, or FAILED. Continue to ping this service until you receive a status = SUCCEEDED or FAILED. Created report results have one month retention period.

Response

application/json

Report status

{
  "report_id": "979a6aa8-4f2-400d-9451-80ee1e127485",
  "status": "SUCCEEDED",
  "created_at": "2022-05-06:11:53:38",
  "finished_at": "2022-05-06:11:55:10",
  "expired_at": "1654864684",
  "report_data": {
    "total": 0,
    "price_amount_unit_type": "cents",
    "environments": []
  }
}

Parameters

Parameter	Type	Example	Description
`x-api-key` required	`string` header	`<redacted>`	API key
`report_id` required	`string` path	`979a6aa8-4f2-400d-9451-80ee1e127485`	Report ID

Response `200application/json`

6 fields

Report status

Field	Type	Description
`report_id`	`string`	Report ID
`status`	`string`	IN_PROGRESS, FAILED, or SUCCEEDED`FAILEDIN_PROGRESSSUCCEEDED`
`report_data`	`object`	Report payload
`created_at`	`string`	Create date of report executionExample `2022-05-06:11:53:38`
`finished_at`	`string`	Finish date of report executionExample `2022-05-06:11:55:10`
`expired_at`	`string`	Expiration timestamp in string formatExample `1654864684`

Response `400application/json`

1 fields

Bad request syntax or missed a required field

Field	Type	Description
`message`	`string`	Error message

Response `403application/json`

1 fields

Method not allowed.

Field	Type	Description
`message`	`string`	Error message

Response `404application/json`

1 fields

Not found.

Field	Type	Description
`message`	`string`	Error message

Response `405application/json`

1 fields

Method not allowed.

Field	Type	Description
`message`	`string`	Error message

Other responses

422

Errors

400401403404405422504

How it works

Operations

Metrics

Create Finance Metrics

Request

Response

Parameters

Request bodyapplication/json

Response 201application/json

Response 400application/json

Response 403application/json

Response 404application/json

Response 422application/json

Create Finance Metric

Request

Response

Parameters

Request bodyapplication/json

Response 201application/json

Response 400application/json

Response 403application/json

Response 404application/json

Create Asynchronous Metric Query

Request

Response

Parameters

Request bodyapplication/json

Response 201application/json

Response 400application/json

Response 403application/json

Response 422application/json

Get Asynchronous Query Result

Response

Parameters

Response 200application/json

Response 400application/json

Response 403application/json

Response 404application/json

Response 504application/json

Aggregated Metric Migrations

Create Aggregated Finance Metric Migration Configurations

Request

Response

Parameters

Request bodyapplication/json

Response 201application/json

Response 400application/json

Response 403application/json

Response 404application/json

Response 422application/json

List Aggregated Finance Metric Migration Configurations

Response

Parameters

Response 200application/json

Response 400application/json

Response 403application/json

Response 404application/json

Response 422application/json

Update Aggregated Finance Metric Migration Configurations

Request

Response

Parameters

Request bodyapplication/json

Response 201application/json

Response 400application/json

Response 403application/json

Response 404application/json

Response 422application/json

Get Aggregated Finance Metric Migration Configurations

Response

Parameters

Response 200application/json

Response 400application/json

Response 403application/json

Response 404application/json

Response 422application/json

Delete Aggregated Finance Metric Migration Configurations

Response

Parameters

Response 200application/json

Request body`application/json`

Response `201application/json`

Response `400application/json`

Response `403application/json`

Response `404application/json`

Response `422application/json`

Request body`application/json`

Response `201application/json`

Response `400application/json`

Response `403application/json`

Response `404application/json`

Request body`application/json`

Response `201application/json`

Response `400application/json`

Response `403application/json`

Response `422application/json`

Response `200application/json`

Response `400application/json`

Response `403application/json`

Response `404application/json`

Response `504application/json`

Request body`application/json`

Response `201application/json`

Response `400application/json`

Response `403application/json`

Response `404application/json`

Response `422application/json`

Response `200application/json`

Response `400application/json`

Response `403application/json`

Response `404application/json`

Response `422application/json`

Request body`application/json`

Response `201application/json`

Response `400application/json`

Response `403application/json`

Response `404application/json`

Response `422application/json`

Response `200application/json`

Response `400application/json`

Response `403application/json`

Response `404application/json`

Response `422application/json`

Response `200application/json`

Response `400application/json`

Response `403application/json`

Response `404application/json`

Response `422application/json`

Request body`application/json`

Response `202application/json`

Response `400application/json`

Response `401application/json`

Response `403application/json`

Response `404application/json`

Response `405application/json`

Request body`application/json`

Response `202application/json`

Response `400application/json`

Response `401application/json`

Response `403application/json`

Response `404application/json`

Response `405application/json`

Response `200application/json`

Response `400application/json`

Response `403application/json`

Response `404application/json`

Response `405application/json`