---
title: "Post financial transactions"
method: POST
path: "/finance/v1/financial-transactions"
tags: ["finance_endpoints"]
---

# Post financial transactions

`POST /finance/v1/financial-transactions`

## Request

- Base URL: `https://partners.tryotter.com`
- URL: `https://partners.tryotter.com/finance/v1/financial-transactions`
- Auth: OAuth 2
  - Authorization code: `/v1/auth/oauth2/authorize`
  - Client credentials
  - Token URL: `/v1/auth/token` scopes: `finance`
- TypeScript: <https://skmtc.dev/cloudkitchens/apis/otter-api/docs/finance/v1/financial-transactions/post.ts> (a function with typed inputs; its response is checked against the schema)

Post financial data related to a given order.

## Headers

- `X-Store-Id` string, required: The unique identifier of the store in your app. This ID, along with the `Application ID`, will be used to match the correct store when performing operations. It cannot be longer than 255 characters and must only contain printable ASCII characters. During on-boarding, this ID will be similar to `onboarding:905bb725-b141-4a9b-832a-1f254f772c94` (where the UUID is the Internal Store ID). During off-boarding, this field will be filled with the last known Store ID, or with an empty string, in case none is found. In that case, please fall back to the provided `internalStoreId` (a.k.a. Sku-Sku ID).

## Request body

