Show / Hide Table of Contents

    Quotes Flow

    • v1
    • pro
    • api
    • consignments
    • flows
    • quotes

    The Quotes flow is intended as a back-end customer service integration to help you resolve delivery issues that require manual intervention. In this flow, a consignment is created and then allocated to a carrier service based on a specific quote for that consignment.

    The Quotes flow is useful to your business for:

    • Customer contact centre use.
    • In store delivery booking.
    • ERP workflows (e.g. SAP, Oracle).

    There are five steps to the flow:

    1. Create the consignment - Use the Create Consignment endpoint to record the details of a new consignment.
    2. Get quotes for the consignment - Use the Get Quotes by Consignment Reference endpoint to get delivery quotes for the consignment.
    3. Select a quote - Use the Allocate With Quote endpoint to select one of the returned quotes.
    4. Get the consignment's labels - Use the Get Labels in Format endpoint to get the delivery label for your consignment.
    5. Manifest the consignment - Use the Manifest Consignments from Query endpoint to send consignment data to the selected carrier.

    This section gives more detail on each step of the flow and provides worked examples.


    Step 1: Creating Consignments

    • Create Consignments Endpoint
    POST https://api.electioapp.com/consignments
    

    The first step toward manifesting a consignment is to create that consignment in Ship.

    Consignments are created using the Create Consignment endpoint, which takes information about new consignments, adds them to the database, and returns a link to the newly-created consignment, including its {consignmentReference}. A newly created consignment has a {consignmentState} of Unallocated.

    As a minimum, the Create Consignments endpoint requires you to send package weights and dimensions, origin address, and destination address data.

    Note
    • For full reference information on the Create Consignment endpoint, see the Create Consignment page of the API reference.
    • For a user guide explaining the Create Consignment endpoint, see the Creating New Consignments page.

    Create Consignments Example

    These examples show the creation of a fairly standard consignment. In this case, we have an outbound consignment comprising a single package with a single item inside it.

    After receiving the request, Ship returns a {consignmentReference} of EC-000-05B-MMA. Many of Ship's functions require you to provide a {consignmentReference} as a parameter. Therefore, you should store the {consignmentReference} for later use.

    • Create Consignments Request
    • Create Consignments Response

    POST https://api.electioapp.com/consignments

    {
      "ConsignmentReferenceProvidedByCustomer": "MYCONS-098998",
      "Source": "Api",
      "MetaData": [
        {
          "KeyValue": "Restock_Date",
          "DateTimeValue": "2019-06-18T00:00:00+00:00"
        }
      ],
      "Packages": [
        {
          "Items": [
            {
              "Sku": "SKU093434",
              "Model": "ITM-002",
              "Description": "Striped Bamboo Red/White",
              "CountryOfOrigin": {
                "IsoCode": {
                  "TwoLetterCode": "GB"
                }
              },
              "HarmonisationCode": "Harmonisation_Code",
              "Weight": {
                "Value": 0.5,
                "Unit": "Kg"
              },
              "Dimensions": {
                "Unit": "Cm",
                "Width": 10.0,
                "Length": 10.0,
                "Height": 10.0
              },
              "Value": {
                "Amount": 5.99,
                "Currency": {
                  "IsoCode": "GBP"
                }
              },
              "ItemReferenceProvidedByCustomer": "ITEMREF-098",
              "Barcode": {
                "Code": "09887-091221",
                "BarcodeType": "Code39"
              },
              "MetaData": [
                {
                  "KeyValue": "Picker",
                  "StringValue": "David Thomas"
                }
              ],
              "Quantity": 1,
              "Unit": "Box",
              "HarmonisationKeyWords": [
                "Keyword1"
              ],
              "ContentClassification": "Unrestricted",
              "ContentClassificationDetails": "NotSpecified"
            }
          ],
          "PackageReferenceProvidedByCustomer": "MYPACK-00923",
          "Weight": {
            "Value": 0.5,
            "Unit": "Kg"
          },
          "Dimensions": {
            "Unit": "Cm",
            "Width": 10.0,
            "Length": 10.0,
            "Height": 10.0
          },
          "Description": "Socks",
          "Value": {
            "Amount": 5.99,
            "Currency": {
              "IsoCode": "GBP"
            }
          },
          "Barcode": {
            "Code": "09887-091221",
            "BarcodeType": "Code39"
          },
          "MetaData": [
            {
              "KeyValue": "WMS-REF",
              "IntValue": 77656555
            }
          ]
        }
      ],
      "CustomsDocumentation": {
        "DesignatedPersonResponsible": "Peter McPetersson",
        "ImportersVatNumber": "02345555",
        "CategoryType": "Other",
        "ShipperCustomsReference": "CREF0001",
        "ImportersTaxCode": "TC001",
        "ImportersTelephone": "0161123456",
        "ImportersFax": "01611124547",
        "ImportersEmail": "peter.mcpetersson@test.com",
        "CN23Comments": "Comments",
        "ReferencesOfAttachedInvoices": [
          "INV001"
        ],
        "ReferencesOfAttachedCertificates": [
          "CERT001"
        ],
        "ReferencesOfAttachedLicences": [
          "LIC001"
        ],
        "CategoryTypeExplanation": "Explanation",
        "DeclarationDate": "2019-06-14T00:00:00+00:00",
        "OfficeOfPosting": "Manchester",
        "ReasonForExport": "Sale",
        "ShippingTerms": "CFR",
        "ShippersVatNumber": "874541414",
        "ReceiversTaxCode": "TC5454",
        "ReceiversVatNumber": "8745474",
        "InvoiceDate": "2019-06-14T00:00:00+00:00"
      },
      "Addresses": [
        {
          "AddressType": "Origin",
          "ShippingLocationReference": "EDC5_Electio",
          "IsCached": false
        },
        {
          "AddressType": "Destination",
          "Contact": {
            "Title": "Mr",
            "FirstName": "Peter",
            "LastName": "McPetersson",
            "Telephone": "07702123456",
            "Mobile": "07702123456",
            "LandLine": "0161544123",
            "Email": "peter.mcpetersson@test.com"
          },
          "CompanyName": "Test Company (UK) Ltd.",
          "AddressLine1": "13 Porter Street",
          "AddressLine2": "Pressington",
          "AddressLine3": "Carlsby",
          "Town": "Manchester",
          "Region": "Greater Manchester",
          "Postcode": "M1 5WG",
          "Country": {
            "Name": "Great Britain",
            "IsoCode": {
              "TwoLetterCode": "GB"
            }
          },
          "SpecialInstructions": "Gate code: 4454",
          "LatLong": {
            "Latitude": 53.474220,
            "Longitude": -2.246049
          },
          "IsCached": false
        }
      ],
      "Direction": "Outbound"
    }
    
    [
      {
        "Rel": "Link",
        "Href": "https://api.electioapp.com/consignments/EC-000-05B-MMA"
      }
    ]
    

    Step 2: Getting Quotes by Consignment Reference

    • Get Quotes by Consignment Reference Endpoint
    GET https://api.electioapp.com/quotes/consignment/{consignmentReference}
    

    Once you've created a consignment, you'll need to use the Get Quotes by Consignment Reference endpoint to get some delivery quotes for it.

    Get Quotes by Consignment Reference returns quotes based on the details of an existing consignment. Specifically, it takes a {consignmentReference} as a path parameter and returns an array of {Quotes} for that consignment, as well as a list of services that were unable to quote for the consignment.

    Note
    • For full reference information on the Get Quotes by Consignment Reference endpoint, see the Get Quotes by Consignment Reference page of the API reference.
    • For a user guide on quotes in Ship, see the Managing Quotes section.

    Get Quotes By Consignment Reference Example

    The example shows a Get Quotes by Consignment Reference request and its accompanying response. In this case, Ship has returned two quotes for the service. The next step in the process is to select one of those quotes.

    • Get Quotes by Consignment Reference Request
    • Get Quotes by Consignment Reference Response
    https://api.electioapp.com/quotes/consignment/EC-000-05B-1CM
    
    {
        "QuoteRequestReference": "6f9c7ee5-a97e-4df9-bc07-aa3f00e99316",
        "Quotes": [
            {
                "MpdCarrierServiceSource": 2,
                "MpdCarrierService": "1st and 2nd Class Account Mail (1st Parcel)",
                "OriginAddress": {
                    "ShippingLocationReference": "EDC5_Electio",
                    "AddressLine1": "Third Floor",
                    "AddressLine2": "Merchant Exchange",
                    "AddressLine3": "Whitworth Street West",
                    "Town": "Manchester",
                    "Region": "",
                    "Postcode": "M1 5WG",
                    "Country": {
                        "Name": "United Kingdom",
                        "IsoCode": {
                            "TwoLetterCode": "GB",
                            "ThreeLetterCode": "GBR",
                            "NumericCode": "826"
                        }
                    },
                    "RegionCode": "",
                    "SpecialInstructions": "",
                    "IsCached": false
                },
                "DestinationAddress": {
                    "AddressLine1": "13 Porter Street",
                    "AddressLine2": "Pressington",
                    "AddressLine3": "Carlsby",
                    "Town": "Manchester",
                    "Region": "Greater Manchester",
                    "Postcode": "M1 5WG",
                    "Country": {
                        "Name": "United Kingdom",
                        "IsoCode": {
                            "TwoLetterCode": "GB",
                            "ThreeLetterCode": "GBR",
                            "NumericCode": "826"
                        }
                    },
                    "SpecialInstructions": "Gate code: 4454",
                    "IsCached": false
                },
                "CollectionDate": "2019-05-01T00:00:00",
                "EarliestDeliveryDate": "2019-05-02T00:00:00",
                "LatestDeliveryDate": "2019-05-02T23:59:00",
                "BasePrice": {
                    "Net": 27.69,
                    "Gross": 33.23,
                    "VatRate": {
                        "Reference": "GB-0.2000",
                        "CountryIsoCode": "GB",
                        "Type": "Standard",
                        "Rate": 0.2
                    },
                    "VatAmount": 5.54,
                    "Currency": {
                        "Name": "Pound Sterling",
                        "IsoCode": "GBP"
                    }
                },
                "Price": {
                    "Net": 27.69,
                    "Gross": 33.23,
                    "VatRate": {
                        "Reference": "GB-0.2000",
                        "CountryIsoCode": "GB",
                        "Type": "Standard",
                        "Rate": 0.2
                    },
                    "VatAmount": 5.54,
                    "Currency": {
                        "Name": "Pound Sterling",
                        "IsoCode": "GBP"
                    }
                },
                "Surcharges": [],
                "Legs": [
                    {
                        "JourneyStage": 1,
                        "CarrierService": {
                            "Reference": "RMDBPR1STPSU",
                            "Name": "1st and 2nd Class Account Mail (1st Parcel)",
                            "CarrierReference": "ROYAL_MAIL",
                            "CarrierName": null,
                            "IsDropOff": false,
                            "IsPickUp": false,
                            "IsTimed": false
                        },
                        "CarrierAccountReference": "RM1",
                        "DeliveryHub": null,
                        "CostItems": null,
                        "VolumetricParcelWeight": null,
                        "CollectionType": "NotApplicable"
                    }
                ],
                "CarrierAccountOwner": null,
                "IsElectioService": false,
                "QuoteReference": "f6374a18-a6b5-48c1-841c-aa3f00e9951a",
                "CreationDate": "2019-04-30T14:10:26.8551633+00:00",
                "ExpiryDate": "2019-05-01T00:00:00+01:00",
                "Requestor": "Andy Walton",
                "ConsignmentReference": "EC-000-05B-1CM",
                "ConsignmentReferenceProvidedByCustomer": "",
                "MpdCarrierServiceReference": "MPD_RMDBPR1STPSU"
            },
            {
                "MpdCarrierServiceSource": 2,
                "MpdCarrierService": "Tracked 48 Signed For",
                "OriginAddress": {
                    "ShippingLocationReference": "EDC5_Electio",
                    "AddressLine1": "Third Floor",
                    "AddressLine2": "Merchant Exchange",
                    "AddressLine3": "Whitworth Street West",
                    "Town": "Manchester",
                    "Region": "",
                    "Postcode": "M1 5WG",
                    "Country": {
                        "Name": "United Kingdom",
                        "IsoCode": {
                            "TwoLetterCode": "GB",
                            "ThreeLetterCode": "GBR",
                            "NumericCode": "826"
                        }
                    },
                    "RegionCode": "",
                    "SpecialInstructions": "",
                    "IsCached": false
                },
                "DestinationAddress": {
                    "AddressLine1": "13 Porter Street",
                    "AddressLine2": "Pressington",
                    "AddressLine3": "Carlsby",
                    "Town": "Manchester",
                    "Region": "Greater Manchester",
                    "Postcode": "M1 5WG",
                    "Country": {
                        "Name": "United Kingdom",
                        "IsoCode": {
                            "TwoLetterCode": "GB",
                            "ThreeLetterCode": "GBR",
                            "NumericCode": "826"
                        }
                    },
                    "SpecialInstructions": "Gate code: 4454",
                    "IsCached": false
                },
                "CollectionDate": "2019-05-01T00:00:00",
                "EarliestDeliveryDate": "2019-05-03T00:00:00",
                "LatestDeliveryDate": "2019-05-03T23:59:00",
                "BasePrice": {
                    "Net": 27.69,
                    "Gross": 33.23,
                    "VatRate": {
                        "Reference": "GB-0.2000",
                        "CountryIsoCode": "GB",
                        "Type": "Standard",
                        "Rate": 0.2
                    },
                    "VatAmount": 5.54,
                    "Currency": {
                        "Name": "Pound Sterling",
                        "IsoCode": "GBP"
                    }
                },
                "Price": {
                    "Net": 27.69,
                    "Gross": 33.23,
                    "VatRate": {
                        "Reference": "GB-0.2000",
                        "CountryIsoCode": "GB",
                        "Type": "Standard",
                        "Rate": 0.2
                    },
                    "VatAmount": 5.54,
                    "Currency": {
                        "Name": "Pound Sterling",
                        "IsoCode": "GBP"
                    }
                },
                "Surcharges": [],
                "Legs": [
                    {
                        "JourneyStage": 1,
                        "CarrierService": {
                            "Reference": "RMDTPS48HNAST",
                            "Name": "Tracked 48 Signed For",
                            "CarrierReference": "ROYAL_MAIL",
                            "CarrierName": null,
                            "IsDropOff": false,
                            "IsPickUp": false,
                            "IsTimed": false
                        },
                        "CarrierAccountReference": "RM1",
                        "DeliveryHub": null,
                        "CostItems": null,
                        "VolumetricParcelWeight": null,
                        "CollectionType": "NotApplicable"
                    }
                ],
                "CarrierAccountOwner": null,
                "IsElectioService": false,
                "QuoteReference": "f63bd4ab-d519-4547-b361-aa3f00e9951a",
                "CreationDate": "2019-04-30T14:10:26.8551633+00:00",
                "ExpiryDate": "2019-05-01T00:00:00+01:00",
                "Requestor": "Andy Walton",
                "ConsignmentReference": "EC-000-05B-1CM",
                "ConsignmentReferenceProvidedByCustomer": "",
                "MpdCarrierServiceReference": "MPD_RMDTPS48HNAST"
            }
        ],
        "Message": null,
        "UnqualifiedServices": [
            {
                "Available": true,
                "Rates": false,
                "MpdCarrierService": "acceptanceTestCarrier_825d",
                "MpdCarrierServiceReference": "acceptanceTestCarrier_f8fe",
                "ExclusionReason": "No cost and/or pricing data configured"
            },
            {
                "Available": false,
                "Rates": false,
                "MpdCarrierService": "Express With Signature Parcel",
                "MpdCarrierServiceReference": "MPD_ANPOS-00001",
                "ExclusionReason": "This service is not available for the selected collection/delivery dates."
            },
            {
                "Available": false,
                "Rates": true,
                "MpdCarrierService": "Next Day Monday - Saturday",
                "MpdCarrierServiceReference": "MPD_MNZIS-00001",
                "ExclusionReason": "This service is not available between the selected addresses."
            },
            {
                "Available": true,
                "Rates": false,
                "MpdCarrierService": "UPS EXPRESS (Delivery Confirmation Signature Required)",
                "MpdCarrierServiceReference": "EDC5_UPSHEXDCS",
                "ExclusionReason": "No cost and/or pricing data configured"
            },
            {
                "Available": true,
                "Rates": false,
                "MpdCarrierService": "UPS EXPRESS (Saturday Delivery, Delivery Confirmation Signature Required)",
                "MpdCarrierServiceReference": "EDC5_UPSHEXSDDCS",
                "ExclusionReason": "No cost and/or pricing data configured"
            },
            {
                "Available": true,
                "Rates": false,
                "MpdCarrierService": "UPS EXPRESS PLUS (Delivery Confirmation Signature Required)",
                "MpdCarrierServiceReference": "EDC5_UPSHEP",
                "ExclusionReason": "No cost and/or pricing data configured"
            },
            {
                "Available": true,
                "Rates": false,
                "MpdCarrierService": "UPS SAVER (Delivery Confirmation Signature Required)",
                "MpdCarrierServiceReference": "EDC5_UPSHSADCS",
                "ExclusionReason": "No cost and/or pricing data configured"
            },
            {
                "Available": true,
                "Rates": false,
                "MpdCarrierService": "UPS STANDARD (Delivery Confirmation Signature Required)",
                "MpdCarrierServiceReference": "EDC5_UPSHSTDCS",
                "ExclusionReason": "No cost and/or pricing data configured"
            },
            {
                "Available": false,
                "Rates": false,
                "MpdCarrierService": "wnDirect International Economy",
                "MpdCarrierServiceReference": "MPD_WNDECOM",
                "ExclusionReason": "This service is not available between the selected addresses. This service is not available for the given package dimensions/weight."
            }
        ]
    }
    

    Step 3: Selecting a Quote

    • Allocate with Quote Endpoint
    PUT https://api.electioapp.com/allocation/{consignmentReference}/allocatewithquote/{quoteReference}
    

    To allocate an individual consignment based on a specific delivery quote from a carrier, use the Allocate With Quote endpoint.

    The Allocate With Quote endpoint takes the {consignmentReference} of the consignment you want to allocate and the {quoteReference} of a particular quote. Once the request is received Ship attempts to allocate the consignment to the carrier service specified in the quote, and returns an Allocation Summary.

    Note
    • For full reference information on the Allocate With Quote endpoint, see the Allocate With Quote page of the API reference.
    • For a user guide on allocating to specific delivery quotes, see the Allocating to a Specific Quote page.

    Allocate With Quote Example

    The example shows a request to allocate a consignment with a {consignmentReference} of EC-000-05B-N40 to the carrier service associated with a quote that has the {quoteReference} 112236d5-4460-492f-a6bd-aa3f00f62dfb.

    • Allocate with Quote Request
    • Allocate with Quote Response
    PUT https://api.electioapp.com/allocation/EC-000-05B-N40/allocatewithquote/112236d5-4460-492f-a6bd-aa3f00f62dfb
    
    [
        {
            "StatusCode": 200,
            "ApiLinks": [
                {
                    "Rel": "detail",
                    "Href": "https://apisandbox.electioapp.com/consignments/EC-000-05B-N40"
                },
                {
                    "Rel": "label",
                    "Href": "https://apisandbox.electioapp.com/labels/EC-000-05B-N40"
                }
            ],
            "Description": "Consignment EC-000-05B-N40 has been successfully allocated with UPS STANDARD (Delivery Confirmation Signature Required) for shipping on 18/06/2019 17:00:00 +00:00",
            "ConsignmentLegs": [
                {
                    "Leg": 1,
                    "TrackingReferences": [
                        "1Z9A80W5DK96293164"
                    ],
                    "CarrierReference": "UPS",
                    "CarrierServiceReference": null,
                    "CarrierName": "UPS"
                }
            ],
            "CarrierReference": "UPS",
            "CarrierName": "UPS",
            "CarrierServiceReference": "EDC5_UPSHSTDCS",
            "CarrierServiceName": "UPS STANDARD (Delivery Confirmation Signature Required)"
        }
    ]
    

    Step 4: Getting Consignment Labels

    • Get Labels in Format Endpoint
    GET https://api.electioapp.com/labels/{consignmentReference}/{labelFormat}
    

    When a consignment is allocated, Ship generates labels for each package in that consignment. You can retrieve these delivery labels via the Get Labels in Format endpoint.

    The Get Labels in Format endpoint takes a {consignmentReference} and {labelFormat} as path parameters. Ship returns all package labels associated with that consignment as a base64-encoded byte array that decodes to the format requested.

    Note
    • For full reference information on the Get Labels in Format endpoint, see the Get Labels in Format page of the API reference.
    • For a user guide on retrieving labels in Ship, see the Getting Labels page.

    Get Labels in Format Example

    The example shows a request to get PDF labels for a consignment with a {consignmentReference} of EC-000-05B-MMA. The file data in the response has been truncated for clarity.

    You will need to decode the File's Base64 data in order to view or print the label. If you are unsure how to do so, see the MDN docs for more information.

    • Get Labels in Format Request
    • Get Labels in Format Response
    GET https://api.electioapp.com/labels/EC-000-05B-MMA/pdf
    
    {
      "File": "SlZCRVJpMHhMalFLSmRQcjZ ... TVRrNU9ERUtKU1ZGVDBZPQ==",
      "ContentType": "application/pdf"
    }
    

    Step 5: Manifesting a Consignment

    • Manifest Consignments From Query Endpoint
    PUT https://api.electioapp.com/consignments/manifestFromQuery
    

    Once you've created a consignment, allocated it to a carrier service and printed labels for it, you're ready to manifest it. To manifest a consignment, use the Manifest Consignments From Query endpoint. In the context of Ship, the term "manifesting" refers to collating, formatting and transmitting the consignment data to carriers.

    The Manifest Consignments From Query endpoint enables you to use a query to select consignments to be manifested. Once Ship has added those consignments to a manifest and queued the data to be sent, the Manifest Consignments From Query endpoint returns a Message detailing how many consignments met the terms of the query, how many of those consignments were successfully queued, and how many could not be queued.

    Note
    • For full reference information on the Manifest Consignments From Query endpoint, see the Manifest Consignments From Query page of the API Reference.
    • For a user guide on manifesting consignments, see the Manifesting Consignments page.

    Manifest Consignments From Query Example

    The example shows a request to manifest all consignments that are allocated to Carrier X, shipping from a location with the ShippingLocationReference Location1, and have already had their labels printed. The response indicates that Ship found 10 consignments meeting these criteria, and that all 10 were successfully queued for manifest.

    • Manifest Consignments From Query Request
    • Manifest Consignments From Query Response

    PUT https://api.electioapp.com/consignments/manifestFromQuery

    {
      "ShippingLocationReferences": [
        "Location1"
      ],
      "States": [
        "Allocated"
      ],
      "Carriers": [
        "CARRIER_X"
      ],
      "LabelsPrinted": true
    }
    
    {
      "Message": "Query found 10 consignment(s). 10 successfully queued to manifest. 0 failed to be added to the queue"
    }
    
    Back to top Copyright © Sorted Group 2023. Generated by DocFX