New Zealand Couriers Knowledge

Help Centre

    New Zealand Couriers Knowledge

    Help Centre

    GoSweetSpot: Customer Orders

    Updated: 21 Apr 24

    Included in this document:

     

    Get the list of Customer Orders

    Description

    Get the list of customer orders published in the queue. You can filter on processed or non-processed.

    Requests

    Method: GET
    Content Type: application/json
    URL: https://api.gosweetspot.com/api/customerorders

    Headers

    access_key : your unique API key provided by GSS.
    site_id : which site you are requesting action for.

    Parameters

    Parameter Type Description
    packingslipno string Comma separated list of packing slip numbers to apply filter on.
     
    createdfrom string UTC formatted date and time to filter the shipments. This field is for the earliest date.
    createdto string UTC formatted date and time to filter the shipments. This field is for the latest date.
    excludecompleted string true/false - when true excludes all completed packing slips and only returns pending orders.
    page integer when multiple pages of results are available, specify which page to get.
    pagesize integer how many records to return per page. Default = 100 records.
    includeProducts boolean true/false - when true, each customer order record will also include the product lines associated with the record

    Return format

    A JSON Object of available carriers.

    Root Object

    Attribute Type Description
    Page integer index of the page of all results.
    pagesize integer how many records to return per page.
    Pages integer how many pages of results are available.
    Results object list list of customer orders.

    Request example

    curl --location --request DELETE 'https://api.gosweetspot.com/api/customerorders?packingslipno=test%25231234%2Ctest%25231235%2Ctest%25231236' \
--header 'access_key;' \
--header 'site_id;' \
--header 'Content-Type: application/json; charset=utf-8'

curl --location --request DELETE 'https://api.gosweetspot.com/api/customerorders?packingslipno=test%25231234%2Ctest%25231235%2Ctest%25231236' \
--header 'access_key;' \
--header 'site_id;' \
--header 'Content-Type: application/json; charset=utf-8'

    Response example

    {
  "test#1234": "Cannot be deleted. Already processed.",
  "test#1235": "Cannot be deleted. Already deleted.",
  "test#1236": "Deleted.",
}{
  "test#1234": "Cannot be deleted. Already processed.",
  "test#1235": "Cannot be deleted. Already deleted.",
  "test#1236": "Deleted.",
}

     

     

    Input new Customer Orders

    Description

    Submit new customer order batched. Saves a new orders or updates a pending order. If the packing slip number has already been processed, the message will be ignored. This method will accept orders as an array.

    Requests

    Method: PUT
    Content Type: application/json
    URL: https://api.gosweetspot.com/api/customerorders

    Headers

    access_key : your unique API key provided by GSS.
    site_id : which site you are requesting action for.

    Parameters

    Parameter Type Description
    packingslipno string Specify the unique order number from your source system, that was used as the packing slip no when the order was published.
    consignee string Recipient name.
    address1
         		 string Address line 1, eg, building identifier, like Level 1, Fisher House, etc.
    address2
         		 string
         		 Address line 2, street name.
    suburb string
         		 Suburb name.
    city string
         		 City name or state name. Depending on destination country, if state information is available, this should be the abbreviated state code.
    postcode string
         		 Post code, for NZ addresses, this can be left blank if unknown.
    country string
         		 ISO Alpha 2 country code, eg NZ, AU, US, UK, CN.
    delvref string Order number, or customer reference for this order.
    delvinstructions string Any specific instructions to be printed on the label.
    contactname string
         		 Name of person, optional.
    contactphone string Phone number of person, optional.
    email string Email address for track & trace email, optional.
    rawaddress string
         		 Full, unvalidated address body for display purposes only. Use \n for newline in this field, optional.
    costcentre string
         		 Put the exact name of a cost centre here and the cost centre will be pre-selected when fulfilling the order, optional.
    products object list Optional, JSON object of product.
    packages object list Optional, JSON object of package.
    iconUrl string
         		 Optional, custom icon Url link.

    Return format

    JSON object array per order with true for a successful submit or false for an ignored submit.

    Request example

    curl --location 'https://api.gosweetspot.com/api/customerorders?createdfrom=2023-08-01&page=2' \
