Create a shipment
=================

.. toctree::
    :hidden:

    create-a-shipment/idempotency
    create-a-shipment/carrier-specific-requirements
    create-a-shipment/add-liability-coverage

Before printing a label to put on a parcel, a :doc:`shipment </api/resources/shipments>` resource should be created in the MyParcel.com API.
Creating such a shipment is done by making a ``POST`` request to either the ``/shipments`` endpoint or the ``/registered-shipments`` endpoint.
The former will create the shipment, save it and depending on the parameters, queue it for registration with the carrier,
while the latter will create the shipment, save it and immediately register it with the carrier.

In order to be able to create a shipment in the MyParcel.com API, the ``shipments.manage`` :doc:`scope </api/authentication/scopes>` needs to be present in the access token used in the request.

Minimum shipment requirements
-----------------------------
In order to successfully register a shipment with a carrier, the following attributes and relationships are always required.

Attributes
__________
The following attributes should always be included in a shipment request:

===================  ===========
Attribute            Description
===================  ===========
recipient_address    :doc:`Address </api/resources/common-objects/addresses>` object containing information of the shipments recipient address.
sender_address       :doc:`Address </api/resources/common-objects/addresses>` object containing information about where the shipment is sent from.
return_address       :doc:`Address </api/resources/common-objects/addresses>` object containing information about where the shipment should be returned to.
physical_properties  `Physical properties </api/resources/shipments.html#physical-properties>`_ object containing information about the dimensions and weight of the shipment.
===================  ===========

.. note::
    Depending on the carrier, additional information may be required.
    For more information, see our page about :doc:`carrier specific requirements </api/create-a-shipment/carrier-specific-requirements>`.

Relationships
_____________
The shop relationship is always required in any shipment creation request.
The service and contract relationships are required for registering the shipment with the carrier,
but do not necessarily have to be set in the initial shipment creation request.

============  ===========
Relationship  Description
============  ===========
shop          A :doc:`shop </api/resources/shops>` relationship object containing the uuid of the shop for which this shipment should be created.
service       A :doc:`service </api/resources/services>` relationship object containing the uuid of the desired service.
contract      A :doc:`contract </api/resources/contracts>` relationship object containing the uuid of the desired contract.
============  ===========

Additionally, you could add a ``service_options`` relationship if you would like to add service options to the shipment. For more information, see the :doc:`service options resource page </api/resources/service-options>`.

Shop relationship
_________________
A shipment is always created for a shop. The shop's ``uuid`` should therefore always be included the shipment request.
To retrieve your shop's ``uuid``, simply call the ``/shops`` endpoint to retrieve all ``shops`` resources available to you.
You can then include the desired shop's ``uuid`` in the shipment request. For an overview of the shop resource, it's attributes and relationships and how to retrieve them, visit the :doc:`resource page on shops </api/resources/shops>`.

Service relationship
____________________
Carriers often have different services available to ship parcels with. These are defined in the MyParcel.com API and should be included as a relationship when creating a shipment. Since services are :doc:`region </api/resources/regions>` specific they should be chosen with the shipments ``sender_address`` and ``recipient_address`` attributes in mind. A shipment from England to England will not be valid if the chosen service only has Spain as destination. For an overview of the service resource, its attributes and relationships and how to retrieve them, visit the :doc:`resource page on services </api/resources/services>`.

Contract relationship
_____________________
Besides a service and a shop, a shipment needs a contract relationship. Contracts are used to communicate to the carrier which party is making the request. The carrier then bills that party accordingly. Different contracts can have different credentials, rates and even services, so it might be the case that a service is available for two different prices, or it might not be available at all. This is what the contracts relationship is for. To create a valid shipment, the related contract of a shipment should be for the same carrier as the chosen service. For an overview of the contract resource, it's attributes and relationships and how to retrieve them, visit the :doc:`resource page on contracts </api/resources/contracts>`.

Service rates
_____________
A service rate cannot be linked to a shipment directly, but should instead be used to consider which service or contract to use for a shipment. The service rate resource is a combination of a service and contract and details the specifics of said service and contract. It contains information on the price, maximum dimensions, weight range and lists which service options are available for this specific combination of service and contract. More information on service rates can be found on the :doc:`service rate resource page </api/resources/service-rates>`.

