Integration Design - Shipment Groups

  • Ship
  • api
  • flows
  • integration design
  • shipment groups

The Shipment Groups integration design enables you to perform operations on an entire group of shipments at once. A common use case for shipment groups is to match operational flows, such as adding multiple shipments to a cage or trailer to be taken in a batch by a carrier.

For example, suppose that you allocate 500 shipments to Carrier X, which are all loaded on to the same outbound trailer in a cage. The Shipment Groups design enables you to add each shipment to a group corresponding to that cage, before manifesting the entire group in a single API call.

Note

This page provides help and support for Sorted Ship. As Ship is currently in development, content may be updated as and when necessary.

For support with Ship (Consignments), click here.

There are ten steps to the design:

  1. Create the shipment - Use the Create Shipment endpoint to record the details of your new shipments.
  2. (Optional) Add Paperless Documents - Use the Add Paperless Document endpoint to add documents to shipment data.
  3. Allocate the shipment - Use the Allocate Shipment endpoint to assign your shipment to a suitable carrier service.
  4. Create the shipment group - Use the Create Shipment Group endpoint to create the shipment group and add your shipments to it.
  5. (Optional) Update the shipment group - Use the Update Shipment Group endpoint to add or remove shipments from your shipment group.
  6. Lock the shipment group - Use the Lock Shipment Group endpoint to prevent further changes from being made to the group.
  7. Get the shipment's labels - Use the Get Labels endpoint to get delivery label for the shipment.
  8. (Optional) Get customs documents for the shipment - Use the Get Customs Documents to generate printable customs documents for international shipments.
  9. Manifest the shipment - Use the Manifest Shipment by Shipment Group endpoint to send shipment data to the selected carriers.

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

Step 1: Creating the Shipment

POST https://api.sorted.com/pro/shipments

The first step toward manifesting a shipment is to create that shipment in SortedPRO.

Shipments are created using the Create Shipment endpoint, which takes information about new shipments, adds them to the database, and returns a link to the newly-created shipment, including its {reference}. A newly created shipment has a {state} of unallocated.

As a minimum, the Create Shipments endpoint requires you to send details of the contents of the shipment and its origin and destination addresses. You must also specify whether the shipment is on_demand (i.e. will require an ad-hoc carrier collection to be booked) or scheduled (i.e. will be picked up as part of a regularly scheduled carrier collection).

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

Create Shipments Example

This example shows the creation of a fairly standard shipment. In this case, we have an outbound shipment comprising a single package.

After receiving the request, Ship returns a shipment {reference} of sp_00595452779180472847666078547968. Many of Ship's functions require you to provide this shipment {reference} as a parameter.

POST https://api.sorted.com/pro/shipments


{
    "shipment_type": "on_demand",
    "contents": [
        {
            "custom_reference": "b9fa91b0-0dd0-4dd5-986f-363fa8cb2386",
            "package_size_reference": null,
            "weight": {
                "value": 2.40,
                "unit": "Kg"
            },
            "dimensions": {
                "unit": "Cm",
                "width": 15.0,
                "height": 15.5,
                "length": 20.0
            },
            "description": "Jeans",
            "value": {
                "amount": 8.99,
                "currency": "GBP"
            },
            "sku": "SKU09876",
            "model": "MOD-009",
            "country_of_origin": "PT",
            "harmonisation_code": "09021000",
            "shipping_terms": "fca",
            "quantity": 2,
            "unit": "Box",
            "metadata": [
                {
                    "key": "Category",
                    "value": "Menswear",
                    "type": "string"
                }
            ],
            "label_properties": null,
            "Contents": null
        }
    ],
    "addresses": [
        {
            "address_type": "Origin",
            "contact": {
                "reference": "co_9953035290535460864",
                "title": "Mr",
                "first_name": "Mark",
                "last_name": "Brunell",
                "contact_details": {
                    "mobile": "+447495747987",
                    "email": "mark@62-7.com"
                }
            },
            "property_number": "1",
            "property_name": "Frank's Place",
            "address_line1": "Zappa Avenue",
            "address_line2": "Off Rock Road",
            "address_line3": "Off Heavy Crescent",
            "locality": "Manchester",
            "region": "Greater Manchester",
            "postal_code": "M2 6LW",
            "country_iso_code": "GB"
        },
        {
            "address_type": "destination",
            "custom_reference": "21bbd58a-6dec-4097-9106-17501ddca38d",
            "contact": {
                "reference": "co_9953035290535460865",
                "title": "Mr",
                "first_name": "Gardner",
                "last_name": "Minshew",
                "middle_name": null,
                "position": null,
                "contact_details": {
                    "landline": null,
                    "mobile": "+447495747987",
                    "email": "gminshew@test.com"
                }
            },
            "property_number": "8",
            "property_name": null,
            "address_line1": "Norbert Road",
            "address_line2": "Bertwistle",
            "address_line3": null,
            "locality": "Preston",
            "region": "Lancashire",
            "postal_code": "PR4 5LE",
            "country_iso_code": "GB",
            "lat_long": null
        }
    ]
}

