# Creates or Updates Transactions

##### Matching and Processing
This endpoint is all about submitting sales transactions to Yellow Dog.
<details id="transaction-number">
<summary> Identifying sales transactions. </summary>
Three properties in the request payload identify the transaction and its parts.
- transactionNumber
- thirdPartyId
- thirdPartyLineId

See [Submit Sales via API](/rest/user-guide/05-pos-integrations/submit-sales)
for guidance in using these properties correctly.
</details>
<details id="matching-processing">
<summary> Match transaction lines to Yellow Dog Items via id,
sku, or itemNumber. </summary>
This endpoint matches transaction lines to Yellow Dog Items by either the **id**,
**sku**, or **itemNumber** field.
- line[].item.id
  - This will match a transaction line immediately to the Yellow Dog Item with the same id.
  - This is the preferred method for matching Transaction Lines to the appropriate Yellow Dog Item
but would only be used by integrations that are also pulling item data from Yellow Dog's API.
- line[].sku
  - This will match a transaction line to the Yellow Dog Item with the same SKU.
  - This is the most common method of matching sales to items in Retail and Concessions environments.
  - Yellow Dog can also be configured to match line[].sku to the Yellow Dog item with the same UPC.
- line[].itemNumber
  - This will match a transaction line to a Yellow Dog Recipe using a Third Party ItemNumber.
  - This can be performed by using the POS Item Map feature in Yellow Dog.
  - This is the most common method of matching sales to items in F&B environments.

Only one of the three fields are required to have a non-null or non-whitespace value.
</details>
<details id="processing-after-closeout">
<summary> Processing depends on checkClosed and closeout dates. </summary>
Only transactions with a **checkClosed** date later than the current closeout date will
be processed. This setting can be found in the Stores Tab of YDInv.
</details>
<details id="processing-hourly">
<summary> Periodic processing of transactions </summary>
Transactions are added to the specified Yellow Dog database in real time as they
are received but the impact of these sales on inventory is calculated by a separate
periodic process.
This process can be configured to run at least daily and as often as multiple
times per hour depending on database complexity.
</details>
<br/>
##### Examples
For the examples that follow, select the corresponding sample payload from the pull-down
menu in the request pane.
<details id="transaction-with-multiple-lines">
<summary> Example A: Sending a transaction with multiple lines </summary>
In ***Example A***, there was a sale of a Burger and a bottle of water.
The expected total for the transaction with all the lines will have a retail of $17.00.
</details>
<details id="transaction-with-item-modifier-lines">
<summary> Example B: A transaction with item modifier lines </summary>
In ***Example B***, there was a sale of a Burger with the additional modifiers for adding
cheese and bacon.
As part of the inventory processing the use of the modifiers will allow for the
processing of the transactions to deduct the 2 cheese and 2 bacon appropriately.
In this example the expected total for the transaction with all the lines will have
a retail of $23.00.
</details>
<details id="transaction-with-check-wide-discount">
<summary> Example C: A transaction with a Check-Wide Discount </summary>
In ***Example C***, there was a sale of a Burger with the additional modifiers for adding
cheese and bacon.
There was also a discount set for 20% off the entire check.
Notice how the itemDiscount is set for each line of the transaction.
This allows for proper setting of the item price.
In this example the expected total for the transaction with all the lines will have a
retail of $18.40.
</details>
<details id="handling-return">
<summary> Examples D&E: Handling of Refunded Return </summary>
In this example, there was a sale of a Tee Shirt that was then returned with refund
the following day.
To properly handle the deduction and then increment of inventory for the two actions,
there should be two separate transactions sent to the api.
Here, ***Example D*** shows the initial sale and ***Example E*** shows the return.
Ideally, the transactions should be marked for the appropriate times that they
happened at.
Notice that in this example the **thirdPartyId** and **thirdPartyLineId** are different values
between the sale and the refund.
</details>
<details id="handling-void">
<summary> Examples F&G: Handling of a Void or a Cancellation </summary>
In this example, there was a sale of a Tee Shirt that was canceled or voided without a
decrement of inventory.
This could have been an accidential addition of an item for the transaction.
Here, ***Example F*** shows the initial sale and ***Example G*** shows the cancellation.
Since this this event is not supposed to impact the inventory onhand, it is
appropriate to set the quantity of the existing line to 0 as an update to the original
transaction.
Notice that in this example the **thirdPartyId** and **thirdPartyLineId** are the same values
between the sale and the voided line.
</details>
<br/>