Attaching a service and contract to the shipment
------------------------------------------------
Choosing a service and contract for your shipment and attaching them to the shipment can be quite confusing at first.
There are multiple ways to determine what service and contract to use, and multiple ways of attaching them to a shipment.
Below is an explanation of two recommended ways of doing so:

- `Retrieving services and contracts based on a shipment </api/create-a-shipment.html#retrieving-services-and-contracts-based-on-shipment-attributes>`_ (if you want to show the price and/or be sure the weight is supported).
- `Use the service-code meta property when posting a shipment </api/create-a-shipment.html#use-the-service-code-meta-property-to-let-the-api-resolve-the-service-and-contract>`_ (if you consider hardcoding values to avoid lookup requests).

You can even omit all service-specific properties and create automation rules for your shop using our `hooks resource </api/using-hooks.html>`_ or `our web interface <https://app.myparcel.com/hooks/new>`_.
This is mainly useful if you are writing an API implementation for a specific shop, for example when you are pushing order data from an e-commerce application.

Retrieving services and contracts based on shipment attributes
______________________________________________________________
In this flow, you do a filtered request to ``GET /services`` followed by a filtered request to ``GET /service-rates``.
Using these endpoints guarantees that we can create the shipment and it provides you with an accurate estimate of the price (if available).

To ensure that a service can be used for a shipment, the services should be retrieved using information from the shipment.
Using filters on the ``GET /services`` endpoint greatly reduces the amount of services returned in the response.
Using the following filters will result in services that are valid for the origin and destination of a shipment:

- ``filter[address_from][country_code]=...``
- ``filter[address_from][postal_code]=...``
- ``filter[address_to][country_code]=...``
- ``filter[address_to][postal_code]=...``

Additionally, the following query parameter should be added to only retrieve services for which your user has active contracts:

- ``filter[has_active_contract]=true``

.. note::
    For an overview of all available filters, visit the `resource page on services </api/resources/services.html#endpoints>`_.

The retrieved services can be used to query the ``GET /service-rates`` endpoint using the ``filter[service]`` filter.
Additionally, the ``filter[weight]`` query parameter should be used to ensure that the shipment's weight is supported with the chosen service.
This should result in some :doc:`service rates </api/resources/service-rates>`.
The returned service rates will contain information on the price, what :doc:`service options </api/resources/service-options>` are available, and what contract is linked to that price.
When a desired service-rate is found, the related service ID and contract ID can be posted with the shipment in the respective relationship objects.

.. raw:: html

    <details>
        <summary><a>See example services request and response (using address filters)</a></summary>

.. code-block:: http

    GET /services HTTP/1.1
    Accept: application/vnd.api+json
    Example: https://api.sandbox.myparcel.com/services?filter[has_active_contract]=true&filter[address_from][country_code]=US&filter[address_from][state_code]=DC&filter[address_from][postal_code]=20500&filter[address_to][country_code]=US&filter[address_to][state_code]=NY&filter[address_to][postal_code]=10005

