Shipments

Shipments are at the core of our API. They contain files such as labels and are used to track the status of the physical shipment being delivered by the carrier.

Attributes

Attribute

Type

Required

Description

recipient_address

address

The address of the recipient of the shipment.

return_address

address

The address the shipment can be returned to when shipment fails.

sender_address

address

The address of the sender of the shipment.

physical_properties

physical-properties

Weight and dimensions of the shipment.

pickup_location

pickup-dropoff-locations

When chosen service has delivery method pick-up

The place where the recipient can pick up their shipment.

description

string

For international shipments

Short description of the shipment that will be printed on the label when possible.

items

array of items

For international shipments

The contents of the shipment.

customs

customs

For international shipments

Information required for the shipment to pass customs.

sender_tax_identification_numbers

array of tax-identification-numbers

Tax ID numbers of the sender. Any numbers passed on the shipment will overwrite numbers of the same type and country_code defined on the organization of this shipment’s shop during registration.

recipient_tax_identification_numbers

array of tax-identification-numbers

Tax ID numbers of the recipient.

customer_reference

string

Internal customer reference that can be used to identify shipments. This field is not communicated to the carrier.

channel

string

Name of the application or integration (and potentially version number) used to create the shipment.

price

price

The price of the shipment.

total_value

price

The total value of the shipment.

barcode

string

Textual representation of the barcode present on the label.

tracking_code

string

Used to request tracking status from the carrier.

tracking_url

string

Points to the tracking software of the carrier.

register_at

integer

Unix timestamp for when the shipment will be registered with the carrier. After registration, labels will be made available.

created_at

integer

Unix timestamp for when the shipment was created.

updated_at

integer

Unix timestamp for when the shipment resource was last updated.

synced_at

integer

Unix timestamp for when the shipment status was last checked with the carrier.

tags

array of strings or numbers

User defined tags for the shipment.

Relationship

Type

Required

Description

shop

shops

The shop the shipment belongs to.

service

services

The service used to send the shipment.

contract

contracts

The contract to use for the chosen service.

service_options

array of service-options

The service options chosen for the shipment.

shipment_status

shipment-statuses

The current shipment status for the shipment.

files

array of files

The files available for the shipment. Such as the label and possible customs documents.

hook_logs

array of hook-logs

The logs of the hooks that were applied to this this shipment. Such as updating the service or the contract.

Endpoints

GET /shipments

Retrieving a list of shipments.

Scope

Any of the following scopes:

  • shipments.manage

Request

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

Response

