Let's start off by defining some terms so we are all talking about the same things:

Order - In VineSpring an order is a fully paid record of a purchase. You cannot have an "unpaid" order as that is considered a Draft. When you search in VineSpring and view and Order you are looking at the order with all the changes that have been made.

Line Items - In each order there are one or more Line Items. You will have one Line Item for each SKU purchased. For example one Line Item would represent 12 bottles of ABC Wine were purchased. You are not able to add the same SKU to a new Line Item in VineSpring, only to modify the quantities.

Transactions - Each modification that could have a reporting or reconciliation impact records a transaction. Transactions represent a snapshot in time and will show what was changed on an order. When an order is first created there is a Transaction created. When SKUs are added or removed Transactions are created. Not every change to an Order will result in a Transaction. If you click the "Edit" button and make a modification that will always result in Transactions.

Here is an example of what a Transaction looks like when an order is first created. At this point there is only one transaction for the order.

We are now going to modify the order the next day and add an additional product. On the screen this is what it will look like. Note that you now see two payments on the right hand side:

What is happening behind the scenes? There will be TWO new transactions rows created. To better see what is happening I will show this now in a spreadsheet format although note that the data is all stored and sent via API in JSON. We will also only show a few of the fields to better illustrate the concepts.

While this might seem like there is a lot going on just to add one product to the order it will correctly show what is happening to inventory. For example, let's see what happens when we now remove the first product from the order.

There are two new transaction rows created. One again that puts back all the inventory. The difference here is that on the last row the first product is not put back on the order. So this will correctly report that the inventory was sold on the 15th but then put back into inventory on the 16th.

If you summarize or total up the line items you will see what is on the order today. The total of the order is $109.99 with the one NEW999 product being the only product left on the order.

Let's look at a fully refunded order:

You will see the credit line will always indicate what the customer was charged or refunded. You will also see in this case that the summary line is all zeros indicating that the one product was fully refunded and there is nothing left on this order. But what these three lines represent correctly is that the product was sold on the 15th and then refunded on the 16th. So if you pulled daily reports you would only see the sale on the 15th but then the next day when you pulled your report you would only see the negative line items as that product sale was put back into inventory.


If there are TWO transactions for each change does that mean our client will see a reversal on their credit card and then another charge?

No, the amount listed under the "credit" line is what will be occurring on the customer's credit card. You will notice that the negative or reversal transactions always have an amount of 0 meaning there was no activity on the customer's card. The customer will only be refunded any amount due or charged the additional amount after the changes are complete.

Will there still be two transactions if the only thing that was done is we refunded shipping?

Yes, in this case you will still see the negative or reversal transaction but then the final transaction will put all the products back on the order However the shipping amount will not be put back on. This will show you that shipping was removed and date and time it was removed.

How can I uniquely identify a transaction? I am used to systems where a new order number is created when a change is made.

Each transaction is assigned a unique identifier. The JSON attribute is called "id" and it will begin with otrx_. Each transaction also points back to the original order using the orderId, so the combination of the orderId and id will provide you with a unique identifier if you need this for your financial or other 3rd party system.

We also need a unique identifier for each of the line items. How does that work?

VineSpring does not allow a SKU to be added to an order in more than one line item. So you can use the SKU itself added to the orderId or id as the unique identifier.

What changes to an order will create new transaction rows?

Any change that could have an impact on financial reporting or inventory will result in transaction rows being created. For example changing a customer, adding or removing products, changing the shipping method, manually overriding shipping or tax, adding or removing discounts, changing the sales representative or changing an order's type will all create transaction rows.

If I add note to an order will that create transaction rows?

No, adding a note, or changing the source, status or adding tags will not create transactions.

Why are all the dates on the transactions in UTC?

We store all date and time stamps in UTC format. If we stored the time stamp in the local time and you had a VineSpring user in Eastern time add an order and an hour later a VineSpring user in the Pacific timezone refunded it, the transactions would appear as if the refund occurred before the initial purchase. By storing the date and time as UTC we know the exact point in time an action occurred. You can convert this date and time stamp to your local time if that is how you wish to see it in your 3rd party system.

Did this answer your question?