.. code-block:: http

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json

    {
      "data": [
        {
          "type": "services",
          "id": "175a235f-aff5-4e44-87b5-3657b75c1deb",
          "attributes": {
            "name": "Next Day Packet",
            "code": "carrier-packet-next-day",
            "package_type": "letterbox",
            "delivery_days": [
              "Monday",
              "Tuesday",
              "Wednesday",
              "Thursday",
              "Friday"
            ],
            "transit_time": {
              "min": 1,
              "max": 3
            },
            "handover_method": "drop-off",
            "delivery_method": "delivery",
            "regions_from": [
              {
                "country_code": "US",
                "state_code": "DC"
              }
            ],
            "regions_to": [
              {
                "country_code": "US",
                "state_code": "NY"
              }
            ],
            "uses_volumetric_weight": false,
            "strict_consolidation": false
          },
          "relationships": {
            "carrier": {
              "data": {
                "type": "carriers",
                "id": "be7f6752-34e0-49a1-a832-bcc209450ea9"
              },
              "links": {
                "related": "https://api.sandbox.myparcel.com/carriers/be7f6752-34e0-49a1-a832-bcc209450ea9"
              }
            }
          },
          "links": {
            "self": "https://api.sandbox.myparcel.com/services/175a235f-aff5-4e44-87b5-3657b75c1deb"
          }
        },
        {
          "type": "services",
          "id": "f1abf94d-b39e-44ac-bf6e-d425316fe134",
          "attributes": {
            "name": "Next Day Parcel",
            "code": "carrier-parcel-next-day",
            "package_type": "parcel",
            "delivery_days": [
              "Monday",
              "Tuesday",
              "Wednesday",
              "Thursday",
              "Friday"
            ],
            "transit_time": {
              "min": 1,
              "max": 3
            },
            "handover_method": "drop-off",
            "delivery_method": "delivery",
            "regions_from": [
              {
                "country_code": "US",
                "state_code": "DC"
              }
            ],
            "regions_to": [
              {
                "country_code": "US",
                "state_code": "NY"
              }
            ],
            "uses_volumetric_weight": false,
            "strict_consolidation": false
          },
          "relationships": {
            "carrier": {
              "data": {
                "type": "carriers",
                "id": "be7f6752-34e0-49a1-a832-bcc209450ea9"
              },
              "links": {
                "related": "https://api.sandbox.myparcel.com/carriers/be7f6752-34e0-49a1-a832-bcc209450ea9"
              }
            },
            "service_options": {
              "data": [
                {
                  "type": "service-options",
                  "id": "4c675b1a-516c-4410-abff-d237fd45bcd0"
                }
              ]
            }
          },
          "links": {
            "self": "https://api.sandbox.myparcel.com/services/f1abf94d-b39e-44ac-bf6e-d425316fe134"
          }
        }
      ],
      "meta": {
        "total_pages": 1,
        "total_records": 2
      },
      "links": {
        "self": "https://api.sandbox.myparcel.com/services?filter[has_active_contract]=true&filter[address_from][country_code]=US&filter[address_from][state_code]=DC&filter[address_from][postal_code]=20500&filter[address_to][country_code]=US&filter[address_to][state_code]=NY&filter[address_to][postal_code]=10005&page[size]=100&page[number]=1",
        "first": "https://api.sandbox.myparcel.com/services?filter[has_active_contract]=true&filter[address_from][country_code]=US&filter[address_from][state_code]=DC&filter[address_from][postal_code]=20500&filter[address_to][country_code]=US&filter[address_to][state_code]=NY&filter[address_to][postal_code]=10005&page[size]=100&page[number]=1",
        "last": "https://api.sandbox.myparcel.com/services?filter[has_active_contract]=true&filter[address_from][country_code]=US&filter[address_from][state_code]=DC&filter[address_from][postal_code]=20500&filter[address_to][country_code]=US&filter[address_to][state_code]=NY&filter[address_to][postal_code]=10005&page[size]=100&page[number]=1"
      }
    }

.. raw:: html

    </details>

    <details>
        <summary><a>See example service-rates request and response (using the service ids from the previous request)</a></summary>

.. code-block:: http

    GET /services-rates HTTP/1.1
    Accept: application/vnd.api+json
    Example: https://api.sandbox.myparcel.com/services-rates?filter[has_active_contract]=true&filter[service]=175a235f-aff5-4e44-87b5-3657b75c1deb,f1abf94d-b39e-44ac-bf6e-d425316fe134&filter[weight]=5000

