# Creates or Updates Transactions

##### Matching and Processing

This endpoint is all about submitting sales transactions to Yellow Dog.


 Identifying sales transactions. 

Three properties in the request payload identify the transaction and its parts.
  - transactionNumber
  - thirdPartyId
  - thirdPartyLineId
  
See Submit Sales via API
for guidance in using these properties correctly.




 Match transaction lines to Yellow Dog Items via id,
sku, or itemNumber. 

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.
- line[].sku
  - This will match a transaction line to the Yellow Dog Item with the same SKU.
- line[].itemNumber
  - This will match a transaction line to the Yellow Dog Item using a Third Party ItemNumber.
  - This can be performed by using the POS Item Map feature in Yellow Dog.

Only one of the three fields are required to have a non-null or non-whitespace value.




 Processing depends on checkClosed and closeout dates. 

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.




 Periodic processing of transactions 

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.






##### Examples

For the examples that follow, select the corresponding sample payload from the pull-down
menu in the request pane.



 Example A: Sending a transaction with multiple lines 

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.




 Example B: A transaction with item modifier lines 

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.




 Example C: A transaction with a Check-Wide Discount 

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.




 Examples D&E: Handling of Refunded Return 

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.




 Examples F&G: Handling of a Void or a Cancellation 

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.

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.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.

  - `lines.item` (object)

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

## 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)


## Response 200 fields

## Response 201 fields

## Response 400 fields

## Response 429 fields