{
  "data": [
    {
      "type": "shipments",
      "id": "7b808eee-bf1c-40cd-98f2-3c335a06417e",
      "attributes": {
        "recipient_address": {
          "street_1": "Baker Street",
          "street_2": "Marylebone",
          "street_number": 221,
          "street_number_suffix": "B",
          "postal_code": "NW1 6XE",
          "city": "London",
          "country_code": "GB",
          "first_name": "Sherlock",
          "last_name": "Holmes",
          "company": "Holmes Investigations",
          "phone_number": "+31 234 567 890"
        },
        "return_address": {
          "street_1": "Baker Street",
          "street_2": "Marylebone",
          "street_number": 221,
          "street_number_suffix": "B",
          "postal_code": "NW1 6XE",
          "city": "London",
          "country_code": "GB",
          "first_name": "Sherlock",
          "last_name": "Holmes",
          "company": "Holmes Investigations",
          "phone_number": "+31 234 567 890"
        },
        "sender_address": {
          "street_1": "Baker Street",
          "street_2": "Marylebone",
          "street_number": 221,
          "street_number_suffix": "B",
          "postal_code": "NW1 6XE",
          "city": "London",
          "country_code": "GB",
          "first_name": "Sherlock",
          "last_name": "Holmes",
          "company": "Holmes Investigations",
          "phone_number": "+31 234 567 890"
        },
        "pickup_location": {
          "code": "205604",
          "address": {
            "street_1": "Baker Street",
            "street_2": "Marylebone",
            "street_number": 221,
            "street_number_suffix": "B",
            "postal_code": "NW1 6XE",
            "city": "London",
            "country_code": "GB",
            "first_name": "Sherlock",
            "last_name": "Holmes",
            "company": "Holmes Investigations",
            "phone_number": "+31 234 567 890"
          }
        },
        "description": "Fidget spinners",
        "customer_reference": "#8008135",
        "channel": "MyParcel.com Back Office",
        "price": {
          "amount": 995,
          "currency": "EUR"
        },
        "total_value": {
          "amount": 25000,
          "currency": "EUR"
        },
        "barcode": "3SABCD0123456789",
        "tracking_code": "3SABCD0123456789",
        "tracking_url": "https://tracker.carrier.com/3SABCD0123456789",
        "physical_properties": {
          "height": 150,
          "width": 300,
          "length": 500,
          "volume": 22.5,
          "weight": 5000,
          "volumetric_weight": 4500
        },
        "items": [
          {
            "sku": "123456789",
            "description": "OnePlus X",
            "image_url": "https://some.image.url/file.png",
            "item_value": {
              "amount": 995,
              "currency": "EUR"
            },
            "quantity": 2,
            "hs_code": "8517.12.00",
            "origin_country_code": "GB",
            "nett_weight": 135
          }
        ],
        "register_at": 1504801719,
        "created_at": 1504801719,
        "updated_at": 1504801719,
        "synced_at": 1504801719,
        "tags": ["my", "personal", "tags"]
      },
      "relationships": {
        "service_options": {
          "data": [
            {
              "type": "service-options",
              "id": "4c675b1a-516c-4410-abff-d237fd45bcd0"
            }
          ]
        },
        "service": {
          "data": {
            "type": "services",
            "id": "175a235f-aff5-4e44-87b5-3657b75c1deb"
          },
          "links": {
            "related": "https://sandbox-api.myparcel.com/services/175a235f-aff5-4e44-87b5-3657b75c1deb"
          }
        },
        "contract": {
          "data": {
            "type": "contracts",
            "id": "2cb32706-5762-4b96-9212-327e6afaeeff"
          },
          "links": {
            "related": "https://sandbox-api.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff"
          }
        },
        "shop": {
          "data": {
            "type": "shops",
            "id": "35eddf50-1d84-47a3-8479-6bfda729cd99"
          },
          "links": {
            "related": "https://sandbox-api.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99"
          }
        },
        "shipment_status": {
          "data": {
            "type": "shipment-statuses",
            "id": "9e6d8dba-7c45-4351-a9fc-b55a0cbafbad"
          },
          "links": {
            "related": "https://sandbox-api.myparcel.com/shipments/7b808eee-bf1c-40cd-98f2-3c335a06417e/statuses/9e6d8dba-7c45-4351-a9fc-b55a0cbafbad"
          }
        },
        "files": {
          "data": [
            {
              "type": "files",
              "id": "0f621db6-d239-4ae9-b85d-8e97469b10ce"
            }
          ]
        },
        "hook_logs": {
          "data": [
            {
              "type": "hook-logs",
              "id": "8e141db6-d638-9ae0-e33d-8e97469b10ce"
            }
          ]
        }
      },
      "links": {
        "self": "https://sandbox-api.myparcel.com/shipments/7b808eee-bf1c-40cd-98f2-3c335a06417e",
        "files": "https://sandbox-api.myparcel.com/shipments/0f621db6-d239-4ae9-b85d-8e97469b10ce/files"
      }
    },
    {
      "type": "shipments",
      "id": "7b808eee-bf1c-40cd-98f2-3c335a06417e",
      "attributes": {
        "recipient_address": {
          "street_1": "Baker Street",
          "street_2": "Marylebone",
          "street_number": 221,
          "street_number_suffix": "B",
          "postal_code": "NW1 6XE",
          "city": "London",
          "country_code": "GB",
          "first_name": "Sherlock",
          "last_name": "Holmes",
          "company": "Holmes Investigations",
          "phone_number": "+31 234 567 890"
        },
        "return_address": {
          "street_1": "Baker Street",
          "street_2": "Marylebone",
          "street_number": 221,
          "street_number_suffix": "B",
          "postal_code": "NW1 6XE",
          "city": "London",
          "country_code": "GB",
          "first_name": "Sherlock",
          "last_name": "Holmes",
          "company": "Holmes Investigations",
          "phone_number": "+31 234 567 890"
        },
        "sender_address": {
          "street_1": "Baker Street",
          "street_2": "Marylebone",
          "street_number": 221,
          "street_number_suffix": "B",
          "postal_code": "NW1 6XE",
          "city": "London",
          "country_code": "GB",
          "first_name": "Sherlock",
          "last_name": "Holmes",
          "company": "Holmes Investigations",
          "phone_number": "+31 234 567 890"
        },
        "pickup_location": {
          "code": "205604",
          "address": {
            "street_1": "Baker Street",
            "street_2": "Marylebone",
            "street_number": 221,
            "street_number_suffix": "B",
            "postal_code": "NW1 6XE",
            "city": "London",
            "country_code": "GB",
            "first_name": "Sherlock",
            "last_name": "Holmes",
            "company": "Holmes Investigations",
            "phone_number": "+31 234 567 890"
          }
        },
        "description": "Fidget spinners",
        "customer_reference": "#8008135",
        "channel": "MyParcel.com Back Office",
        "price": {
          "amount": 995,
          "currency": "EUR"
        },
        "total_value": {
          "amount": 25000,
          "currency": "EUR"
        },
        "barcode": "3SABCD0123456789",
        "tracking_code": "3SABCD0123456789",
        "tracking_url": "https://tracker.carrier.com/3SABCD0123456789",
        "physical_properties": {
          "height": 150,
          "width": 300,
          "length": 500,
          "volume": 22.5,
          "weight": 5000,
          "volumetric_weight": 4500
        },
        "items": [
          {
            "sku": "123456789",
            "description": "OnePlus X",
            "image_url": "https://some.image.url/file.png",
            "item_value": {
              "amount": 995,
              "currency": "EUR"
            },
            "quantity": 2,
            "hs_code": "8517.12.00",
            "origin_country_code": "GB",
            "nett_weight": 135
          }
        ],
        "register_at": 1504801719,
        "created_at": 1504801719,
        "updated_at": 1504801719,
        "synced_at": 1504801719,
        "tags": ["my", "personal", "tags"]
      },
      "relationships": {
        "service_options": {
          "data": [
            {
              "type": "service-options",
              "id": "4c675b1a-516c-4410-abff-d237fd45bcd0"
            }
          ]
        },
        "service": {
          "data": {
            "type": "services",
            "id": "175a235f-aff5-4e44-87b5-3657b75c1deb"
          },
          "links": {
            "related": "https://sandbox-api.myparcel.com/services/175a235f-aff5-4e44-87b5-3657b75c1deb"
          }
        },
        "contract": {
          "data": {
            "type": "contracts",
            "id": "2cb32706-5762-4b96-9212-327e6afaeeff"
          },
          "links": {
            "related": "https://sandbox-api.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff"
          }
        },
        "shop": {
          "data": {
            "type": "shops",
            "id": "35eddf50-1d84-47a3-8479-6bfda729cd99"
          },
          "links": {
            "related": "https://sandbox-api.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99"
          }
        },
        "shipment_status": {
          "data": {
            "type": "shipment-statuses",
            "id": "9e6d8dba-7c45-4351-a9fc-b55a0cbafbad"
          },
          "links": {
            "related": "https://sandbox-api.myparcel.com/shipments/7b808eee-bf1c-40cd-98f2-3c335a06417e/statuses/9e6d8dba-7c45-4351-a9fc-b55a0cbafbad"
          }
        },
        "files": {
          "data": [
            {
              "type": "files",
              "id": "0f621db6-d239-4ae9-b85d-8e97469b10ce"
            }
          ]
        },
        "hook_logs": {
          "data": [
            {
              "type": "hook-logs",
              "id": "8e141db6-d638-9ae0-e33d-8e97469b10ce"
            }
          ]
        }
      },
      "links": {
        "self": "https://sandbox-api.myparcel.com/shipments/7b808eee-bf1c-40cd-98f2-3c335a06417e",
        "files": "https://sandbox-api.myparcel.com/shipments/0f621db6-d239-4ae9-b85d-8e97469b10ce/files"
      }
    }
  ],
  "meta": {
    "total_pages": 13,
    "total_records": 373
  },
  "links": {
    "self": "https://sandbox-api.myparcel.com/shipments?page[number]=3&page[size]=30",
    "first": "https://sandbox-api.myparcel.com/shipments?page[number]=1&page[size]=30",
    "prev": "https://sandbox-api.myparcel.com/shipments?page[number]=2&page[size]=30",
    "next": "https://sandbox-api.myparcel.com/shipments?page[number]=4&page[size]=30",
    "last": "https://sandbox-api.myparcel.com/shipments?page[number]=13&page[size]=30"
  }
}
GET /shipments/{shipment_id}