.. code-block:: http

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json

    {
      "data": [
        {
          "id": "801c5098-2d5a-4b6d-a673-d902a1b9366d",
          "type": "service-rates",
          "attributes": {
            "weight_min": 0,
            "weight_max": 1000,
            "is_dynamic": false
          },
          "links": {
            "self": "https://api.sandbox.myparcel.com/service-rates/801c5098-2d5a-4b6d-a673-d902a1b9366d"
          },
          "relationships": {
            "service": {
              "data": {
                "id": "175a235f-aff5-4e44-87b5-3657b75c1deb",
                "type": "services"
              },
              "links": {
                "related": "https://api.sandbox.myparcel.com/services/175a235f-aff5-4e44-87b5-3657b75c1deb"
              }
            },
            "contract": {
              "data": {
                "id": "375a973b-a09e-4265-9b6c-9e36aa72ce52",
                "type": "contracts"
              },
              "links": {
                "related": "https://api.sandbox.myparcel.com/contracts/375a973b-a09e-4265-9b6c-9e36aa72ce52"
              }
            }
          }
        },
        {
          "id": "9352826e-15a3-4358-81df-3adac618ca3e",
          "type": "service-rates",
          "attributes": {
            "weight_min": 1001,
            "weight_max": 5000,
            "is_dynamic": false
          },
          "links": {
            "self": "https://api.sandbox.myparcel.com/service-rates/9352826e-15a3-4358-81df-3adac618ca3e"
          },
          "relationships": {
            "service": {
              "data": {
                "id": "175a235f-aff5-4e44-87b5-3657b75c1deb",
                "type": "services"
              },
              "links": {
                "related": "https://api.sandbox.myparcel.com/services/175a235f-aff5-4e44-87b5-3657b75c1deb"
              }
            },
            "contract": {
              "data": {
                "id": "375a973b-a09e-4265-9b6c-9e36aa72ce52",
                "type": "contracts"
              },
              "links": {
                "related": "https://api.sandbox.myparcel.com/contracts/375a973b-a09e-4265-9b6c-9e36aa72ce52"
              }
            }
          }
        },
        {
          "id": "56695a47-2a6a-4da3-8f12-98782f495644",
          "type": "service-rates",
          "attributes": {
            "weight_min": 0,
            "weight_max": 10000,
            "width_max": 800,
            "height_max": 600,
            "length_max": 1200,
            "fuel_surcharge": {
              "amount": 50,
              "currency": "EUR"
            },
            "is_dynamic": false
          },
          "links": {
            "self": "https://api.sandbox.myparcel.com/service-rates/56695a47-2a6a-4da3-8f12-98782f495644"
          },
          "relationships": {
            "service_options": {
              "data": [
                {
                  "id": "6f9e3780-0d5a-4fd4-a539-9e3fc8c11727",
                  "type": "service-options",
                  "meta": {
                    "included": false
                  }
                }
              ]
            },
            "service": {
              "data": {
                "id": "f1abf94d-b39e-44ac-bf6e-d425316fe134",
                "type": "services"
              },
              "links": {
                "related": "https://api.sandbox.myparcel.com/services/f1abf94d-b39e-44ac-bf6e-d425316fe134"
              }
            },
            "contract": {
              "data": {
                "id": "cbc7ffd7-2f78-4245-94b0-9f83cab3ea60",
                "type": "contracts"
              },
              "links": {
                "related": "https://api.sandbox.myparcel.com/contracts/cbc7ffd7-2f78-4245-94b0-9f83cab3ea60"
              }
            }
          }
        },
        {
          "id": "c1832b71-96a0-4937-a583-70992e717ea8",
          "type": "service-rates",
          "attributes": {
            "weight_min": 10001,
            "weight_max": 30000,
            "width_max": 1000,
            "height_max": 1000,
            "length_max": 2000,
            "fuel_surcharge": {
              "amount": 75,
              "currency": "EUR"
            },
            "is_dynamic": false
          },
          "links": {
            "self": "https://api.sandbox.myparcel.com/service-rates/c1832b71-96a0-4937-a583-70992e717ea8"
          },
          "relationships": {
            "service_options": {
              "data": [
                {
                  "id": "6f9e3780-0d5a-4fd4-a539-9e3fc8c11727",
                  "type": "service-options",
                  "meta": {
                    "included": false
                  }
                }
              ]
            },
            "service": {
              "data": {
                "id": "f1abf94d-b39e-44ac-bf6e-d425316fe134",
                "type": "services"
              },
              "links": {
                "related": "https://api.sandbox.myparcel.com/services/f1abf94d-b39e-44ac-bf6e-d425316fe134"
              }
            },
            "contract": {
              "data": {
                "id": "cbc7ffd7-2f78-4245-94b0-9f83cab3ea60",
                "type": "contracts"
              },
              "links": {
                "related": "https://api.sandbox.myparcel.com/contracts/cbc7ffd7-2f78-4245-94b0-9f83cab3ea60"
              }
            }
          }
        }
      ],
      "meta": {
        "total_pages": 1,
        "total_records": 4
      },
      "links": {
        "self": "https://api.sandbox.myparcel.com/services-rates?filter[has_active_contract]=true&filter[service]=175a235f-aff5-4e44-87b5-3657b75c1deb,f1abf94d-b39e-44ac-bf6e-d425316fe134&filter[weight]=5000&page[size]=100&page[number]=1",
        "first": "https://api.sandbox.myparcel.com/services-rates?filter[has_active_contract]=true&filter[service]=175a235f-aff5-4e44-87b5-3657b75c1deb,f1abf94d-b39e-44ac-bf6e-d425316fe134&filter[weight]=5000&page[size]=100&page[number]=1",
        "last": "https://api.sandbox.myparcel.com/services-rates?filter[has_active_contract]=true&filter[service]=175a235f-aff5-4e44-87b5-3657b75c1deb,f1abf94d-b39e-44ac-bf6e-d425316fe134&filter[weight]=5000&page[size]=100&page[number]=1"
      }
    }

