api/shipments

About 4 min

api/shipments

Description

This method is used to create new shipments.

There are 2 pre-conditions that need to be considered before calling this method.

Does your workflow require you to display/calculate the freight costs and options prior to creating the shipment?
Does your workflow already know which carrier is to be used for creating the shipment?

1. Display/Calculate rates first

In this scenario, you need to call the POST api/rates endpoint first to resolve the different price options you may have. Every option is accompanied by a QuoteId which needs to be retain to be used with the create shipment method.

2. Create by Carrier Name and service

In this scenario, you won't know the cost of the freight for the shipment till after the shipment is created. You will request the shipment to be used by specifying the carrier name, and service.

Printing - if the accesskey has an associated printer setup, the print job is activated by default. This can be turned off by specifying PrintToPrinter="false"_

Request

Method: POST
Content Type: application/json
URL: https://api.gosweetspot.com/api/shipments

Headers

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

Parameters

You need to extend the POST api/rates post body to include other fields specified below.

When QuoteId is supplied, the carrier and service fields are ignored. They should be used in exclusive pattern.

Parameter	Type	Description
QuoteId	string	Unique quote identifier returned on the `POST` api/rates endpoint query.
Carrier	string	Name of the carrier to use for the shipment. You can query the `POST` api/availableservices endpoint to find the valid carrier names. You can also pass '*' to choose the cheapest of any carrier.
Service	string	Carrier service name, for which the shipment should be created for. If not supplied, the cheapest price option is selected.
origin	object	Leave blank when using site address, or provide one for freight forwards (Contact Model).
destination	object	Recepient address details (Contact Model).
packages	object list	Array of package sizes (Rate Package Model).
issaturdaydelivery	boolean	Is saturday delivery required.
issignaturerequired	boolean	Is signature on delivery required.
dutiesandtaxesbyreceiver	boolean	Where duties are due, is the receiver paying for these.
deliveryreference	string	Order reference, max length is 50.
commodities	object list	Customs declared commoditiy information. Only required for international shipments.
printtoprinter	string	Use "true" to send a print request to your default printer. "false" indicates no printing is required. You can also put a printer name here and the print request would be sent directly to that printer.
CustomField1Value	string	Value of "Custom field 1" in Site Settingsopen in new window, only able to take the value when "Custom Field 1 Enabled" under "Internal References" is checked. Will response error when "Custom Field 1 Mandatory" is checked and the field is missing.
CustomField2Value	string	Value of "Custom field 2" in Site Settingsopen in new window, only able to take the value when "Custom Field 2 Enabled" under "Internal References" is checked. Will response error when "Custom Field 2 Mandatory" is checked and the field is missing.
outputs	string list	optional - JSON string list. Returns output of label as a PNG or PDF. Acceptable value are Print Output Formats.
hasdg	boolean	True or false - does your shipment contain any dangerous goods.
dangerousgoods	object	JSON object of dangerous goods.
RecipientTaxId	string	Optional, Goods shipped into or transiting through certain countries will need to have this value.
IncludeInsurance	boolean	True or false - Optionally add additional insurance cover for international shipments if applicable. Will use total declared value as insurance value.
DeclarationType	string	Optional, Type of item being sent for custom's use. Declaration options include merchandise, documents, gift, returned, sample. Merchandise will be used as default if not provided.

Return format

A JSON object with the created shipment details.

Response

Attribute	Type	Description
carrier	string	Internal system carrier identifier.
carriername	string	Courier provider name.
isfreightforward	boolean	Is shipment a freight forward shipment.
message	string	Action outcome message.
errors	string list	List of error messages.
siteid	integer	Account site id.
consignments	object list	JSON object arrary or consignments created. Generally only 1 is created, however were a split is required, more could be created (Consignment Model)

Request example

1. Domestic Outbound Shipment

curl --location --request POST 'http://api.gosweetspot.com/api/shipments' \
--header 'access_key;' \
--header 'site_id;' \
--header 'Content-Type: application/json' \
--data-raw '{
    "Origin": null,
    "Destination": {
        "Name": "DestinationName",
        "Address": {
            "BuildingName": "",
            "StreetAddress": "DestinationStreetAddress",
            "Suburb": "Avonside",
            "City": "Christchurch",
            "PostCode": "8061",
            "CountryCode": "NZ"
        },
        "Email": "[email protected]",
        "ContactPerson": "DestinationContact",
        "PhoneNumber": "123456789",
        "IsRural": false,
        "DeliveryInstructions": "Desinationdeliveryinstructions",
        "SendTrackingEmail": false,
        "ExplicitNotRural": false
    },
    "Packages": [
        {
            "Name": "GSS-DLE SATCHEL",
            "Length": 1,
            "Width": 10,
            "Height": 1,
            "Kg": 0.1,
        }
    ],
    "Commodities": null,
    "IsSaturdayDelivery": false,
    "IsSignatureRequired": true,
    "IsUrgentCouriers": false,
    "DutiesAndTaxesByReceiver": false,
    "DeliveryReference": "ORDER123",
    "PrintToPrinter": "false",
    "Carrier": "Post Haste"
}'

