Financial Transaction Export Sample

ft_sample.xml

<!-- Exported amounts are rounded to two decimal places -->
<!-- For all statuses, we use numeric codes instead of strings and provide a mapping on a separate endpoint -->
<!-- Datetime stamp here is when the entire report was generated -->
<FinancialTransactionExport dateTime="2016-03-01T12:47:34.542145">
    <!-- One InvoiceHeader per SalesOrder -->
  <SalesOrder>
    <InvoiceHeader>
        <FinancialTransactionID>23e4687e-1edf-4731-ad4e-1e84deea6c03</FinancialTransactionID>
        <SalesOrderID>e259965b-8179-45cb-b1d7-82b6eb8babe8</SalesOrderID>
        <!-- ID of the (paper) invoice sent to the consumer for this order -->
        <InvoiceID>e39a34cc-6b12-4867-8da1-3fd2eb3f409d</InvoiceID>
        <!-- Date on the consumer's (paper) invoice -->
        <InvoiceDate>2016-02-29</InvoiceDate>
        <!-- Our internal consumer ID -->
        <ConsumerID>453b932b-0932-402e-a1e2-69bc85f1f2f0</ConsumerID>
        <!-- External consumer ID of the system that the order was placed in, e.g. Demandware -->
        <ExternalConsumerID></ExternalConsumerID>
        <!-- The date this transaction was written, on shipment handover -->
        <TransactionDateTime>2016-02-29T12:42:12.982492</TransactionDateTime>
        <!-- Type 0 = Order, Type 1 = Return -->
        <TransactionType>0</TransactionType>
        <!-- CreditAmount = we got money, DebitAmount = we paid out money -->
        <CreditAmount>0.00</CreditAmount>
        <DebitAmount>0.00</DebitAmount>
        <CurrencyCode>USD</CurrencyCode>
        <!-- InvoiceStatus signals if all order items in this sales order are shipped/cancelled
             0: complete: all items are either shipped or cancelled
             1: partial: some items are not shipped and not cancelled -->
        <InvoiceStatus>0</InvoiceStatus>
    </InvoiceHeader>
    <!-- One InvoiceDetail per SalesOrderItem -->
    <InvoiceDetails>
      <InvoiceDetail>
          <!-- References the InvoiceHeader from above -->
          <FinancialTransactionID>23e4687e-1edf-4731-ad4e-1e84deea6c03</FinancialTransactionID>
          <!-- unique ID for this InvoiceDetail -->
          <InvoiceDetailID>7312a2dc-f1b2-4ed5-8756-0bb113182747</InvoiceDetailID>
          <SalesOrderID>e259965b-8179-45cb-b1d7-82b6eb8babe8</SalesOrderID>
          <SalesOrderItemID></SalesOrderItemID>
          <LogisticOrderItemID></LogisticOrderItemID>
          <Quantity>1</Quantity>
          <!-- Who shipped the products: DivisionID 1 = New York/Thakoon US, Type 2 = Hong Kong/Thakoon HK -->
          <DivisionID>2</DivisionID>
          <!-- includes product price line item amount plus partial shipping amount plus tax for this orderline -->
          <!-- total shipping cost is a field in the OrderHeader -->
          <CreditAmount>0.00</CreditAmount>
          <DebitAmount>0.00</DebitAmount>
      </InvoiceDetail>
      <InvoiceDetail>
        <!-- This is a shipping line item -->
        <FinancialTransactionID>23e4687e-1edf-4731-ad4e-1e84deea6c03</FinancialTransactionID>
        <SalesOrderID>e259965b-8179-45cb-b1d7-82b6eb8babe8</SalesOrderID>
        <!-- unique ID for this InvoiceDetail -->
        <InvoiceDetailID></InvoiceDetailID>
        <SalesOrderItemID></SalesOrderItemID>
        <LogisticOrderItemID></LogisticOrderItemID>
        <Quantity>1</Quantity>
        <DivisionID>2</DivisionID>
        <!-- includes product price line item amount plus partial shipping amount plus tax for this orderline -->
        <!-- total shipping cost is a field in the OrderHeader -->
        <CreditAmount>0.00</CreditAmount>
        <DebitAmount>0.00</DebitAmount>
      </InvoiceDetail>
    </InvoiceDetails>
    <OrderHeader>
        <SalesOrderID>e259965b-8179-45cb-b1d7-82b6eb8babe8</SalesOrderID>
        <ExternalOrderID>DW-something-something-1234</ExternalOrderID>
        <DivisionID>2</DivisionID>
        <BillToAddress><!-- Insert billing address with all fields here --></BillToAddress>
        <!-- Date the order was received in NewStore -->
        <OrderYear>2016</OrderYear>
        <OrderMonth>02</OrderMonth>
        <OrderDay>29</OrderDay>
        <OrderDate>2016-02-29</OrderDate>
        <!-- Date when the order was recorded in the original system, e.g. Demandware -->
        <KeyedDate>2016-02-28</KeyedDate>
        <!-- Total tax amount for this order -->
        <TotalTaxAmount>12.00</TotalTaxAmount>
        <NetAmount>100.00</NetAmount>
        <TotalDiscountAmount>10.00</TotalDiscountAmount>
        <!-- total shipping and handling amount -->
        <ShippingHandlingAmount>5.00</ShippingHandlingAmount>
        <!-- Net + Tax + ShippingHandling - Discount -->
        <!-- Needs to be equal to sum of amounts of all OrderDetail entries -->
        <TotalAmount>97.00</TotalAmount>
        <TotalPaidAmount>97.00</TotalPaidAmount>
        <TotalMiscChargesAmount></TotalMiscChargesAmount>
        <!-- ChannelType: 0 = desktop web, 1 = mobile web, 2 = NS consumer app, phone, etc -->
        <ChannelType>0</ChannelType>
        <!-- numeric value for mapping to channel instance, e.g. 0 = "Demandware US Desktop Web" -->
        <ChannelName>0</ChannelName>
        <!-- Balance for this customer after this order was processed, e.g. when settlement failed or order is overpaid -->
        <!-- gt 0 means customer owes, lt 0 means overpaid -->
        <Balance>0.00</Balance>
        <TaxInformation><!-- copy from avalara --></TaxInformation>
    </OrderHeader>
    <OrderDetails>
      <OrderDetail>
        <SalesOrderItemId>5c387c74-93cc-4dfe-95fe-7a5a15bdac24</SalesOrderItemId>
        <!-- reference to the corresponding InvoiceDetailID from above -->
        <InvoiceDetailID></InvoiceDetailID>
        <SKU>platinum-blue-stripes-blue-size-M</SKU>
        <ProductName>Platinum Blue Stripes Easy Care Fitted Shirt</ProductName>
        <ProductDescription>Love our easy care solid shirting? Then give our stripes a try! This subtle blue stripe is a nice option to have in your closet for workplace wear and it even has a bit of stretch for extra comfort.","description":"Love our easy care solid shirting? Then give our stripes a try! This subtle blue stripe is a nice option to have in your closet for workplace wear and it even has a bit of stretch for extra comfort.</ProductDescription>
        <GTIN>008884303989</GTIN>
        <UPC>8884303989</UPC>
        <!-- Serial numbers of all individual items in the whole quantity of this line item -->
        <SerialNumbers>
          <SerialNumber></SerialNumber>
        </SerialNumbers>
        <!-- 0 = Unit, others to be defined -->
        <UnitOfMeasure>0</UnitOfMeasure>
        <Quantity>1</Quantity>
        <!-- for total quantity -->
        <TotalPrice>112.00</TotalPrice>
        <!-- for quantity 1 -->
        <UnitPrice>112.00</UnitPrice>
        <NetPrice>100.00></NetPrice>
        <TaxAmount>12.00</TaxAmount>
        <DiscountAmount></DiscountAmount>
        <!-- OrderStatus, 'closed' when everything is delivered and captured and the invoice record is written -->
        <!-- Can be different, when OrderLines not fulfilled/closed yet but requested to be included in the export -->
        <LineStatus>10</LineStatus>
        <!-- monetary amount; where applicable, e.g. not for discounts on shipping -->
        <LineDiscount>10.00</LineDiscount>
        <TaxInformation><!-- copy from avalara --></TaxInformation>
      </OrderDetail>
      <OrderDetail>
        <!-- ... -->
      </OrderDetail>
    </OrderDetails>
    <ShipmentInformation>
      <!-- List of all individual Shipments for this SalesOrder -->
      <!-- Either:
          1. One shipment for entire order, or
          2. Multiple shipments for an order with complete orderlines in a shipment
          3. Multiple shipments for an orderline
        -->
      <Shipment>
        <ShippedDate></ShippedDate>
        <!-- Numeric Codes for: Same-day, traditional carrier, in-store pickup -->
        <DeliveryMethod></DeliveryMethod>
        <!-- Numeric codes for carriers: UPS, USPS, FedEx, DHL, Deliv, Uber -->
        <Carrier></Carrier>
        <!-- Numeric code for the specific method used by the carrier, e.g. Overnight Express next-day 9am -->
        <CarrierMethod></CarrierMethod>
        <!-- Numeric code for the type of store that that sent this shipment, e.g. regular store, DC, dark store -->
        <StoreType></StoreType>
        <!-- Our internal store ID of the store that sent this shipment -->
        <StoreID></StoreID>
        <ShipToAddress><!-- Insert complete ship-to address here --></ShipToAddress>
        <!-- Code used to access the carrier's tracking information for this shipment -->
        <TrackingCode></TrackingCode>
        <!-- Can be different from the tracking code -->
        <ShipmentNumber></ShipmentNumber>
      </Shipment>
    </ShipmentInformation>
  </SalesOrder>
  <SalesOrder>
    <!-- ... -->
  </SalesOrder>
