Create a collection

There are multiple ways to have a shipment enter the carrier’s network. The shipment can be brought to a drop-off point, it can be injected straight into a carrier hub, or a request can be made to the carrier to arrange collection of the shipment. In the latter case, there are four steps to be taken in order to get this done:

The order in which these steps are taken are important, especially since different carriers have different requirements for collections.

Create a collection resource

The first step is to create a collections resource. As a minimum, the collection needs to have the collection_time and address attributes, as well as the shop and contract relationships. For the contract relationship it is important that the carrier that the contract is for, does offer collections. This is checked by retrieving the desired carrier and checking the value of its collections.offers_collections attribute.

A collection is then created by calling the POST /collections endpoint on the MyParcel.com API.

POST /collections HTTP/1.1
Accept: application/vnd.api+json
Example: https://sandbox-api.myparcel.com/collections

{
  "data": {
    "type": "collections",
    "attributes": {
      "description": "First Collection",
      "address": {
        "street_1": "Baker Street",
        "street_2": "Marylebone",
        "street_number": 221,
        "street_number_suffix": "B",
        "postal_code": "NW1 6XE",
        "city": "London",
        "state_code": "ENG",
        "country_code": "GB",
        "first_name": "Sherlock",
        "last_name": "Holmes",
        "company": "Holmes Investigations",
        "email": "s.holmes@holmesinvestigations.com",
        "phone_number": "+31 234 567 890"
      },
      "collection_time": {
        "from": 1648110600,
        "to": 1648114200
      }
    },
    "relationships": {
      "contract": {
        "data": {
          "type": "contracts",
          "id": "2cb32706-5762-4b96-9212-327e6afaeeff"
        }
      },
      "shop": {
        "data": {
          "type": "shops",
          "id": "35eddf50-1d84-47a3-8479-6bfda729cd99"
        }
      }
    }
  }
}

Add shipments to the collection

Once the collection has been created, it is possible to add shipments to it. Before doing so, make sure that the shipment and the collection are created for the same shop and that they use the same contract.

There are three ways to add a shipment to a collection:

  • posting or patching the collection with the shipments relationship

  • posting or patching the collection relationship of a shipment

  • posting a shipment with the add_to_next_collection meta property set to true

This last option of using the add_to_next_collection meta property will automatically add the shipment to the next collection that is created for the shop and contract that the shipment is created for. Selection of the next available collection is based on the nearest collection_time.from attribute of the compatible collections.

Warning

It is important to know that both the shipment and the collection have to be unregistered in order to add a shipment to a collection.

Register the shipments in the collection

Once the shipments have been added to the collection, the shipments need to be registered. It is not possible to remove a shipment from a collection once it has been registered, so make sure that you have added the shipment to the correct collection before registering it. It is still possible to add new shipments to the collection, as long as the collection itself has not been registered yet.

Register the collection

Finally, after all the shipments in a collection have been registered, the collection can be registered with the carrier. This is done by patching the collection’s register attribute and setting it to true. Since all shipments have to be registered before the collection is registered, it is not possible to register the collection and add shipments in the same request (except for when using ad-hoc collections).

PATCH /collections/e26d781b-6c56-4be5-ae72-505db793d2bd HTTP/1.1
Accept: application/vnd.api+json
Example: https://sandbox-api.myparcel.com/collections/e26d781b-6c56-4be5-ae72-505db793d2bd

{
  "data": {
    "id": "e26d781b-6c56-4be5-ae72-505db793d2bd",
    "type": "collections",
    "attributes": {
      "register": true
    },
  }
}

Warning

The register attribute is only available through the PATCH endpoint. This is because the /collections endpoint does not do shipment registration. See the section on ad-hoc collections for a way to do everything in one go.

Ad-hoc collections

When using the synchronous /registered-shipments endpoint, it is possible to create and register both a shipment and a collection in the same request. This collection will then only contain the shipment that is being created. This is useful when you want to create a shipment and register it in one go.

This endpoint exposes a collection meta property that accepts a description and a collection_time property that will be used to create the collection. The sender_address of the shipment will be used as the address of the collection.

Below is an example of such a request:

POST /registered-shipments HTTP/1.1
Accept: application/vnd.api+json
Example: https://sandbox-api.myparcel.com/registered-shipments

{
  "data": {
    "type": "shipments",
    "attributes": {
      "...": "..."
    },
    "relationships": {
      "...": "..."
    }
  },
  "meta": {
    "collection": {
      "description": "First Collection",
      "collection_time": {
        "from": 1648110600,
        "to": 1648114200
      }
    }
  }
}

Warning

Note that because the collection is registered in this request, it is not possible to add more shipments to this collection. It is a single shipment collection.