Create Incomplete Courier Order

[This is preliminary documentation and is subject to change.]

This walkthrough is for creating a courier (Purolator, Canada Post, PuroPost) order in multiple steps using AddOrder(OrderRequestV3) to create the order, and AddPackage(AddPackageRequestV3) and/or AddItem(AddItemRequestV3) to update the order information; if you are creating an LTL order then see the LTL walkthrough. This walkthrough assumes that Purolator is handling customs; if you are using a different customs broker then ignore code related to Item data.

Create an order with no packages using AddOrder(OrderRequestV3).

If Purolator is handling customs for the account, then customs information for at least one item is required, otherwise the item information is ignored.

C++

ASP.NET

Copy

CredentialInfo credentials = new CredentialInfo { UserName = "User", Password = "****", ClientID = "0000000" };

OrderRequestV3 orderRequest = new OrderRequestV3
{
    Credentials = credentials,
    ShipToAddress = new Address
    {
        Name       = "Test Customer Name",
        Add1       = "560 Kings Road",
        City       = "Sydney",
        StateProv  = "NS",
        PostalCode = "B1S1B8",
        Country    = "CA"
    },
    OrderNumber    = "Order-13544364-2",
    ShipMethod     = "Purolator Ground",
    LabelType      = "ZPLIMAGES",
    ShipDate       = DateTime.Today,
    // Package data not yet available.
    Items = new List<RequestItemV3>
    {
        new RequestItemV3
        {
            SKU         = "x35135",
            CustomsDesc = "Documents",
            Quantity    = 2,
            TotalValue  = 10,
            Currency    = "CAD",
            CountryOfOrigin = "United States",
        }
    }.ToArray()
};

Dim credentials As CredentialInfo = New CredentialInfo With {.UserName = "User", .Password = "****", .ClientID = "0000000"}

Dim orderRequest As New OrderRequestV3() With {
    .Credentials   = credentials,
    .ShipToAddress = New Address() With {
        .Name       = "Test Customer Name",
        .Add1       = "560 Kings Road",
        .City       = "Sydney",
        .StateProv  = "NS",
        .PostalCode = "B1S1B8",
        .Country    = "CA"
    },
    .OrderNumber    = "Order-13544364-2",
    .ShipMethod     = "Purolator Ground",
    .LabelType      = "ZPLIMAGES",
    .ShipDate       = DateTime.Today,
    ' Package data not available.
    .Items = New List(Of RequestItemV3)() From {
        New RequestItemV3() With {
            .SKU         = "x35135",
            .CustomsDesc = "Documents",
            .Quantity    = 2,
            .TotalValue  = 10,
            .Currency    = "CAD",
            .CountryOfOrigin = "United States"
        }
    }.ToArray()
}

If the response indicated an error, fix the information and repeat step 1.

When complete information for a package (a customer generated unique PackageID, weight, dimensions(optional)) is determined, use an AddPackage(AddPackageRequestV3) request to update the order and then print and attach the label to the package.

C++

ASP.NET

Copy

AddPackageRequest addPackageRequest = new AddPackageRequest
{
    Credentials = credentials,
    OrderNumber = request.OrderNumber,
    Packages = new List<RequestPackageV3>
    {
        new RequestPackageV3 { PackageID = "PKG-13544364-1", WeightUOM = "LB", Weight = 10.0m, },
        new RequestPackageV3 { PackageID = "PKG-13544364-2", WeightUOM = "LB", Weight = 2.34m, },
    }.ToArray(),
    LabelType = "ZPLIMAGES",
};

AddPackageResponse addPackageResponse = client.AddPackage(addPackageRequest);

if (addPackageResponse.Status == (int)SeverityEnum.Error)
{
    foreach (ResponseMessage message in addPackageResponse.Messages)
    {
        switch (message.Number)
        {
            case 1:  // Invalid Credentials
                Console.Write("Invalid Credentials");
                return addPackageResponse;
            case 80: // Duplicate Package Numbers
                for (int index = 0; index < addPackageRequest.Packages.Length; index++)
                    addPackageRequest.Packages[index].PackageID += "-" + (index + 1);
                break;
        }
        // Add cases to fix other errors....
    }

    addPackageResponse = client.AddPackage(addPackageRequest);
    if (addPackageResponse.Status == (int)SeverityEnum.Error)
        return null;
}