2. Domestic Outbound Shipment with Dangerous Goods

curl --location --request POST 'http://api.gosweetspot.com/api/shipments' \
--header 'access_key;' \
--header 'site_id;' \
--header 'Content-Type: application/json' \
--data-raw '{
    "Origin": null,
    "Destination": {
        "Id": 0,
        "Name": "DestinationName",
        "Address": {
            "BuildingName": "",
            "StreetAddress": "DestinationStreetAddress",
            "Suburb": "Avonside",
            "City": "Christchurch",
            "PostCode": "8061",
            "CountryCode": "NZ"
        },
        "Email": "[email protected]",
        "ContactPerson": "DestinationContact",
        "PhoneNumber": "123456789",
        "IsRural": false,
        "DeliveryInstructions": "Desinationdeliveryinstructions",
        "SendTrackingEmail": false,
        "CostCentreId": 0,
        "ExplicitNotRural": false
    },
    "Packages": [
        {
            "Id": 0,
            "Name": "GSS-DLE SATCHEL",
            "Length": 1,
            "Width": 10,
            "Height": 1,
            "Kg": 0.1
        }
    ],
    "Commodities": null,
    "IsSaturdayDelivery": false,
    "IsSignatureRequired": true,
    "IsUrgentCouriers": false,
    "DutiesAndTaxesByReceiver": false,
    "RuralOverride": false,
    "DeliveryReference": "ORDER123",
    "PrintToPrinter": "false",
    "Outputs": [
        10
    ],
    "CarrierId": 0,
    "Carrier": "Post Haste",
    "Service": null,
    "SiteId": 0,
    "IncludeLineDetails": false,
    "ShipType": 1,
    "HasDG": true,
    "DangerousGoods": {
        "AdditionalHandlingInfo": "Some info",
        "HazchemCode": "HC",
        "IsRadioActive": false,
        "CargoAircraftOnly": false,
        "IsDGLQ":true,
        "TotalKg":5.2,
        "TotalQuantity":"2",
        "SignOffName":"name",
        "SignOffRole":"role",
        "LineItems": [
            {
                "ConsignmentId": 0,
                "Description": "desc",
                "ClassOrDivision": "class",
                "UNorIDNo": "",
                "PackingGroup": "",
                "SubsidaryRisk": "",
                "Packing": "",
                "PackingInstr": "",
                "Authorization": ""
            }
        ]
    },
    "DisableFreightForwardEmails": false
}'

3. International Outbound Shipment

curl --location --request POST 'https://api.gosweetspot.com/api/shipments' \
--header 'access_key: Your API Access Key' \
--header 'site_id: Your Site ID' \
--header 'Content-Type: application/json' \
--data-raw '{
    "Origin": null,
    "Destination": {
        "Name": "DestinationName",
        "Address": {
            "BuildingName": "",
            "StreetAddress": "8 Althea Clos",
            "Suburb": "Sinnamon Park",
            "City": "Queensland",
            "PostCode": "4073",
            "CountryCode": "AU"
        },
        "Email": "[email protected]",
        "ContactPerson": "DestinationContact",
        "PhoneNumber": "123456789",
        "IsRural": false,
        "DeliveryInstructions": "Desinationdeliveryinstructions",
        "SendTrackingEmail": false,
        "ExplicitNotRural": false
    },
    "Packages": [
        {
            "Name": "GSS-DLE SATCHEL",
            "Length": 10,
            "Width": 10,
            "Height": 10,
            "Kg": 1
        }
    ],
    "Commodities": [
        {
            "Description":"test",
            "unitvalue":100,
            "UnitKg":1,
            "units":1,
            "currency":"NZD",
            "Country":"CN"
        }
    ],
    "IsSaturdayDelivery": false,
    "IsSignatureRequired": true,
    "IsUrgentCouriers": false,
    "DutiesAndTaxesByReceiver": false,
    "DeliveryReference": "ORDER123",
    "PrintToPrinter": "false",
    "Carrier": "FedEx",
    "IncludeInsurance": true,
    "DeclarationType": "GIFT"
}'

Response example

1. Domestic Outbound Shipment