Step 2 (Optional) Adding Paperless Documents

POST https://api.sorted.com/pro/documents/paperless/{shipment_reference}

Paperless documents are customer-generated documents that are transmitted to carriers as part of a shipment's data, as opposed to being generated separately by the carrier. They can help to make your workflows more efficient, reducing steps in the manifest process and enabling you to attach document data to a shipment directly.

Note

PRO's paperless document functionality should not be confused with PRO's customs documents functionality. Paperless documents are added to the shipment before allocation and transmitted as part of that shipment's data, while customs documents are generated post-allocation and are intended to be printed before dispatch. For more information on working with customs documents in Ship, see the Getting Shipment Documents page.

Not all carriers support paperless trade.

You can add paperless documents to an unallocated shipment via the Add Paperless Document endpoint. As a minimum, Add Paperless Document requests should include the document's file_format, document_type, and file_content (as a base64-encoded byte array). You can also add expiration and usage data if required.

Once it has received the request, Ship attaches the document to the specified shipment and returns a unique reference for the paperless document. You can use this reference to retrieve details of the paperless document (via the Get Paperless Document endpoint), or delete the paperless document entirely (via the Remove Paperless Document endpoint).

Note

Add Paperless Document Example

The example shows a successful request to add a commercial_invoice paperless document to shipment sp_00595452779180472847666078547968. Ship has responded with a paperless document reference of pd_00797582543150236528252876881920.

POST https://api.sorted.com/pro/documents/paperless/sp_00595452779180472847666078547968

{
  "file_format": "pdf",
  "document_type": "commercial_invoice",
  "expiration": "2021-09-01T06:00:00+00:00",
  "file_content": (Base64 document data),
  "usage": "electronic_trade"
}

Step 3: Allocating the Shipment using Default Rules

PUT https://api.sorted.com/pro/shipments/{reference}/allocate

To allocate a shipment based on your organisation's custom allocation rules, use the Allocate Shipment endpoint. Ship enables you to configure custom allocation rules for individual carrier services - such as valid package dimensions, maximum shipment value, and geographical availability - via the UI.

Once the request is received, Ship uses your shipping rules and modes to ascertain the most suitable carrier service for the shipment, and then allocates the shipment to that service. The system then returns an Allocate Shipments Response.

Note
  • For more information on the wider process Ship uses to allocate shipments, see the Selecting a Carrier Service section of the Allocating Shipments page.
  • For more information on configuring and using shipping rules, see the Managing Shipping Rules page of the UI user guide.
  • For more information on configuring and using shipping modes, see the Managing Shipping Modes page of the UI user guide.

Allocate Shipments with Default Rules Example

The example shows a successful request to allocate a shipment with a {reference} of sp_01017652898121961272041674506240 via the Allocate Shipment endpoint. Ship has selected a service and returned tracking_references for the shipment.

PUT https://api.sorted.com/pro/shipments/sp_01017652898121961272041674506240/allocate

Step 4: Creating the Shipment Group

POST https://api.sorted.com/pro/shipment_groups

Next, you'll need to create a shipment group by making a Create Shipment Group request. The body of the request should contain a list of up to 10,000 shipments that you want to add to the group, and an optional custom_reference that can be used as a unique identifier for the group.

Once it has received and validated the request, Ship creates the shipment group and returns a Resource Result containing the group reference. This reference will be used as an identifier for the group later on in the process.

Note

Example Create Shipment Group Call

The example shows a successful request to add three shipments to a group.

POST https://api.sorted.com/pro/shipment_groups/

{
    "custom_reference": "Example123",
    "shipments": [
        "sp_00013464648910021776641789788160",
        "sp_00013464648910021776641789784435",
        "sp_00013464648910021776641789790773"
    ]
}

Step 5: Updating the Shipment Group

PUT https://api.sorted.com/pro/shipment_groups

You can amend the shipments in a shipment group using the Update Shipment Group endpoint. For example, you may have added extra shipments to a particular warehouse cage, and you want to amend the corresponding shipment group to also contain those shipments.

The Update Shipment Group request should contain the reference of the group you want to amend and optional add_shipments and/or remove_shipments properties listing the shipments that you want to either add to or remove from the group.