.. raw:: html

    </details>

Use the service_code meta property to let the API resolve the service and contract
__________________________________________________________________________________
While the above mentioned way of retrieving services and contracts gives high confidence that the chosen service and contract can be used for the shipment,
it does require quite some requests to be made to the MyParcel.com API.
An alternative way to attach a service and contract to a shipment, is by posting a service-code in the ``meta`` of the post body of the shipment.
This can be useful if a user knows for sure a service exists for a certain service code and that the service can be used for this shipment.

During your development process, you will need to query our services manually to discover the available service codes for your account.
A full list of service codes is available via your account manager.

See the below example of what such a request body would look like.

.. code-block:: json

    {
      "data": {
        "type": "shipments",
        "attributes": {
          "...": "..."
        },
        "relationships": {
          "shop": {
            "data": {
              "type": "shops",
              "id": "35eddf50-1d84-47a3-8479-6bfda729cd99"
            }
          }
        }
      },
      "meta": {
        "service_code": "dpd-classic"
      }
    }

Note that in this example, no service and no contract relationships have been specified in the request body.
In this case, the user would already know what service they would like to use for the shipment.
The API will try to find a service and contract that match the shipment and service code and attach it to the shipment.
If successful, the API will then attach the found service and contract to the shipment, and the returned response should include the service and contract relationship objects.
If however, the API cannot resolve the service-code into a valid service and contract, the shipment will be created without a service and contract relationship,
which means that they need to be set manually after the shipment has been created.

.. warning::
    If multiple contracts are found for a service, the API will find which contract results in a cheaper shipment and attach that contract to the shipment.

Customs information
___________________
When shipping from one country to another, chances are that your parcel will have to go through customs.
The required customs information can be included in the shipment request.
Whenever the `customs </api/resources/shipments.html#customs>`_ object is present in the shipment request, the `items </api/resources/shipments.html#items>`_ object is also required.
Furthermore, a ``phone_number`` of the recipient and ``description`` of the shipment are also required for customs related shipments.
A customs declaration form will be automatically generated and returned when printing the label for this shipment.

Label format
____________
If you do not specify particular label format, we will request the default file offered by the carrier, which in almost all cases will be a PDF file in A6 size.
Some carriers offer different label formats, such as ZPL or A4 size. The available label formats for a specific carrier can be found on the :doc:`carrier resource </api/resources/carriers>`.

.. code-block:: json

    {
      "data": {
        "...": "..."
      },
      "meta": {
        "label": {
          "mime_type": "application/pdf",
          "size": "A6"
        }
      }
    }

.. warning::
    Once a shipment has been registered, the label file will become available in the format you have specified. It is not possible to retrieve the file in a different format.

.. _shipment-registration:

Registering your shipment with the carrier
------------------------------------------
When you use our ``POST /registered-shipments`` endpoint, the shipment is synchronously registered with the carrier.
Our system awaits the carrier's response and returns the label data or registration errors if any occurred.
You will have to handle and log all errors on your side.

