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:

Create a collection resource

Add shipments to the collection

Register the shipments in the collection

Register the collection

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://api.sandbox.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 some carriers allow adding registered shipments to a collection. This is checked by retrieving the desired carrier and checking the value of its allows_adding_registered_shipments_to_collection attribute.

Register the shipments in the collection

If the shipments that have been added to the collection are in an unregistered state, 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 making sure all shipments are registered and patching the collection’s register attribute and setting it to true.

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

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

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://api.sandbox.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.

Single-request collections

When creating a collection it is also possible to directly add shipments and register the collection in a single request. It is important that the carrier allows adding registered shipments to a collection. This can be checked by retrieving the carrier. This is checked by retrieving the desired carrier and checking the value of its allows_adding_registered_shipments_to_collection attribute. After validating that the carrier supports the above, you can do a single request containing the collection information with the register property set to true and the registered shipments that you want to add to the collection.

Below is an example of such a request:

POST /collections HTTP/1.1
Accept: application/vnd.api+json
Example: https://api.sandbox.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"
      },
      "register": true,
      "collection_time": {
        "from": 1648110600,
        "to": 1648114200
      }
    },
    "relationships": {
      "contract": {
        "data": {
          "type": "contracts",
          "id": "2cb32706-5762-4b96-9212-327e6afaeeff"
        }
      },
      "shipments": {
        "data": [
          {
            "type": "shipments",
            "id": "7b808eee-bf1c-40cd-98f2-3c335a06417e"
          }
        ]
      },
      "shop": {
        "data": {
          "type": "shops",
          "id": "35eddf50-1d84-47a3-8479-6bfda729cd99"
        }
      }
    }
  }
}