Collections
===========
Collections are used to have the carrier pick up shipments from a home or business address.
.. seealso::
https://api-specification.myparcel.com/#tag/Collections
Attributes
----------
================== ================================================================== ========== =============================================================
Attribute Type Required Description
================== ================================================================== ========== =============================================================
address :doc:`address ` ✓ The address where the collection should take place.
collection_time :doc:`collection_time ` ✓ The requested time slot for the collection.
description string Description of the collection. Useful as internal reference.
register boolean Indicates whether the collection should be registered.
tracking_code string The tracking code of the collection.
================== ================================================================== ========== =============================================================
================== ================================================================== ========== =============================================================
Relationships Type Required Description
================== ================================================================== ========== =============================================================
contract :doc:`contract ` ✓ The contract that is used for this collection. Its credentials
will be used to create the collection at the carrier.
shop :doc:`shop ` ✓ The shop to create the collection for.
status :doc:`status ` ✓ The status of the collection.
files array of :doc:`files ` The files that are attached to the collection.
manifest :doc:`manifest ` The manifest of the shipments to be collected.
shipments array of :doc:`shipments ` The shipments that are to be collected.
================== ================================================================== ========== =============================================================
Collection statuses
-------------------
================================== ==========================================
Status code Description
================================== ==========================================
collection-concept The collection has been created but not yet
registered. It can still be edited.
collection-registered The collection has been registered with the
carrier. It can no longer be edited.
collection-registration-failed The collection could not be registered with
the carrier.
collection-voided The collection has been voided.
================================== ==========================================
Endpoints
---------
.. raw:: html
GET /collections
Retrieving a list of collections.
**Scope**
Any of the following scopes:
- ``shipments.manage``
- ``shipments.view``
**Request**
.. code-block:: http
GET /collections HTTP/1.1
Accept: application/vnd.api+json
Example: https://api.sandbox.myparcel.com/collections
**Response**
.. code-block:: json
{
"data": [
{
"type": "collections",
"id": "e26d781b-6c56-4be5-ae72-505db793d2bd",
"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
},
"tracking_code": "TRC123456",
"created_at": 1504801719
},
"relationships": {
"contract": {
"data": {
"type": "contracts",
"id": "2cb32706-5762-4b96-9212-327e6afaeeff"
},
"links": {
"related": "https://api.sandbox.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff"
}
},
"files": {
"data": [
{
"type": "files",
"id": "0f621db6-d239-4ae9-b85d-8e97469b10ce"
}
],
"links": {
"related": "https://api.sandbox.myparcel.com/files/0f621db6-d239-4ae9-b85d-8e97469b10ce"
}
},
"manifest": {
"data": {
"type": "manifests",
"id": "ce7f6752-34e0-49a1-a832-bcc209450ea8"
},
"links": {
"related": "https://api.sandbox.myparcel.com/manifests/ce7f6752-34e0-49a1-a832-bcc209450ea8"
}
},
"shipments": {
"data": [
{
"type": "shipments",
"id": "7b808eee-bf1c-40cd-98f2-3c335a06417e"
}
]
},
"shop": {
"data": {
"type": "shops",
"id": "35eddf50-1d84-47a3-8479-6bfda729cd99"
},
"links": {
"related": "https://api.sandbox.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99"
}
},
"status": {
"data": {
"type": "statuses",
"id": "5c868557-0827-4d21-a7f4-9820f01769f4"
},
"links": {
"related": "https://api.sandbox.myparcel.com/statuses/5c868557-0827-4d21-a7f4-9820f01769f4"
}
}
},
"links": {
"self": "https://api.sandbox.myparcel.com/collections/e26d781b-6c56-4be5-ae72-505db793d2bd"
}
}
],
"meta": {
"total_pages": 13,
"total_records": 373
},
"included": [
{
"type": "contracts",
"id": "2cb32706-5762-4b96-9212-327e6afaeeff",
"attributes": {
"currency": "EUR",
"name": "My Custom Contract",
"status": "active",
"created_at": 1504801719,
"updated_at": 1504801719
},
"relationships": {
"carrier": {
"data": {
"type": "carriers",
"id": "be7f6752-34e0-49a1-a832-bcc209450ea9"
},
"links": {
"related": "https://api.sandbox.myparcel.com/carriers/be7f6752-34e0-49a1-a832-bcc209450ea9"
}
},
"owner": {
"data": {
"type": "organizations",
"id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
}
},
"liability_coverages": {
"data": [
{
"type": "liability-coverages",
"id": "5a7ef73a-ddea-11e9-8a34-2a2ae2dbcce4"
}
]
},
"template": {
"data": {
"type": "contracts",
"id": "2cb32706-5762-4b96-9212-327e6afaeeff"
},
"links": {
"related": "https://api.sandbox.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff"
}
}
},
"links": {
"self": "https://api.sandbox.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff"
}
}
],
"links": {
"self": "https://api.sandbox.myparcel.com/collections?page[number]=3&page[size]=30",
"first": "https://api.sandbox.myparcel.com/collections?page[number]=1&page[size]=30",
"prev": "https://api.sandbox.myparcel.com/collections?page[number]=2&page[size]=30",
"next": "https://api.sandbox.myparcel.com/collections?page[number]=4&page[size]=30",
"last": "https://api.sandbox.myparcel.com/collections?page[number]=13&page[size]=30"
}
}
.. raw:: html
GET /collections/{collection_id}
Retrieve a specific collection.
**Scope**
Any of the following scopes:
- ``shipments.manage``
- ``shipments.view``
**Request**
.. code-block:: http
GET /collections/{collection_id} HTTP/1.1
Accept: application/vnd.api+json
Example: https://api.sandbox.myparcel.com/collections/e26d781b-6c56-4be5-ae72-505db793d2bd
**Response**
.. code-block:: json
{
"data": {
"type": "collections",
"id": "e26d781b-6c56-4be5-ae72-505db793d2bd",
"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
},
"tracking_code": "TRC123456",
"created_at": 1504801719
},
"relationships": {
"contract": {
"data": {
"type": "contracts",
"id": "2cb32706-5762-4b96-9212-327e6afaeeff"
},
"links": {
"related": "https://api.sandbox.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff"
}
},
"files": {
"data": [
{
"type": "files",
"id": "0f621db6-d239-4ae9-b85d-8e97469b10ce"
}
],
"links": {
"related": "https://api.sandbox.myparcel.com/files/0f621db6-d239-4ae9-b85d-8e97469b10ce"
}
},
"manifest": {
"data": {
"type": "manifests",
"id": "ce7f6752-34e0-49a1-a832-bcc209450ea8"
},
"links": {
"related": "https://api.sandbox.myparcel.com/manifests/ce7f6752-34e0-49a1-a832-bcc209450ea8"
}
},
"shipments": {
"data": [
{
"type": "shipments",
"id": "7b808eee-bf1c-40cd-98f2-3c335a06417e"
}
]
},
"shop": {
"data": {
"type": "shops",
"id": "35eddf50-1d84-47a3-8479-6bfda729cd99"
},
"links": {
"related": "https://api.sandbox.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99"
}
},
"status": {
"data": {
"type": "statuses",
"id": "5c868557-0827-4d21-a7f4-9820f01769f4"
},
"links": {
"related": "https://api.sandbox.myparcel.com/statuses/5c868557-0827-4d21-a7f4-9820f01769f4"
}
}
},
"links": {
"self": "https://api.sandbox.myparcel.com/collections/e26d781b-6c56-4be5-ae72-505db793d2bd"
}
},
"included": [
{
"type": "contracts",
"id": "2cb32706-5762-4b96-9212-327e6afaeeff",
"attributes": {
"currency": "EUR",
"name": "My Custom Contract",
"status": "active",
"created_at": 1504801719,
"updated_at": 1504801719
},
"relationships": {
"carrier": {
"data": {
"type": "carriers",
"id": "be7f6752-34e0-49a1-a832-bcc209450ea9"
},
"links": {
"related": "https://api.sandbox.myparcel.com/carriers/be7f6752-34e0-49a1-a832-bcc209450ea9"
}
},
"owner": {
"data": {
"type": "organizations",
"id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
}
},
"liability_coverages": {
"data": [
{
"type": "liability-coverages",
"id": "5a7ef73a-ddea-11e9-8a34-2a2ae2dbcce4"
}
]
},
"template": {
"data": {
"type": "contracts",
"id": "2cb32706-5762-4b96-9212-327e6afaeeff"
},
"links": {
"related": "https://api.sandbox.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff"
}
}
},
"links": {
"self": "https://api.sandbox.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff"
}
}
]
}
.. raw:: html
POST /collections
Create a new collection.
**Scope**
Any of the following scopes:
- ``shipments.manage``
**Request**
.. code-block:: http
POST /collections HTTP/1.1
Accept: application/vnd.api+json
Example: https://api.sandbox.myparcel.com/collections
.. code-block:: json
{
"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"
}
}
}
}
}
**Response**
.. code-block:: json
{
"data": {
"type": "collections",
"id": "e26d781b-6c56-4be5-ae72-505db793d2bd",
"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
},
"tracking_code": "TRC123456",
"created_at": 1504801719
},
"relationships": {
"contract": {
"data": {
"type": "contracts",
"id": "2cb32706-5762-4b96-9212-327e6afaeeff"
},
"links": {
"related": "https://api.sandbox.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff"
}
},
"files": {
"data": [
{
"type": "files",
"id": "0f621db6-d239-4ae9-b85d-8e97469b10ce"
}
],
"links": {
"related": "https://api.sandbox.myparcel.com/files/0f621db6-d239-4ae9-b85d-8e97469b10ce"
}
},
"manifest": {
"data": {
"type": "manifests",
"id": "ce7f6752-34e0-49a1-a832-bcc209450ea8"
},
"links": {
"related": "https://api.sandbox.myparcel.com/manifests/ce7f6752-34e0-49a1-a832-bcc209450ea8"
}
},
"shipments": {
"data": [
{
"type": "shipments",
"id": "7b808eee-bf1c-40cd-98f2-3c335a06417e"
}
]
},
"shop": {
"data": {
"type": "shops",
"id": "35eddf50-1d84-47a3-8479-6bfda729cd99"
},
"links": {
"related": "https://api.sandbox.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99"
}
},
"status": {
"data": {
"type": "statuses",
"id": "5c868557-0827-4d21-a7f4-9820f01769f4"
},
"links": {
"related": "https://api.sandbox.myparcel.com/statuses/5c868557-0827-4d21-a7f4-9820f01769f4"
}
}
},
"links": {
"self": "https://api.sandbox.myparcel.com/collections/e26d781b-6c56-4be5-ae72-505db793d2bd"
}
}
}
.. raw:: html
PATCH /collections/{collection_id}
Update a specific collection.
**Scope**
Any of the following scopes:
- ``shipments.manage``
**Request**
.. code-block:: http
PATCH /collections/{collection_id} HTTP/1.1
Accept: application/vnd.api+json
Example: https://api.sandbox.myparcel.com/collections/e26d781b-6c56-4be5-ae72-505db793d2bd
.. code-block:: json
{
"data": {
"type": "collections",
"id": "e26d781b-6c56-4be5-ae72-505db793d2bd",
"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"
}
}
}
}
}
**Response**
.. code-block:: json
{
"data": {
"type": "collections",
"id": "e26d781b-6c56-4be5-ae72-505db793d2bd",
"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
},
"tracking_code": "TRC123456",
"created_at": 1504801719
},
"relationships": {
"contract": {
"data": {
"type": "contracts",
"id": "2cb32706-5762-4b96-9212-327e6afaeeff"
},
"links": {
"related": "https://api.sandbox.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff"
}
},
"files": {
"data": [
{
"type": "files",
"id": "0f621db6-d239-4ae9-b85d-8e97469b10ce"
}
],
"links": {
"related": "https://api.sandbox.myparcel.com/files/0f621db6-d239-4ae9-b85d-8e97469b10ce"
}
},
"manifest": {
"data": {
"type": "manifests",
"id": "ce7f6752-34e0-49a1-a832-bcc209450ea8"
},
"links": {
"related": "https://api.sandbox.myparcel.com/manifests/ce7f6752-34e0-49a1-a832-bcc209450ea8"
}
},
"shipments": {
"data": [
{
"type": "shipments",
"id": "7b808eee-bf1c-40cd-98f2-3c335a06417e"
}
]
},
"shop": {
"data": {
"type": "shops",
"id": "35eddf50-1d84-47a3-8479-6bfda729cd99"
},
"links": {
"related": "https://api.sandbox.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99"
}
},
"status": {
"data": {
"type": "statuses",
"id": "5c868557-0827-4d21-a7f4-9820f01769f4"
},
"links": {
"related": "https://api.sandbox.myparcel.com/statuses/5c868557-0827-4d21-a7f4-9820f01769f4"
}
}
},
"links": {
"self": "https://api.sandbox.myparcel.com/collections/e26d781b-6c56-4be5-ae72-505db793d2bd"
}
}
}
.. raw:: html
DELETE /collections/{collection_id}
Delete a collection.
.. note::
Collections that have been registered cannot be deleted.
**Scope**
Any of the following scopes:
- ``shipments.manage``
**Request**
.. code-block:: http
DELETE /collections/{collection_id} HTTP/1.1
Accept: application/vnd.api+json
Example: https://api.sandbox.myparcel.com/collections/e26d781b-6c56-4be5-ae72-505db793d2bd
**Response**
.. code-block:: http
HTTP/1.1 204 The collection has been deleted.
.. raw:: html