Endpoint: POST /transactions
Version: v3.0: 3.30.0
Security: Auth API User Token

## Query parameters:

  - `suppressOutput` (boolean)
    If true the api will not respond with transactions created or updated in the response. 
Errors are still shown if applicable.

## Request fields (application/json-patch+json):

  - `thirdPartyId` (string | null)
    This field serves as a globally unique identifier for a transaction and its lines.
This ensures all lines associated with a transaction can also be associated to the POS sales event

  - `transactionNumber` (string, required)
    Unique ID representing a collection of multiple lines from a single transaction, also commonly referred to as a check number. This number is usually a receipt and can be used to match up POS transactions to on hand affecting events

  - `checkClosed` (string, required)
    The DateTime that the check was closed or made effective at the point of sale, in ISO 8601 format.
For example, to effectively post a checkclosed datetime of 2024-07-02 14:11:52.9366717 in PST when the offset for PST is -07:00, you could post any of the following:
- 2024-07-02T14:11:52.9366717-07:00
- 2024-07-02 14:11:52.9366717-07:00
- 2024-07-02T21:11:52.9366717Z
- 2024-07-02 21:11:52.9366717Z

  - `employeeNumber` (string | null)
    Alpha numeric code for the Employee that closed the transaction (if available)

  - `employeeName` (string | null)
    Name of the Employee that closed the transaction (if available)

  - `tender` (string | null)
    Method of payment, if there are multiple Tenders, provide a comma separated list of all unique tenders used in the Transaction (if available)

  - `registerNumber` (string | null)
    Identifier of the register or pos station that the Transaction was closed on (if available)

  - `registerName` (string | null)
    Name of the register or pos station that the Transaction was closed on (if available)

  - `reference` (string | null)
    Field for recording any notes or additional information about the line

  - `store` (object, required)

  - `store.id` (string)

  - `lines` (array, required)
    Array of individual lines representing the items that were included in this transaction

  - `lines.thirdPartyLineId` (string | null)
    Unique identifier for this transaction line. When provided this should be globally unique across all transactions.
When the unique identifier from a third party only contains incrementing integers, it is
required that there be additional data points to ensure that the incrementing integers are
unique across all transactions as additional integrations or instances of the same integration are maintained.
In cases like this the recommended format for thirdPartyLineIds is as followed
`uniqueSiteNameOrId_uniqueRevenueCenterId_transactionNumber_transactionLineNumber`
Alternatively we have seen GUIDs, cuids or other unique identifiers that are not necessarily
auto incrementing integers used successfully in the past for the thirdPartyLineIds.

  - `lines.itemNumber` (string | null)
    Third Party Item ID or number; any unique number associated with your item

  - `lines.sku` (string | null)
    Yellow Dog SKU

  - `lines.itemDescription` (string | null)
    Item Description

  - `lines.itemRetail` (number, required)
    Unit Retail for the item

  - `lines.baseRetail` (number | null)
    As of 2026, this property is deprecated. We recommend that it be omitted from request payloads going forward.

  - `lines.itemDiscount` (number | null)
    Unit Discount for the item. Should always be negative

  - `lines.discountDescription` (string | null)
    Discount Description, comma separated list of any discount descriptions or names that were applied to this line

  - `lines.quantity` (number, required)
    Quantity sold, negative designates a return

  - `lines.lineNumber` (integer, required)
    Transaction line number, can be an index or a number that is associated to the individual line of the transaction

  - `lines.modifier` (string | null)
    This field should contain the ThirdPartyLineID of the line it is modifying.

## Response 422 fields (application/json):

  - `message` (string | null)

  - `errors` (array | null)

  - `errors.field` (string | null)

  - `errors.message` (string | null)

## Response 500 fields (application/json):

  - `message` (string | null)

  - `errors` (array | null)

  - `errors.message` (string | null)

  - `errors.extensions` (string | null)