Once it has received the request, Ship returns a Resource Result confirming the result of the operation.

Note

Example Update Shipment Group Call

The example shows a successful request to update the group created in the previous example. Three new shipments have been added to the group, while one of the group's existing shipments has been removed.

PUT https://api.sorted.com/pro/shipment_groups/

{
  "reference": "sg_00679577652026749527919113797632",
  "add_shipments": [
      "sp_00682731282010871067439042134016",
      "sp_00682731282010871067439042134045",
      "sp_00682731282010871067439042134076"
    ],
  "remove_shipments": [
      "sp_00013464648910021776641789788160"
    ]
}

Step 6: Locking the Shipment Group

POST https://api.sorted.com/pro/shipment_groups/{reference}/lock

You'll need to lock your shipment group via the Lock Shipment Group endpoint before you can get a collection note for it. Locking a shipment group means that it can no longer be edited.

Note

Locked shipment groups can be unlocked via the Unlock Shipment Group endpoint, making it possible to add or remove shipments from the group.

  • For a user guide on locking shipment groups, see the Locking Shipment Groups section of the Editing Shipment Groups page.
  • For full reference information on the Lock Shipment Groups endpoint, see the Ship API reference.

Example Lock Shipment Group Call

The example shows a successful request to lock shipment group sg_00679577652026749527919113797632.

POST https://api.sorted.com/pro/shipment_groups/sg_00679577652026749527919113797632/lock

Step 7: Getting Collection Notes for the Shipment Group

POST https://api.sorted.com/pro/collection_notes/shipment_group/{reference}

In Ship, a collection note (sometimes referred to as a driver's manifest) is a document listing items that are to be collected by a driver. It is intended to be printed and given to the driver at the point of collection.

The Get Shipment Group Collection Note endpoint returns a collection note document listing all of the shipments in the specified group. The group must be locked in order for a collection note to be generated.

Note

Example Get Shipment Group Collection Note Call

The example shows a successful request to get a collection note for shipment group sg_00679577652026749527919113797632.

POST https://api.sorted.com/pro/collection_notes/shipment_group/sg_00679577652026749527919113797632

Step 8: Getting Shipment Labels

GET https://api.sorted.com/pro/labels/{shipmentReference}/{contentType}/{dpi}

When a shipment is allocated, Ship generates labels for each item of contents in that shipment. You can retrieve these delivery labels via the Get Labels endpoint.

The Get Labels endpoint takes shipment {reference}, {contentType}, and {dpi} as path parameters, where {reference} is the unique reference of the shipment you want to get labels for, {contentType} is an optional property indicating the file format required (either PDF or ZPL), and {dpi} an optional property indicating is the resolution required. Ship returns all package labels associated with that shipment as a base64-encoded byte array that decodes to the format and resolution requested.

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

Get Labels Example

The example shows a request to get PDF labels for a shipment with a {reference} of sp_00668400124857422605561635799040. 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 https://api.sorted.com/pro/labels/sp_00668400124857422605561635799040/pdf

Step 9 (Optional): Getting Customs Docs

GET https://api.sorted.com/pro/documents/{shipment_reference}

When shipping internationally, Ship automatically determines whether customs documentation is necessary for a shipment, and generates documents where required. You can retrieve customs documentation via the Get Customs Documents endpoint.

The Get Customs Documents endpoint takes a shipment {reference} as a path parameter. If CN22/CN23 or commercial invoice documents exist for the specified shipment, then Ship returns these documents as a base64-encoded byte array that decodes to a PDF document.

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

Note
  • For full reference information on the Get Customs Documents endpoint, see the Get Customs Documents page of the API reference.
  • For a user guide on retrieving customs documents and commercial invoices in Ship, see the Getting Shipment Documents page.

Get Customs Documents Example

This example shows a Get Customs Documents response for shipment sp_00670175533382557003917067812864. Ship has returned a CN22 document.

GET https://api.sorted.com/pro/documents/sp_00670175533382557003917067812864

Step 10: Manifesting the Shipment

POST https://api.sorted.com/pro/shipment_groups/{reference}/manifest

Once you've added your shipments to the shipment group, you're ready to manifest it. To manifest a shipment group, use the Manifest Shipments by Shipment Group endpoint.

In the context of Ship, the term "manifesting" refers to collating, formatting and transmitting shipment data to carriers. The Manifest Shipments by Shipment Group endpoint queues all of the shipments in the specified shipment group for manifest.

Note

Manifest Shipment Group Example

The example shows a successful request to manifest a shipment group.

POST https://api.sorted.com/pro/shipment_groups/sg_00679577652026749527919113797632/manifest