# Finance
# 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 Copy
```
{
"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
201400 application/json400 text/html403404
application/json Copy Success response.
```
{
"message": "metric created"
}
```
application/json Copy Error Response.
```
{
"message": "Bad Request"
}
```
text/html Copy Error Response.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Not found.
```
{
"message": "Not found."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | 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_call``datapoint``document``environment``hour``image``page``person``person-hour``pm``pm-hour``product``seat``subscription``transaction`Example `product` |
| `price_timing_type`required | `string` | Price is included into billing based on this defined schedule.`completion``monthly`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 `201``application/json`
1 fields
Success response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message response |
##### Response `400``application/json`
1 fields
Error Response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `422``application/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 restic_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 Copy
```
{
"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
201400
application/json Copy 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"
}
```
application/json Copy Bad request
```
{
"message": {
"schema_type": [
"Must be one of: create, update."
]
}
}
```
##### Parameters
1
| 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 `201``application/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 `400``application/json`
1 fields
Bad request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Either message or object with additional properties. |
##### Response `403``application/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 `404``application/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 Copy 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
201400 application/json400 text/html403
application/json Copy Ok.
```
{
"query_id": "c62a1228-fae7-44c8-aebe-8706ecfb9fc4",
"status": "IN_PROGRESS"
}
```
application/json Copy Failed Creation.
```
{
"message": "Error in creating metric "
}
```
text/html Copy Failed Creation.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | 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_call``datapoint``document``environment``hour``image``page``person``person-hour``pm``pm-hour``product``seat``subscription``transaction`Example `product` |
| `price_timing_type` | `string` | Price is included into billing based on this defined schedule.`completion``monthly`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 `201``application/json`
2 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `query_id` | `string` | Unique identifier for running query execution |
| `status` | `string` | Status of the query execution |
##### Response `400``application/json`
1 fields
Failed Creation.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message reason why the creation has failed |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `422``application/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
200400 application/json400 text/html403404
application/json Copy 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 Copy 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"
]
}
}
}
```
text/html Copy Error Response.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Not found.
```
{
"message": "Not found."
}
```
##### Parameters
4
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `query_id` required | `string` path | `1fc23e2-b13e-405a-a3de-a5228950e3b8` | Unique query execution id |
| `x-api-key` required | `string` header | `` | 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 `200``application/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 `400``application/json`
1 fields
Error Response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `504``application/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 Copy
```
{
"migration_configuration_name": "test_name",
"target_environment_api_key": "apikey",
"target_environment_domain": "documentation.staircaseapi.com"
}
```
##### Response
201400 application/json400 text/html403404
application/json Copy Success response.
```
{
"message": "migration configuration created"
}
```
application/json Copy Error Response.
```
{
"message": "Bad Request"
}
```
text/html Copy Error Response.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Not found.
```
{
"message": "Not found."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | 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 `201``application/json`
1 fields
Success response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message response |
##### Response `400``application/json`
1 fields
Error Response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `422``application/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
200400 error response400 text/html403404
application/json Copy Ok.
```
{
"migration_configurations": [
{
"migration_configuration_name": "test_name",
"target_environment_api_key": "apikey",
"target_environment_domain": "template.staircaseapi.com"
}
]
}
```
application/json Copy Error response example
```
{
"Error": "Invalid Parameter document"
}
```
text/html Copy Error response example
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Not found.
```
{
"message": "Not found."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | API key |
##### Response `200``application/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 `400``application/json`
1 fields
Error response example
| Field | Type | Description |
| --- | --- | --- |
| `Error` | `string` | Error |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `422``application/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 Copy
```
{
"target_environment_api_key": "apikey",
"target_environment_domain": "documentation.staircaseapi.com"
}
```
##### Response
201400 application/json400 text/html403404
application/json Copy Success response.
```
{
"message": "migration configuration updated"
}
```
application/json Copy Error Response.
```
{
"message": "Bad Request"
}
```
text/html Copy Error Response.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Not found.
```
{
"message": "Not found."
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | API key |
| `migration_configuration_name` required | `string` path | `test_configuration_name` | Unique configuration name |
| `x-api-key` required | `string` header | `` | 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 `201``application/json`
1 fields
Success response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message response |
##### Response `400``application/json`
1 fields
Error Response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `422``application/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
200400 error response400 text/html403404
application/json Copy Ok.
```
{
"migration_configuration_name": "test_name",
"target_environment_api_key": "apikey",
"target_environment_domain": "documentation.staircaseapi.com"
}
```
application/json Copy Error response example
```
{
"Error": "Invalid Parameter document"
}
```
text/html Copy Error response example
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Not found.
```
{
"message": "Not found."
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | API key |
| `migration_configuration_name` required | `string` path | `test_configuration_name` | Unique configuration name |
| `x-api-key` required | `string` header | `` | API key |
##### Response `200``application/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 `400``application/json`
1 fields
Error response example
| Field | Type | Description |
| --- | --- | --- |
| `Error` | `string` | Error |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `422``application/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
200400 error response400 text/html403404
application/json Copy Ok.
```
{
"message": "migration configuration deleted"
}
```
application/json Copy Error response example
```
{
"Error": "Invalid Parameter document"
}
```
text/html Copy Error response example
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Not found.
```
{
"message": "Not found."
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | API key |
| `migration_configuration_name` required | `string` path | `test_configuration_name` | Unique configuration name |
| `x-api-key` required | `string` header | `` | API key |
##### Response `200``application/json`
1 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Unique configuration nameExample `test_configuration` |
##### Response `400``application/json`
1 fields
Error response example
| Field | Type | Description |
| --- | --- | --- |
| `Error` | `string` | Error |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `422``application/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 Copy
```
{
"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
202400401403404405
application/json Copy Report execution started
```
{
"report_id": "9a6aa8-4f2-400d-9451-e1e127485"
}
```
application/json Copy Bad request syntax or missed a required field
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Unauthorized, Bad credentials.
```
{
"message": "Unauthorized, Bad credentials."
}
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Not found.
```
{
"message": "Not found."
}
```
application/json Copy Method not allowed.
```
{
"message": "The method is not allowed for the requested URL"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | 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 `202``application/json`
1 fields
Report execution started
| Field | Type | Description |
| --- | --- | --- |
| `report_id` | `string` | Report ID |
##### Response `400``application/json`
1 fields
Bad request syntax or missed a required field
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `401``application/json`
1 fields
Unauthorized, Bad credentials.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `405``application/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 Copy
```
{
"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
202400401403404405
application/json Copy Report execution started
```
{
"report_id": "9a6aa8-4f2-400d-9451-e1e127485"
}
```
application/json Copy Bad request syntax or missed a required field
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Unauthorized, Bad credentials.
```
{
"message": "Unauthorized, Bad credentials."
}
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Not found.
```
{
"message": "Not found."
}
```
application/json Copy Method not allowed.
```
{
"message": "The method is not allowed for the requested URL"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | 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 `202``application/json`
1 fields
Report execution started
| Field | Type | Description |
| --- | --- | --- |
| `report_id` | `string` | Report ID |
##### Response `400``application/json`
1 fields
Bad request syntax or missed a required field
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `401``application/json`
1 fields
Unauthorized, Bad credentials.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `405``application/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
200400403404405
application/json Copy 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": []
}
}
```
application/json Copy Bad request syntax or missed a required field
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Method not allowed.
```
{
"message": "The method is not allowed for the requested URL"
}
```
application/json Copy Not found.
```
{
"message": "Not found."
}
```
application/json Copy Method not allowed.
```
{
"message": "The method is not allowed for the requested URL"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | API key |
| `report_id` required | `string` path | `979a6aa8-4f2-400d-9451-80ee1e127485` | Report ID |
##### Response `200``application/json`
6 fields
Report status
| Field | Type | Description |
| --- | --- | --- |
| `report_id` | `string` | Report ID |
| `status` | `string` | IN_PROGRESS, FAILED, or SUCCEEDED`FAILED``IN_PROGRESS``SUCCEEDED` |
| `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 `400``application/json`
1 fields
Bad request syntax or missed a required field
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Method not allowed.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `405``application/json`
1 fields
Method not allowed.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`422`
## Errors
`400``401``403``404``405``422``504`
## More in Distribution
- Previous product: Environment
- Next product: Host