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://sandbox-api.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"
        },
        "register": true,
        "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://sandbox-api.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff"
          }
        },
        "files": {
          "data": [
            {
              "type": "files",
              "id": "0f621db6-d239-4ae9-b85d-8e97469b10ce"
            }
          ],
          "links": {
            "related": "https://sandbox-api.myparcel.com/files/0f621db6-d239-4ae9-b85d-8e97469b10ce"
          }
        },
        "manifest": {
          "data": {
            "type": "manifests",
            "id": "ce7f6752-34e0-49a1-a832-bcc209450ea8"
          },
          "links": {
            "related": "https://sandbox-api.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://sandbox-api.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99"
          }
        },
        "status": {
          "data": {
            "type": "statuses",
            "id": "5c868557-0827-4d21-a7f4-9820f01769f4"
          },
          "links": {
            "related": "https://sandbox-api.myparcel.com/statuses/5c868557-0827-4d21-a7f4-9820f01769f4"
          }
        }
      },
      "links": {
        "self": "https://sandbox-api.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://sandbox-api.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://sandbox-api.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff"
          }
        }
      },
      "links": {
        "self": "https://sandbox-api.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff"
      }
    }
  ],
  "links": {
    "self": "https://sandbox-api.myparcel.com/collections?page[number]=3&page[size]=30",
    "first": "https://sandbox-api.myparcel.com/collections?page[number]=1&page[size]=30",
    "prev": "https://sandbox-api.myparcel.com/collections?page[number]=2&page[size]=30",
    "next": "https://sandbox-api.myparcel.com/collections?page[number]=4&page[size]=30",
    "last": "https://sandbox-api.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://sandbox-api.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"
      },
      "register": true,
      "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://sandbox-api.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff"
        }
      },
      "files": {
        "data": [
          {
            "type": "files",
            "id": "0f621db6-d239-4ae9-b85d-8e97469b10ce"
          }
        ],
        "links": {
          "related": "https://sandbox-api.myparcel.com/files/0f621db6-d239-4ae9-b85d-8e97469b10ce"
        }
      },
      "manifest": {
        "data": {
          "type": "manifests",
          "id": "ce7f6752-34e0-49a1-a832-bcc209450ea8"
        },
        "links": {
          "related": "https://sandbox-api.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://sandbox-api.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99"
        }
      },
      "status": {
        "data": {
          "type": "statuses",
          "id": "5c868557-0827-4d21-a7f4-9820f01769f4"
        },
        "links": {
          "related": "https://sandbox-api.myparcel.com/statuses/5c868557-0827-4d21-a7f4-9820f01769f4"
        }
      }
    },
    "links": {
      "self": "https://sandbox-api.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://sandbox-api.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://sandbox-api.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff"
          }
        }
      },
      "links": {
        "self": "https://sandbox-api.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://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"
        }
      },
      "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"
      },
      "register": true,
      "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.develop.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff"
        }
      },
      "files": {
        "data": [
          {
            "type": "files",
            "id": "0f621db6-d239-4ae9-b85d-8e97469b10ce"
          }
        ],
        "links": {
          "related": "https://api.develop.myparcel.com/files/0f621db6-d239-4ae9-b85d-8e97469b10ce"
        }
      },
      "manifest": {
        "data": {
          "type": "manifests",
          "id": "ce7f6752-34e0-49a1-a832-bcc209450ea8"
        },
        "links": {
          "related": "https://api.develop.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.develop.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99"
        }
      },
      "status": {
        "data": {
          "type": "statuses",
          "id": "5c868557-0827-4d21-a7f4-9820f01769f4"
        },
        "links": {
          "related": "https://api.develop.myparcel.com/statuses/5c868557-0827-4d21-a7f4-9820f01769f4"
        }
      }
    },
    "links": {
      "self": "https://api.develop.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://sandbox-api.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"
      },
      "register": true,
      "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.develop.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff"
        }
      },
      "files": {
        "data": [
          {
            "type": "files",
            "id": "0f621db6-d239-4ae9-b85d-8e97469b10ce"
          }
        ],
        "links": {
          "related": "https://api.develop.myparcel.com/files/0f621db6-d239-4ae9-b85d-8e97469b10ce"
        }
      },
      "manifest": {
        "data": {
          "type": "manifests",
          "id": "ce7f6752-34e0-49a1-a832-bcc209450ea8"
        },
        "links": {
          "related": "https://api.develop.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.develop.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99"
        }
      },
      "status": {
        "data": {
          "type": "statuses",
          "id": "5c868557-0827-4d21-a7f4-9820f01769f4"
        },
        "links": {
          "related": "https://api.develop.myparcel.com/statuses/5c868557-0827-4d21-a7f4-9820f01769f4"
        }
      }
    },
    "links": {
      "self": "https://api.develop.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://sandbox-api.myparcel.com/collections/e26d781b-6c56-4be5-ae72-505db793d2bd

Response

HTTP/1.1 204 The collection has been deleted.