Create a shipment
Create shipments to and then update it when necessary during its lifecycle.
Create a shipment
When an order is ready to be shipped, create a shipment with the createShipment mutation. It creates a Shipment object that contains all the relevant information about the shipment.
mutation {
createShipment(input: {...})
{
id
}
}
The createShipmentInput type requires the following fields as a minimum:
provider: Specifies a provider with aProviderEnum!.referenceId: The ID of the shipment.recipient: The name and the selected language of the customer who will receive the shipment.destination: The address to where the shipment will be delivered. Depending on the order, this can be home delivery, a pickup point, or a store pickup.
In the example, we're creating a shipment that will be delivered using the provider RIV to a pickup point for Fictitious Customer:
mutation {
createShipment(
input: {
provider: "RIV",
referenceId: "12345",
recipient: {
firstName: "Fictitious",
lastName: "Customer",
language: HU
},
destination: {
pickupPointId: "12345"
}
}
) {
id
}
}
Specify shipment address and location
The shipment's destination can be a pickup point, an address, and/or a precise location.
The simplest way is to specify the pickup point ID:
mutation {
createShipment(
input: {
provider: "RIV",
referenceId: "12345",
recipient: {
firstName: "Fictitious",
lastName: "Customer",
language: HU
},
destination: {
pickupPointId: "12345"
}
}
) {
id
}
}
To set the full address, you need the address field which requires:
country: See the available country codes.citypostalCodeaddressLine1
mutation {
createShipment(
input: {
provider: "RIV",
referenceId: "12345",
recipient: {
firstName: "Fictitious",
lastName: "Customer",
language: HU
},
destination: {
address: {
country: HU,
city: "Budapest",
postalCode: "1061",
addressLine1: "Nyugati tér 1."
}
}
}
) {
id
}
}
- You can add a
statefield: it can be used for any type of administrative subdivision of a country, if you need it. - If the address is longer and more complex, you can add
addressLine2. - Add a
noteto include additional information about the address.
mutation {
createShipment(
input: {
provider: "RIV",
referenceId: "12345",
recipient: {
firstName: "Fictitious",
lastName: "Customer",
language: HU
},
destination: {
address: {
country: CA,
state: "Ontario"
city: "Ottawa",
postalCode: "K2C 0A6",
addressLine1: "1026 Baseline Rd",
addressLine2: "Building B, 4th floor"
note: "The receptionist is grumpy"
}
}
}
) {
id
}
}
You can specify a precise location with the location field that requires a latitude and a longitude fields:
mutation {
createShipment(
input: {
provider: "RIV",
referenceId: "12345",
recipient: {
firstName: "Fictitious",
lastName: "Customer",
language: HU
},
destination: {
location: {
latitude: 12.000245,
longitude: 23.101214
}
}
}
) {
id
}
}
Shipment recipient
The shipment recipient is the customer who will receive the shipment. The createShipment mutation requires its name and language as a minimum but you can add additional contact information: email and phone number, both as strings.
mutation {
createShipment(
input: {
[...]
recipient: {
firstName: "Fictitious",
lastName: "Customer",
language: HU,
email: "example_customer@example.org",
phone: "00 01 234 5678"
},
}
) {
id
}
}
Shipment sender
You can specify a sender for your shipment with the sender field. It is an optional field: it allows you to pass the name, email, phone number, and the bank account number of the shipment's sender. The field requires the name field only.
mutation {
createShipment(
input: {
[...]
sender: {
firstName: "Fictitious",
lastName: "Sender",
email: "example_customer@example.org",
phone: "00 01 234 5678",
bankAccountNumber: "HU99111122223333444400000000"
},
}
) {
id
}
}
Shipment origin
You can set an origin for the shipment. This can be a specific address or a pickup point ID, or even exact coordinates, depending on the shipment mode. The origin field uses the ShipmentOriginInput type.
In the example, we're setting an address with an exact location.
mutation {
createShipment(
input: {
[...]
origin: {
address: {
country: HU,
city: "Budapest",
postalCode: "1061",
addressLine1: "Nyugati tér 1."
},
location: {
latitude: 12.000245,
longitude: 23.101214
}
}
}
) {
id
}
}
Add a waybill to a shipment
You can add a waybill to your shipment when creating it. It requires an existing waybill ID.
You can assign a waybill to your shipment later with the assignShipmentToWaybill mutation.
mutation {
createShipment(
input: {
provider: "RIV",
referenceId: "12345",
recipient: {
firstName: "Fictitious",
lastName: "Customer",
language: HU
},
destination: {
pickupPointId: "12345"
},
waybillId: "abc123"
}
) {
id
}
}
Add parcels to a shipment
You can specify the exact contents of a shipment with the parcels field. It requires:
- A
referenceId: A unique identifier for the parcel. - A
weightfield: The weight of the parcel in kilograms. Accepts a float as a value.
mutation {
createShipment(
input: {
provider: "RIV",
referenceId: "12345",
recipient: {
firstName: "Fictitious",
lastName: "Customer",
language: HU
},
destination: {
pickupPointId: "12345"
},
parcels: {
referenceId: "asdf4567",
weight: 1.5
}
}
) {
id
}
}
Parcel dimensions
You can specify the dimensions of the parcel: length, width, and height, all in meters.
mutation {
createShipment(
input: {
provider: "RIV",
referenceId: "12345",
recipient: {
firstName: "Fictitious",
lastName: "Customer",
language: HU
},
destination: {
pickupPointId: "12345"
},
parcels: {
referenceId: "asdf4567",
weight: 1.5,
dimensions: {
width: 0.5,
height: 0.5,
length: 0.7
}
}
}
) {
id
}
}
Parcel payment
If the recipient must pay for their parcel on delivery, set the cashOnDelivery field. It requires an amount and a currency field:
mutation {
createShipment(
input: {
provider: "RIV",
referenceId: "12345",
recipient: {
firstName: "Fictitious",
lastName: "Customer",
language: HU
},
destination: {
pickupPointId: "12345"
},
parcels: {
referenceId: "asdf4567",
weight: 1.5,
cashOnDelivery: {
amount: 1500,
currency: HUF
}
}
}
) {
id
}
}
Update the shipment information
Use the updateShipment mutation to modify an existing shipment.
When updating a shipment, you must set the shipment mode in the mode field. It can be one of three options:
- Sender to recipient: The shipment is sent from the merchant to the customer.
- Recipient to sender: The shipment is sent from the customer to the merchant. For example, the customer returns a previously ordered item.
- Third-party to third-party: For example, a fulfillment center shipping to a logistics provider.
mutation {
updateShipment(
input: {
id: "12345"
referenceId: "12345",
recipient: {
firstName: "Fictitious",
lastName: "Customer",
language: HU
},
destination: {
pickupPointId: "12345"
},
mode: SENDER_TO_RECIPIENT
}
) {
id
status {
status
}
}
}
The updateShipment mutation lets you modify all fields that you can set with the createShipment input.