--header 'access_key;' \
--header 'site_id;' \
--header 'Content-Type: application/json; charset=utf-8'
curl --location 'https://api.gosweetspot.com/api/customerorders?createdfrom=2023-08-01&page=2' \
--header 'access_key;' \
--header 'site_id;' \
--header 'Content-Type: application/json; charset=utf-8'

    Response example

    {
    "Page": 1,
    "PageSize": 100,
    "Pages": 6,
    "Results": [
        {
            "packingslipno": "SSORDER13667",
            "consignee": "LITTLE LAMB",
            "address1": "",
            "address2": "103 HAVENWOOD PLACE",
            "suburb": "BIRKENHEAD",
            "city": "NORTH SHORE CITY",
            "postcode": "0626",
            "country": "NZ",
            "delvref": "SSORDER13667",
            "delvinstructions": "A5SHEET X 1  A5 X 1",
            "contactname": "BROOKES STONE",
            "contactphone": "021 123456",
            "email": "info@littlelamb.co.nz",
            "isrural": null,
            "notrural": null,
            "costcentre": null,
            "status": {
                "Status": "DELIVERED",
                "ticketnumber": "SSPOT018162",
                "trackingurl": "http://gosweetspot.com/track/123-SSPOT018162",
                "Picked": "2016-02-22T15:31:21",
                "Delivered": "2016-02-23T12:46:45",
                "manualticket": true
            },
            "products": [
                {
                    "productcode": "ABC",
                    "description": "WALL PAINT",
                    "units": 1,
                    "unitvalue": 10,
                    "countryofManufacture": "",
                    "unitkg": 1,
                    "imageurl": null,
                    "currency": "NZD",
                    "alreadySent": 0,
                    "fulfilledQty": 1,
                    "linetotal": 10
                }
            ]
        },
        {
            "packingslipno": "SSORDER13668",
            "consignee": "ROCK ON",
            "address1": "",
            "address2": "226 STEWART ROAD",
            "suburb": "RAMARAMA",
            "city": "AUCKLAND",
            "postcode": "2579",
            "country": "NZ",
            "delvref": "SSORDER13668",
            "delvinstructions": "A5 X 2  A4 X 5  OVERNIGHT X 2",
            "contactname": "ALBERT",
            "contactphone": "021212563",
            "email": "albert@rockon.co.nz",
            "isrural": null,
            "notrural": null,
            "costcentre": null,
            "status": {
                "Status": "DELIVERED",
                "ticketnumber": "SSPOT018161",
                "trackingurl": "http://gosweetspot.com/track/4180-SSPOT018161",
                "Picked": "2016-02-22T15:31:21",
                "Delivered": "2016-02-24T08:42:22",
                "manualticket": true
            },
            "products": [
                {
                    "productcode": "ABC",
                    "description": "WALL PAINT",
                    "units": 1,
                    "unitvalue": 10,
                    "countryofManufacture": "",
                    "unitkg": 1,
                    "imageurl": null,
                    "currency": "NZD",
                    "alreadySent": 0,
                    "fulfilledQty": 1,
                    "linetotal": 10
                }
            ]
        },
        {
            "packingslipno": "SSORDER13669",
            "consignee": "PREMIUM BLUE LTD",
            "address1": "5C",
            "address2": "102 ELLICE RD",
            "suburb": "GLENFIELD",
            "city": "NORTH SHORE CITY",
            "postcode": "0629",
            "country": "NZ",
            "delvref": "SSORDER13669",
            "delvinstructions": "A4 X 1  A2 X 1  OVERNIGHT X 1",
            "contactname": "ANDREW BURNS",
            "contactphone": "09 444 2131",
            "email": "andy@blueltd.co.nz",
            "isrural": null,
            "notrural": null,
            "costcentre": null,
            "status": {
                "Status": "DELIVERED",
                "ticketnumber": "SSPOT018160",
                "trackingurl": "http://gosweetspot.com/track/1234-SSPOT018160",
                "Picked": "2016-02-25T15:24:10",
                "Delivered": "2016-02-26T08:11:14",
                "manualticket": true
            },
            "products": [
                {
                    "productcode": "ABC",
                    "description": "WALL PAINT",
                    "units": 1,
                    "unitvalue": 10,
                    "countryofManufacture": "",
                    "unitkg": 1,
                    "imageurl": null,
                    "currency": "NZD",
                    "alreadySent": 0,
                    "fulfilledQty": 1,
                    "linetotal": 10
                }
            ]
        }
    ]
}

 {
    "Page": 1,
    "PageSize": 100,
    "Pages": 6,
    "Results": [
        {
            "packingslipno": "SSORDER13667",
            "consignee": "LITTLE LAMB",
            "address1": "",
            "address2": "103 HAVENWOOD PLACE",
            "suburb": "BIRKENHEAD",
            "city": "NORTH SHORE CITY",
            "postcode": "0626",
            "country": "NZ",
            "delvref": "SSORDER13667",
            "delvinstructions": "A5SHEET X 1  A5 X 1",
            "contactname": "BROOKES STONE",
            "contactphone": "021 123456",
            "email": "info@littlelamb.co.nz",
            "isrural": null,
            "notrural": null,
            "costcentre": null,
            "status": {
                "Status": "DELIVERED",
                "ticketnumber": "SSPOT018162",
                "trackingurl": "http://gosweetspot.com/track/123-SSPOT018162",
                "Picked": "2016-02-22T15:31:21",
                "Delivered": "2016-02-23T12:46:45",
                "manualticket": true
            },
            "products": [
                {
                    "productcode": "ABC",
                    "description": "WALL PAINT",
                    "units": 1,
                    "unitvalue": 10,
                    "countryofManufacture": "",
                    "unitkg": 1,
                    "imageurl": null,
                    "currency": "NZD",
                    "alreadySent": 0,
                    "fulfilledQty": 1,
                    "linetotal": 10
                }
            ]
        },
        {
            "packingslipno": "SSORDER13668",
            "consignee": "ROCK ON",
            "address1": "",
            "address2": "226 STEWART ROAD",
            "suburb": "RAMARAMA",
            "city": "AUCKLAND",
            "postcode": "2579",
            "country": "NZ",
            "delvref": "SSORDER13668",
            "delvinstructions": "A5 X 2  A4 X 5  OVERNIGHT X 2",
            "contactname": "ALBERT",
            "contactphone": "021212563",
            "email": "albert@rockon.co.nz",
            "isrural": null,
            "notrural": null,
            "costcentre": null,
            "status": {
                "Status": "DELIVERED",
                "ticketnumber": "SSPOT018161",
                "trackingurl": "http://gosweetspot.com/track/4180-SSPOT018161",
                "Picked": "2016-02-22T15:31:21",
                "Delivered": "2016-02-24T08:42:22",
                "manualticket": true
            },
            "products": [
                {
                    "productcode": "ABC",
                    "description": "WALL PAINT",
                    "units": 1,
                    "unitvalue": 10,
                    "countryofManufacture": "",
                    "unitkg": 1,
                    "imageurl": null,
                    "currency": "NZD",
                    "alreadySent": 0,
                    "fulfilledQty": 1,
                    "linetotal": 10
                }
            ]
        },
        {
            "packingslipno": "SSORDER13669",
            "consignee": "PREMIUM BLUE LTD",
            "address1": "5C",
            "address2": "102 ELLICE RD",
            "suburb": "GLENFIELD",
            "city": "NORTH SHORE CITY",
            "postcode": "0629",
            "country": "NZ",
            "delvref": "SSORDER13669",
            "delvinstructions": "A4 X 1  A2 X 1  OVERNIGHT X 1",
            "contactname": "ANDREW BURNS",
            "contactphone": "09 444 2131",
            "email": "andy@blueltd.co.nz",
            "isrural": null,
            "notrural": null,
            "costcentre": null,
            "status": {
                "Status": "DELIVERED",
                "ticketnumber": "SSPOT018160",
                "trackingurl": "http://gosweetspot.com/track/1234-SSPOT018160",
                "Picked": "2016-02-25T15:24:10",
                "Delivered": "2016-02-26T08:11:14",
                "manualticket": true
            },
            "products": [
                {
                    "productcode": "ABC",
                    "description": "WALL PAINT",
                    "units": 1,
                    "unitvalue": 10,
                    "countryofManufacture": "",
                    "unitkg": 1,
                    "imageurl": null,
                    "currency": "NZD",
                    "alreadySent": 0,
                    "fulfilledQty": 1,
                    "linetotal": 10
                }
            ]
        }
    ]
}

 

     

     

    Delete Customer Orders

    Description

    Delete unprocessed customer orders from the system.

    Requests

    Method: DEL
    Content Type: application/json
    URL: https://api.gosweetspot.com/api/customerorders

    Headers

    access_key : your unique API key provided by GSS.
    site_id : which site you are requesting action for.

    Parameters

    Parameter Type Description
    packingslipno string A comma separated list of orders numbers (packing slip numbers) to be deleted. A maximum of 50 orders can be deleted per call.

    Response

    A JSON object, with order numbers and associated outcome.

    Valid outcome states are:

    • Invalid packing slip number.
    • Cannot be deleted. Already deleted.
    • Cannot be deleted. Already processed.
    • Max delete limit is 50 packing slip numbers

    Request example

    curl --location 'https://api.gosweetspot.com/api/customerorders?createdfrom=2023-08-01&page=2' \