Dim addPackageRequest As New AddPackageRequest() With {
    .Credentials = credentials,
    .OrderNumber = request.OrderNumber,
    .Packages = New List(Of RequestPackageV3)() From {
        New RequestPackageV3() With { .PackageID = "PKG-13544364-1", .WeightUOM = "LB", .Weight = 10.0 },
        New RequestPackageV3() With { .PackageID = "PKG-13544364-2", .WeightUOM = "LB", .Weight = 2.34 }
    }.ToArray(),
    .LabelType = "ZPLIMAGES"
}

Dim addPackageResponse As AddPackageResponse = client.AddPackage(addPackageRequest)

If addPackageResponse.Status = CInt(SeverityEnum.FatalError) Then
    For Each message As ResponseMessage In addPackageResponse.Messages
        Select Case message.Number
            Case 1  ' Invalid Credentials
                Console.Write("Invalid Credentials")
                Return addPackageResponse
            Case 80 ' Duplicate Package Numbers
                For index As Integer = 0 To addPackageRequest.Packages.Length - 1
                    addPackageRequest.Packages(index).PackageID += "-" & (index + 1)
                Next
                Exit Select
            ' Add cases to fix other errors....
        End Select
    Next

    addPackageResponse = client.AddPackage(addPackageRequest)
    If addPackageResponse.Status = CInt(SeverityEnum.FatalError) Then
        Return Nothing
    End If
End If

Print and apply the label for each package. See ZPL page for more information.

C++

ASP.NET

Copy

foreach (ResponsePackage package in addPackageResponse.Packages)
{
    // This method sends raw ZPL data to the printer using Windows API.
    RawDataPrinterHelper.SendStringToPrinter(zplPrinterName, package.ZPLCode);
}

For Each package As ResponsePackage In addPackageResponse.Packages
    ' This method sends raw ZPL data to the printer using Windows API.
    RawDataPrinterHelper.SendStringToPrinter(zplPrinterName, package.ZPLCode)
Next

If any additional customs item information needs to be added, AddItem(AddItemRequestV3) can be used to add item information.

C++

ASP.NET

Copy

AddItemRequest addItemRequest = new AddItemRequest
{
    Credentials = credentials,
    OrderNumber = request.OrderNumber,
    Items = new List<RequestItemV3>
    {
        new RequestItemV3
        {
            SKU         = "x35135",
            CustomsDesc = "Documents",
            Quantity    = 3,
            TotalValue  = 2.35m,
            Currency    = "CAD",
            CountryOfOrigin = "United States",
        },
    }.ToArray()
};

AddItemResponse addItemResponse = client.AddItem(addItemRequest);

if (addItemResponse.Status == (int)SeverityEnum.Error)
{
    foreach (ResponseMessage message in addItemResponse.Messages)
    {
        switch (message.Number)
        {
            case 1:  // Invalid Credentials
                Console.Write("Invalid Credentials");
                return;
            case 60: // SKU is required.
                foreach (RequestItemV3 requestItem in addItemRequest.Items.Where(item => string.IsNullOrEmpty(item.SKU)))
                    if (requestItem.CustomsDesc == "Documents")
                        requestItem.SKU = "x35135";
                break;
        }
        // Add cases to fix other errors....
    }

    addItemResponse = client.AddItem(addItemRequest);
    if (addItemResponse.Status == (int)SeverityEnum.Error)
        return;
}

Dim addItemRequest As New AddItemRequest() With {
    .Credentials = credentials,
    .OrderNumber = request.OrderNumber,
    .Items = New List(Of RequestItemV3)() From {
        New RequestItemV3() With {
            .SKU         = "x35135",
            .CustomsDesc = "Documents",
            .Quantity    = 3,
            .TotalValue  = 2.35,
            .Currency    = "CAD",
            .CountryOfOrigin = "United States"
        }
    }.ToArray()
}

Dim addItemResponse As AddItemResponse = client.AddItem(addItemRequest)

If addItemResponse.Status = CInt(SeverityEnum.FatalError) Then
    For Each message As ResponseMessage In addItemResponse.Messages
        Select Case message.Number
            Case 1  ' Invalid Credentials
                Console.Write("Invalid Credentials")
                Return
            Case 60 ' SKU is required.
                For Each requestItem As RequestItemV3 In addItemRequest.Items.Where(Function(item) String.IsNullOrEmpty(item.SKU))
                    If requestItem.CustomsDesc = "Documents" Then
                        requestItem.SKU = "x35135"
                    End If
                Next
                Exit Select
            ' Add cases to fix other errors....
        End Select
    Next

    addItemResponse = client.AddItem(addItemRequest)
    If addItemResponse.Status = CInt(SeverityEnum.FatalError) Then
        Return
    End If
End If

When all orders have the correct labels attached and are ready to ship, create a Closeout to complete processing. See the Closeout page for more information.