Retrieve a specific shipment.

Scope

Any of the following scopes:

  • shipments.manage

Request

GET /shipments/{shipment_id} HTTP/1.1
Accept: application/vnd.api+json
Example: https://sandbox-api.myparcel.com/shipments/7b808eee-bf1c-40cd-98f2-3c335a06417e

Response

{
  "data": {
    "type": "shipments",
    "id": "7b808eee-bf1c-40cd-98f2-3c335a06417e",
    "attributes": {
      "recipient_address": {
        "street_1": "Hoofdweg 679",
        "street_number": 679,
        "postal_code": "2131BC",
        "city": "Amsterdam",
        "country_code": "NL",
        "first_name": "Sherlock",
        "last_name": "Holmes",
        "company": "Holmes Investigations",
        "email": "s.holmes@holmesinvestigations.com",
        "phone_number": "+31 234 567 890"
      },
      "return_address": {
        "street_1": "Baker Street",
        "street_2": "Marylebone",
        "street_number": 221,
        "street_number_suffix": "B",
        "postal_code": "NW1 6XE",
        "city": "London",
        "country_code": "GB",
        "first_name": "Sherlock",
        "last_name": "Holmes",
        "company": "Holmes Investigations",
        "email": "s.holmes@holmesinvestigations.com",
        "phone_number": "+31 234 567 890"
      },
      "sender_address": {
        "street_1": "Baker Street",
        "street_2": "Marylebone",
        "street_number": 221,
        "street_number_suffix": "B",
        "postal_code": "NW1 6XE",
        "city": "London",
        "country_code": "GB",
        "first_name": "Sherlock",
        "last_name": "Holmes",
        "company": "Holmes Investigations",
        "email": "s.holmes@holmesinvestigations.com",
        "phone_number": "+31 234 567 890"
      },
      "description": "Phones",
      "customer_reference": "#8008135",
      "channel": "MyParcel.com Back Office",
      "physical_properties": {
        "height": 150,
        "width": 300,
        "length": 500,
        "volume": 22.5,
        "weight": 5000,
        "volumetric_weight": 4500
      },
      "sender_tax_identification_numbers": [
        {
          "type": "ioss",
          "country_code": "GB",
          "description": "My IOSS number for GB",
          "number": "1055405334"
        },
        {
          "type": "eori",
          "country_code": "GB",
          "description": "My GB EORI number",
          "number": "XI459273951"
        }
      ],
      "recipient_tax_identification_numbers": [
        {
          "type": "vat",
          "country_code": "NL",
          "description": "VAT number for NL",
          "number": "123abc456"
        }
      ],
      "items": [
        {
          "sku": "123456789",
          "description": "OnePlus X",
          "image_url": "https://some.image.url/file.png",
          "item_value": {
            "amount": 995,
            "currency": "EUR"
          },
          "quantity": 2,
          "hs_code": "8517.12.00",
          "origin_country_code": "GB",
          "nett_weight": 135
        }
      ],
      "customs": {
        "content_type": "merchandise",
        "invoice_number": "9000",
        "non_delivery": "return",
        "incoterm": "DAP",
        "shipping_value": {
          "amount": 995,
          "currency": "EUR"
        },
        "license_number": "218532158",
        "certificate_number": "12122121"
      },
      "register_at": 1504801719,
      "price": {
        "amount": 995,
        "currency": "EUR"
      },
      "total_value": {
        "amount": 25000,
        "currency": "EUR"
      },
      "barcode": "3SABCD0123456789",
      "tracking_code": "3SABCD0123456789",
      "tracking_url": "https://tracker.carrier.com/3SABCD0123456789",
      "created_at": 1504801719,
      "updated_at": 1504801719,
      "synced_at": 1504801719,
      "tags": ["my", "personal", "tags"]
    },
    "relationships": {
      "service_options": {
        "data": [
          {
            "type": "service-options",
            "id": "4c675b1a-516c-4410-abff-d237fd45bcd0"
          }
        ]
      },
      "shop": {
        "data": {
          "type": "shops",
          "id": "35eddf50-1d84-47a3-8479-6bfda729cd99"
        },
        "links": {
          "related": "https://sandbox-api.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99"
        }
      },
      "service": {
        "data": {
          "type": "services",
          "id": "175a235f-aff5-4e44-87b5-3657b75c1deb"
        },
        "links": {
          "related": "https://sandbox-api.myparcel.com/services/175a235f-aff5-4e44-87b5-3657b75c1deb"
        }
      },
      "contract": {
        "data": {
          "type": "contracts",
          "id": "2cb32706-5762-4b96-9212-327e6afaeeff"
        },
        "links": {
          "related": "https://sandbox-api.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff"
        }
      },
      "shipment_status": {
        "data": {
          "type": "shipment-statuses",
          "id": "9e6d8dba-7c45-4351-a9fc-b55a0cbafbad"
        },
        "links": {
          "related": "https://sandbox-api.myparcel.com/shipments/7b808eee-bf1c-40cd-98f2-3c335a06417e/statuses/9e6d8dba-7c45-4351-a9fc-b55a0cbafbad"
        }
      },
      "files": {
        "data": [
          {
            "type": "files",
            "id": "0f621db6-d239-4ae9-b85d-8e97469b10ce"
          }
        ]
      },
      "hook_logs": {
        "data": [
          {
            "type": "hook-logs",
            "id": "8e141db6-d638-9ae0-e33d-8e97469b10ce"
          }
        ]
      }
    },
    "links": {
      "self": "https://sandbox-api.myparcel.com/shipments/7b808eee-bf1c-40cd-98f2-3c335a06417e",
      "files": "https://sandbox-api.myparcel.com/shipments/0f621db6-d239-4ae9-b85d-8e97469b10ce/files"
    }
  }
}
POST /shipments