When you use our ``POST /shipments`` endpoint, the shipment is saved, but not registered with the carrier unless the ``register_at`` attribute is set.
The ``register_at`` attribute expects a unix timestamp as integer value.
Sending ``0`` or a timestamp in the past will queue the shipment for registration immediately.
Sending in a timestamp that lies in the future will queue the registration of the shipment for that exact time.
If you omit the ``register_at`` attribute from the request, the shipment will be created with a ``shipment-concept`` status.
A concept shipment will not be registered with the carrier until it is patched with a ``register_at`` value.

Choose the right endpoint
_________________________
The below table lists the differences of both approaches, so you can choose the one that fits your situation. It basically comes down to:

- If your application can receive `webhooks </api/create-a-webhook.html>`_ and process the shipment file data asynchronously, use ``POST /shipments``.
- If you need the files within the same process that's creating the shipment, use ``POST /registered-shipments`` and implement error handling.
- Do not use a combination of ``POST /shipments`` and polling every second for a status change, this is not practical for both parties.

.. list-table::
   :header-rows: 1
   :width: 100%
   :widths: 33 33 33

   * - Use case
     - POST /shipments
     - POST /registered-shipments
   * - Processing
     - Asynchronous
     - Synchronous
   * - Number of request to obtain label data
     - 2 (post shipment, receive webhook, get file)
     - 1
   * - Error handling
     - Check the ``errors`` attribute on the ``shipment_status`` relationship
     - Your code catches errors during POST request and keeps a log of these errors somewhere
   * - Retry method
     - Patch the concept shipment
     - Post the entire request again
   * - Response time
     - fast
     - slow, multiple seconds (carrier dependent)
   * - Availability
     - Dependent on our API, covered by our SLA
     - Dependent on our API, but down when the carrier is down

.. warning::
    After a shipment is registered with a carrier, it is no longer possible to **edit** or **delete** that shipment!

Example requests
----------------
Below are two examples for shipment requests. Note that one is an international shipment that includes customs information.
An example response of the domestic shipment request is also provided.

.. raw:: html

    <details>
        <summary><a>See example domestic shipment request</a></summary>

.. code-block:: http

    POST /shipments HTTP/1.1
    Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiSm9obiBEb2UiLCJhZG1pbiI6dHJ1ZX0.OLvs36KmqB9cmsUrMpUutfhV52_iSz4bQMYJjkI_TLQ
    Content-Type: application/vnd.api+json

    {
      "data": {
        "type": "shipments",
        "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",
            "email": "s.holmes@holmesinvestigations.com",
            "phone_number": "+44 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": "+44 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": "+44 234 567 890"
          },
          "description": "Order #8008135",
          "physical_properties": {
            "height": 150,
            "width": 300,
            "length": 500,
            "volume": 22.5,
            "weight": 5000
          },
          "register_at": 1504801719
        },
        "relationships": {
          "shop": {
            "data": {
              "type": "shops",
              "id": "35eddf50-1d84-47a3-8479-6bfda729cd99"
            }
          },
          "service": {
            "data": {
              "type": "services",
              "id": "af5e65b6-a709-4f61-a565-7c12a752482f"
            }
          },
          "contract": {
            "data": {
              "type": "contracts",
              "id": "448e55b3-0829-4783-a9ca-1078697cdb46"
            }
          }
        }
      }
    }

.. raw:: html

    </details>
    <details>
        <summary><a>See example registered shipment request</a></summary>

.. code-block:: http

    POST /registered-shipments HTTP/1.1
    Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiSm9obiBEb2UiLCJhZG1pbiI6dHJ1ZX0.OLvs36KmqB9cmsUrMpUutfhV52_iSz4bQMYJjkI_TLQ
    Content-Type: application/vnd.api+json

    {
      "data": {
        "type": "shipments",
        "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",
            "email": "s.holmes@holmesinvestigations.com",
            "phone_number": "+44 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": "+44 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": "+44 234 567 890"
          },
          "description": "Order #8008135",
          "physical_properties": {
            "height": 150,
            "width": 300,
            "length": 500,
            "volume": 22.5,
            "weight": 5000
          },
        },
        "relationships": {
          "shop": {
            "data": {
              "type": "shops",
              "id": "35eddf50-1d84-47a3-8479-6bfda729cd99"
            }
          },
          "service": {
            "data": {
              "type": "services",
              "id": "af5e65b6-a709-4f61-a565-7c12a752482f"
            }
          },
          "contract": {
            "data": {
              "type": "contracts",
              "id": "448e55b3-0829-4783-a9ca-1078697cdb46"
            }
          }
        }
      }
    }

