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
relationshipposting or patching the
collection
relationship of a shipmentposting a shipment with the
add_to_next_collection
meta property set totrue
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.