Create a shipment.

Scope

  • shipments.manage

Meta data

The POST /shipments endpoint allows the user to send a meta property in addition to the main data attribute. In this meta property, the following properties can be included:

Property

Type

Description

label

object

Requested mime_type and size for the shipment’s label.

service_code

string

Requested code for the shipment’s service.

Note

This meta information is not returned in the response.

Request headers

Header Description =============== =========== Idempotency-Key Populate this header with a value unique to the request data if you want to prevent duplicate shipments when you call this endpoint multiple times, for example due to network issues. See how to create an idempotency key.

Note

If a request with the same idempotency key has been processed in the last 24 hours, the response of that request will be replayed (same resource data or carrier error). Replays are indicated by the Idempotency-Replay header with value true on the response.

Request

POST /shipments HTTP/1.1
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Example: https://sandbox-api.myparcel.com/shipments

{
  "data": {
    "type": "shipments",
    "attributes": {
      "recipient_address": {
        "street_1": "Hoofdweg 679",
        "street_number": 679,
        "postal_code": "2131BC",
        "city": "Amsterdam",
        "country_code": "NL",
        "first_name": "Sherlock",
        "last_name": "Holmes",
        "company": "Holmes Investigations",
        "email": "s.holmes@holmesinvestigations.com",
        "phone_number": "+31 234 567 890"
      },
      "return_address": {
        "street_1": "Baker Street",
        "street_2": "Marylebone",
        "street_number": 221,
        "street_number_suffix": "B",
        "postal_code": "NW1 6XE",
        "city": "London",
        "country_code": "GB",
        "first_name": "Sherlock",
        "last_name": "Holmes",
        "company": "Holmes Investigations",
        "email": "s.holmes@holmesinvestigations.com",
        "phone_number": "+31 234 567 890"
      },
      "sender_address": {
        "street_1": "Baker Street",
        "street_2": "Marylebone",
        "street_number": 221,
        "street_number_suffix": "B",
        "postal_code": "NW1 6XE",
        "city": "London",
        "country_code": "GB",
        "first_name": "Sherlock",
        "last_name": "Holmes",
        "company": "Holmes Investigations",
        "email": "s.holmes@holmesinvestigations.com",
        "phone_number": "+31 234 567 890"
      },
      "pickup_location": {
        "code": "205604",
        "address": {
          "street_1": "Baker Street",
          "street_2": "Marylebone",
          "street_number": 221,
          "street_number_suffix": "B",
          "postal_code": "NW1 6XE",
          "city": "London",
          "country_code": "GB",
          "first_name": "Sherlock",
          "last_name": "Holmes",
          "company": "Holmes Investigations",
          "email": "s.holmes@holmesinvestigations.com",
          "phone_number": "+31 234 567 890"
        }
      },
      "description": "Phones",
      "customer_reference": "#8008135",
      "channel": "MyParcel.com Back Office",
      "physical_properties": {
        "height": 150,
        "width": 300,
        "length": 500,
        "volume": 22.5,
        "weight": 5000
      },
      "items": [
        {
          "sku": "123456789",
          "description": "OnePlus X",
          "image_url": "https://some.image.url/file.png",
          "item_value": {
            "amount": 995,
            "currency": "EUR"
          },
          "quantity": 2,
          "hs_code": "8517.12.00",
          "origin_country_code": "GB",
          "nett_weight": 135
        }
      ],
      "sender_tax_identification_numbers": [
        {
          "type": "ioss",
          "country_code": "GB",
          "description": "My IOSS number for GB",
          "number": "1055405334"
        },
        {
          "type": "eori",
          "country_code": "GB",
          "description": "My GB EORI number",
          "number": "XI459273951"
        }
      ],
      "recipient_tax_identification_numbers": [
        {
          "type": "vat",
          "country_code": "NL",
          "description": "VAT number for NL",
          "number": "123abc456"
        }
      ],
      "customs": {
        "content_type": "merchandise",
        "invoice_number": "9000",
        "non_delivery": "return",
        "incoterm": "DAP",
        "shipping_value": {
          "amount": 995,
          "currency": "EUR"
        },
        "license_number": "218532158",
        "certificate_number": "12122121"
      },
      "register_at": 1504801719,
      "tags": ["my", "personal", "tags"]
    },
    "relationships": {
      "service_options": {
        "data": [
          {
            "type": "service-options",
            "id": "4c675b1a-516c-4410-abff-d237fd45bcd0"
          }
        ]
      },
      "shop": {
        "data": {
          "type": "shops",
          "id": "35eddf50-1d84-47a3-8479-6bfda729cd99"
        }
      },
      "service": {
        "data": {
          "type": "services",
          "id": "175a235f-aff5-4e44-87b5-3657b75c1deb"
        }
      },
      "contract": {
        "data": {
          "type": "contracts",
          "id": "2cb32706-5762-4b96-9212-327e6afaeeff"
        }
      }
    }
  },
  "meta": {
    "label_mime_type": "application/zpl"
  }
}