</FinancialTransactionExport>

https://gist.github.com/tcmb/bcf56d33fd03b3beb1db#file-ft_sample-xml-L8
Can you change the TransactionID to FinancialTransactionID here, please?

https://gist.github.com/tcmb/bcf56d33fd03b3beb1db#file-ft_sample-xml-L133
Here: LogisticOrder to SalesOrder.

Don't know if it's possible or not, but it would make sense, from my point of view, to have here numerical mappings too. What do you think?

The same suggestion goes here

Talking about InvoiceStatus here at line 26 it seems like this is not necessary, as long as we have the demultiplexer transitioning the SalesOrder to sales_order.closed, which in fact means that the order is in the final state, and no other things will happen to it.

Nevertheless, if there are some other ways to use this field, it could make sense to create the FinancialTransaction earlier than sales_order.closed... Can you share some light on that?

@line2sun Good comments, thank you, I changed the sample accordingly.

For the InvoiceStatus, the idea was to have the partial/complete indicator so that we can write the record and mark it as partial even before the SalesOrder is ready for export (complete). Depending on the implementation, we might not need that, i.e. if we only write the record once the SalesOrder is in a final state.

https://gist.github.com/tcmb/bcf56d33fd03b3beb1db#file-ft_sample-xml-L122

Does this mean that there has to be some additional arguments that can be passed to the endpoint for FinancialTransactionExport in order to get the not closed/fulfilled LineItems?
If so, there has to be a subtask for that in place.