.. raw:: html

    </details>
    <details>
        <summary><a>See example international shipment request that includes customs</a></summary>

.. code-block:: http

    POST /shipments HTTP/1.1
    Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiSm9obiBEb2UiLCJhZG1pbiI6dHJ1ZX0.OLvs36KmqB9cmsUrMpUutfhV52_iSz4bQMYJjkI_TLQ
    Content-Type: application/vnd.api+json

    {
      "data": {
        "type": "shipments",
        "attributes": {
          "recipient_address": {
            "street_1": "5th Avenue",
            "street_number": 890,
            "postal_code": "10021",
            "city": "New York",
            "country_code": "US",
            "first_name": "Bruce",
            "last_name": "Banner",
            "email": "bruce.banner@example-email.com",
            "phone_number": "+1 234 555 6789"
          },
          "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": "+44 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": "+44 234 567 890"
          },
          "description": "Order #8008135",
          "physical_properties": {
            "height": 150,
            "width": 300,
            "length": 500,
            "volume": 22.5,
            "weight": 5000
          },
          "items": [
            {
              "sku": "123456789",
              "description": "OnePlus X",
              "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"
          },
          "register_at": 1504801719
        },
        "relationships": {
          "shop": {
            "data": {
              "type": "shops",
              "id": "35eddf50-1d84-47a3-8479-6bfda729cd99"
            }
          },
          "service": {
            "data": {
              "type": "services",
              "id": "af5e65b6-a709-4f61-a565-7c12a752482f"
            }
          },
          "contract": {
            "data": {
              "type": "contracts",
              "id": "448e55b3-0829-4783-a9ca-1078697cdb46"
            }
          }
        }
      }
    }

.. raw:: html

    </details>
    <details>
        <summary><a>See example domestic shipment response</a></summary>

.. code-block:: http

    HTTP/1.1 201 Created
    Content-Type: application/vnd.api+json

    {
      "data": {
        "type": "shipments",
        "id": "6b5db4f9-37ea-437a-b2f9-7f2d146d5bb8",
        "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",
            "email": "s.holmes@holmesinvestigations.com",
            "phone_number": "+44 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": "+44 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": "+44 234 567 890"
          },
          "description": "Order #8008135",
          "physical_properties": {
            "height": 150,
            "width": 300,
            "length": 500,
            "volume": 22.5,
            "weight": 5000
          },
          "register_at": 1504801719
        },
        "relationships": {
          "shop": {
            "data": {
              "type": "shops",
              "id": "35eddf50-1d84-47a3-8479-6bfda729cd99"
            },
            "links": {
              "related": "https://api.sandbox.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99"
            }
          },
          "service": {
            "data": {
              "type": "services",
              "id": "af5e65b6-a709-4f61-a565-7c12a752482f"
            },
            "links": {
              "related": "https://api.sandbox.myparcel.com/services/af5e65b6-a709-4f61-a565-7c12a752482f"
            }
          },
          "contract": {
            "data": {
              "type": "contracts",
              "id": "448e55b3-0829-4783-a9ca-1078697cdb46"
            },
            "links": {
              "related": "https://api.sandbox.myparcel.com/contracts/448e55b3-0829-4783-a9ca-1078697cdb46"
            }
          },
          "shipment_status": {
            "data": {
              "type": "shipment-statuses",
              "id": "5781d596-1bf2-44ba-bcaf-d356117cbb94"
            },
            "links": {
              "related": "https://api.sandbox.myparcel.com/shipments/6b5db4f9-37ea-437a-b2f9-7f2d146d5bb8/statuses/5781d596-1bf2-44ba-bcaf-d356117cbb94"
            }
          }
        },
        "links": {
          "self": "https://api.sandbox.myparcel.com/shipments/6b5db4f9-37ea-437a-b2f9-7f2d146d5bb8",
          "files": "https://api.sandbox.myparcel.com/shipments/6b5db4f9-37ea-437a-b2f9-7f2d146d5bb8/files"
        }
      }
    }

.. raw:: html

    </details>