Response

{
  "data": {
    "type": "shipments",
    "id": "7b808eee-bf1c-40cd-98f2-3c335a06417e",
    "attributes": {
      "recipient_address": {
        "street_1": "Hoofdweg 679",
        "street_number": 679,
        "postal_code": "2131BC",
        "city": "Amsterdam",
        "country_code": "NL",
        "first_name": "Sherlock",
        "last_name": "Holmes",
        "company": "Holmes Investigations",
        "email": "s.holmes@holmesinvestigations.com",
        "phone_number": "+31 234 567 890"
      },
      "return_address": {
        "street_1": "Baker Street",
        "street_2": "Marylebone",
        "street_number": 221,
        "street_number_suffix": "B",
        "postal_code": "NW1 6XE",
        "city": "London",
        "country_code": "GB",
        "first_name": "Sherlock",
        "last_name": "Holmes",
        "company": "Holmes Investigations",
        "email": "s.holmes@holmesinvestigations.com",
        "phone_number": "+31 234 567 890"
      },
      "sender_address": {
        "street_1": "Baker Street",
        "street_2": "Marylebone",
        "street_number": 221,
        "street_number_suffix": "B",
        "postal_code": "NW1 6XE",
        "city": "London",
        "country_code": "GB",
        "first_name": "Sherlock",
        "last_name": "Holmes",
        "company": "Holmes Investigations",
        "email": "s.holmes@holmesinvestigations.com",
        "phone_number": "+31 234 567 890"
      },
      "pickup_location": {
        "code": "205604",
        "address": {
          "street_1": "Baker Street",
          "street_2": "Marylebone",
          "street_number": 221,
          "street_number_suffix": "B",
          "postal_code": "NW1 6XE",
          "city": "London",
          "country_code": "GB",
          "first_name": "Sherlock",
          "last_name": "Holmes",
          "company": "Holmes Investigations",
          "email": "s.holmes@holmesinvestigations.com",
          "phone_number": "+31 234 567 890"
        }
      },
      "description": "Phones",
      "customer_reference": "#8008135",
      "channel": "MyParcel.com Back Office",
      "physical_properties": {
        "height": 150,
        "width": 300,
        "length": 500,
        "volume": 22.5,
        "weight": 5000,
        "volumetric_weight": 4500
      },
      "items": [
        {
          "sku": "123456789",
          "description": "OnePlus X",
          "image_url": "https://some.image.url/file.png",
          "item_value": {
            "amount": 995,
            "currency": "EUR"
          },
          "quantity": 2,
          "hs_code": "8517.12.00",
          "origin_country_code": "GB",
          "nett_weight": 135
        }
      ],
      "sender_tax_identification_numbers": [
        {
          "type": "ioss",
          "country_code": "GB",
          "description": "My IOSS number for GB",
          "number": "1055405334"
        },
        {
          "type": "eori",
          "country_code": "GB",
          "description": "My GB EORI number",
          "number": "XI459273951"
        }
      ],
      "recipient_tax_identification_numbers": [
        {
          "type": "vat",
          "country_code": "NL",
          "description": "VAT number for NL",
          "number": "123abc456"
        }
      ],
      "customs": {
        "content_type": "merchandise",
        "invoice_number": "9000",
        "non_delivery": "return",
        "incoterm": "DAP",
        "shipping_value": {
          "amount": 995,
          "currency": "EUR"
        },
        "license_number": "218532158",
        "certificate_number": "12122121"
      },
      "register_at": 1504801719,
      "price": {
        "amount": 995,
        "currency": "EUR"
      },
      "total_value": {
        "amount": 25000,
        "currency": "EUR"
      },
      "barcode": "3SABCD0123456789",
      "tracking_code": "3SABCD0123456789",
      "tracking_url": "https://tracker.carrier.com/3SABCD0123456789",
      "created_at": 1504801719,
      "updated_at": 1504801719,
      "synced_at": 1504801719,
      "tags": ["my", "personal", "tags"]
    },
    "relationships": {
      "service_options": {
        "data": [
          {
            "type": "service-options",
            "id": "4c675b1a-516c-4410-abff-d237fd45bcd0"
          }
        ]
      },
      "shop": {
        "data": {
          "type": "shops",
          "id": "35eddf50-1d84-47a3-8479-6bfda729cd99"
        },
        "links": {
          "related": "https://sandbox-api.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99"
        }
      },
      "service": {
        "data": {
          "type": "services",
          "id": "175a235f-aff5-4e44-87b5-3657b75c1deb"
        },
        "links": {
          "related": "https://sandbox-api.myparcel.com/services/175a235f-aff5-4e44-87b5-3657b75c1deb"
        }
      },
      "contract": {
        "data": {
          "type": "contracts",
          "id": "2cb32706-5762-4b96-9212-327e6afaeeff"
        },
        "links": {
          "related": "https://sandbox-api.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff"
        }
      },
      "shipment_status": {
        "data": {
          "type": "shipment-statuses",
          "id": "9e6d8dba-7c45-4351-a9fc-b55a0cbafbad"
        },
        "links": {
          "related": "https://sandbox-api.myparcel.com/shipments/7b808eee-bf1c-40cd-98f2-3c335a06417e/statuses/9e6d8dba-7c45-4351-a9fc-b55a0cbafbad"
        }
      },
      "files": {
        "data": [
          {
            "type": "files",
            "id": "0f621db6-d239-4ae9-b85d-8e97469b10ce"
          }
        ]
      },
      "hook_logs": {
        "data": [
          {
            "type": "hook-logs",
            "id": "8e141db6-d638-9ae0-e33d-8e97469b10ce"
          }
        ]
      }
    },
    "links": {
      "self": "https://sandbox-api.myparcel.com/shipments/7b808eee-bf1c-40cd-98f2-3c335a06417e",
      "files": "https://sandbox-api.myparcel.com/shipments/0f621db6-d239-4ae9-b85d-8e97469b10ce/files"
    }
  }
}
PATCH /shipments/{shipment_id}

