Create calculation

POST 
/calculations

Calculates carbon emission for one or more transactions. If the request contains a transaction with an unsupported merchant category (MCC) the response still contains that item but without any values returned, except the reference which is echoed back.

Request

Header Parameters

forwarded-partner string

Partner identification in case the request is proxied by another partner

application/json

Body

required

Transaction information required to perform the calculation

cardTransactions

object[]

required

Possible values: >= 1, <= 5000

Array [

reference stringrequired

Possible values: non-empty and <= 100 characters

Any unique reference to the transaction to be used for mapping back with the result on the response

mcc stringrequired

Possible values: non-empty and <= 4 characters, Value must match regular expression [0-9]{1,4}

Merchant Category Code in ISO 18245 format

amount

object

required

Expresses a monetary amount

value numberrequired

Possible values: >= -1000000000 and <= 1000000000

currency stringrequired

Possible values: >= 3 characters and <= 3 characters, Value must match regular expression ^(EUR|GBP|RUB|SEK|USD)$

Currency in ISO 4217 code format; EUR, GBP, RUB, SEK or USD

]

Responses

200

Calculation response

application/json

Schema

Schema

transactionFootprints

object[]

Array [

reference string

Possible values: non-empty and <= 100 characters

A reference to the transaction this calculation was based on (from request)

categoryId integer

The category ID of the transaction, can be retrieved from /categories

carbonEmissionInGrams number

The transaction's CO2 emission in grams

carbonEmissionInOunces number

The transaction's CO2 emission in ounces

carbonSocialCost

object

Expresses a monetary amount

value numberrequired

Possible values: >= -1000000000 and <= 1000000000

currency stringrequired

Possible values: >= 3 characters and <= 3 characters, Value must match regular expression ^(EUR|GBP|RUB|SEK|USD)$

Currency in ISO 4217 code format; EUR, GBP, RUB, SEK or USD

]

Example (from schema)

{
  "transactionFootprints": [
    {
      "reference": "string",
      "categoryId": 0,
      "carbonEmissionInGrams": 0,
      "carbonEmissionInOunces": 0,
      "carbonSocialCost": {
        "value": 0,
        "currency": "string"
      }
    }
  ]
}

400

Bad request

application/json

Schema

Schema

errors

object[]

required

Errors

Array [

source stringrequired

Possible values: non-empty and <= 100 characters

The application name that generated this error.

reasonCode stringrequired

Possible values: non-empty and <= 100 characters

A unique constant identifying the error case encountered during request processing.

• BAD_REQUEST - Malformed request, please advice the description and details fields for more information
• FORBIDDEN - Insufficient scope to access the resource
• INTERNAL_SERVER_ERROR - Unexpected server error
• METHOD_NOT_ALLOWED - Method not allowed
• UNSUPPORTED_MEDIA_TYPE - Unsupported media type
• SERVICE_UNAVAILABLE - Service is unavailable

description stringrequired

Possible values: >= 10 characters and <= 1000 characters

Short description of the reasonCode field.

recoverable booleanrequired

Indicates whether this error will always be returned for this request, or retrying could change the outcome.

details string

Possible values: <= 5000 characters

Where appropriate, indicates detailed information about data received and calculated during request processing, to help the user with diagnosing errors.

]

Example (from schema)

{
  "errors": [
    {
      "source": "Doconomy",
      "reasonCode": "BAD_REQUEST",
      "description": "cardTransactions[0].mcc must match \\\"[0-9]{1,4}\\\"",
      "recoverable": false,
      "details": "string"
    }
  ]
}

401

Unauthorized client

403

Insufficient scope for accessing this resource

application/json

Schema

Schema

errors

object[]

required

Errors

Array [

source stringrequired

Possible values: non-empty and <= 100 characters

The application name that generated this error.

reasonCode stringrequired

Possible values: non-empty and <= 100 characters

A unique constant identifying the error case encountered during request processing.

• BAD_REQUEST - Malformed request, please advice the description and details fields for more information
• FORBIDDEN - Insufficient scope to access the resource
• INTERNAL_SERVER_ERROR - Unexpected server error
• METHOD_NOT_ALLOWED - Method not allowed
• UNSUPPORTED_MEDIA_TYPE - Unsupported media type
• SERVICE_UNAVAILABLE - Service is unavailable

description stringrequired

Possible values: >= 10 characters and <= 1000 characters

Short description of the reasonCode field.

recoverable booleanrequired

Indicates whether this error will always be returned for this request, or retrying could change the outcome.

details string

Possible values: <= 5000 characters

Where appropriate, indicates detailed information about data received and calculated during request processing, to help the user with diagnosing errors.

]