https://gist.github.com/tcmb/bcf56d33fd03b3beb1db#file-ft_sample-xml-L12

Is it fine to have a DateTime field here?

Do we really need the date as separate fields here: https://gist.github.com/tcmb/bcf56d33fd03b3beb1db#file-ft_sample-xml-L71 ?

https://gist.github.com/tcmb/bcf56d33fd03b3beb1db#file-ft_sample-xml-L68

I think as long as the FinancialTransaction is binded to a SalesOrder we can't have the DivisionID field in order_header, because the same order can have multiple shipments.

https://gist.github.com/tcmb/bcf56d33fd03b3beb1db#file-ft_sample-xml-L40

Can you explain what is the idea behind having the LogisticOrderItemID here, because from the data perspective it doesn't make any sense.

@line2sun to answer your questions:

https://gist.github.com/tcmb/bcf56d33fd03b3beb1db#file-ft_sample-xml-L122 - At least for now we do not need to provide the possibility to include un-finished items or transactions in an export. This is something that might come for later customers.

https://gist.github.com/tcmb/bcf56d33fd03b3beb1db#file-ft_sample-xml-L12 - This should remain a Date field, as it is literally the date that is printed on the consumer's invoice, which is a date, not a DateTime. There is a separate field TransactionDateTime further down.

https://gist.github.com/tcmb/bcf56d33fd03b3beb1db#file-ft_sample-xml-L71 - It's a courtesy to the 'reader' of the export, to make it easier for them to group by certain attributes (I.e. all transactions from all Decembers for the past 5 years).

https://gist.github.com/tcmb/bcf56d33fd03b3beb1db#file-ft_sample-xml-L68 - You're right, this can't be on the Header level anymore and is safe to be removed. I'll not edit the sample anymore as Alex is now the owner of this.

https://gist.github.com/tcmb/bcf56d33fd03b3beb1db#file-ft_sample-xml-L40 - This should make it easier to track the item for us. In case the 'reader' of the report comes back and asks why X is the case for item Y, we can pull not only the sales order item id but also the logistic order item id directly out of the reports itself.