Update an existing shipment.

Scope

  • shipments.manage

Meta data

The PATCH /shipments/{shipment_id} endpoint allows the user to send a meta property in addition to the main data attribute. In this meta property, the following properties can be included:

Property

Type

Description

label

object

Requested mime_type and size for the shipment’s label.

service_code

string

Requested code for the shipment’s service.

Note

This meta information is not returned in the response.

Request

In this example we’re updating the recipient_address.

PATCH /shipments/{shipment_id} HTTP/1.1
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Example: https://sandbox-api.myparcel.com/shipments/7b808eee-bf1c-40cd-98f2-3c335a06417e

{
  "data": {
    "type": "shipments",
    "id": "7b808eee-bf1c-40cd-98f2-3c335a06417e",
    "attributes": {
      "recipient_address": {
        "street_1": "Fifth Avenue",
        "street_2": "Manhattan",
        "street_number": 890,
        "postal_code": "10020",
        "city": "New York",
        "state_code": "NY",
        "country_code": "US",
        "first_name": "Tony",
        "last_name": "Stark",
        "company": "Avengers, inc.",
        "phone_number": "+31 234 567 890"
      }
    }
  }
}

Response

{
  "data": {
    "type": "shipments",
    "id": "7b808eee-bf1c-40cd-98f2-3c335a06417e",
    "attributes": {
      "recipient_address": {
        "street_1": "Fifth Avenue",
        "street_2": "Manhattan",
        "street_number": 890,
        "postal_code": "10020",
        "city": "New York",
        "state_code": "NY",
        "country_code": "US",
        "first_name": "Tony",
        "last_name": "Stark",
        "company": "Avengers, inc.",
        "phone_number": "+31 234 567 890"
      },
      "return_address": {
        "street_1": "Baker Street",
        "street_2": "Marylebone",
        "street_number": 221,
        "street_number_suffix": "B",
        "postal_code": "NW1 6XE",
        "city": "London",
        "country_code": "GB",
        "first_name": "Sherlock",
        "last_name": "Holmes",
        "company": "Holmes Investigations",
        "email": "s.holmes@holmesinvestigations.com",
        "phone_number": "+31 234 567 890"
      },
      "sender_address": {
        "street_1": "Baker Street",
        "street_2": "Marylebone",
        "street_number": 221,
        "street_number_suffix": "B",
        "postal_code": "NW1 6XE",
        "city": "London",
        "country_code": "GB",
        "first_name": "Sherlock",
        "last_name": "Holmes",
        "company": "Holmes Investigations",
        "email": "s.holmes@holmesinvestigations.com",
        "phone_number": "+31 234 567 890"
      },
      "pickup_location": {
        "code": "205604",
        "address": {
          "street_1": "Baker Street",
          "street_2": "Marylebone",
          "street_number": 221,
          "street_number_suffix": "B",
          "postal_code": "NW1 6XE",
          "city": "London",
          "country_code": "GB",
          "first_name": "Sherlock",
          "last_name": "Holmes",
          "company": "Holmes Investigations",
          "email": "s.holmes@holmesinvestigations.com",
          "phone_number": "+31 234 567 890"
        }
      },
      "description": "Fidget spinners",
      "customer_reference": "#8008135",
      "channel": "MyParcel.com Back Office",
      "physical_properties": {
        "height": 150,
        "width": 300,
        "length": 500,
        "volume": 22.5,
        "weight": 5000,
        "volumetric_weight": 4500
      },
      "items": [
        {
          "sku": "123456789",
          "description": "OnePlus X",
          "image_url": "https://some.image.url/file.png",
          "item_value": {
            "amount": 995,
            "currency": "EUR"
          },
          "quantity": 2,
          "hs_code": "8517.12.00",
          "origin_country_code": "GB",
          "nett_weight": 135
        }
      ],
      "customs": {
        "content_type": "merchandise",
        "invoice_number": "9000",
        "non_delivery": "return",
        "incoterm": "DAP",
        "shipping_value": {
          "amount": 995,
          "currency": "EUR"
        },
        "license_number": "218532158",
        "certificate_number": "12122121"
      },
      "register_at": 1504801719,
      "price": {
        "amount": 995,
        "currency": "EUR"
      },
      "total_value": {
        "amount": 25000,
        "currency": "EUR"
      },
      "barcode": "3SABCD0123456789",
      "tracking_code": "3SABCD0123456789",
      "tracking_url": "https://tracker.carrier.com/3SABCD0123456789",
      "created_at": 1504801719,
      "updated_at": 1504801719,
      "synced_at": 1504801719,
      "tags": ["my", "personal", "tags"]
    },
    "relationships": {
      "service_options": {
        "data": [
          {
            "type": "service-options",
            "id": "4c675b1a-516c-4410-abff-d237fd45bcd0"
          }
        ]
      },
      "shop": {
        "data": {
          "type": "shops",
          "id": "35eddf50-1d84-47a3-8479-6bfda729cd99"
        },
        "links": {
          "related": "https://sandbox-api.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99"
        }
      },
      "service": {
        "data": {
          "type": "services",
          "id": "175a235f-aff5-4e44-87b5-3657b75c1deb"
        },
        "links": {
          "related": "https://sandbox-api.myparcel.com/services/175a235f-aff5-4e44-87b5-3657b75c1deb"
        }
      },
      "contract": {
        "data": {
          "type": "contracts",
          "id": "2cb32706-5762-4b96-9212-327e6afaeeff"
        },
        "links": {
          "related": "https://sandbox-api.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff"
        }
      },
      "shipment_status": {
        "data": {
          "type": "shipment-statuses",
          "id": "9e6d8dba-7c45-4351-a9fc-b55a0cbafbad"
        },
        "links": {
          "related": "https://sandbox-api.myparcel.com/shipments/7b808eee-bf1c-40cd-98f2-3c335a06417e/statuses/9e6d8dba-7c45-4351-a9fc-b55a0cbafbad"
        }
      },
      "files": {
        "data": [
          {
            "type": "files",
            "id": "0f621db6-d239-4ae9-b85d-8e97469b10ce"
          }
        ]
      },
      "hook_logs": {
        "data": [
          {
            "type": "hook-logs",
            "id": "8e141db6-d638-9ae0-e33d-8e97469b10ce"
          }
        ]
      }
    },
    "links": {
      "self": "https://sandbox-api.myparcel.com/shipments/7b808eee-bf1c-40cd-98f2-3c335a06417e",
      "files": "https://sandbox-api.myparcel.com/shipments/0f621db6-d239-4ae9-b85d-8e97469b10ce/files"
    }
  }
}
DELETE /shipments/{shipment_id}

Delete an existing shipment.

Note

This is only possible for shipments with the status shipment_concept.

Scope

  • shipments.manage

Request

DELETE /shipments/{shipment_id} HTTP/1.1
Accept: application/vnd.api+json
Example: https://sandbox-api.myparcel.com/shipments/7b808eee-bf1c-40cd-98f2-3c335a06417e

Response

HTTP/1.1 202 The shipment will be deleted.
HTTP/1.1 204 The shipment is deleted.