--header 'access_key;' \
--header 'site_id;' \
--header 'Content-Type: application/json; charset=utf-8'
curl --location 'https://api.gosweetspot.com/api/customerorders?createdfrom=2023-08-01&page=2' \
--header 'access_key;' \
--header 'site_id;' \
--header 'Content-Type: application/json; charset=utf-8'

    Response example

    {
    "Page": 1,
    "PageSize": 100,
    "Pages": 6,
    "Results": [
        {
            "packingslipno": "SSORDER13667",
            "consignee": "LITTLE LAMB",
            "address1": "",
            "address2": "103 HAVENWOOD PLACE",
            "suburb": "BIRKENHEAD",
            "city": "NORTH SHORE CITY",
            "postcode": "0626",
            "country": "NZ",
            "delvref": "SSORDER13667",
            "delvinstructions": "A5SHEET X 1  A5 X 1",
            "contactname": "BROOKES STONE",
            "contactphone": "021 123456",
            "email": "info@littlelamb.co.nz",
            "isrural": null,
 {
    "Page": 1,
    "PageSize": 100,
    "Pages": 6,
    "Results": [
        {
            "packingslipno": "SSORDER13667",
            "consignee": "LITTLE LAMB",
            "address1": "",
            "address2": "103 HAVENWOOD PLACE",
            "suburb": "BIRKENHEAD",
            "city": "NORTH SHORE CITY",
            "postcode": "0626",
            "country": "NZ",
            "delvref": "SSORDER13667",
            "delvinstructions": "A5SHEET X 1  A5 X 1",
            "contactname": "BROOKES STONE",
            "contactphone": "021 123456",
            "email": "info@littlelamb.co.nz",
            "isrural": null,
 

     

     

    Order Status

    Description

    Get the current status of an order.

    Requests

    Method: GET
    Content Type: application/json
    URL: https://api.gosweetspot.com/api/customerorders

    Headers

    access_key : your unique API key provided by GSS.
    site_id : which site you are requesting action for.

    Parameters

    Parameter Type Description
    packingslipno string Specify the unique order number from your source system, that was used as the packing slip no when the order was published.
     

    Return format

    A JSON object with order status.

    Response

    Parameter Type Description
    packingslipno string Unique order number or packing slip number from your system.
     
    consignee
         		 string Recipient name.
     
    status
         		 string Current status of an order, options PENDING/PICKED/DELIVERED.
     
    ticketnumber
         		 string Unique consignment number.
     
    trackingurl
         		 string Track and trace website URL.
     
    picked date Localised to pickup timezone, pickup time stamp. null if not picked yet.
     
    delivered date Localised to destination timezone, delivery time stamp. null if not delivered yet.
     
    ticketprinteddate
         		 date
         		 Localised to origin timezone when the shipment ticket was created. null if not created yet.
     
    ticketprintedby
         		 string Username of the user, creating the ticket.
     
    ticketdeleteddate
         		 date
         		 Localised to NZ timezone, date and time when the ticket was deleted, if deleted. null if not deleted.
     
    ticketdeletedby
         		 string Username of the user, deleting the ticket.
     

    Request example

    curl --location --request PUT 'https://api.gosweetspot.com/v2/order/SSORDER5840' \
--header 'access_key;' \
--header 'site_id;' \
--header 'Content-Type: application/json' \
--data ''
curl --location --request PUT 'https://api.gosweetspot.com/v2/order/SSORDER5840' \
--header 'access_key;' \
--header 'site_id;' \
--header 'Content-Type: application/json' \
--data ''

    Response example

    {
  "packingslipno": "SSORDER5840",
  "consignee": "PHOTO DREAMS LIMITED",
  "status": "DELIVERED",
  "ticketnumber": "SSPOT012671",
  "trackingurl": "http://gosweetspot.com/track/1234-SSPOT012671",
  "picked": "2014-06-03T08:40:00",
  "delivered": "2014-06-03T14:46:45",
  "ticketprinteddate": "2014-06-03T08:30:00",
  "ticketprintedby": "abc@accompany.co.nz",
  "ticketdeleteddate": null,
  "ticketdeletedby": null
}
{
  "packingslipno": "SSORDER5840",
  "consignee": "PHOTO DREAMS LIMITED",
  "status": "DELIVERED",
  "ticketnumber": "SSPOT012671",
  "trackingurl": "http://gosweetspot.com/track/1234-SSPOT012671",
  "picked": "2014-06-03T08:40:00",
  "delivered": "2014-06-03T14:46:45",
  "ticketprinteddate": "2014-06-03T08:30:00",
  "ticketprintedby": "abc@accompany.co.nz",
  "ticketdeleteddate": null,
  "ticketdeletedby": null
}

     

     

    Pending Orders

    Description

    Get a list of orders published but not processed.

    Requests

    Method: GET
    Content Type: application/json
    URL: https://api.gosweetspot.com/v2/pendingorders

    Headers

    access_key : your unique API key provided by GSS.
    site_id : which site you are requesting action for.

    Parameters

    None

    Return format

    A JSON object with array of customer orders.

    Response

    Parameter Type Description
    object list list of customer orders

    Request example

    curl --location 'https://api.gosweetspot.com/v2/pendingorders' \
--header 'access_key;' \
--header 'site_id;' \
--header 'Content-Type: application/json' \
--data ''
curl --location 'https://api.gosweetspot.com/v2/pendingorders' \
--header 'access_key;' \
--header 'site_id;' \
--header 'Content-Type: application/json' \
--data ''

    Response example

    [
  {
    "packingslipno": "test1-14-07-01",
    "consignee": "TEST 1",
    "address1": "",
    "address2": "1 QUEENS STREET",
    "suburb": "AUCKLAND CENTRAL",
    "city": "AUCKLAND",
    "postcode": "",
    "country": "NZ",
    "delvref": "TEST1-14-07-01",
    "delvinstructions": "",
    "contactname": "",
    "contactphone": "",
    "email": "",
    "rawAddress": null,
    "iconUrl": null,
    "isrural": null,
    "notrural": null,
    "costcentre": null,
    "status": null,
    "products": [],
    "packages": []
  },
  {
    "packingslipno": "test2-14-07-01",
    "consignee": "TEST 2",
    "address1": "",
    "address2": "1 QUEENS STREET",
    "suburb": "AUCKLAND CENTRAL",
    "city": "AUCKLAND",
    "postcode": "",
    "country": "NZ",
    "delvref": "TEST2-14-07-01",
    "delvinstructions": "",
    "contactname": "",
    "contactphone": "",
    "email": "",
    "rawAddress": null,
    "iconUrl": null,
    "isrural": null,
    "notrural": null,
    "costcentre": null,
    "status": null,
    "products": [],
    "packages": []
  }
]
[
  {
    "packingslipno": "test1-14-07-01",
    "consignee": "TEST 1",
    "address1": "",
    "address2": "1 QUEENS STREET",
    "suburb": "AUCKLAND CENTRAL",
    "city": "AUCKLAND",
    "postcode": "",
    "country": "NZ",
    "delvref": "TEST1-14-07-01",
    "delvinstructions": "",
    "contactname": "",
    "contactphone": "",
    "email": "",
    "rawAddress": null,
    "iconUrl": null,
    "isrural": null,
    "notrural": null,
    "costcentre": null,
    "status": null,
    "products": [],
    "packages": []
  },
  {
    "packingslipno": "test2-14-07-01",
    "consignee": "TEST 2",
    "address1": "",
    "address2": "1 QUEENS STREET",
    "suburb": "AUCKLAND CENTRAL",
    "city": "AUCKLAND",
    "postcode": "",
    "country": "NZ",
    "delvref": "TEST2-14-07-01",
    "delvinstructions": "",
    "contactname": "",
    "contactphone": "",
    "email": "",
    "rawAddress": null,
    "iconUrl": null,
    "isrural": null,
    "notrural": null,
    "costcentre": null,
    "status": null,
    "products": [],
    "packages": []
  }
]

    Did this article answer your question?

    Related Articles

    GoSweetSpot: API introduction

    GoSweetSpot: Labels

    GoSweetSpot: Models

    GoSweetSpot: Book a Pickup

    Popular Articles

    Domestic Delivery Updates

    Missing, Lost or Damaged Deliveries

    Terms and Conditions for sending within New Zealand

    What time will my parcel be delivered? Expected delivery time

    Can't find the answer to your question?

    Suggest an article