{
  "CarrierId": 102,
  "CarrierName": "Post Haste",
  "IsFreightForward": false,
  "IsOvernight": false,
  "IsResidential": true,
  "IsSaturdayDelivery": false,
  "IsRural": false,
  "HasTrackPaks": false,
  "Message": "Connote created and print queued.",
  "AddressLabelMessage": null,
  "AddressLabelError": null,
  "Errors": [],
  "SiteId": 4180,
  "Consignments": [
    {
      "Connote": "SSPOT018667",
      "TrackingUrl": "http://gosweetspot.com/track/4180-SSPOT018667",
      "Cost": 4.07,
      "CarrierType": 13,
      "IsSaturdayDelivery": false,
      "IsRural": false,
      "IsOvernight": false,
      "IsResidential": true,
      "HasTrackPaks": false,
      "ConsignmentId": 6215942,
      "OutputFiles": null,
      "Items": null
    }
  ],
  "Downloads": [],
  "CarrierType": 13,
  "AlertPath": null,
  "Notifications": [],
  "HasSaturdayDeliveryLabel": false
}

2. Domestic Outbound Shipment with Dangerous Goods

{
  "CarrierId": 102,
  "CarrierName": "Post Haste",
  "IsFreightForward": false,
  "IsOvernight": false,
  "IsResidential": true,
  "IsSaturdayDelivery": false,
  "IsRural": false,
  "HasTrackPaks": false,
  "Message": "Connote created and print queued.",
  "AddressLabelMessage": null,
  "AddressLabelError": null,
  "Errors": [],
  "SiteId": 4180,
  "Consignments": [
    {
      "Connote": "SSPOT018668",
      "TrackingUrl": "http://gosweetspot.com/track/4180-SSPOT018668",
      "Cost": 4.07,
      "CarrierType": 13,
      "IsSaturdayDelivery": false,
      "IsRural": false,
      "IsOvernight": false,
      "IsResidential": true,
      "HasTrackPaks": false,
      "ConsignmentId": 6215944,
      "OutputFiles": {
        "DG_FORM_PDF": [
          "JVBERi0xLjQKJdP0zOEKMSAwIG9iago8PAovQ3JlYXRpb25EYXRlKEQ6MjAxNjA0MTYxMDI5MTIrMTInMDAnKQovQ3JlYXRvcihQREZzaGFycCAxLjMyLjMwNTctRU9GCg=="
        ]
      },
      "Items": null
    }
  ],
  "Downloads": [],
  "CarrierType": 13,
  "AlertPath": null,
  "Notifications": [],
  "HasSaturdayDeliveryLabel": false
}

3. International Outbound Shipment

{
  "CarrierId": 96,
  "CarrierName": "FedEx",
  "IsFreightForward": false,
  "IsOvernight": false,
  "IsSaturdayDelivery": false,
  "IsRural": false,
  "IsResidential": false,
  "HasTrackPaks": false,
  "Message": "Connote created and print queued.",
  "AddressLabelMessage": null,
  "AddressLabelError": null,
  "Errors": [],
  "SiteId": 1234567,
  "IncludePackingSlip": false,
  "Consignments": [
    {
      "Connote": "ABCDEFG",
      "TrackingUrl": "https://gosweetspot.com/track/1234567-ABCDEFG",
      "Cost": 0,
      "CarrierType": 4,
      "IsSaturdayDelivery": false,
      "IsRural": false,
      "IsOvernight": false,
      "IsResidential": false,
      "HasTrackPaks": false,
      "ConsignmentId": 99999999,
      "OutputFiles": null,
      "Items": null
    }
  ],
  "Downloads": [],
  "CarrierType": 4,
  "AlertPath": null,
  "Notifications": [],
  "HasSaturdayDeliveryLabel": false,
  "SentToPrinter": null,
  "ExternalLinksToOpen": [],
  "CustomField1Value": null,
  "CustomField2Value": null
}

api/shipments

# api/shipments

# Description

# 1. Display/Calculate rates first

# 2. Create by Carrier Name and service

# Request

# Headers

# Parameters

# Return format

# Response

# Request example

# 1. Domestic Outbound Shipment

# 2. Domestic Outbound Shipment with Dangerous Goods

# 3. International Outbound Shipment

# Response example

# 1. Domestic Outbound Shipment

# 2. Domestic Outbound Shipment with Dangerous Goods

# 3. International Outbound Shipment

api/shipments

Description

1. Display/Calculate rates first

2. Create by Carrier Name and service

Request

Headers

Parameters

Return format

Response

Request example

1. Domestic Outbound Shipment

2. Domestic Outbound Shipment with Dangerous Goods

3. International Outbound Shipment

Response example

1. Domestic Outbound Shipment

2. Domestic Outbound Shipment with Dangerous Goods

3. International Outbound Shipment