Accounting Export Reports that can be consumed by 3rd Party accounting systems
API Support Group api@yellowdogsoftware.com
Fetch API (v3.0: 3.22.2.4)
For differences between versions, see Changelog.
Request
This endpoint allows for pulling of raw transaction information that is stored in the Yellow Dog Database. As this data is considered to be raw and not processed there is not a way to determine directly with certainty what items or recipes had inventory adjustments from this endpoint. Due to the various Point of Sale integrations that may be connected with the database instance, there is not a guarentee that all transactions will match using the criteria represented in the POST /transactions Endpoint documentation.
Query
Only one filter parameter field is allowed for this endpoint.
- checkClosed (DateTime in v2, DateTimeOffset in v3: See Differences between v2 and v3 in Getting Started Section for more information)
It is recommended when pulling transactions to always supply a date range that has already been settle in the Point of Sale Systems that are connected to the instance of Yellow Dog. Since the CheckClosed Field of the system is a datetime based value supplying a filter as like soe filter=checkClosed>=2020-05-29
Transactions closed between two dates
You can use the filter options for checkClosed to return a specific time range of when they were indicated to have been closed to the YellowDog Inventory System.
/transactions?filter=checkClosed>=2020-05-29,checkClosed<=2020-06-01
/transactions?filter=checkClosed>=2020-05-29 00:00:00,checkClosed<=2020-06-01 00:00:00
/transactions?filter=checkClosed>=2020-05-29T00:00:00-04:00,checkClosed<=2020-06-01T00:00:00-04:00
All of these request uri stubs will return the same list of all transactions that reflect a check closed value between 2020-05-29T00:00:00-04:00 and 2020-06-01T00:00:00-04:00
Page Number for the result set.
This is expected to be an integer value greater than 0. Defaults to 1 when not passed in.
For more information see the Getting Started Section for Pagination.
- Mock server https://developer.yellowdogsoftware.com/_mock/fetch/api/api/v3/transactions
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://developer.yellowdogsoftware.com/_mock/fetch/api/api/v3/transactions?Filter=string&PageNumber=0&PageSize=0' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'OK
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
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
The DateTime that the check was closed or made effective at the point of sale, in ISO 8601 format
Alpha numeric code for the Employee that closed the transaction (if available)
Name of the Employee that closed the transaction (if available)
Method of payment, if there are multiple Tenders, provide a comma separated list of all the tenders used in the Transaction (if available)
Identifier of the register or pos station that the Transaction was closed on (if available)
Name of the register or pos station that the Transaction was closed on (if available)
Field for recording any notes or additional information about the line
Array of individual lines representing the items that were included in this transaction
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.
Third Party Item ID or number; any unique number associated with your item
Standard unit retail for the item; usually the same as ItemRetail.
In some cases, an item might be sold at a different ItemRetail than the standard price, but it is not actually discounted; in this case, the BaseRetail would be different than the ItemRetail
Discount Description, comma separated list of any discount descriptions or names that were applied to this line
Transaction line number is associated to the individual line of the transaction
This field should contain the ThirdPartyLineID of the line it is modifying.
Response
application/json
[ { "thirdPartyId": "string", "transactionNumber": "string", "checkClosed": "2019-08-24T14:15:22Z", "employeeNumber": "string", "employeeName": "string", "tender": "string", "registerNumber": "string", "registerName": "string", "reference": "string", "store": { … }, "lines": [ … ] } ]
Request
Matching and Processing
The transactionNumber field uniquely identifies a transaction.
This POST endpoint will record a new transaction if the transactionNumber does not yet exist. If it does exist, it will overwrite the transaction previously submitted with this value. Both cases assume that the request is not blocked by a closeout date.
Note that since this endpoint uses POST, not PATCH, a request that refers to an existing transactionNumber will rewrite the entire transaction and any unspecified fields will be set to empty.
Use thirdPartyId & thirdPartyLineId to associate lines within a transaction.
When inserting a new record, it is highly recommended that you specify thirdPartyId and thirdPartyLineId values to help you update transactions, when necessary, and to assist in troubleshooting. It is considered a best practice to use a thirdPartyId that corresponds to the ID your system uses to uniquely identify the transaction. If not provided, the API will insert default values in these fields for you. The system uses the thirdPartyId to mantain an internal association between a set of lines and the transaction that contains them.
When specifying a preexisting transactionNumber to update a previously submitted transaction, the endpoint will first remove any existing transaction line records that match the specified thirdPartyId. It will then record the lines provided in the current payload as the only lines associated with this transaction.
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.
Hourly processing matches lines to items.
Transactions will be processed on an hourly basis. Each transaction line will be matched to the appropriate Yellow Dog item when processing occurs. For assistance on this matter, please contact your Implementation Guide.
Examples
For the examples that follow, select the corresponding sample payload from the pull-down menu in the request pane.
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.
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.
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.
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.
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 F shows the cancellation. Since this this event is not supposted 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.
- application/json-patch+json
- application/json
- text/json
- application/*+json
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
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
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
Alpha numeric code for the Employee that closed the transaction (if available)
Name of the Employee that closed the transaction (if available)
Method of payment, if there are multiple Tenders, provide a comma separated list of all unique tenders used in the Transaction (if available)
Identifier of the register or pos station that the Transaction was closed on (if available)
Name of the register or pos station that the Transaction was closed on (if available)
Field for recording any notes or additional information about the line
Array of individual lines representing the items that were included in this transaction
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.
Third Party Item ID or number; any unique number associated with your item
Standard unit retail for the item; usually the same as ItemRetail.
In some cases, an item might be sold at a different ItemRetail than the standard price, but it is not actually discounted; in this case, the BaseRetail would be different than the ItemRetail
Discount Description, comma separated list of any discount descriptions or names that were applied to this line
Transaction line number, can be an index or a number that is associated to the individual line of the transaction
This field should contain the ThirdPartyLineID of the line it is modifying.
- Mock server https://developer.yellowdogsoftware.com/_mock/fetch/api/api/v3/transactions
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
'https://developer.yellowdogsoftware.com/_mock/fetch/api/api/v3/transactions?suppressOutput=true' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json-patch+json' \
-d '[
{
"thirdPartyId": "thirdpartyUniqueIDForEntireTicket",
"transactionNumber": "454545",
"checkClosed": "2021-03-11T15:38:55Z",
"employeeNumber": "OneRing",
"employeeName": "Bilbo Baggins",
"tender": "Cash",
"registerNumber": "1",
"registerName": "Shire",
"reference": "Transaction with Multiple Lines",
"store": {
"id": "6a5386e3-f6f3-11e3-8ff2-000c29d58da6"
},
"lines": [
{
"thirdPartyLineId": "thirdpartyUniqueIDForEntireTicket_1",
"itemNumber": "101",
"itemDescription": "Burger",
"itemRetail": 15,
"baseRetail": 15,
"itemDiscount": 0,
"quantity": 1,
"lineNumber": 1
},
{
"thirdPartyLineId": "thirdpartyUniqueIDForEntireTicket_2",
"itemNumber": "100",
"itemDescription": "Btl Water 20 oz.",
"itemRetail": 2,
"baseRetail": 2,
"itemDiscount": 0,
"quantity": 1,
"lineNumber": 2
}
]
}
]'Query
Only one filter parameter field is allowed for this endpoint.
- checkClosed (DateTime in v2, DateTimeOffset in v3: See Differences between v2 and v3 in Getting Started Section for more information)
It is recommended when pulling transactions to always supply a date range that has already been settle in the Point of Sale Systems that are connected to the instance of Yellow Dog. Since the CheckClosed Field of the system is a datetime based value supplying a filter as like soe filter=checkClosed>=2020-05-29
Transactions closed between two dates
You can use the filter options for checkClosed to return a specific time range of when they were indicated to have been closed to the YellowDog Inventory System.
/transactions?filter=checkClosed>=2020-05-29,checkClosed<=2020-06-01
/transactions?filter=checkClosed>=2020-05-29 00:00:00,checkClosed<=2020-06-01 00:00:00
/transactions?filter=checkClosed>=2020-05-29T00:00:00-04:00,checkClosed<=2020-06-01T00:00:00-04:00
All of these request uri stubs will return the same list of all transactions that reflect a check closed value between 2020-05-29T00:00:00-04:00 and 2020-06-01T00:00:00-04:00
Page Number for the result set.
This is expected to be an integer value greater than 0. Defaults to 1 when not passed in.
For more information see the Getting Started Section for Pagination.
- Mock server https://developer.yellowdogsoftware.com/_mock/fetch/api/api/v3/transactions/store/{storeId}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://developer.yellowdogsoftware.com/_mock/fetch/api/api/v3/transactions/store/{storeId}?Filter=string&PageNumber=0&PageSize=0' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'OK
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
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
The DateTime that the check was closed or made effective at the point of sale, in ISO 8601 format
Alpha numeric code for the Employee that closed the transaction (if available)
Name of the Employee that closed the transaction (if available)
Method of payment, if there are multiple Tenders, provide a comma separated list of all the tenders used in the Transaction (if available)
Identifier of the register or pos station that the Transaction was closed on (if available)
Name of the register or pos station that the Transaction was closed on (if available)
Field for recording any notes or additional information about the line
Array of individual lines representing the items that were included in this transaction
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.
Third Party Item ID or number; any unique number associated with your item
Standard unit retail for the item; usually the same as ItemRetail.
In some cases, an item might be sold at a different ItemRetail than the standard price, but it is not actually discounted; in this case, the BaseRetail would be different than the ItemRetail
Discount Description, comma separated list of any discount descriptions or names that were applied to this line
Transaction line number is associated to the individual line of the transaction
This field should contain the ThirdPartyLineID of the line it is modifying.
Response
application/json
[ { "thirdPartyId": "string", "transactionNumber": "string", "checkClosed": "2019-08-24T14:15:22Z", "employeeNumber": "string", "employeeName": "string", "tender": "string", "registerNumber": "string", "registerName": "string", "reference": "string", "store": { … }, "lines": [ … ] } ]
- Mock server https://developer.yellowdogsoftware.com/_mock/fetch/api/api/v3/transactions/{thirdPartyId}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://developer.yellowdogsoftware.com/_mock/fetch/api/api/v3/transactions/{thirdPartyId}' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'OK
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
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
The DateTime that the check was closed or made effective at the point of sale, in ISO 8601 format
Alpha numeric code for the Employee that closed the transaction (if available)
Name of the Employee that closed the transaction (if available)
Method of payment, if there are multiple Tenders, provide a comma separated list of all the tenders used in the Transaction (if available)
Identifier of the register or pos station that the Transaction was closed on (if available)
Name of the register or pos station that the Transaction was closed on (if available)
Field for recording any notes or additional information about the line
Array of individual lines representing the items that were included in this transaction
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.
Third Party Item ID or number; any unique number associated with your item
Standard unit retail for the item; usually the same as ItemRetail.
In some cases, an item might be sold at a different ItemRetail than the standard price, but it is not actually discounted; in this case, the BaseRetail would be different than the ItemRetail
Discount Description, comma separated list of any discount descriptions or names that were applied to this line
Transaction line number is associated to the individual line of the transaction
This field should contain the ThirdPartyLineID of the line it is modifying.
Response
application/json
{ "thirdPartyId": "string", "transactionNumber": "string", "checkClosed": "2019-08-24T14:15:22Z", "employeeNumber": "string", "employeeName": "string", "tender": "string", "registerNumber": "string", "registerName": "string", "reference": "string", "store": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08" }, "lines": [ { … } ] }