Create a shipment

Before printing a label to put on a parcel, a shipment resource should be created in the API.
Creating such a shipment is done by making a POST request to the /shipments endpoint.

In order to be able to create a shipment in the API, the shipments.manage scope 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.


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

Attribute Description
recipient_address Address object containing information of the shipments recipient address.
sender_address Address object containing information about where the shipment is sent from.
return_address Address object containing information about where the shipment should be returned to.
physical_properties Physical properties object containing information about the dimensions and weight of the shipment.

Depending on the carrier, additional information may be required. For more information, see our page about carrier specific requirements.


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 shop relationship object containing the uuid of the shop for which this shipment should be created.
service A service relationship object containing the uuid of the desired service.
contract A contract 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 service options resource page.

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 resource page on shops.

Service relationship

Carriers often have different services available to ship parcels with. These are defined in the API and should be included as a relationship when creating a shipment. Since services are region 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 resource page on 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 resource page on contracts.

Service rates

A service rate can not 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 service rate resource page.

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 object is present in the shipment request, the 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.

Registering your shipment with the carrier

After a shipment is created, the next step is the registration of your shipment with the carrier that corresponds to the chosen service and contract. That’s where the register_at attribute comes in. The register_at attribute expects a unix timestamp as integer value. Sending in a timestamp that lies in the future will queue the registration of the shipment for that exact time. Otherwise, sending in a timestamp that lies in the past or corresponds to the current time, will cause the shipment to be queued for registration immediately. Lastly, because the register_at attribute is an optional attribute, you can choose to omit it from the request. This means that the shipment will not be registered with the carrier until it is patched with a register_at value.

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.

See example domestic shipment request
See example international shipment request that includes customs
See example domestic shipment response