Example (from schema)

{
  "errors": [
    {
      "source": "Doconomy",
      "reasonCode": "BAD_REQUEST",
      "description": "cardTransactions[0].mcc must match \\\"[0-9]{1,4}\\\"",
      "recoverable": false,
      "details": "string"
    }
  ]
}

405

Method not allowed

application/json

Schema

Schema

errors

object[]

required

Errors

Array [

source stringrequired

Possible values: non-empty and <= 100 characters

The application name that generated this error.

reasonCode stringrequired

Possible values: non-empty and <= 100 characters

A unique constant identifying the error case encountered during request processing.

• BAD_REQUEST - Malformed request, please advice the description and details fields for more information
• FORBIDDEN - Insufficient scope to access the resource
• INTERNAL_SERVER_ERROR - Unexpected server error
• METHOD_NOT_ALLOWED - Method not allowed
• UNSUPPORTED_MEDIA_TYPE - Unsupported media type
• SERVICE_UNAVAILABLE - Service is unavailable

description stringrequired

Possible values: >= 10 characters and <= 1000 characters

Short description of the reasonCode field.

recoverable booleanrequired

Indicates whether this error will always be returned for this request, or retrying could change the outcome.

details string

Possible values: <= 5000 characters

Where appropriate, indicates detailed information about data received and calculated during request processing, to help the user with diagnosing errors.

]

Example (from schema)

{
  "errors": [
    {
      "source": "Doconomy",
      "reasonCode": "BAD_REQUEST",
      "description": "cardTransactions[0].mcc must match \\\"[0-9]{1,4}\\\"",
      "recoverable": false,
      "details": "string"
    }
  ]
}

415

Unsupported media type

application/json

Schema

Schema

errors

object[]

required

Errors

Array [

source stringrequired

Possible values: non-empty and <= 100 characters

The application name that generated this error.

reasonCode stringrequired

Possible values: non-empty and <= 100 characters

A unique constant identifying the error case encountered during request processing.

• BAD_REQUEST - Malformed request, please advice the description and details fields for more information
• FORBIDDEN - Insufficient scope to access the resource
• INTERNAL_SERVER_ERROR - Unexpected server error
• METHOD_NOT_ALLOWED - Method not allowed
• UNSUPPORTED_MEDIA_TYPE - Unsupported media type
• SERVICE_UNAVAILABLE - Service is unavailable

description stringrequired

Possible values: >= 10 characters and <= 1000 characters

Short description of the reasonCode field.

recoverable booleanrequired

Indicates whether this error will always be returned for this request, or retrying could change the outcome.

details string

Possible values: <= 5000 characters

Where appropriate, indicates detailed information about data received and calculated during request processing, to help the user with diagnosing errors.

]

Example (from schema)

{
  "errors": [
    {
      "source": "Doconomy",
      "reasonCode": "BAD_REQUEST",
      "description": "cardTransactions[0].mcc must match \\\"[0-9]{1,4}\\\"",
      "recoverable": false,
      "details": "string"
    }
  ]
}

429

Too many requests, check the headers X-RateLimit-Limit-second and X-RateLimit-Remaining-second

500

Unexpected server error

application/json

Schema

Schema

errors

object[]

required

Errors

Array [

source stringrequired

Possible values: non-empty and <= 100 characters

The application name that generated this error.

reasonCode stringrequired

Possible values: non-empty and <= 100 characters

A unique constant identifying the error case encountered during request processing.

• BAD_REQUEST - Malformed request, please advice the description and details fields for more information
• FORBIDDEN - Insufficient scope to access the resource
• INTERNAL_SERVER_ERROR - Unexpected server error
• METHOD_NOT_ALLOWED - Method not allowed
• UNSUPPORTED_MEDIA_TYPE - Unsupported media type
• SERVICE_UNAVAILABLE - Service is unavailable

description stringrequired

Possible values: >= 10 characters and <= 1000 characters

Short description of the reasonCode field.

recoverable booleanrequired

Indicates whether this error will always be returned for this request, or retrying could change the outcome.

details string

Possible values: <= 5000 characters

Where appropriate, indicates detailed information about data received and calculated during request processing, to help the user with diagnosing errors.

]

Example (from schema)

{
  "errors": [
    {
      "source": "Doconomy",
      "reasonCode": "BAD_REQUEST",
      "description": "cardTransactions[0].mcc must match \\\"[0-9]{1,4}\\\"",
      "recoverable": false,
      "details": "string"
    }
  ]
}

default

Default response

Response Headers

• X-RateLimit-Limit-second

  integer

  Request limit per second

• X-RateLimit-Remaining-second

  integer

  Number of requests left for the time window

Loading...