Order Confirmation File
Introduction
This page describes the properties and format of Order Confirmation files sent by Blackhawk Network to distribution partner via secure FTP Server. Blackhawk Network will send one file in response for each dropship order received.
File Naming Convention
<partner name>_dropshiporderconfirmation_<externaldropshipid>_GUID.xml
Example: Giftcardmall_dropshipprderconfirmation_NM0115_SSXCWNVN9MLM2N5PSZXH3BQ0S4.xml
File Frequency
Order confirmation will be sent out within the SLA limit agreed with the distribution partner. Typically this is within 1 Hour.
XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified">
<xs:element name="dropshiporderconfirmation">
<xs:annotation>
<xs:documentation>This notification is sent to acknowledge that an
order was received and either successfully processes (in which case
a bhnordernumber is returned) or rejected (in which case a message
with reason code is returned.)
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:all>
<xs:element ref="version" />
<xs:element ref="externaldropshipid" minOccurs='0' />
<xs:element ref="partneridentifier" minOccurs='0' />
<xs:element ref="status" />
<xs:element ref="reasonforrejection" minOccurs='0' />
<xs:element ref="orders" minOccurs='0' />
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="version">
<xs:annotation>
<xs:documentation>Mandatory</xs:documentation>
<xs:documentation>Version of the spec </xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:pattern value="3.0" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="externaldropshipid">
<xs:annotation>
<xs:documentation>This id will be the same externaldropshipid, which
we recieved in the order request file. It is a string identifier
specific to a file
</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:string">
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="partneridentifier">
<xs:annotation>
<xs:documentation>Optional</xs:documentation>
<xs:documentation>BHN will issue an identifier to identify the
Distribution Partner
</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:whiteSpace value="collapse" />
<xs:minLength value="1" />
<xs:maxLength value="50" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="status">
<xs:annotation>
<xs:documentation> (Mandatory) Dropship Order request is either
'accepted', 'rejected' or 'partial'
</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="accepted" />
<xs:enumeration value="rejected" />
<xs:enumeration value="partial" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="orders">
<xs:annotation>
<xs:documentation>Multiple orders listed. This is a collection of
orders.
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element ref="order" minOccurs='0' maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="order">
<xs:annotation>
<xs:documentation>Each order will have multiple line items. The
status of the order can be accepted/rejected or partial
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:all>
<xs:element ref="partnerordernumber" minOccurs='0' />
<xs:element name="status" type="orderstatus" />
<xs:element ref="reasonforrejection" minOccurs='0' />
<xs:element ref="bhnordernumber" minOccurs='0' />
<xs:element ref="totalcards" minOccurs='0' />
<xs:element ref="totalloadvalue" minOccurs='0' />
<xs:element ref="ispartialorder" />
<xs:element ref="items" minOccurs='0' />
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="partnerordernumber">
<xs:annotation>
<xs:documentation>Optional</xs:documentation>
<xs:documentation> The Partner reference to the order request.
</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:whiteSpace value="collapse" />
<xs:minLength value="1" />
<xs:maxLength value="30" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="ispartialorder">
<xs:annotation>
<xs:documentation> (Mandatory) if order is partially fulfilled.
</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="true" />
<xs:enumeration value="false" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="reasonforrejection">
<xs:annotation>
<xs:documentation>
Contains a complete list of ALL errors in the order
request that failed either 1 or more of the validation rules.
Each
error will be comma-separated.
E.g.,
"
Error with zip code on lineN.
Invalid format.;
Error with NameOnCard on line 22. Invalid Length.;
Error with NameOnCard on line 22. Accent not supported.;
Error with
NameOnCard with trackingkey 123456789; Error Code; Invalid
productupc.;
"
</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:string">
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="bhnordernumber">
<xs:annotation>
<xs:documentation>(Optional) BHN generated Order Number.
</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:string">
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="totalcards">
<xs:annotation>
<xs:documentation>Optional</xs:documentation>
<xs:documentation>to be used by BHN to validate order.
</xs:documentation>
<xs:documentation>Inbound request and Outbound confirmation must
include the same value of totalcards
</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:union>
<xs:simpleType>
<xs:restriction base='xs:string'>
<xs:length value="0" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType>
<xs:restriction base="xs:int">
</xs:restriction>
</xs:simpleType>
</xs:union>
</xs:simpleType>
</xs:element>
<xs:element name="totalloadvalue">
<xs:annotation>
<xs:documentation>Optional</xs:documentation>
<xs:documentation>to be used by BHN to validate order.
</xs:documentation>
<xs:documentation>Inbound request and Outbound confirmation must
include the same value of totalcards
</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base='xs:string'>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="items">
<xs:complexType>
<xs:sequence>
<xs:element ref="item" minOccurs='1' maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="item">
<xs:complexType>
<xs:all>
<xs:element ref="partnerorderlineitemidentifier"
minOccurs='0' />
<xs:element ref="bhnorderlineitemidentifier" />
<xs:element ref="productidentifier" minOccurs='0' />
<xs:element ref="partnersku" minOccurs='0' />
<xs:element ref="productupc" minOccurs='0' />
<xs:element ref="quantity" />
<xs:element name="status" type="orderstatus" />
<xs:element ref="reasonforrejection" minOccurs='0' />
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="partnerorderlineitemidentifier">
<xs:annotation>
<xs:documentation>(Optional) This is the Partner reference for the
order line item
</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="100" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="bhnorderlineitemidentifier">
<xs:annotation>
<xs:documentation>(Mandatory) BHN generated Order line item Number.
</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:string">
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="productidentifier">
<xs:annotation>
<xs:documentation>(Optional) This is the identifier of the
gift/reward card product
</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:whiteSpace value="collapse" />
<xs:maxLength value="100" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="partnersku">
<xs:annotation>
<xs:documentation>Optional</xs:documentation>
<xs:documentation>Partner SKU </xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="100" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="productupc">
<xs:annotation>
<xs:documentation>Optional</xs:documentation>
<xs:documentation>Product UPC </xs:documentation>
<xs:documentation>BHN assigned product upc</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="100" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="quantity">
<xs:annotation>
<xs:documentation>Mandatory</xs:documentation>
<xs:documentation>Quantity of card requested</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:int">
<xs:minInclusive value="1" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:simpleType name="orderstatus">
<xs:annotation>
<xs:documentation> (Mandatory) order or item status is either
'accepted' or 'rejected'
</xs:documentation>
</xs:annotation>
<xs:restriction base="xs:string">
<xs:enumeration value="accepted" />
<xs:enumeration value="rejected" />
</xs:restriction>
</xs:simpleType>
</xs:schema>
Sample File
<?xml version="1.0" encoding="UTF-8"?>
<dropshiporderconfirmation>
<version>3.0</version>
<externaldropshipid>BUGMHO</externaldropshipid>
<partneridentifier>ORDERCENTRAL10</partneridentifier>
<status>accepted</status>
<orders>
<order>
<partnerordernumber>XM5WV0</partnerordernumber>
<status>accepted</status>
<bhnordernumber>2077702</bhnordernumber>
<totalcards>1</totalcards>
<totalloadvalue>50.0</totalloadvalue>
<ispartialorder>false</ispartialorder>
<items>
<item>
<partnerorderlineitemidentifier>100001</partnerorderlineitemidentifier>
<bhnorderlineitemidentifier>073QBYPX57VHDYLTHY21GKA7TR</bhnorderlineitemidentifier>
<productidentifier>36988</productidentifier>
<quantity>1</quantity>
<status>accepted</status>
</item>
</items>
</order>
</orders>
</dropshiporderconfirmation>
Updated 7 months ago