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>

Did this page help you?