Collections

Collections are used to have the carrier pick up shipments from a home or business address.

Attributes

Attribute	Type	Required	Description
address	address	✓	The address where the collection should take place.
collection_time	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	contract	✓	The contract that is used for this collection. Its credentials will be used to create the collection at the carrier.
shop	shop	✓	The shop to create the collection for.
status	status	✓	The status of the collection.
files	array of files		The files that are attached to the collection.
manifest	manifest		The manifest of the shipments to be collected.
shipments	array of 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

GET /collections

Retrieving a list of collections.

Scope

Any of the following scopes:

shipments.manage
shipments.view

Request

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

Response

{
  "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"
  }
}

GET /collections/{collection_id}

Retrieve a specific collection.

Scope

Any of the following scopes:

shipments.manage
shipments.view

Request

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

{
  "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"
      }
    }
  ]
}

POST /collections

Create a new collection.

Scope

Any of the following scopes:

shipments.manage

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"
        }
      }
    }
  }
}

Response

{
  "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"
    }
  }
}

PATCH /collections/{collection_id}

Update a specific collection.

Scope

Any of the following scopes:

shipments.manage

Request

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

{
  "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

{
  "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"
    }
  }
}

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

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

HTTP/1.1 204 The collection has been deleted.