- FinancialTransaction
  - `orderIdentifiers` OrderIdentifierFinance, required: The external identifiers of the order.
    - `id` string, required: Unique ID for the order that was placed.
    - `source` string, nullable: Describes the source of the order, typically from a food ordering marketplace.
  - `id` string, required: Stable external financial transaction identifier. Resubmitting with the same identifier and store updates the existing transaction; changing an identity value may create a separate record.
  - `pending` boolean, required: Whether the transaction may be corrected later. The current ingestion API does not reject a later submission solely because this value was false.
  - `currencyCode` string, required: The 3-letter currency code (ISO 4217) to use for all monetary values in this order.
  - `createdAt` string, date-time, required: The date (in UTC) when the financial transaction was created.
  - `customerId` string, nullable: Customer identifier.
  - `notes` string, nullable: General notes about the financial transaction.
  - `type` 'PAYMENT' | 'ADJUSTMENT' | 'CANCELLATION' | 'MISC', required: Financial transaction operation type.
  - `payout` PayoutInfo
    - `id` string, required: Payout identifier.
    - `date` string, date, required: The payout date.
  - `orderItems` OrderItemInformation[], nullable: Detailed financial per order item.
    - `id` string, required: Regular item identifier.
    - `name` string, nullable: Item name
    - `issues` OrderIssue[], nullable: Order issues that relate to this item.
      - `type` 'MISSING_ITEM' | 'INCOMPLETE' | 'WRONG_INGREDIENTS' | 'WRONG_SIZE' | 'WRONG_INSTRUCTIONS' | 'TEMPERATURE_COLD' | 'WRONG_ORDER' | 'POOR_QUALITY' | 'HANDLED_POORLY' | 'WRONG_ITEM' | 'WRONG_QUANTITY' | 'LATE_TO_COURIER', required: Order issue type.
  - `issues` OrderIssue[], nullable: List of issues that might have happened with the order.
    - `type` 'MISSING_ITEM' | 'INCOMPLETE' | 'WRONG_INGREDIENTS' | 'WRONG_SIZE' | 'WRONG_INSTRUCTIONS' | 'TEMPERATURE_COLD' | 'WRONG_ORDER' | 'POOR_QUALITY' | 'HANDLED_POORLY' | 'WRONG_ITEM' | 'WRONG_QUANTITY' | 'LATE_TO_COURIER', required: Order issue type.
  - `data` FinancialData, required: Breakdown of order values. Represents total values, fees, discounts, and any possible adjustments that may happen in the order value. Breakdown lists can be used to represent aggregate values (e.g. order total value) or, when available, can accurately represent the values of each item/fee/tax/charges related to the order. All objects in breakdown lists have a required property "subType". Allowed values are: **VALUE**: represent the net value of the order/item/fee. Should be used in the following cases: - when the amount does not contain taxes or VAT - when tax/VAT is a known value, in that case, the list must contain an object with subtype TAX or VAT representing this value. **TAX**: represent the tax value for the order/item/fee. Should be used when tax amount is available, in that case, this information should be part of the breakdown list with the "VALUE" as the net amount, example below: ``` "breakdown": [ { "name": "Item 1", "value": 10, "subType": "VALUE" }, { "name": "Item 1 - Tax", "value": 2, "subType": "TAX" } ] ``` **VAT**: represents the amount for value-added tax. Should be used when the order/item/fee contains VAT. In that case, this information should be part of the breakdown list with the "VALUE" as net amount, example below: ``` "breakdown": [ { "name": "Item 1", "value": 12, "subType": "VALUE" }, { "name": "Item 1 - Tax", "value": 2, "subType": "VAT" } ] ``` **VALUE_WITH_TAX**: represents the gross value of the order/item/fee. Should be used when the value includes tax/VAT and values related to taxation are not available. ``` "breakdown": [ { "name": "Item 1", "value": 12, "subType": "VALUE_WITH_TAX" } ] ```
    - `foodSales` CompositeFinanceLine, required: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects
      - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line.
        - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line.
        - `name` string, required: name of the finance line.
        - `value` number, required: money amount.
    - `feeForRestaurantProvidedDelivery` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects
      - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line.
        - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line.
        - `name` string, required: name of the finance line.
        - `value` number, required: money amount.
    - `restaurantFundedDiscount` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects
      - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line.
        - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line.
        - `name` string, required: name of the finance line.
        - `value` number, required: money amount.
    - `voucherDiscount` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects
      - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line.
        - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line.
        - `name` string, required: name of the finance line.
        - `value` number, required: money amount.
    - `promotionDiscount` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects
      - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line.
        - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line.
        - `name` string, required: name of the finance line.
        - `value` number, required: money amount.
    - `operatorDiscount` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects
      - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line.
        - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line.
        - `name` string, required: name of the finance line.
        - `value` number, required: money amount.
    - `loyaltyDiscount` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects
      - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line.
        - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line.
        - `name` string, required: name of the finance line.
        - `value` number, required: money amount.
    - `tipForRestaurant` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects
      - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line.
        - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line.
        - `name` string, required: name of the finance line.
        - `value` number, required: money amount.
    - `adjustments` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects
      - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line.
        - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line.
        - `name` string, required: name of the finance line.
        - `value` number, required: money amount.
    - `packingFee` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects
      - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line.
        - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line.
        - `name` string, required: name of the finance line.
        - `value` number, required: money amount.
    - `bagFee` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects
      - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line.
        - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line.
        - `name` string, required: name of the finance line.
        - `value` number, required: money amount.
    - `serviceProviderDiscount` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects
      - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line.
        - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line.
        - `name` string, required: name of the finance line.
        - `value` number, required: money amount.
    - `tipForServiceProviderCourier` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects
      - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line.
        - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line.
        - `name` string, required: name of the finance line.
        - `value` number, required: money amount.
    - `feeForServiceProviderDelivery` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects
      - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line.
        - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line.
        - `name` string, required: name of the finance line.
        - `value` number, required: money amount.
    - `smallOrderFee` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects
      - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line.
        - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line.
        - `name` string, required: name of the finance line.
        - `value` number, required: money amount.
    - `serviceFee` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects
      - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line.
        - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line.
        - `name` string, required: name of the finance line.
        - `value` number, required: money amount.
    - `otherFee` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects
      - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line.
        - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line.
        - `name` string, required: name of the finance line.
        - `value` number, required: money amount.
    - `netPayout` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects
      - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line.
        - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line.
        - `name` string, required: name of the finance line.
        - `value` number, required: money amount.
    - `couponCodes` string[], nullable: Any codes entered by the customer at order checkout.

## Response `202`

The financial transaction passed synchronous validation and was published to and queued by the ingestion system. This response does not confirm processing completion, including downstream validation, order association, or persistence.

## Other responses

- `400`: The request is malformed.
- `401`: Invalid authorization.
- `403`: Authorization not valid for the requested resource.
- `404`: Resource not found.

---

[API](https://skmtc.dev/cloudkitchens/apis/otter-api.md) - [All operations](https://skmtc.dev/cloudkitchens/apis/otter-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cloudkitchens/apis/otter-api/revisions/4c868194a467?raw)