Pircel public API
Pircel provides you with APIs that you can use for processes involving your store and your partner carriers. For a procedure such as "Create Voucher", we provide you with an API call for all delivery companies.
How to send a request?
const response = await fetch("https://test-api.pircel.com", {
method: "POST",
mode: "cors",
headers: new Headers({
"Content-Type": "application/json",
// replace '1234' with your API key
apikey: "1234"
}),
body: JSON.stringify({
query: `mutation createVoucher(: String, : String!, : Int!, : Date){
createVoucher(notes: , orderId: , packagesQuantity: , pickupDate: ){
voucherPrintDocuments
vouchers
}
}`,
variables: {
notes: "Fragile packages",
orderId: "14317",
packagesQuantity: 2,
pickupDate: "2023-10-03",
}
})
});
With JavaScript, it is possible to just use a template literal and simplify the API call body.
const response = await fetch('https://test-api.pircel.com', {
method: 'POST',
mode: 'cors',
headers: new Headers({
'Content-Type': 'application/json',
// replace '1234' with your API key
apikey: '1234',
}),
body: JSON.stringify({
query: `mutation {
createVoucher(
notes: "Fragile",
orderId: "A1",
packagesQuantity: 1,
pickupDate: "2023-03-06",
) {
vouchers
voucherPrintDocuments
}
}`
}),
});
You can find a working example on codesandbox.
We are using GraphQL API.
GraphQL is a query language and server-side runtime for application programming interfaces (APIs) that prioritizes giving clients exactly the data they request and no more. GraphQL is designed to make APIs fast, flexible, and developer-friendly.
API are separate in two categories query & mutation:
query: When we want to read an information that is already stored.
structure:
{
field(arg: "value") {
subField
}
}
mutation: When we want to change information (create, update, delete).
structure:
mutation {
field (arg: "value") {
subField
}
}
You can go to https://test-api.pircel.com and have access to try all the queries/mutations (API) we provide to you.
To try any of the API first you should add a shipment.
Follow the link and run the default mutation that we provide to you. 
The following error messages were suggested:
'addShipment.invalidPostcode' ⇒ Μη έγκυρος ταχυδρομικός κώδικας
'addShipment.orderIdAlreadyExists' ⇒ Η παραγγελία υπάρχει ήδη
'authenticate.invalidToken' ⇒ Μη έγκυρο authentication token, παρακαλώ συνδεθείτε ξανά
'cancelVoucher.eshopNotFound' ⇒ Δεν βρέθηκε ηλεκτρονικό κατάστημα
'cancelVoucher.orderNotFound' ⇒ Δεν βρέθηκε η παραγγελία
'createPickupList.invalidDeliveryCompany' ⇒ Μη έγκυρη μεταφορική εταιρεία
'createPickupList.noShipmentsForSelectedDeliveryCompanies' ⇒ Δεν βρέθηκαν οι αποστολές για τις επιλεγμένες μεταφορικές εταιρείες
'createPickupList.noShipmentsFound' ⇒ Δεν βρέθηκαν οι αποστολές
'createPickupList.unprintedVouchers' ⇒ Βρέθηκαν μη εκτυπωμένα παραστατικά
'createVoucher.invalidDeliveryCompany' ⇒ Μη έγκυρη μεταφορική εταιρεία
'createVoucher.invalidPickupDate' ⇒ Μη έγκυρη ημερομηνία παραλαβής
'createVoucher.newArgsCancelFirstExistingVouchers' ⇒ Αδυναμία δημιουργίας ή λήψης νέου παραστατικού. Το παραστατικό έχει ήδη δημιουργηθεί για αυτή την παραγγελία. Παρακαλούμε για να προβείτε σε νέα δημιουργία ακυρώστε πρώτα το προηγούμενο παραστατικό.
'createVoucher.orderNotFound' ⇒ Δεν βρέθηκε παραγγελία
'forbidden'⇒ Απαγορεύεται η πρόσβαση
'invalidpickuDateType', ⇒ Μη έγκυρη μορφή ημερομηνίας παραλαβής
'login.userNotFound' ⇒ Δεν βρέθηκε ο χρήστης
'pintVoucher.canceledVouchersFound' ⇒ Βρέθηκαν ακυρωμένα παραστατικά
'printVoucher.orderNotFound' ⇒ Δεν βρέθηκε η παραγγελία
'printVoucher.vouchersNotFound' ⇒ Δεν βρέθηκαν παραστατικά
'updateShipment.invalidPostcode' ⇒ Μη έγκυρος ταχυδρομικός κώδικας
'updateShipment.orderIdCannotChange' ⇒ Ο κωδικός της παραγγελίας δεν μπορεί να αλλάξει
'updateShipment.shipmentCannotChange' ⇒ Η παραγγελία δεν μπορεί να αλλάξει γιατι έχουν ήδη δημιουργηθεί παραστατικά
'speedex.apiInaccessible' ⇒ Το API της Speedex δεν είναι διαθέσιμο
'speedex.cannotCreateSession' ⇒ Το API της Speedex δεν είναι διαθέσιμο
'createVoucher.speedex.invalidPostcode' ⇒ Μη έγκυρος ταχυδρομικός κώδικας
'speedex.noResponse' ⇒ Το API της Speedex δεν είναι διαθέσιμο
'printPickupList.speedex.noPickupListNumber' ⇒ Δεν υπάρχει αριθμός λίστας παραλαβής
'printVoucher.speedex.noVoucher' ⇒ Δεν βρέθηκε παραστατικό
API Endpoints
# Test (Currently offline):
https://test-api.pircel.com
# Production:
https://api.pircel.com
Headers
# Your API token from the dashboard. Must be included in all API calls.
apikey: <YOUR_TOKEN_HERE>Queries
deliveryCompanies
Description
Get delivery companies with optional filtering
Response
Returns [DeliveryCompany]
Arguments
| Name | Description |
|---|---|
companies - [DeliveryCompanyIDOrSlugInput]
|
Specific delivery companies to retrieve by ID or slug |
eshopId - String
|
Filter delivery companies by eshop ID |
forCheckout - Boolean
|
Only return companies visible at checkout |
tags - [String]
|
Filter by tags |
withApiIntegration - Boolean
|
Only return companies with API integration |
Example
Query
query DeliveryCompanies(
$companies: [DeliveryCompanyIDOrSlugInput],
$eshopId: String,
$forCheckout: Boolean,
$tags: [String],
$withApiIntegration: Boolean
) {
deliveryCompanies(
companies: $companies,
eshopId: $eshopId,
forCheckout: $forCheckout,
tags: $tags,
withApiIntegration: $withApiIntegration
) {
_id
acceptedPaymentMethods
capabilities {
cancellation {
...CancellationCapabilityFragment
}
multiPiece {
...MultiPieceCapabilityFragment
}
parcelIdentityMode
perPieceTracking
referenceScope
}
createdAt
credentialFields {
isRequired
isSecret
key
label
type
}
defaultConfig {
displayAtCheckout
minimumPrice
priceMultiplier
roundingIncrement
}
description
hasAction
hasApiIntegration
internalOnly
isEnabled
isVisibleAtCheckout
logo {
alt
path
}
minimumWeight
name
pickupTimeOptions {
closeOptions
fixedOptions
mode
readyOptions
}
services {
code
name
}
slug
supportedActions
tags
trackingUrlInformation {
baseUrl
exampleUrl
parameterName
supportsDeepLink
urlType
}
updatedAt
usesAccountShipperAddress
}
}
Variables
{
"companies": [DeliveryCompanyIDOrSlugInput],
"eshopId": "abc123",
"forCheckout": false,
"tags": ["xyz789"],
"withApiIntegration": false
}
Response
{
"data": {
"deliveryCompanies": [
{
"_id": 4,
"acceptedPaymentMethods": ["AFTERPAY_CLEARPAY"],
"capabilities": DeliveryCompanyCapabilities,
"createdAt": "2007-12-03T10:15:30Z",
"credentialFields": [CredentialField],
"defaultConfig": DeliveryCompanyDefaultConfig,
"description": "abc123",
"hasAction": true,
"hasApiIntegration": false,
"internalOnly": false,
"isEnabled": false,
"isVisibleAtCheckout": false,
"logo": Logo,
"minimumWeight": 987.65,
"name": "abc123",
"pickupTimeOptions": PickupTimeOptions,
"services": [DeliveryCompanyService],
"slug": "xyz789",
"supportedActions": ["CANCEL_VOUCHER"],
"tags": ["xyz789"],
"trackingUrlInformation": TrackingUrlInformation,
"updatedAt": "2007-12-03T10:15:30Z",
"usesAccountShipperAddress": true
}
]
}
}
eshop
Description
Get eshop details
Example
Query
query Eshop($_id: ObjectID) {
eshop(_id: $_id) {
_id
address
addressBook {
_id
address {
...AddressFragment
}
contact {
...ContactFragment
}
isDefault
name
}
apikey
brandAssets {
logos {
...BrandLogosFragment
}
}
city
deliveryCompanies {
config {
...EshopDeliveryCompanyConfigFragment
}
deliveryCompany {
...DeliveryCompanyFragment
}
isEnabled
}
freeShipping {
checkoutDisplay
isEnabled
restOfWorld {
...FreeShippingRestOfWorldFragment
}
rules {
...FreeShippingRuleFragment
}
}
general {
checkout {
...GeneralCheckoutConfigFragment
}
}
name
packageInsurance
pageCustomization {
colorScheme {
...ColorSchemeFragment
}
}
phone
postcode
securityValue
slug
storeConnections {
_id
consecutiveFailures
credentialTransport
expiresAt
externalId
lastFailedAt
lastSyncedAt
platform
pluginVersion
scopes
status
storeDomain
}
taxProfile {
confirmedAt
confirmedBy
establishmentCountry
goodsRateCategory
islandEstablishment
mode
ossRegistered
pricesIncludeVat
}
}
}
Variables
{"_id": "5e5677d71bdc2ae76344968c"}
Response
{
"data": {
"eshop": {
"_id": "5e5677d71bdc2ae76344968c",
"address": "xyz789",
"addressBook": [AddressBookEntryType],
"apikey": "xyz789",
"brandAssets": BrandAssets,
"city": "xyz789",
"deliveryCompanies": [EshopDeliveryCompany],
"freeShipping": FreeShippingConfig,
"general": GeneralConfig,
"name": "abc123",
"packageInsurance": 123.45,
"pageCustomization": PageCustomization,
"phone": "abc123",
"postcode": "abc123",
"securityValue": 123.45,
"slug": "abc123",
"storeConnections": [StoreConnection],
"taxProfile": TaxProfile
}
}
}
eshopBranding
Description
Get public branding information for an eshop, can be used for branded pages (tracking, returns portal, etc.).
Response
Returns an EshopBranding
Arguments
| Name | Description |
|---|---|
eshopId - ObjectID!
|
Eshop identifier |
Example
Query
query EshopBranding($eshopId: ObjectID!) {
eshopBranding(eshopId: $eshopId) {
_id
colorScheme {
accent
background
primary
secondary
}
customization {
_placeholder
}
logos {
horizontal {
...LogoFragment
}
icon {
...LogoFragment
}
primary {
...LogoFragment
}
}
name
}
}
Variables
{"eshopId": "5e5677d71bdc2ae76344968c"}
Response
{
"data": {
"eshopBranding": {
"_id": "5e5677d71bdc2ae76344968c",
"colorScheme": BrandColorScheme,
"customization": CustomizationExtensions,
"logos": BrandLogos,
"name": "abc123"
}
}
}
trackShipment
Description
Track an order based on eshop ID and shipment ID
Response
Returns a TrackingResult
Example
Query
query TrackShipment(
$eshopId: ObjectID!,
$shipmentId: ObjectID!
) {
trackShipment(
eshopId: $eshopId,
shipmentId: $shipmentId
) {
parcels {
_id
billableWeight
contents {
...ParcelContentsFragment
}
dimensions {
...ParcelDimensionsFragment
}
returnVoucher {
...ParcelVoucherFragment
}
volumetricWeight
voucher {
...ParcelVoucherFragment
}
weight
}
products {
_id
categories
countryOfOrigin
description
dimensions {
...ProductDimensionsFragment
}
externalId
extraAttributes
harmonizedSystemCode
image
kind
lineDiscount
lineSubtotal
lineTotal
metadata
price
quantity
requiresShipping
size
sku
title
weight
}
recipient {
address {
...AddressFragment
}
contact {
...ContactFragment
}
}
trackingDetails {
carrierTrackingUrl
deliveredAt
deliveryCompany {
...DeliveryCompanyFragment
}
eshopTrackingUrl
estimatedDelivery
events {
...TrackingEventFragment
}
isActive
lastStatus
lastSyncedAt
lastUpdated
nextPollAt
returnToSender
slaTier
voucherCode
}
}
}
Variables
{
"eshopId": "5e5677d71bdc2ae76344968c",
"shipmentId": "5e5677d71bdc2ae76344968c"
}
Response
{
"data": {
"trackShipment": {
"parcels": [Parcel],
"products": [Product],
"recipient": Recipient,
"trackingDetails": TrackingDetails
}
}
}
trackVoucher
Response
Returns [VoucherTracking]
Arguments
| Name | Description |
|---|---|
code - String
|
Voucher code |
Example
Query
query TrackVoucher($code: String) {
trackVoucher(code: $code) {
checkpointAction
checkpointDateTime
checkpointLocation
checkpointNotes
code
shipmentId
}
}
Variables
{"code": "xyz789"}
Response
{
"data": {
"trackVoucher": [
{
"checkpointAction": "abc123",
"checkpointDateTime": "2007-12-03T10:15:30Z",
"checkpointLocation": "xyz789",
"checkpointNotes": "xyz789",
"code": "abc123",
"shipmentId": "5e5677d71bdc2ae76344968c"
}
]
}
}
validateTrackingRequest
Description
Validate a tracking request for a shipment
Response
Returns a ValidateTrackingResult
Example
Query
query ValidateTrackingRequest(
$email: String!,
$eshopId: ObjectID!,
$orderId: String!
) {
validateTrackingRequest(
email: $email,
eshopId: $eshopId,
orderId: $orderId
) {
isValid
shipmentId
}
}
Variables
{
"email": "xyz789",
"eshopId": "5e5677d71bdc2ae76344968c",
"orderId": "xyz789"
}
Response
{
"data": {
"validateTrackingRequest": {
"isValid": true,
"shipmentId": "5e5677d71bdc2ae76344968c"
}
}
}
Mutations
addShipment
Description
Add a shipment. A refused money payload throws its orderAmounts.* code and repeats the rejection on extensions: always type, naming the specific check that refused — several share one code — plus field and the submitted value on orderAmounts.invalidAmount. Read it rather than the code alone; the code cannot say which figure was wrong.
Response
Returns a Shipment
Arguments
| Name | Description |
|---|---|
buyerNotes - String
|
Customer's notes. |
checkout - ShipmentCheckoutInput
|
Checkout provenance: the flow/architecture the order came through, whether it was an express checkout, and the entry-point page. Typically set by the storefront plugin at order creation. |
eshopId - ObjectID
|
Required if the user belongs to or owns multiple eshops. Admins must specify an eshop. Not required for eshop integrations. |
geniki - GenikiInput
|
Geniki delivery company specific fields |
includeVat - Boolean
|
Whether to include VAT in the calculated shipping prices. Defaults to true if not specified. |
isB2BInvoice - Boolean
|
Indicates if the shipment is for a B2B invoice (true) or B2C invoice (false). False by default. |
orderAmounts - OrderAmountsInput
|
The order totals as the seller states them, passed verbatim (amounts-first contract). The COD collectible is amountDue when present, else grandTotal. |
orderId - String
|
Order's id. Must be provided for the prod-test environment |
parcels - [ParcelInput!]
|
List of parcels in this shipment, each with its dimensions, weight and optional product distribution. At least one is required unless nothing on the order is shipped, in which case send an empty list. |
paymentMethod - ShipmentPaymentMethodEnum
|
Customer's payment method. |
products - [ProductInput]!
|
List of products. |
productsQuantity - Int!
|
Products quantity. |
recipient - RecipientCreateInput!
|
Recipient details including address and contact information. |
recipientLogistics - RecipientLogisticsInput
|
Customer-provided logistics company details when using recipient-logistics. |
requiresShipping - Boolean
|
Whether any part of this order is shipped, as stated by the source platform. Takes precedence over the order lines, except that a line explicitly marked requiresShipping: true always wins. Omit it unless the platform states it, in which case the lines are used instead. |
selectedRate - SelectedRateInput
|
The selected service and rate for the shipment |
senderNotes - String
|
Sender's notes. |
shipper - ShipperInput
|
Shipper details including address and contact information. |
source - ShipmentSourceEnum
|
Source of the shipment creation. |
status - ShipmentStatusEnum
|
Shipment's status. For non-admin users, the only valid option is NEW, MANUALLY_CREATED or CHECKOUT_COMPLETE. |
Example
Query
mutation AddShipment(
$buyerNotes: String,
$checkout: ShipmentCheckoutInput,
$eshopId: ObjectID,
$geniki: GenikiInput,
$includeVat: Boolean,
$isB2BInvoice: Boolean,
$orderAmounts: OrderAmountsInput,
$orderId: String,
$parcels: [ParcelInput!],
$paymentMethod: ShipmentPaymentMethodEnum,
$products: [ProductInput]!,
$productsQuantity: Int!,
$recipient: RecipientCreateInput!,
$recipientLogistics: RecipientLogisticsInput,
$requiresShipping: Boolean,
$selectedRate: SelectedRateInput,
$senderNotes: String,
$shipper: ShipperInput,
$source: ShipmentSourceEnum,
$status: ShipmentStatusEnum
) {
addShipment(
buyerNotes: $buyerNotes,
checkout: $checkout,
eshopId: $eshopId,
geniki: $geniki,
includeVat: $includeVat,
isB2BInvoice: $isB2BInvoice,
orderAmounts: $orderAmounts,
orderId: $orderId,
parcels: $parcels,
paymentMethod: $paymentMethod,
products: $products,
productsQuantity: $productsQuantity,
recipient: $recipient,
recipientLogistics: $recipientLogistics,
requiresShipping: $requiresShipping,
selectedRate: $selectedRate,
senderNotes: $senderNotes,
shipper: $shipper,
source: $source,
status: $status
) {
_id
auditLog {
_id
actor {
...UserFragment
}
actorType
changes {
...ShipmentAuditChangeFragment
}
createdAt
event
metadata
summary
}
availableRates {
deliveryCompany {
...DeliveryCompanyFragment
}
error
quotedAt
rating
services {
...ServiceFragment
}
}
buyerNotes
checkout {
entryPoint
flow
isExpress
}
checkoutCompletedAt
codCollectible {
amount
source
status
}
codDeclaration {
amount
currency
declaredAt
source
voucherCodes
}
costSummary {
deliveryCost
productsTotal
totalCost
totalCostVatInclusive
vatRate
}
createdAt
documentUpload {
available
reason
}
effectiveDate
eshop {
_id
address
addressBook {
...AddressBookEntryTypeFragment
}
apikey
brandAssets {
...BrandAssetsFragment
}
city
deliveryCompanies {
...EshopDeliveryCompanyFragment
}
freeShipping {
...FreeShippingConfigFragment
}
general {
...GeneralConfigFragment
}
name
packageInsurance
pageCustomization {
...PageCustomizationFragment
}
phone
postcode
securityValue
slug
storeConnections {
...StoreConnectionFragment
}
taxProfile {
...TaxProfileFragment
}
}
freeShipping {
applied
appliedRegionSource
appliedRuleId
appliedRuleName
checkoutDisplay
codFeeCharged
defaultCarrier {
...DeliveryCompanyFragment
}
discountAmount
originalCost
reason
threshold
}
geniki {
chargeCode
jobId
}
isB2BInvoice
notificationsSent {
sentAt
trigger
}
orderAmounts {
amountDue
currency
discountLines {
...OrderDiscountLineFragment
}
discountTotal
feeLines {
...OrderFeeLineFragment
}
feesTotal
grandTotal
itemsSubtotal
payments {
...OrderPaymentFragment
}
prepaidTotal
pricesIncludeTax
shippingTax
shippingTotal
taxLines {
...OrderTaxLineFragment
}
totalTax
}
orderId
otherDocuments {
documentType
encodedDocument
externalId
}
parcels {
_id
billableWeight
contents {
...ParcelContentsFragment
}
dimensions {
...ParcelDimensionsFragment
}
returnVoucher {
...ParcelVoucherFragment
}
volumetricWeight
voucher {
...ParcelVoucherFragment
}
weight
}
paymentMethod
pickupAddress {
address
addressBookEntry
city
country
countryCode
name
postcode
}
pickupDate
products {
_id
categories
countryOfOrigin
description
dimensions {
...ProductDimensionsFragment
}
externalId
extraAttributes
harmonizedSystemCode
image
kind
lineDiscount
lineSubtotal
lineTotal
metadata
price
quantity
requiresShipping
size
sku
title
weight
}
productsQuantity
recipient {
address {
...AddressFragment
}
contact {
...ContactFragment
}
}
recipientLogistics {
companyName
email
phone
}
requiresShipping
returnShipmentVoucher {
code
createdAt
deliveryCompanyReference
merchantReference
status
}
selectedRate {
costs {
...CostsFragment
}
deliveryCompany {
...DeliveryCompanyFragment
}
fulfillmentType
negotiatedCosts {
...CostsFragment
}
priceComponents {
...PricingComponentFragment
}
quoteBasis {
...QuoteBasisFragment
}
rating
serviceCode
serviceName
transitTime {
...TransitTimeFragment
}
}
senderNotes
shipmentPurpose
shipmentVoucher {
code
createdAt
deliveryCompanyReference
merchantReference
status
}
shipper {
address {
...AddressFragment
}
addressBookEntry
contact {
...ContactFragment
}
}
shippingRegionType
status
trackingDetails {
carrierTrackingUrl
deliveredAt
deliveryCompany {
...DeliveryCompanyFragment
}
eshopTrackingUrl
estimatedDelivery
events {
...TrackingEventFragment
}
isActive
lastStatus
lastSyncedAt
lastUpdated
nextPollAt
returnToSender
slaTier
voucherCode
}
unassociatedVouchers {
code
rawDeliveryCompanyResponse
reason
status
}
unavailableRates {
deliveryCompany {
...DeliveryCompanyFragment
}
error
quotedAt
rating
services {
...ServiceFragment
}
}
vatDetails {
basisSource
valueAddedTaxIncluded
vatRate
}
}
}
Variables
{
"buyerNotes": "xyz789",
"checkout": ShipmentCheckoutInput,
"eshopId": "5e5677d71bdc2ae76344968c",
"geniki": GenikiInput,
"includeVat": true,
"isB2BInvoice": false,
"orderAmounts": OrderAmountsInput,
"orderId": "xyz789",
"parcels": [ParcelInput],
"paymentMethod": "AFTERPAY_CLEARPAY",
"products": [ProductInput],
"productsQuantity": 123,
"recipient": RecipientCreateInput,
"recipientLogistics": RecipientLogisticsInput,
"requiresShipping": true,
"selectedRate": SelectedRateInput,
"senderNotes": "xyz789",
"shipper": ShipperInput,
"source": "CHECKOUT",
"status": "CANCELED"
}
Response
{
"data": {
"addShipment": {
"_id": "5e5677d71bdc2ae76344968c",
"auditLog": [ShipmentAuditEntry],
"availableRates": [DeliveryRate],
"buyerNotes": "xyz789",
"checkout": ShipmentCheckout,
"checkoutCompletedAt": "2007-12-03T10:15:30Z",
"codCollectible": CodCollectible,
"codDeclaration": CodDeclaration,
"costSummary": CostSummary,
"createdAt": "2007-12-03T10:15:30Z",
"documentUpload": DocumentUploadEligibility,
"effectiveDate": "2007-12-03T10:15:30Z",
"eshop": Eshop,
"freeShipping": ShipmentFreeShipping,
"geniki": GenikiFields,
"isB2BInvoice": true,
"notificationsSent": [NotificationSent],
"orderAmounts": OrderAmounts,
"orderId": "xyz789",
"otherDocuments": [OtherDocument],
"parcels": [Parcel],
"paymentMethod": "AFTERPAY_CLEARPAY",
"pickupAddress": PickupAddress,
"pickupDate": "2007-12-03",
"products": [Product],
"productsQuantity": 987,
"recipient": Recipient,
"recipientLogistics": RecipientLogistics,
"requiresShipping": true,
"returnShipmentVoucher": ShipmentVoucher,
"selectedRate": SelectedRate,
"senderNotes": "xyz789",
"shipmentPurpose": "GIFT",
"shipmentVoucher": ShipmentVoucher,
"shipper": Shipper,
"shippingRegionType": "DOMESTIC",
"status": "CANCELED",
"trackingDetails": TrackingDetails,
"unassociatedVouchers": [UnassociatedVoucher],
"unavailableRates": [DeliveryRate],
"vatDetails": VatDetails
}
}
}
cancelVoucher
Description
Cancel every active voucher on a shipment. Returns a CancelVoucherPayload with the updated shipment and the carrier-confirmed canceled codes.
Response
Returns a CancelVoucherPayload!
Arguments
| Name | Description |
|---|---|
eshopId - ObjectID
|
Required if the user belongs to or owns multiple eshops. Admins must specify an eshop. Not required for eshop integrations. |
orderId - String
|
The order id. Either orderId or shipmentId must be provided |
shipmentId - ObjectID
|
The shipment id. Either orderId or shipmentId must be provided |
Example
Query
mutation CancelVoucher(
$eshopId: ObjectID,
$orderId: String,
$shipmentId: ObjectID
) {
cancelVoucher(
eshopId: $eshopId,
orderId: $orderId,
shipmentId: $shipmentId
) {
canceledCodes
shipment {
_id
auditLog {
...ShipmentAuditEntryFragment
}
availableRates {
...DeliveryRateFragment
}
buyerNotes
checkout {
...ShipmentCheckoutFragment
}
checkoutCompletedAt
codCollectible {
...CodCollectibleFragment
}
codDeclaration {
...CodDeclarationFragment
}
costSummary {
...CostSummaryFragment
}
createdAt
documentUpload {
...DocumentUploadEligibilityFragment
}
effectiveDate
eshop {
...EshopFragment
}
freeShipping {
...ShipmentFreeShippingFragment
}
geniki {
...GenikiFieldsFragment
}
isB2BInvoice
notificationsSent {
...NotificationSentFragment
}
orderAmounts {
...OrderAmountsFragment
}
orderId
otherDocuments {
...OtherDocumentFragment
}
parcels {
...ParcelFragment
}
paymentMethod
pickupAddress {
...PickupAddressFragment
}
pickupDate
products {
...ProductFragment
}
productsQuantity
recipient {
...RecipientFragment
}
recipientLogistics {
...RecipientLogisticsFragment
}
requiresShipping
returnShipmentVoucher {
...ShipmentVoucherFragment
}
selectedRate {
...SelectedRateFragment
}
senderNotes
shipmentPurpose
shipmentVoucher {
...ShipmentVoucherFragment
}
shipper {
...ShipperFragment
}
shippingRegionType
status
trackingDetails {
...TrackingDetailsFragment
}
unassociatedVouchers {
...UnassociatedVoucherFragment
}
unavailableRates {
...DeliveryRateFragment
}
vatDetails {
...VatDetailsFragment
}
}
}
}
Variables
{
"eshopId": "5e5677d71bdc2ae76344968c",
"orderId": "xyz789",
"shipmentId": "5e5677d71bdc2ae76344968c"
}
Response
{
"data": {
"cancelVoucher": {
"canceledCodes": ["xyz789"],
"shipment": Shipment
}
}
}
createPickupList
Description
Create pickup lists for all delivery companies which had been chosen for this pickup date
Response
Returns a CreatePickupListReturn
Arguments
| Name | Description |
|---|---|
eshopId - ObjectID
|
Optional if user belongs to single eshop; required for admins or multiple eshops |
pickupDate - String!
|
Date "YYYY-MM-DD" that the delivery companies should pick up shipments |
pickupTimes - [PickupTimeInput!]!
|
List of per-company pickup time inputs |
shipmentIds - [ObjectID!]!
|
Array of shipment IDs to include in the pickup list. |
Example
Query
mutation CreatePickupList(
$eshopId: ObjectID,
$pickupDate: String!,
$pickupTimes: [PickupTimeInput!]!,
$shipmentIds: [ObjectID!]!
) {
createPickupList(
eshopId: $eshopId,
pickupDate: $pickupDate,
pickupTimes: $pickupTimes,
shipmentIds: $shipmentIds
) {
lists {
closeTime
code
deliveryCompany {
...DeliveryCompanyFragment
}
printDocument
readyTime
}
}
}
Variables
{
"eshopId": "5e5677d71bdc2ae76344968c",
"pickupDate": "xyz789",
"pickupTimes": [PickupTimeInput],
"shipmentIds": [
"5e5677d71bdc2ae76344968c"
]
}
Response
{
"data": {
"createPickupList": {"lists": [PickupListsList]}
}
}
createVoucher
Description
Create the carrier voucher(s) for a shipment. Returns a CreateVoucherPayload wrapping the updated shipment; read voucher state off payload.shipment.shipmentVoucher and payload.shipment.parcels[i].voucher.
Response
Returns a CreateVoucherPayload!
Arguments
| Name | Description |
|---|---|
eshopId - ObjectID
|
Required if the user belongs to or owns multiple eshops. Admins must specify an eshop. Not required for eshop integrations. |
generateCommercialInvoice - Boolean
|
Whether to generate a commercial invoice. Defaults to true for international shipments. |
notes - String
|
Notes/comments for the delivery company |
orderId - String
|
The id of the order. Either orderId or shipmentId must be provided |
pickupDate - String
|
Date "YYYY-MM-DD" that the delivery company should receive the package from the shop. Defaults to today. |
shipmentId - ObjectID
|
The id of the shipment. Either orderId or shipmentId must be provided |
shipmentPurpose - ShipmentPurposeEnum
|
The purpose of the shipment |
Example
Query
mutation CreateVoucher(
$eshopId: ObjectID,
$generateCommercialInvoice: Boolean,
$notes: String,
$orderId: String,
$pickupDate: String,
$shipmentId: ObjectID,
$shipmentPurpose: ShipmentPurposeEnum
) {
createVoucher(
eshopId: $eshopId,
generateCommercialInvoice: $generateCommercialInvoice,
notes: $notes,
orderId: $orderId,
pickupDate: $pickupDate,
shipmentId: $shipmentId,
shipmentPurpose: $shipmentPurpose
) {
createdCodes
shipment {
_id
auditLog {
...ShipmentAuditEntryFragment
}
availableRates {
...DeliveryRateFragment
}
buyerNotes
checkout {
...ShipmentCheckoutFragment
}
checkoutCompletedAt
codCollectible {
...CodCollectibleFragment
}
codDeclaration {
...CodDeclarationFragment
}
costSummary {
...CostSummaryFragment
}
createdAt
documentUpload {
...DocumentUploadEligibilityFragment
}
effectiveDate
eshop {
...EshopFragment
}
freeShipping {
...ShipmentFreeShippingFragment
}
geniki {
...GenikiFieldsFragment
}
isB2BInvoice
notificationsSent {
...NotificationSentFragment
}
orderAmounts {
...OrderAmountsFragment
}
orderId
otherDocuments {
...OtherDocumentFragment
}
parcels {
...ParcelFragment
}
paymentMethod
pickupAddress {
...PickupAddressFragment
}
pickupDate
products {
...ProductFragment
}
productsQuantity
recipient {
...RecipientFragment
}
recipientLogistics {
...RecipientLogisticsFragment
}
requiresShipping
returnShipmentVoucher {
...ShipmentVoucherFragment
}
selectedRate {
...SelectedRateFragment
}
senderNotes
shipmentPurpose
shipmentVoucher {
...ShipmentVoucherFragment
}
shipper {
...ShipperFragment
}
shippingRegionType
status
trackingDetails {
...TrackingDetailsFragment
}
unassociatedVouchers {
...UnassociatedVoucherFragment
}
unavailableRates {
...DeliveryRateFragment
}
vatDetails {
...VatDetailsFragment
}
}
}
}
Variables
{
"eshopId": "5e5677d71bdc2ae76344968c",
"generateCommercialInvoice": true,
"notes": "abc123",
"orderId": "abc123",
"pickupDate": "xyz789",
"shipmentId": "5e5677d71bdc2ae76344968c",
"shipmentPurpose": "GIFT"
}
Response
{
"data": {
"createVoucher": {
"createdCodes": ["xyz789"],
"shipment": Shipment
}
}
}
printVoucher
Description
Print labels for one shipment in a single merged PDF. Labels are placed according to the carrier's configured outputMedium and stickerLayout: slot-grid snapping for sticker-paper customers, FFDH-packed onto the configured paper sheet for free-canvas customers, or concatenated at native cropped dimensions for thermal-printer customers. Multi-parcel shipments are merged into one document so callers receive a single printable file regardless of parcel count.
Response
Returns a PrintVoucherPayload!
Arguments
| Name | Description |
|---|---|
eshopId - ObjectID
|
Required if the user belongs to or owns multiple eshops. Admins must specify an eshop. Not required for eshop integrations. |
orderId - String
|
The order id. Either orderId or shipmentId must be provided |
shipmentId - ObjectID
|
The shipment id. Either orderId or shipmentId must be provided |
Example
Query
mutation PrintVoucher(
$eshopId: ObjectID,
$orderId: String,
$shipmentId: ObjectID
) {
printVoucher(
eshopId: $eshopId,
orderId: $orderId,
shipmentId: $shipmentId
) {
document
}
}
Variables
{
"eshopId": "5e5677d71bdc2ae76344968c",
"orderId": "abc123",
"shipmentId": "5e5677d71bdc2ae76344968c"
}
Response
{
"data": {
"printVoucher": {"document": "xyz789"}
}
}
Types
Address
Fields
| Field Name | Description |
|---|---|
addressLine1 - String
|
Address line 1 (original input). |
addressLine2 - String
|
Address line 2 (original input). |
addressLine3 - String
|
Address line 3 (original input). |
canonicalAddress - CanonicalAddress
|
Canonicalized address for internal use |
city - String
|
City (original input). |
country - String
|
Country (original input). |
countryCode - String
|
Country code in ISO 3166-1 alpha-2 format. |
county - String
|
County (original input). |
postcode - String
|
Postcode (original input). |
Example
{
"addressLine1": "xyz789",
"addressLine2": "xyz789",
"addressLine3": "abc123",
"canonicalAddress": CanonicalAddress,
"city": "xyz789",
"country": "abc123",
"countryCode": "abc123",
"county": "xyz789",
"postcode": "abc123"
}
AddressBookEntryType
AddressInput
Fields
| Input Field | Description |
|---|---|
addressLine1 - String
|
Address line 1. |
addressLine2 - String
|
Address line 2. |
addressLine3 - String
|
Address line 3. |
city - String
|
City. |
country - String
|
Country. |
countryCode - String
|
Country code in ISO 3166-1 alpha-2 format. |
county - String
|
County. |
postcode - String
|
Postcode. |
Example
{
"addressLine1": "xyz789",
"addressLine2": "xyz789",
"addressLine3": "abc123",
"city": "xyz789",
"country": "abc123",
"countryCode": "abc123",
"county": "xyz789",
"postcode": "xyz789"
}
AddressTypeEnum
Description
Type of address location from Google Places API
Values
| Enum Value | Description |
|---|---|
|
|
Business address (offices, stores, commercial buildings) |
|
|
Mixed-use address (both residential and business) |
|
|
Residential address (homes, apartments) |
Example
"BUSINESS"
AppliedRegionSourceEnum
Values
| Enum Value | Description |
|---|---|
|
|
Free shipping was applied via the rest-of-world fallback deal |
|
|
Free shipping was applied via a named regional rule |
Example
"REST_OF_WORLD"
AuditActorTypeEnum
Description
Which kind of caller performed an audited action.
Values
| Enum Value | Description |
|---|---|
|
|
An authenticated admin user |
|
|
A direct API-key integration (no user, no actor id) |
|
|
An authenticated eshop user |
|
|
The system itself (backfills, automated processes) |
Example
"ADMIN"
Boolean
Description
The Boolean scalar type represents true or false.
Example
true
BrandAssets
Fields
| Field Name | Description |
|---|---|
logos - BrandLogos
|
Example
{"logos": BrandLogos}
BrandColorScheme
Description
Color scheme for UI theming
Example
{
"accent": "xyz789",
"background": "abc123",
"primary": "xyz789",
"secondary": "abc123"
}
BrandLogos
CancelVoucherPayload
Description
Result of cancelVoucher. Wraps the updated shipment plus the list of voucher codes the carrier confirmed canceled by this call.
Fields
| Field Name | Description |
|---|---|
canceledCodes - [String!]!
|
Carrier-confirmed voucher codes canceled by this call. For carriers with API integration this is the carrier's exact confirmation list; for non-API carriers it's every active voucher code on the shipment immediately before cancellation. Useful for distinguishing 'just canceled' from 'previously canceled' when auditing. |
shipment - Shipment!
|
The shipment after cancellation. All voucher slots will have status: canceled and shipment.status will be voucher-canceled. trackingDetails is cleared. |
Example
{
"canceledCodes": ["xyz789"],
"shipment": Shipment
}
CancellationCapability
Fields
| Field Name | Description |
|---|---|
mode - VoucherCancellationModeEnum!
|
Example
{"mode": "CASCADE"}
CanonicalAddress
Description
Canonicalized address for internal use (analytics, pricing, rate lookups, etc.)
Fields
| Field Name | Description |
|---|---|
addressLine1 - String
|
Canonicalized primary address line. |
addressType - AddressTypeEnum
|
Type of address location (residential, business, mixed) |
city - String
|
Canonicalized city. |
coordinates - Coordinates
|
Geographic coordinates. |
country - String
|
Canonicalized country. |
countryCode - String
|
Canonicalized country code in ISO 3166-1 alpha-2 format. |
county - String
|
Canonicalized county. |
isCanonical - Boolean
|
Flag indicating if this address was successfully canonicalized via Google Places API |
placeId - String
|
Google Places API unique place identifier for future lookups |
postcode - String
|
Canonicalized postcode. |
Example
{
"addressLine1": "abc123",
"addressType": "BUSINESS",
"city": "abc123",
"coordinates": Coordinates,
"country": "abc123",
"countryCode": "xyz789",
"county": "xyz789",
"isCanonical": true,
"placeId": "xyz789",
"postcode": "abc123"
}
CheckoutDefaultSelectionEnum
Values
| Enum Value | Description |
|---|---|
|
|
Pre-select the pinned default carrier, or the first rate by sort order when none is pinned |
|
|
No server-side pre-selection; the buyer chooses a rate |
Example
"AUTO"
CodCollectible
Description
What the courier would be told to collect if the label were minted now, and how that was determined. Resolved server-side through the single accessor every carrier adapter uses — do not re-implement the fallback ladder client-side. On a shipment whose label already exists this is a LIVE figure and can differ from the printed one: read codDeclaration for what the courier will actually ask for.
Fields
| Field Name | Description |
|---|---|
amount - Float
|
The amount to collect. Set only when status is RESOLVED; null otherwise. A null here is never a zero. |
source - CodCollectibleSourceEnum
|
Which figure answered. Null when nothing was resolved. DERIVED_COST_SUMMARY means the figure is an estimate, not the platform's own number. |
status - CodCollectibleStatusEnum!
|
Distinguishes "not COD", "COD but nothing to collect" and "we could not tell" — all three of which would otherwise render as 0. |
Example
{"amount": 123.45, "source": "AMOUNT_DUE", "status": "NOT_COD"}
CodCollectibleSourceEnum
Description
Which figure the collectible was taken from.
Values
| Enum Value | Description |
|---|---|
|
|
orderAmounts.amountDue — what the platform says remains to be paid.
|
|
|
Pircel's own costSummary estimate, used only when the shipment carries no platform totals at all (pre-contract and CSV-imported orders). Discount-blind — treat as an estimate. |
|
|
orderAmounts.grandTotal — the platform total, used when no amountDue was sent. On a partly-prepaid order this over-states what is actually owed.
|
Example
"AMOUNT_DUE"
CodCollectibleStatusEnum
Description
Whether a COD collectible could be resolved, and to what.
Values
| Enum Value | Description |
|---|---|
|
|
The order is not cash-on-delivery; nothing is collected. |
|
|
A COD order the platform states is already fully paid (a verbatim amountDue of 0). The voucher takes the non-COD path. |
|
|
An amount was resolved; amount and source are set. |
|
|
A COD order carrying no usable total. Voucher creation fails closed rather than shipping a label that collects nothing — do NOT render this as 0. |
Example
"NOT_COD"
CodDeclaration
Description
What the carrier was told to collect, frozen when the label was minted. Stored, never recomputed: this is the number the courier will ask for even if the order has changed since. Absent on shipments with no live label, and on shipments vouchered before declarations were recorded — in both cases fall back to codCollectible.
Fields
| Field Name | Description |
|---|---|
amount - Float!
|
The COD amount printed on the label. |
currency - String
|
Currency the amount was declared in. Null when it came from the legacy costSummary rung, which predates any stated currency. |
declaredAt - DateTime!
|
When the label carrying this amount was minted. |
source - CodCollectibleSourceEnum!
|
Which figure the printed amount came from. DERIVED_COST_SUMMARY on a discounted order means the label was priced before discounts. |
voucherCodes - [String!]
|
The voucher codes issued alongside this declaration. |
Example
{
"amount": 987.65,
"currency": "xyz789",
"declaredAt": "2007-12-03T10:15:30Z",
"source": "AMOUNT_DUE",
"voucherCodes": ["abc123"]
}
ColorScheme
ConnectionStatus
Values
| Enum Value | Description |
|---|---|
|
|
Store connection is active and working |
|
|
Store connection has an error |
|
|
Store connection has been revoked |
Example
"ACTIVE"
Contact
Example
{
"companyName": "abc123",
"email": "xyz789",
"firstname": "abc123",
"lastname": "abc123",
"phone": "abc123"
}
ContactInput
Fields
| Input Field | Description |
|---|---|
companyName - String
|
Company name. Either company name OR first and last name is required. |
email - String
|
Email address. |
firstname - String
|
First name. Either first and last name OR company name is required. |
lastname - String
|
Last name. Either first and last name OR company name is required. |
phone - String
|
Phone number. |
Example
{
"companyName": "abc123",
"email": "xyz789",
"firstname": "abc123",
"lastname": "xyz789",
"phone": "abc123"
}
Coordinates
CostSummary
Description
Pircel's OWN view of the order: catalog product prices plus the delivery rate Pircel quoted. It is NOT the buyer's money and it is not the platform's total — it knows nothing about coupons, store fees, gift cards, or what the storefront actually charged for shipping (those live on orderAmounts). Frozen once checkout completes, so on an order edited afterwards it can disagree with products. For what the courier collects, read Shipment.codCollectible.
Fields
| Field Name | Description |
|---|---|
deliveryCost - Float
|
What Pircel charged for delivery: the quoted rate including surcharges, taxes and the eshop multiplier. The storefront may have charged the buyer something else — that is orderAmounts.shippingTotal. |
productsTotal - Float
|
Sum of catalog line prices (price × quantity) as sent. PRE-discount: per-line lineDiscount/lineTotal and order-level discountTotal are not subtracted here. |
totalCost - Float
|
productsTotal + deliveryCost, on the basis the eshop prices in. Not the order total the buyer paid — no discount, fee or tender is applied.
|
totalCostVatInclusive - Float
|
totalCost with VAT: equal to it for eshops pricing VAT-inclusive, grossed up by vatRate for net-priced ones. Historically the COD collectible, and still the last fallback rung for shipments with no orderAmounts — but on any order carrying platform totals the collectible is orderAmounts.amountDue/grandTotal and this number is only an estimate. ⚠️ The uplift is applied to the whole total at one order-level rate, without reading the selected rate's costs.vatBasis. On a net-priced eshop that grosses a UPS delivery leg whose basis is unconfirmed and which the quote deliberately left untaxed — so on that path this figure states a VAT position the quote refuses to state. Known; tracked against the UPS basis ruling. Never the COD collectible once the shipment carries orderAmounts — read Shipment.codCollectible for what the courier collects. Still valid as Pircel's VAT-inclusive estimate.
|
vatRate - Float
|
VAT rate (percent) applied to totalCost to produce totalCostVatInclusive. Present only for net-priced eshops; absent when prices already included VAT and no uplift was applied. It is ONE rate for the whole order, resolved from the destination — not the rate of any individual line, and not the rate of the delivery leg, whose own basis is selectedRate.costs.vatBasis. |
Example
{
"deliveryCost": 987.65,
"productsTotal": 987.65,
"totalCost": 987.65,
"totalCostVatInclusive": 987.65,
"vatRate": 987.65
}
Costs
Description
Cost breakdown for a service. finalPrice is the charge; vatBasis says whether VAT is already inside it, and the answer VARIES BETWEEN RATES IN ONE RESPONSE.
A platform that applies its own tax (Magento base_shipping_amount, and any headless checkout that taxes shipping itself) must post the NET charge, and must derive it per rate:
EX_VAT—finalPriceis already net. Use it as it stands.INC_VATwithvatAmount— net isfinalPrice - vatAmount. Prefer this: the producer back-derives the split from the final gross, so the identity holds exactly even after the minimum-price floor and the rounding increment have moved it. A statedvatAmountof 0 is an answer, not a missing value: it means this price contains no VAT, so the net ISfinalPrice. Do not fall through to the rate — dividing a stated zero would take VAT off a price that never carried any.INC_VATwith onlyvatRate— net isfinalPrice / (1 + vatRate/100). A re-derivation, so it can land a cent from the figure above; use it only whenvatAmountis absent.UNKNOWN, orvatBasisabsent — net is NOT derivable. Do not assumeEX_VATand do not fall back to a store-configured rate: the basis is unstated because it is genuinely unconfirmed (UPS today), and assuming costs ~19.4% on a Greek order in whichever direction the guess was wrong.
A platform that charges shipping gross (WooCommerce shipping_total) reads finalPrice directly and needs none of this.
Every OTHER field here is a partial, producer-dependent itemisation drawn from a different stage of the pipeline — carrier truth, Pircel’s pre-multiplier net tariff, or the final gross — and which stage a field belongs to depends on which producer built the rate, which this object does not say. No combination of them reconstructs finalPrice: the multiplier, the minimum-price floor and the rounding increment land after the itemised legs and appear in none of them. Read a field for what it is; never reconcile a sum against the charge.
⏳ The nine charge* / deliveryCharge* / codFee* fields are INTERIM. They exist because consumers need ready money now and the money rewrite that supersedes them is not close. They will be replaced by charge, deliveryCharge and codFee as TaxedMoney — nested { net, gross, tax } on the same names — and only then marked @deprecated, with a window. They are deliberately NOT deprecated today: a deprecated field is omitted from most codegen clients, which would hide exactly the fields you should be using.
Fields
| Field Name | Description |
|---|---|
basePrice - Float
|
Net, pre-multiplier, and producer-dependent: the carrier tariff base on a file-based rate, the carrier’s own base on FedEx. Not a share of finalPrice. |
chargeGross - Float
|
The delivery charge INCLUDING VAT — what a tax-inclusive storefront shows the buyer. Server-computed so no client repeats the derivation: on an INC_VAT rate this is finalPrice as it stands; on an EX_VAT rate it is the stated charge grossed at the stated vatRate through the one rounding door. Null when the basis is absent or UNKNOWN, or when an EX_VAT rate states no rate — a null is "not derivable", never 0. ⏳ INTERIM: superseded by charge/deliveryCharge/codFee as TaxedMoney when the money rewrite lands. It will be @deprecated then, with a window — not removed underneath you. Adopt it; just do not build a schema that assumes it is permanent. |
chargeNet - Float
|
The delivery charge EXCLUDING VAT — what a platform that applies its own tax must post (Magento base_shipping_amount). Server-computed so no client repeats the derivation: on an EX_VAT rate this is finalPrice; on an INC_VAT rate it is finalPrice - vatAmount, which the producer builds so the identity holds to the cent even after the floor and the rounding increment moved the gross. Null when the basis is absent or UNKNOWN — a null is "not derivable", never 0, and must not be read as finalPrice. ⏳ INTERIM: superseded by charge/deliveryCharge/codFee as TaxedMoney when the money rewrite lands. It will be @deprecated then, with a window — not removed underneath you. Adopt it; just do not build a schema that assumes it is permanent. |
chargeTax - Float
|
The VAT between chargeNet and chargeGross, so chargeNet + chargeTax === chargeGross holds exactly. Null whenever either leg is null. 🔴 NOT the same as vatAmount, which is the VAT contained in finalPrice and is therefore a correct 0 on an EX_VAT rate — where the tax between that rate’s net and its gross is not zero at all. ⏳ INTERIM: superseded by charge/deliveryCharge/codFee as TaxedMoney when the money rewrite lands. It will be @deprecated then, with a window — not removed underneath you. Adopt it; just do not build a schema that assumes it is permanent. |
codFeeGross - Float
|
The cash-on-delivery fee the buyer pays, INCLUDING VAT. Server-computed: the tariff fee carried through the merchant’s multiplier and grossed once, so no client repeats it. Together with deliveryChargeGross it sums to chargeGross exactly. Null whenever the charge legs are null; 0 when the rate was not quoted for cash on delivery. ⏳ INTERIM: superseded by charge/deliveryCharge/codFee as TaxedMoney when the money rewrite lands. It will be @deprecated then, with a window — not removed underneath you. Adopt it; just do not build a schema that assumes it is permanent. |
codFeeNet - Float
|
The cash-on-delivery fee the buyer pays, EXCLUDING VAT. ⚠️ Not the same as codSurcharge, which is the PRE-multiplier tariff figure: this is what the buyer’s fee actually came to after the merchant’s markup. Together with deliveryChargeNet it sums to chargeNet exactly. ⏳ INTERIM: superseded by charge/deliveryCharge/codFee as TaxedMoney when the money rewrite lands. It will be @deprecated then, with a window — not removed underneath you. Adopt it; just do not build a schema that assumes it is permanent. |
codFeeTax - Float
|
The VAT contained in codFeeGross, so codFeeNet + codFeeTax === codFeeGross exactly. ⏳ INTERIM: superseded by charge/deliveryCharge/codFee as TaxedMoney when the money rewrite lands. It will be @deprecated then, with a window — not removed underneath you. Adopt it; just do not build a schema that assumes it is permanent. |
codSurcharge - Float
|
The cash-on-delivery fee, ALWAYS STATED NET — even when vatBasis says every other amount here is gross. It is the one exception to this object's single-basis rule. ⚠️ WHOSE fee it is depends on which object you are reading, because this type is used for two different things: on selectedRate.costs it is the BUYER's fee and is already inside finalPrice; on selectedRate.negotiatedCosts it is what the CARRIER bills the MERCHANT, and has nothing to do with what the buyer pays. Never add the two, and never add either to freeShipping.codFeeCharged. ⚠️ On file-based rates this is the SAME money as surchargesTotal, not a component of it, so adding those two double-counts the fee. ⚠️ There is NO formula that recovers the buyer's fee from it. computeBuyerPrice scales the COD leg by priceMultiplier BEFORE VAT is added, and the minimum-price floor and rounding increment then land on the combined gross — so finalPrice - codSurcharge * (1 + vatRate / 100) is wrong on any rate with a multiplier, and under a binding floor the split does not exist at all. Neither minimumPrice nor roundingIncrement is on this object, so a consumer cannot even detect when it has gone wrong. If a merchant needs a delivery-only display line, that is a server-computed figure, not a client derivation. ⚠️ Under FREE shipping none of this applies: the delivery charge is REPLACED by freeShipping.codFeeCharged, which follows the ESHOP's basis (gross on a VAT-inclusive eshop) rather than being net like this field. Zero or absent when the rate was not quoted for cash on delivery. |
deliveryChargeGross - Float
|
What the buyer pays for DELIVERY alone, INCLUDING VAT — the shipping line a tax-inclusive storefront displays. deliveryChargeGross + codFeeGross === chargeGross exactly. 🔑 It absorbs the minimum-price floor and the rounding increment, which belong to no line and which free shipping already treats the same way: codFeeCharged keeps its own value there while the delivery charge moves. ⚠️ Under free shipping this object is bypassed entirely — the buyer pays freeShipping.codFeeCharged, not these fields. ⏳ INTERIM: superseded by charge/deliveryCharge/codFee as TaxedMoney when the money rewrite lands. It will be @deprecated then, with a window — not removed underneath you. Adopt it; just do not build a schema that assumes it is permanent. |
deliveryChargeNet - Float
|
What the buyer pays for DELIVERY alone, EXCLUDING VAT — the shipping line a platform that applies its own tax posts. deliveryChargeNet + codFeeNet === chargeNet exactly. ⏳ INTERIM: superseded by charge/deliveryCharge/codFee as TaxedMoney when the money rewrite lands. It will be @deprecated then, with a window — not removed underneath you. Adopt it; just do not build a schema that assumes it is permanent. |
deliveryChargeTax - Float
|
The VAT contained in deliveryChargeGross, so deliveryChargeNet + deliveryChargeTax === deliveryChargeGross exactly. ⏳ INTERIM: superseded by charge/deliveryCharge/codFee as TaxedMoney when the money rewrite lands. It will be @deprecated then, with a window — not removed underneath you. Adopt it; just do not build a schema that assumes it is permanent. |
feesTotal - Float
|
Total of all fees |
finalPrice - Float
|
Final price after all fees, surcharges and taxes with multiplier and minimum price constraints applied |
priceMultiplier - Float
|
Multiplier applied to the price |
surchargesTotal - Float
|
Net, pre-multiplier. ⚠️ On file-based rates this is the SAME money as codSurcharge, not a total containing it, so adding the two double-counts the COD fee. |
taxesAndDutiesTotal - Float
|
The CARRIER's own itemised tax and duty at quote time. Hardcoded 0 on every file-based carrier and structurally 0 on UPS, so a 0 here is not evidence that no tax applies. NOT disjoint from vatAmount: on FedEx, the only producer that states a real figure, the VAT inside this IS that field — summing the two counts the same euros twice. |
totalPriceBeforeMultiplier - Float
|
Subtotal before the multiplier, VAT, floor and rounding are applied. On vatBasis-tagged rates this is the EX-VAT subtotal; rates built before the net pipeline may include VAT here. |
vatAmount - Float
|
VAT contained in finalPrice (when vatBasis is inc-vat) — derived from the final, multiplier-scaled gross on net-pipeline rates. 0 on ex-vat rates. |
vatBasis - VatBasis
|
Whether finalPrice contains VAT. Persisted since the taxation module; exposed here because a client could not otherwise tell, and the answer VARIES WITHIN ONE RESPONSE — file-based carriers and FedEx report INC_VAT while UPS reports nothing at all, because its basis is unconfirmed. Absent on rates built before the taxation module. Do not read absent or UNKNOWN as EX_VAT: an amount whose basis is unstated is not comparable with one whose basis is stated, and comparing them is how a quote is picked on a price ~19.4% below what it will actually cost. ⚠️ It governs finalPrice and the totals beside it, NOT every field on this object: codSurcharge is stated net regardless of what this says — see its own description before splitting a COD fee out of a price. |
vatRate - Float
|
VAT rate (percent) in effect for this rate at build time; vatBasis says whether finalPrice contains it. Absent when the rate source exposed no rate — which is why it cannot be used to reconstruct a missing basis. It is the FALLBACK route to a net charge (finalPrice / (1 + vatRate/100)) when vatAmount is absent, never a substitute for vatBasis: knowing the rate says nothing about which side of it this figure sits on. |
Example
{
"basePrice": 987.65,
"chargeGross": 987.65,
"chargeNet": 123.45,
"chargeTax": 987.65,
"codFeeGross": 987.65,
"codFeeNet": 987.65,
"codFeeTax": 123.45,
"codSurcharge": 123.45,
"deliveryChargeGross": 987.65,
"deliveryChargeNet": 123.45,
"deliveryChargeTax": 987.65,
"feesTotal": 123.45,
"finalPrice": 123.45,
"priceMultiplier": 123.45,
"surchargesTotal": 123.45,
"taxesAndDutiesTotal": 987.65,
"totalPriceBeforeMultiplier": 123.45,
"vatAmount": 987.65,
"vatBasis": "EX_VAT",
"vatRate": 987.65
}
CostsInput
Description
Input for cost breakdown
Fields
| Input Field | Description |
|---|---|
basePrice - Float
|
Base price before any surcharges, fees, or taxes |
codSurcharge - Float
|
The cash-on-delivery fee you are echoing back, NET — the basis the server quoted it on, whatever vatBasis says about finalPrice. Send it as it was quoted rather than converting it to match the price beside it: a grossed-up value here reads as a larger fee than the one the buyer was shown. |
feesTotal - Float
|
Total of all fees |
finalPrice - Float
|
Final price after all fees, surcharges and taxes with multiplier and minimum price constraints applied |
priceMultiplier - Float
|
Multiplier applied to the price |
surchargesTotal - Float
|
Total of all surcharges |
taxesAndDutiesTotal - Float
|
Stored verbatim. Do not restate VAT you have already put in vatAmount — the two are not summed, and a reader that took the larger of them would silently drop the smaller. |
totalPriceBeforeMultiplier - Float
|
Subtotal before the multiplier, VAT, floor and rounding are applied. On vatBasis-tagged rates this is the EX-VAT subtotal; rates built before the net pipeline may include VAT here. |
vatAmount - Float
|
VAT contained in finalPrice (when vatBasis is inc-vat) — derived from the final, multiplier-scaled gross on net-pipeline rates. 0 on ex-vat rates. |
vatBasis - VatBasis
|
Whether the finalPrice you are sending contains VAT. OPTIONAL, not required (BE-14): making it mandatory would reject every request from the plugins already in the field, which is a worse failure than the one it prevents. Send it — a plugin that quotes net while the backend assumes gross under-collects COD by roughly the VAT rate, silently, and no existing guard catches it. |
Example
{
"basePrice": 123.45,
"codSurcharge": 987.65,
"feesTotal": 987.65,
"finalPrice": 987.65,
"priceMultiplier": 123.45,
"surchargesTotal": 987.65,
"taxesAndDutiesTotal": 123.45,
"totalPriceBeforeMultiplier": 123.45,
"vatAmount": 123.45,
"vatBasis": "EX_VAT"
}
CreatePickupListReturn
Fields
| Field Name | Description |
|---|---|
lists - [PickupListsList]
|
Example
{"lists": [PickupListsList]}
CreateVoucherPayload
Description
Result of createVoucher. Wraps the updated shipment plus the flat list of voucher codes the carrier issued. Future revisions may add structured warnings (e.g. for a failed customer email notification) without breaking clients.
Fields
| Field Name | Description |
|---|---|
createdCodes - [String!]!
|
Voucher codes the carrier issued in this invocation, in stable order (shipment-level first, then per-parcel) and de-duped (UPS emits the master tracking number as both the shipment-level voucher and the first parcel's code). Empty on the idempotent 'already-created' short-circuit, so createdCodes.length === 0 distinguishes a fresh creation from a no-op. |
shipment - Shipment!
|
The shipment with its voucher state freshly populated. Read shipmentVoucher, parcels[i].voucher, unassociatedVouchers, and otherDocuments for the carrier-issued data. |
Example
{
"createdCodes": ["xyz789"],
"shipment": Shipment
}
CredentialField
Fields
| Field Name | Description |
|---|---|
isRequired - Boolean!
|
|
isSecret - Boolean
|
|
key - String!
|
|
label - String!
|
|
type - CredentialFieldTypeEnum!
|
Example
{
"isRequired": false,
"isSecret": false,
"key": "abc123",
"label": "xyz789",
"type": "ACCOUNT"
}
CredentialFieldTypeEnum
Values
| Enum Value | Description |
|---|---|
|
|
|
|
|
Example
"ACCOUNT"
CredentialTransport
Values
| Enum Value | Description |
|---|---|
|
|
Credentials are sent in the HTTP Authorization header. |
|
|
Credentials are sent as query-string parameters, for stores whose web server does not pass the Authorization header through to the platform. |
Example
"HEADER"
CustomizationExtensions
Description
Extension point for future customization features
Fields
| Field Name | Description |
|---|---|
_placeholder - Boolean
|
Placeholder field for future extensions |
Example
{"_placeholder": false}
Date
Description
A date string, such as 2007-12-03, compliant with the full-date format outlined in section 5.6 of the RFC 3339 profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar.
Example
"2007-12-03"
DateTime
Description
A date-time string at UTC, such as 2007-12-03T10:15:30Z, compliant with the date-time format outlined in section 5.6 of the RFC 3339 profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar.
Example
"2007-12-03T10:15:30Z"
DeliveryCompany
Fields
| Field Name | Description |
|---|---|
_id - ID!
|
|
acceptedPaymentMethods - [ShipmentPaymentMethodEnum!]!
|
Payment methods this carrier can offer the end customer. Cash-on-delivery is carrier-dependent; card/PayPal/bank-deposit are merchant-gateway methods and may be listed for completeness. |
capabilities - DeliveryCompanyCapabilities
|
Per-carrier behavior matrix: multi-piece support, cancellation cascade mode, per-piece tracking, where customer references are accepted. |
createdAt - DateTime!
|
|
credentialFields - [CredentialField!]!
|
|
defaultConfig - DeliveryCompanyDefaultConfig!
|
|
description - String
|
|
hasAction - Boolean!
|
|
Arguments
|
|
hasApiIntegration - Boolean!
|
|
internalOnly - Boolean!
|
|
isEnabled - Boolean!
|
|
isVisibleAtCheckout - Boolean!
|
|
logo - Logo
|
|
minimumWeight - Float!
|
|
name - String!
|
|
pickupTimeOptions - PickupTimeOptions!
|
|
services - [DeliveryCompanyService!]!
|
All services the carrier offers. Each entry includes the carrier-prescribed code and its human-readable display name. |
slug - String!
|
|
supportedActions - [DeliveryCompanyApiActionEnum!]!
|
|
tags - [String!]!
|
|
trackingUrlInformation - TrackingUrlInformation
|
|
updatedAt - DateTime!
|
|
usesAccountShipperAddress - Boolean!
|
|
Example
{
"_id": "4",
"acceptedPaymentMethods": ["AFTERPAY_CLEARPAY"],
"capabilities": DeliveryCompanyCapabilities,
"createdAt": "2007-12-03T10:15:30Z",
"credentialFields": [CredentialField],
"defaultConfig": DeliveryCompanyDefaultConfig,
"description": "xyz789",
"hasAction": true,
"hasApiIntegration": false,
"internalOnly": false,
"isEnabled": true,
"isVisibleAtCheckout": false,
"logo": Logo,
"minimumWeight": 987.65,
"name": "abc123",
"pickupTimeOptions": PickupTimeOptions,
"services": [DeliveryCompanyService],
"slug": "abc123",
"supportedActions": ["CANCEL_VOUCHER"],
"tags": ["abc123"],
"trackingUrlInformation": TrackingUrlInformation,
"updatedAt": "2007-12-03T10:15:30Z",
"usesAccountShipperAddress": false
}
DeliveryCompanyApiActionEnum
Values
| Enum Value | Description |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Example
"CANCEL_VOUCHER"
DeliveryCompanyCapabilities
Description
Per-carrier capability matrix that downstream code branches on for cancellation cascade, multi-piece UI gating, reference-stamping, and parcel-identity round-tripping.
Fields
| Field Name | Description |
|---|---|
cancellation - CancellationCapability!
|
|
multiPiece - MultiPieceCapability!
|
|
parcelIdentityMode - ParcelIdentityModeEnum!
|
How a returned voucher round-trips back to the originating parcel. Drives webhook / callback handler behaviour: 'piece-id' uses parcelVoucher.deliveryCompanyPieceId, 'positional' uses the parcel index, 'none' means no per-piece identity exists. |
perPieceTracking - Boolean!
|
Whether the carrier returns a distinct tracking number per parcel. |
referenceScope - VoucherCapabilityScopeEnum!
|
Where the carrier accepts the customer reference fields we send. |
Example
{
"cancellation": CancellationCapability,
"multiPiece": MultiPieceCapability,
"parcelIdentityMode": "NONE",
"perPieceTracking": false,
"referenceScope": "BOTH"
}
DeliveryCompanyDefaultConfig
DeliveryCompanyIDOrSlugInput
DeliveryCompanyService
Description
A carrier-prescribed service: the carrier's internal code and its human-readable display name.
Fields
| Field Name | Description |
|---|---|
code - String!
|
Carrier-specific service identifier (e.g. "FEDEX_GROUND", "65"). This is the value to use when calling the carrier API or when configuring an eshop's enabled services. |
name - String!
|
Human-readable display name for the service (e.g. "FedEx Ground", "UPS Worldwide Saver"). Falls back to code if the service is not in our catalog. |
Example
{
"code": "abc123",
"name": "abc123"
}
DeliveryRate
Description
Available rates for a delivery company with all available service options
Fields
| Field Name | Description |
|---|---|
deliveryCompany - DeliveryCompany
|
Delivery company providing this rate |
error - String
|
Error message if rate retrieval failed for this delivery company |
quotedAt - DateTime
|
When this carrier quote was fetched. Absent on fan-outs persisted before the stamp existed. |
rating - Float
|
Rating of the delivery company |
services - [Service]
|
Available services from this carrier |
Example
{
"deliveryCompany": DeliveryCompany,
"error": "xyz789",
"quotedAt": "2007-12-03T10:15:30Z",
"rating": 987.65,
"services": [Service]
}
DocumentUploadEligibility
Description
Whether a shipment can take a document upload, and why not when it cannot.
Fields
| Field Name | Description |
|---|---|
available - Boolean!
|
Whether the upload endpoint would accept a document. |
reason - String
|
Null when available. Otherwise the very error code POST /shipments/:shipmentId/documents would answer with for this shipment, so a client renders one message whether the control was hidden or the request refused. |
Example
{"available": false, "reason": "xyz789"}
EncryptedFieldEntry
Eshop
Fields
| Field Name | Description |
|---|---|
_id - ObjectID
|
|
address - String
|
|
addressBook - [AddressBookEntryType]
|
|
apikey - String
|
|
brandAssets - BrandAssets
|
|
city - String
|
|
deliveryCompanies - [EshopDeliveryCompany]
|
|
Arguments
|
|
freeShipping - FreeShippingConfig
|
Free shipping promotion configuration |
general - GeneralConfig
|
General eshop settings |
name - String
|
|
packageInsurance - Float
|
|
pageCustomization - PageCustomization
|
|
phone - String
|
|
postcode - String
|
|
securityValue - Float
|
|
slug - String
|
|
storeConnections - [StoreConnection]
|
|
taxProfile - TaxProfile
|
How VAT is resolved for the charges Pircel prices, and the accountant-confirmed facts law mode needs. READ-ONLY, deliberately — see the type description. |
Example
{
"_id": "5e5677d71bdc2ae76344968c",
"address": "xyz789",
"addressBook": [AddressBookEntryType],
"apikey": "abc123",
"brandAssets": BrandAssets,
"city": "abc123",
"deliveryCompanies": [EshopDeliveryCompany],
"freeShipping": FreeShippingConfig,
"general": GeneralConfig,
"name": "abc123",
"packageInsurance": 987.65,
"pageCustomization": PageCustomization,
"phone": "xyz789",
"postcode": "abc123",
"securityValue": 987.65,
"slug": "xyz789",
"storeConnections": [StoreConnection],
"taxProfile": TaxProfile
}
EshopAuthConfig
Fields
| Field Name | Description |
|---|---|
addressBookEntry - ObjectID
|
Reference to an address book entry from the Eshop address book. |
credentials - [EncryptedFieldEntry]
|
Example
{
"addressBookEntry": "5e5677d71bdc2ae76344968c",
"credentials": [EncryptedFieldEntry]
}
EshopBranding
Description
Public branding information for an eshop to render branded pages
Fields
| Field Name | Description |
|---|---|
_id - ObjectID!
|
Eshop identifier |
colorScheme - BrandColorScheme
|
Color scheme for UI theming |
customization - CustomizationExtensions
|
Extension point for future customization features |
logos - BrandLogos
|
Brand logos for different usage contexts |
name - String!
|
Eshop display name |
Example
{
"_id": "5e5677d71bdc2ae76344968c",
"colorScheme": BrandColorScheme,
"customization": CustomizationExtensions,
"logos": BrandLogos,
"name": "xyz789"
}
EshopDeliveryCompany
Fields
| Field Name | Description |
|---|---|
config - EshopDeliveryCompanyConfig
|
|
deliveryCompany - DeliveryCompany
|
|
isEnabled - Boolean
|
Example
{
"config": EshopDeliveryCompanyConfig,
"deliveryCompany": DeliveryCompany,
"isEnabled": true
}
EshopDeliveryCompanyConfig
Fields
| Field Name | Description |
|---|---|
authConfigs - [EshopAuthConfig]
|
|
displayAtCheckout - Boolean
|
|
enabledServices - [String]
|
|
minimumPrice - Float
|
|
notificationPreferences - NotificationPreferences
|
|
paperType - String
|
|
priceMultiplier - Float
|
|
roundingIncrement - Float
|
|
rules - [Rule]
|
Example
{
"authConfigs": [EshopAuthConfig],
"displayAtCheckout": false,
"enabledServices": ["abc123"],
"minimumPrice": 123.45,
"notificationPreferences": NotificationPreferences,
"paperType": "xyz789",
"priceMultiplier": 123.45,
"roundingIncrement": 987.65,
"rules": [Rule]
}
Float
Description
The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.
Example
987.65
FreeShippingCheckoutDisplayEnum
Values
| Enum Value | Description |
|---|---|
|
|
Show all carrier rates with discounted/free prices at checkout |
|
|
Show a single "Free Shipping" option using the default carrier at checkout |
Example
"ALL_CARRIERS"
FreeShippingConfig
Description
Free shipping promotion configuration for an eshop
Fields
| Field Name | Description |
|---|---|
checkoutDisplay - FreeShippingCheckoutDisplayEnum
|
How free shipping appears at checkout. Defaults to ALL_CARRIERS. |
isEnabled - Boolean
|
Whether free shipping promotion is active for this eshop |
restOfWorld - FreeShippingRestOfWorld
|
Optional fallback applied when no rule matches the destination country |
rules - [FreeShippingRule!]
|
Ordered list of region rules; first match by destination country wins |
Example
{
"checkoutDisplay": "ALL_CARRIERS",
"isEnabled": true,
"restOfWorld": FreeShippingRestOfWorld,
"rules": [FreeShippingRule]
}
FreeShippingRestOfWorld
Description
Fallback free shipping deal applied when no rule matches the destination country
Fields
| Field Name | Description |
|---|---|
codFee - Float
|
Cash on delivery surcharge applied when this rule is active and the customer selects COD |
defaultCarrier - DeliveryCompany
|
Default delivery company used for fulfillment when this rule is applied |
minItemCount - Int
|
Minimum number of product items required in the order for this rule to apply |
name - String!
|
Human-readable label for this rule, shown in admin UI |
threshold - Float!
|
Minimum order value for free shipping under this rule, on the SAME basis as the eshop's own order prices — VAT-inclusive for a VAT-inclusive eshop, matching what the storefront advertises. Not an ex-VAT figure. |
thresholdBasis - FreeShippingThresholdBasisEnum
|
What the threshold compares against, counting the lines that ship and nothing else. PAID (the default) is what the buyer paid: the order totals when every line ships, per-line lineTotal when some do not. CATALOG is the pre-discount sum of price x quantity. PAID falls back to CATALOG on an order stating neither, so a rule set to PAID can still be evaluated pre-discount. Note every major platform evaluates its own free-shipping minimum post-discount. |
waiveCodFee - Boolean
|
Whether to absorb the COD fee in the free shipping promotion under this rule |
excludedCountries - [String!]
|
ISO 3166-1 alpha-2 country codes that receive no free shipping at all |
Example
{
"codFee": 987.65,
"defaultCarrier": DeliveryCompany,
"minItemCount": 123,
"name": "abc123",
"threshold": 987.65,
"thresholdBasis": "CATALOG",
"waiveCodFee": false,
"excludedCountries": ["xyz789"]
}
FreeShippingRule
Description
A region-scoped free shipping rule (named country group with optional exclusions)
Fields
| Field Name | Description |
|---|---|
_id - ObjectID
|
|
codFee - Float
|
Cash on delivery surcharge applied when this rule is active and the customer selects COD |
defaultCarrier - DeliveryCompany
|
Default delivery company used for fulfillment when this rule is applied |
minItemCount - Int
|
Minimum number of product items required in the order for this rule to apply |
name - String!
|
Human-readable label for this rule, shown in admin UI |
threshold - Float!
|
Minimum order value for free shipping under this rule, on the SAME basis as the eshop's own order prices — VAT-inclusive for a VAT-inclusive eshop, matching what the storefront advertises. Not an ex-VAT figure. |
thresholdBasis - FreeShippingThresholdBasisEnum
|
What the threshold compares against, counting the lines that ship and nothing else. PAID (the default) is what the buyer paid: the order totals when every line ships, per-line lineTotal when some do not. CATALOG is the pre-discount sum of price x quantity. PAID falls back to CATALOG on an order stating neither, so a rule set to PAID can still be evaluated pre-discount. Note every major platform evaluates its own free-shipping minimum post-discount. |
waiveCodFee - Boolean
|
Whether to absorb the COD fee in the free shipping promotion under this rule |
countries - [String!]!
|
ISO 3166-1 alpha-2 country codes this rule applies to |
excludedCountries - [String!]
|
ISO 3166-1 alpha-2 country codes carved out of this rule |
Example
{
"_id": "5e5677d71bdc2ae76344968c",
"codFee": 987.65,
"defaultCarrier": DeliveryCompany,
"minItemCount": 123,
"name": "abc123",
"threshold": 123.45,
"thresholdBasis": "CATALOG",
"waiveCodFee": true,
"countries": ["xyz789"],
"excludedCountries": ["xyz789"]
}
FreeShippingThresholdBasisEnum
Values
| Enum Value | Description |
|---|---|
|
|
Threshold compares against the sum of product prices × quantities as sent (pre-discount) — the historical behavior |
|
|
Threshold compares against what the buyer paid for the lines that ship: the order's itemsSubtotal minus discountTotal when every line ships, the shippable lines' own lineTotal when some do not. Falls back to CATALOG on an order stating neither. |
Example
"CATALOG"
FulfillmentType
Description
How a shipment is fulfilled. carrier is a Pircel-mapped courier with a deliveryCompany and full automation. external is an unmappable third-party courier the merchant arranges (ships, but no carrier automation; reassignable to a real carrier later). pickup is collect-from-store (nothing ships).
Values
| Enum Value | Description |
|---|---|
|
|
Pircel-mapped carrier |
|
|
Unmappable third-party courier arranged by the merchant |
|
|
Collect from store; nothing ships |
Example
"CARRIER"
GeneralCheckoutConfig
Description
Checkout-related general settings
Fields
| Field Name | Description |
|---|---|
defaultCarrier - DeliveryCompany
|
Optional carrier pinned to be pre-selected at checkout when defaultSelection is AUTO |
defaultSelection - CheckoutDefaultSelectionEnum
|
Whether a rate is pre-selected at checkout (AUTO) or left to the buyer (NONE). Defaults to AUTO. |
rateSorting - RateSortingEnum
|
How available shipping rates are ordered at checkout. Defaults to PRICE_ASC. |
Example
{
"defaultCarrier": DeliveryCompany,
"defaultSelection": "AUTO",
"rateSorting": "FASTEST"
}
GeneralConfig
Description
General settings configuration for an eshop
Fields
| Field Name | Description |
|---|---|
checkout - GeneralCheckoutConfig
|
Checkout-related general settings |
Example
{"checkout": GeneralCheckoutConfig}
GenikiFields
GenikiInput
GoodsRateCategoryEnum
Description
VAT rate class of the eshop's goods.
Values
| Enum Value | Description |
|---|---|
|
|
The only supported class. Onboarding a reduced-rated eshop means extending the taxation dataset first; until then resolution fails closed rather than guessing a rate. |
Example
"STANDARD"
ID
Description
The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.
Example
"4"
Int
Description
The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.
Example
987
JSON
Description
The JSON scalar type represents JSON values as specified by ECMA-404.
Example
{}
LabelDimensions
Logo
MultiPieceCapability
NotificationPreferences
Description
Email notification trigger preferences per delivery company. Controls when customer notifications are sent.
Fields
| Field Name | Description |
|---|---|
onInTransit - Boolean
|
Send notification when carrier first scans the package (in-transit, picked-up, or out-for-delivery status). |
onPickupCreate - Boolean
|
Send notification when pickup list is created. |
onVoucherCreate - Boolean
|
Send notification when voucher/label is created. |
Example
{"onInTransit": true, "onPickupCreate": false, "onVoucherCreate": true}
NotificationSent
Description
Record of a sent email notification.
Fields
| Field Name | Description |
|---|---|
sentAt - DateTime!
|
Timestamp when the notification was sent |
trigger - NotificationTriggerEnum!
|
The notification trigger type |
Example
{
"sentAt": "2007-12-03T10:15:30Z",
"trigger": "IN_TRANSIT"
}
NotificationTriggerEnum
Description
Types of email notification triggers for shipments.
Values
| Enum Value | Description |
|---|---|
|
|
Triggered when carrier first scans the package |
|
|
Triggered when pickup list is created |
|
|
Triggered when voucher/label is created |
Example
"IN_TRANSIT"
ObjectID
Description
A field whose value conforms with the standard mongodb object ID as described here: https://docs.mongodb.com/manual/reference/method/ObjectId/#ObjectId. Example: 5e5677d71bdc2ae76344968c
Example
"5e5677d71bdc2ae76344968c"
OrderAmounts
Description
The order totals as the seller stated them, ingested verbatim (amounts-first contract) — from a commerce platform relaying its storefront, or from a merchant stating them on a dashboard-created order. The COD collectible is amountDue when present, else grandTotal; Pircel never recomputes these.
Fields
| Field Name | Description |
|---|---|
amountDue - Float
|
What remains to be paid, and therefore the at-door COD collectible. Gift cards, store credit and partial payments are tenders, not discounts: they reduce this and never grandTotal. A verbatim 0 means "collect nothing". |
currency - String
|
ISO 4217 currency of all amounts (EUR). |
discountLines - [OrderDiscountLine]
|
The platform's per-discount breakdown (coupons, automatic promotions, manual edits). Metadata only. |
discountTotal - Float
|
Total coupon/cart/automatic discount the buyer saw, on the order's price basis. Sale prices are already baked into itemsSubtotal. |
feeLines - [OrderFeeLine]
|
Store-charged fee lines (COD surcharges, gift wrap, tips, levies). Signed amounts; metadata only. |
feesTotal - Float
|
Sum of store-charged fee lines the buyer paid, on the order's price basis — the SAME basis as itemsSubtotal and discountTotal (gross for a tax-inclusive store, net for a tax-exclusive one), or the totals identity cannot close. Signed: platforms allow negative pseudo-discount fee lines. |
grandTotal - Float
|
The platform's order grand total, verbatim: the buyer's full obligation for the order BEFORE any tender is applied against it. Discounts are already inside it; gift cards and other prepayments are not — those reduce amountDue. |
itemsSubtotal - Float
|
Line items as sold (post-sale-price, pre coupon/cart discounts), on the order's price basis. |
payments - [OrderPayment]
|
Tenders already applied against this order (gift cards, store credit, deposits, captures). Metadata only. |
prepaidTotal - Float
|
What has already been paid against this order, as the seller states it (EN 16931 BT-113). Never summed by Pircel from payments — a total derived from the lines would be Pircel inventing the buyer's money. Send the lines AND the total; lines alone record an anomaly. |
pricesIncludeTax - Boolean
|
Per-order basis tag: whether the order amounts include tax. Absent when the order was not tagged. |
shippingTax - Float
|
Tax on the platform's shipping charge. |
shippingTotal - Float
|
What the buyer pays for shipping, post shipping-discount, on the order's price basis — the SAME basis as itemsSubtotal and discountTotal. On a tax-inclusive store this INCLUDES shippingTax; sending it net there fails ingestion with inconsistent-totals by exactly the shipping VAT. |
taxLines - [OrderTaxLine]
|
The platform's per-rate tax breakdown (metadata only). |
totalTax - Float
|
Total tax on the order. Already INSIDE grandTotal on a tax-inclusive store; ADDED to the other parts to reach it on a tax-exclusive one — which is why the totals identity adds it only in the exclusive case. Required on a tax-exclusive order for that identity to run at all; without it only plausibility bounds are checked. |
Example
{
"amountDue": 123.45,
"currency": "xyz789",
"discountLines": [OrderDiscountLine],
"discountTotal": 123.45,
"feeLines": [OrderFeeLine],
"feesTotal": 123.45,
"grandTotal": 123.45,
"itemsSubtotal": 123.45,
"payments": [OrderPayment],
"prepaidTotal": 987.65,
"pricesIncludeTax": false,
"shippingTax": 987.65,
"shippingTotal": 123.45,
"taxLines": [OrderTaxLine],
"totalTax": 123.45
}
OrderAmountsInput
Description
The order totals as the seller states them, sent verbatim — never recomputed here (amounts-first contract). Whoever originates the order owns these figures: a commerce platform relaying what its storefront charged, or a dashboard-created order where the merchant states them directly. The rule is the same either way — send a figure a human was shown and accepted, and omit one you would have to derive. The COD collectible is amountDue when present, else grandTotal; re-send on updates so refunds and edits carry through to the voucher.
Fields
| Input Field | Description |
|---|---|
amountDue - Float
|
What remains to be paid after every tender already applied — the at-door COD collectible, and the field that decides how much cash the courier takes. Send 0 for a fully-prepaid order; the voucher is then created without COD collection. Omit it rather than guessing: an absent value falls back to grandTotal, a wrong one is collected verbatim. It must rest on tenders actually applied — a selected payment method is an intent, not a captured payment. Never send more than is owed: under-reporting is a reporting defect, over-collecting from a buyer who already paid is not recoverable. Where it comes from: Shopify total_outstanding, Magento total_due, WooCommerce total (always the residual — gift-card plugins reduce it in place, and the official extension before v1.8.0 omits the amount entirely). |
currency - String!
|
ISO 4217 currency of all amounts. Required; only EUR is accepted. |
discountLines - [OrderDiscountLineInput]
|
The per-discount breakdown behind discountTotal. Stored and rendered as metadata, never computed from — a total is never synthesised from its lines. Where it comes from: WooCommerce coupon_lines, Shopify discount_applications. |
discountTotal - Float
|
Total coupon/cart/automatic discount the buyer saw, on the order's price basis. Sale prices belong in itemsSubtotal, not here. A known zero is a fact and should be stated — the totals identity abstains entirely without it. Where it comes from: WooCommerce discount_total plus discount_tax on a tax-inclusive store; Shopify total_discounts. |
feeLines - [OrderFeeLineInput]
|
Seller-charged fee lines — COD surcharges, gift wrap, tips, statutory levies. Signed amounts. Where it comes from: WooCommerce fee_lines. |
feesTotal - Float
|
Total of the seller-charged fees the buyer paid (signed — negative pseudo-discount fees are legal). State it whenever feeLines carry a non-zero amount: an unstated total is not a stated zero, and the totals identity abstains rather than deriving one from the lines. |
grandTotal - Float!
|
The buyer's full obligation for the order, verbatim, BEFORE any tender (gift card, store credit, deposit) is applied against it. Discounts are already inside it. Never synthesise it from its parts — send a figure the buyer was shown and accepted, which on a seller-originated order means one the form displayed before submit. Where it comes from: Shopify total_price, which stays gross because Shopify models a gift card as a transaction. WooCommerce: send total here AND as amountDue, and never inflate it — WooCommerce stores only the residual (the official Gift Cards extension and the common third-party ones all reduce total), so a gross figure cannot be recovered and inventing one over-collects cash at the door. |
itemsSubtotal - Float
|
Line items as sold: post-sale-price, PRE coupon/cart discounts, on the order's price basis. Sent together with discountTotal and shippingTotal it enables the totals identity, which must compose to grandTotal within rounding tolerance; omit any of the three and that arithmetic check does not run at all. Where it comes from: WooCommerce Σ line subtotal(+tax), Shopify total_line_items_price, Magento subtotal. |
payments - [OrderPaymentInput]
|
Tenders already applied against this order. A gift card or store credit sent as a discountLine is permanently recorded as a promotion — send it here. |
prepaidTotal - Float
|
What has already been paid against this order, as the seller states it (EN 16931 BT-113). Never summed by Pircel from payments — a total derived from the lines would be Pircel inventing the buyer's money. Send the lines AND the total; lines alone record an anomaly. |
pricesIncludeTax - Boolean
|
Whether the order amounts include tax. Falls back to the eshop's declared default when omitted, and must not contradict the legacy includeVat argument when both are sent — prefer this field alone; includeVat is a migration alias for callers that predate it. Where it comes from: WooCommerce prices_include_tax, Shopify taxes_included. |
shippingTax - Float
|
Tax on the platform's shipping charge. |
shippingTotal - Float
|
What the buyer pays for shipping, POST shipping-discount. This is the seller's charge to the buyer, not Pircel's quote — they coincide only where the seller passes the quote through unchanged. Where it comes from: WooCommerce shipping_total is already post-discount; Shopify plugins subtract SHIPPING_LINE discount allocations. |
taxLines - [OrderTaxLineInput]
|
The per-rate tax breakdown behind totalTax. Stored and rendered as metadata, never computed from. |
totalTax - Float
|
Total tax on the order. Already INSIDE grandTotal on a tax-inclusive store; ADDED to the other parts to reach it on a tax-exclusive one — which is why the totals identity adds it only in the exclusive case. Required on a tax-exclusive order for that identity to run at all; without it only plausibility bounds are checked. |
Example
{
"amountDue": 123.45,
"currency": "abc123",
"discountLines": [OrderDiscountLineInput],
"discountTotal": 987.65,
"feeLines": [OrderFeeLineInput],
"feesTotal": 987.65,
"grandTotal": 987.65,
"itemsSubtotal": 123.45,
"payments": [OrderPaymentInput],
"prepaidTotal": 987.65,
"pricesIncludeTax": true,
"shippingTax": 123.45,
"shippingTotal": 123.45,
"taxLines": [OrderTaxLineInput],
"totalTax": 123.45
}
OrderDiscountKindEnum
Values
| Enum Value | Description |
|---|---|
|
|
Platform rule applied without a code |
|
|
Buyer-entered code |
|
|
Merchant order edit |
|
|
Anything else |
Example
"AUTOMATIC"
OrderDiscountLine
Description
One coupon/promotion the platform applied — provenance, never computed from.
Fields
| Field Name | Description |
|---|---|
amount - Float
|
Discount amount of this line in the order currency. |
code - String
|
The coupon/promo code the buyer entered, if any. |
kind - OrderDiscountKindEnum
|
How the platform applied this discount. |
label - String
|
The platform's display label for this discount line. |
Example
{
"amount": 987.65,
"code": "abc123",
"kind": "AUTOMATIC",
"label": "abc123"
}
OrderDiscountLineInput
Fields
| Input Field | Description |
|---|---|
amount - Float
|
Discount amount of this line in the order currency. |
code - String
|
The coupon/promo code the buyer entered, if any. |
kind - OrderDiscountKindEnum
|
How the platform applied this discount; map unknown kinds to OTHER. |
label - String
|
The platform's display label for this discount line. |
Example
{
"amount": 987.65,
"code": "xyz789",
"kind": "AUTOMATIC",
"label": "abc123"
}
OrderFeeKindEnum
Values
| Enum Value | Description |
|---|---|
|
|
Store-charged COD surcharge |
|
|
Gift wrapping |
|
|
Statutory levy (e.g. recycling, plastic bag) |
|
|
Anything else |
|
|
Buyer tip |
Example
"COD_FEE"
OrderFeeLine
Description
One store-charged fee line (signed — platforms allow negative pseudo-discount fees).
Fields
| Field Name | Description |
|---|---|
amount - Float
|
Fee amount in the order currency (signed). |
kind - OrderFeeKindEnum
|
Best-effort fee classification; raw label always kept. |
label - String
|
The platform's display label for this fee line. |
Example
{
"amount": 123.45,
"kind": "COD_FEE",
"label": "xyz789"
}
OrderFeeLineInput
Fields
| Input Field | Description |
|---|---|
amount - Float
|
Fee amount in the order currency (signed). |
kind - OrderFeeKindEnum
|
Best-effort fee classification; map unknown kinds to OTHER. |
label - String
|
The platform's display label for this fee line. |
Example
{
"amount": 987.65,
"kind": "COD_FEE",
"label": "xyz789"
}
OrderPayment
Description
One tender already applied against the order. Tenders are NOT discounts: they reduce what remains to be paid without reducing what the order was worth.
Fields
| Field Name | Description |
|---|---|
amount - Float
|
Amount of this tender in the order currency. |
capturedAt - DateTime
|
When the platform captured this tender, if it says. |
deductedFromGrandTotal - Boolean
|
Whether the platform ALREADY subtracted this tender from the grandTotal it sent. Observed, never inferred: false on Shopify (a gift card is a transaction, the total stays gross), true on Magento and WooCommerce (gift-card plugins reduce the total in place). Omit it rather than guessing — the totals identity abstains and records an anomaly, where a wrong value fails a valid order or admits a wrong one. |
kind - OrderPaymentKindEnum
|
Tender type. |
label - String
|
The platform's display label for this tender. |
reference - String
|
The platform's own id for the tender (gift-card code, transaction id). |
status - OrderPaymentStatusEnum
|
Lifecycle state; only CAPTURED money has moved. |
Example
{
"amount": 123.45,
"capturedAt": "2007-12-03T10:15:30Z",
"deductedFromGrandTotal": true,
"kind": "BANK_TRANSFER",
"label": "xyz789",
"reference": "abc123",
"status": "AUTHORIZED"
}
OrderPaymentInput
Description
A tender already applied against the order. Send gift cards, store credit, deposits and captures here — NEVER as a discountLine, which would inflate discount reporting and deflate revenue.
Fields
| Input Field | Description |
|---|---|
amount - Float
|
Amount of this tender in the order currency. |
capturedAt - DateTime
|
When it was captured. |
deductedFromGrandTotal - Boolean
|
Whether the platform ALREADY subtracted this tender from the grandTotal it sent. Observed, never inferred: false on Shopify (a gift card is a transaction, the total stays gross), true on Magento and WooCommerce (gift-card plugins reduce the total in place). Omit it rather than guessing — the totals identity abstains and records an anomaly, where a wrong value fails a valid order or admits a wrong one. |
kind - OrderPaymentKindEnum
|
Tender type. |
label - String
|
Display label. |
reference - String
|
Platform id for the tender. |
status - OrderPaymentStatusEnum
|
Lifecycle state. Defaults to CAPTURED when omitted, so send it explicitly for anything not yet taken. |
Example
{
"amount": 123.45,
"capturedAt": "2007-12-03T10:15:30Z",
"deductedFromGrandTotal": false,
"kind": "BANK_TRANSFER",
"label": "abc123",
"reference": "xyz789",
"status": "AUTHORIZED"
}
OrderPaymentKindEnum
Description
Tender type. Enum-frozen: an unrecognised instrument is OTHER with its raw label, because widening this list later is a migration.
Values
| Enum Value | Description |
|---|---|
|
|
Bank transfer |
|
|
Card payment |
|
|
Cash taken in person |
|
|
Cash on delivery |
|
|
Part payment taken up front |
|
|
Gift card redemption |
|
|
Anything the plugin cannot classify |
|
|
Store credit / customer balance |
|
|
Prepaid voucher |
|
|
Wallet (PayPal balance, Apple Pay, ...) |
Example
"BANK_TRANSFER"
OrderPaymentStatusEnum
Description
Only CAPTURED money has actually moved; the rest is intent and must not reduce a collectible.
Values
| Enum Value | Description |
|---|---|
|
|
Held but not taken |
|
|
Taken — the money moved |
|
|
Attempted and refused |
|
|
Awaiting settlement |
Example
"AUTHORIZED"
OrderTaxLine
Description
One line of the platform's tax breakdown (metadata only).
Example
{
"amount": 123.45,
"label": "xyz789",
"ratePercent": 123.45
}
OrderTaxLineInput
OtherDocument
Fields
| Field Name | Description |
|---|---|
documentType - OtherDocumentTypeEnum
|
Type of the document. |
encodedDocument - String
|
Base64 encoded document content. |
externalId - String
|
External identifier for the document. |
Example
{
"documentType": "COMMERCIAL_INVOICE",
"encodedDocument": "abc123",
"externalId": "xyz789"
}
OtherDocumentTypeEnum
Values
| Enum Value | Description |
|---|---|
|
|
|
|
|
|
|
|
Example
"COMMERCIAL_INVOICE"
PageCustomization
Fields
| Field Name | Description |
|---|---|
colorScheme - ColorScheme
|
Example
{"colorScheme": ColorScheme}
Parcel
Fields
| Field Name | Description |
|---|---|
_id - ObjectID
|
Unique identifier for this parcel within the shipment, automatically generated |
billableWeight - Float
|
Parcel's billable weight in kilograms. (The weight used for the price calculation. The greater of actual weight or volumetric weight) |
contents - [ParcelContents]
|
Products contained in this parcel with their quantities, enabling proper distribution across multiple parcels |
dimensions - ParcelDimensions
|
|
returnVoucher - ParcelVoucher
|
This parcel's carrier-issued RETURN voucher (reverse-logistics label + tracking number). Independent lifecycle from voucher — issued, canceled, and expires independently. Null until a return voucher has been created for this parcel. |
volumetricWeight - Float
|
Parcel's volumetric weight in kilograms. The overall size of a parcel measured in volumetric kilograms. |
voucher - ParcelVoucher
|
This parcel's carrier-issued FORWARD voucher (tracking number + label + references). Null until createVoucher runs successfully for this parcel. The reverse-logistics counterpart lives on returnVoucher. |
weight - Float
|
Parcel's weight in kilograms. |
Example
{
"_id": "5e5677d71bdc2ae76344968c",
"billableWeight": 123.45,
"contents": [ParcelContents],
"dimensions": ParcelDimensions,
"returnVoucher": ParcelVoucher,
"volumetricWeight": 987.65,
"voucher": ParcelVoucher,
"weight": 123.45
}
ParcelContents
ParcelContentsInput
ParcelDimensions
ParcelIdentityModeEnum
Values
| Enum Value | Description |
|---|---|
|
|
Carrier has no concept of per-piece identity — a single voucher covers the entire shipment regardless of parcel count. |
|
|
Carrier returns a stable per-piece identifier with each voucher. Round-trip via parcelVoucher.deliveryCompanyPieceId. |
|
|
No per-piece identifier; pieces are matched by request/response array position. Adapters MUST preserve order. |
Example
"NONE"
ParcelInput
Fields
| Input Field | Description |
|---|---|
contents - [ParcelContentsInput]
|
Products contained in this parcel (optional, defaults to all products in first parcel if not specified) |
height - Float
|
Parcel height in centimeters (optional) |
length - Float
|
Parcel length in centimeters (optional) |
weight - Float!
|
Parcel weight in kilograms (required) |
width - Float
|
Parcel width in centimeters (optional) |
Example
{
"contents": [ParcelContentsInput],
"height": 123.45,
"length": 987.65,
"weight": 987.65,
"width": 123.45
}
ParcelVoucher
Description
Voucher / tracking number for a single parcel in a multi-piece shipment. Replaces the parcel's slot in the legacy flat Shipment.vouchers[] array.
Fields
| Field Name | Description |
|---|---|
code - String!
|
Carrier-assigned tracking number / voucher code. |
createdAt - DateTime!
|
|
deliveryCompanyPieceId - String
|
Carrier-internal piece key (e.g. FedEx packageSequenceNumber). Lets carrier callbacks map back to the right parcel without relying on positional ordering. |
deliveryCompanyReference - String!
|
Our reference for this parcel ({INTERNAL_SHORT}-{NN}) stamped in the carrier's primary reference slot and printed on the label. |
label - ParcelVoucherLabel
|
|
merchantReference - String
|
Optional secondary reference (sanitized merchant orderId) stamped in the carrier's second reference slot. |
status - VoucherStatusEnum!
|
Example
{
"code": "abc123",
"createdAt": "2007-12-03T10:15:30Z",
"deliveryCompanyPieceId": "xyz789",
"deliveryCompanyReference": "abc123",
"label": ParcelVoucherLabel,
"merchantReference": "xyz789",
"status": "ACTIVE"
}
ParcelVoucherLabel
Description
Carrier-issued shipping label for a single parcel, stored alongside the parcel's voucher.
Fields
| Field Name | Description |
|---|---|
dimensions - LabelDimensions
|
Real label dimensions in PDF points; absent for legacy labels created before cropping was introduced. |
encodedDocument - String!
|
Base64-encoded label PDF. |
Example
{
"dimensions": LabelDimensions,
"encodedDocument": "xyz789"
}
PickupAddress
Example
{
"address": "abc123",
"addressBookEntry": "5e5677d71bdc2ae76344968c",
"city": "abc123",
"country": "abc123",
"countryCode": "abc123",
"name": "abc123",
"postcode": "xyz789"
}
PickupListsList
Fields
| Field Name | Description |
|---|---|
closeTime - String
|
The time "HH:MM" representing the latest time for pickup |
code - String
|
Pickup list number |
deliveryCompany - DeliveryCompany
|
Delivery company for this pickup list |
printDocument - String
|
Pickup list document content or URL |
readyTime - String
|
The time "HH:MM" when the shipment(s) are ready for pickup |
Example
{
"closeTime": "xyz789",
"code": "abc123",
"deliveryCompany": DeliveryCompany,
"printDocument": "abc123",
"readyTime": "abc123"
}
PickupTimeInput
Fields
| Input Field | Description |
|---|---|
closeTime - String
|
The latest time "HH:MM" that the shipment(s) can be picked up |
deliveryCompany - DeliveryCompanyIDOrSlugInput!
|
Delivery company to generate pickup list for (by ID or slug) |
readyTime - String
|
The time "HH:MM" when the shipment(s) are ready for pickup |
Example
{
"closeTime": "abc123",
"deliveryCompany": DeliveryCompanyIDOrSlugInput,
"readyTime": "xyz789"
}
PickupTimeModeEnum
Values
| Enum Value | Description |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
Example
"FIXED"
PickupTimeOptions
Fields
| Field Name | Description |
|---|---|
closeOptions - [String]
|
|
fixedOptions - [String]
|
|
mode - PickupTimeModeEnum!
|
|
readyOptions - [String]
|
Example
{
"closeOptions": ["xyz789"],
"fixedOptions": ["xyz789"],
"mode": "FIXED",
"readyOptions": ["xyz789"]
}
Platform
Values
| Enum Value | Description |
|---|---|
|
|
Example
"WOOCOMMERCE"
PricingComponent
Description
A single pricing component like a surcharge, tax, or fee
Fields
| Field Name | Description |
|---|---|
amount - Float
|
Amount of the pricing component |
category - PricingComponentCategory
|
Category of the pricing component |
code - String
|
Carrier-specific code for this component, if available |
description - String
|
Description of the pricing component |
name - String
|
Human-readable name of the pricing component |
surchargeType - SurchargeType
|
Type of surcharge, applicable when category is SURCHARGE |
Example
{
"amount": 987.65,
"category": "BASE",
"code": "xyz789",
"description": "abc123",
"name": "xyz789",
"surchargeType": "ADDITIONAL_HANDLING"
}
PricingComponentCategory
Description
Categories of pricing components
Values
| Enum Value | Description |
|---|---|
|
|
Base shipping charge |
|
|
Import/export duties |
|
|
Processing or service fees |
|
|
Other fees/charges that don't fit other categories |
|
|
Additional charges applied to shipment |
|
|
Government taxes (VAT, sales tax, etc.) |
Example
"BASE"
PricingComponentInput
Description
Input for defining a pricing component in the complete rate structure
Fields
| Input Field | Description |
|---|---|
amount - Float
|
Amount of the pricing component |
category - PricingComponentCategory
|
Category of the pricing component |
code - String
|
Carrier-specific code for this component (optional) |
description - String
|
Description of the pricing component |
name - String
|
Human-readable name of the pricing component |
surchargeType - SurchargeType
|
Type of surcharge, applicable when category is SURCHARGE |
Example
{
"amount": 123.45,
"category": "BASE",
"code": "abc123",
"description": "abc123",
"name": "abc123",
"surchargeType": "ADDITIONAL_HANDLING"
}
PrintVoucherPayload
Fields
| Field Name | Description |
|---|---|
document - String!
|
Base64-encoded PDF containing every active label for the shipment, merged into a single document according to the carrier's configured outputMedium and stickerLayout. |
Example
{"document": "abc123"}
Product
Description
A line on a shipment, as sold to the buyer.
Fields
| Field Name | Description |
|---|---|
_id - ObjectID
|
Server-generated identifier for this line within the shipment. |
categories - [String]
|
The categories this line's product belongs to, as the source platform names them. A list because products are in several: WooCommerce and Magento assign many, and Shopify has one category but many collections. Free-form strings rather than an enum — the vocabulary is the merchant's, so no fixed set can hold it. Carrier rules that exclude categories match on these; the rule fires if ANY of them is excluded. |
countryOfOrigin - String
|
The country the product was manufactured in. |
description - String
|
A brief description of the product. |
dimensions - ProductDimensions
|
The dimensions of the product. |
externalId - String
|
The product's identifier in the source platform. |
extraAttributes - [ProductExtraAttributesEnumType]
|
Handling attributes that apply to this line. |
harmonizedSystemCode - String
|
The Harmonized System code used to classify the product for customs. |
image - String
|
Full URL to the product's image. |
kind - ProductKind
|
What the buyer receives on this line. Reporting only, and never used to decide whether the line is shipped. Absent means unclassified, which is distinct from OTHER. |
lineDiscount - Float
|
Discount the platform allocated to this line (coupon/cart/automatic), verbatim (WooCommerce line subtotal − total, Shopify discount_allocations). |
lineSubtotal - Float
|
This line as sold before coupon/cart discounts (unit price × quantity at the sold price), verbatim from the platform. |
lineTotal - Float
|
What the buyer pays for this line after discounts, verbatim from the platform. |
metadata - String
|
Additional platform data, JSON-encoded. |
price - Float!
|
Unit price as sold, BEFORE coupon/cart discounts, on the eshop's own order price basis (VAT-inclusive for a VAT-inclusive eshop). price x quantity must equal lineSubtotal where that is sent. Load-bearing beyond display: it drives the free-shipping catalog threshold, and on a shipment carrying no orderAmounts it is what the COD collectible is derived from — so a post-discount value here silently under-collects, and a pre-discount one over-collects once a buyer used a coupon. |
quantity - Int!
|
Number of units on this line. |
requiresShipping - Boolean
|
Whether this line is physically shipped to the buyer. Determines the parcel contents, billable weight, carrier rates, delivery charge and customs declaration. Set it per line rather than per product, since a product can sell as digital or physical depending on the variation chosen. Omitting it treats the line as shipped. |
size - ProductSizeEnumType
|
The size of the product. Not required if the shipment's dimensions and weight are provided. No longer used. Resolve the size to parcels.dimensions instead.
|
sku - String
|
Stock keeping unit identifying the product. |
title - String
|
Name of the product. |
weight - Float
|
Weight of a single unit in kilograms. |
Example
{
"_id": "5e5677d71bdc2ae76344968c",
"categories": ["xyz789"],
"countryOfOrigin": "abc123",
"description": "xyz789",
"dimensions": ProductDimensions,
"externalId": "abc123",
"extraAttributes": ["GIFT"],
"harmonizedSystemCode": "abc123",
"image": "abc123",
"kind": "DIGITAL_GOOD",
"lineDiscount": 987.65,
"lineSubtotal": 123.45,
"lineTotal": 123.45,
"metadata": "xyz789",
"price": 987.65,
"quantity": 123,
"requiresShipping": true,
"size": "L",
"sku": "abc123",
"title": "abc123",
"weight": 987.65
}
ProductDimensions
ProductDimensionsInput
ProductExtraAttributesEnumType
Description
Handling attributes that affect how a product is shipped.
Values
| Enum Value | Description |
|---|---|
|
|
Sent as a gift. |
Example
"GIFT"
ProductInput
Description
A line to record on a shipment.
Fields
| Input Field | Description |
|---|---|
categories - [String]
|
The categories this line's product belongs to, as the source platform names them. A list because products are in several: WooCommerce and Magento assign many, and Shopify has one category but many collections. Free-form strings rather than an enum — the vocabulary is the merchant's, so no fixed set can hold it. Carrier rules that exclude categories match on these; the rule fires if ANY of them is excluded. |
countryOfOrigin - String
|
The country the product was manufactured in. |
description - String
|
A brief description of the product. |
dimensions - ProductDimensionsInput
|
The dimensions of the product. |
externalId - String
|
The product's identifier in the source platform. |
extraAttributes - [ProductExtraAttributesEnumType]
|
Handling attributes that apply to this line. |
harmonizedSystemCode - String
|
The Harmonized System code used to classify the product for customs. |
image - String
|
Full URL to the product's image. |
kind - ProductKind
|
What the buyer receives on this line. Reporting only, and never used to decide whether the line is shipped. Absent means unclassified, which is distinct from OTHER. |
lineDiscount - Float
|
Discount the platform allocated to this line (coupon/cart/automatic), verbatim (WooCommerce line subtotal − total, Shopify discount_allocations). |
lineSubtotal - Float
|
This line as sold before coupon/cart discounts (unit price × quantity at the sold price), verbatim from the platform. |
lineTotal - Float
|
What the buyer pays for this line after discounts, verbatim from the platform. |
metadata - String
|
Additional platform data, JSON-encoded. |
price - Float!
|
Unit price as sold, BEFORE coupon/cart discounts, on the eshop's own order price basis (VAT-inclusive for a VAT-inclusive eshop). price x quantity must equal lineSubtotal where that is sent. Load-bearing beyond display: it drives the free-shipping catalog threshold, and on a shipment carrying no orderAmounts it is what the COD collectible is derived from — so a post-discount value here silently under-collects, and a pre-discount one over-collects once a buyer used a coupon. |
quantity - Int!
|
Number of units on this line. |
requiresShipping - Boolean
|
Whether this line is physically shipped to the buyer. Determines the parcel contents, billable weight, carrier rates, delivery charge and customs declaration. Set it per line rather than per product, since a product can sell as digital or physical depending on the variation chosen. Omitting it treats the line as shipped. |
sku - String
|
Stock keeping unit identifying the product. |
title - String
|
Name of the product. |
weight - Float
|
Weight of a single unit in kilograms. |
_id - ObjectID
|
Echo back the line's _id from a previous read to keep it the SAME line. products is replaced as a whole array, so a line sent without one is a new line and is given a new id — which strands any parcel manifest that referenced the old one. Omit it only for a line that is genuinely new. |
Example
{
"categories": ["abc123"],
"countryOfOrigin": "abc123",
"description": "abc123",
"dimensions": ProductDimensionsInput,
"externalId": "abc123",
"extraAttributes": ["GIFT"],
"harmonizedSystemCode": "abc123",
"image": "xyz789",
"kind": "DIGITAL_GOOD",
"lineDiscount": 987.65,
"lineSubtotal": 987.65,
"lineTotal": 123.45,
"metadata": "xyz789",
"price": 987.65,
"quantity": 123,
"requiresShipping": true,
"sku": "xyz789",
"title": "xyz789",
"weight": 123.45,
"_id": "5e5677d71bdc2ae76344968c"
}
ProductKind
Description
What the buyer receives on an order line. Reporting only: whether a line is shipped is determined by requiresShipping, never by this field. Omit it when the source platform cannot distinguish one kind from another.
Values
| Enum Value | Description |
|---|---|
|
|
Delivered electronically, such as a download, licence key or access grant. A downloadable file is not required. |
|
|
Stored value, either physical or digital. Read requiresShipping to tell which. |
|
|
A kind outside this list. Distinct from omitting the field, which means unclassified. |
|
|
A tangible item delivered to the buyer. |
|
|
Work performed for the buyer, such as a booking or consultation. |
Example
"DIGITAL_GOOD"
ProductSizeEnumType
Description
A rough size band, used to estimate a parcel when a product has no measurements of its own.
Values
| Enum Value | Description |
|---|---|
|
|
Large. |
|
|
Medium. |
|
|
Small. |
|
|
Extra large. |
|
|
Extra small. |
|
|
Double extra large. |
Example
"L"
QuoteBasis
Description
Read-only snapshot of the physical inputs (parcels, destination) the selected rate was priced for. Server-written; compared against the live shipment to detect it changed out from under its rate.
Fields
| Field Name | Description |
|---|---|
destination - QuoteBasisDestination
|
|
parcelCount - Int
|
|
parcels - [QuoteBasisParcel]
|
|
quotedAt - DateTime
|
When the basis was captured (rate quote/selection time) |
Example
{
"destination": QuoteBasisDestination,
"parcelCount": 987,
"parcels": [QuoteBasisParcel],
"quotedAt": "2007-12-03T10:15:30Z"
}
QuoteBasisDestination
QuoteBasisDimensions
QuoteBasisParcel
Description
Per-parcel physical basis a rate was priced for
Fields
| Field Name | Description |
|---|---|
billableWeight - Float
|
Billable weight priced (kg) |
dimensions - QuoteBasisDimensions
|
|
volumetricWeight - Float
|
Volumetric weight priced (kg) |
weight - Float
|
Actual weight priced (kg) |
Example
{
"billableWeight": 123.45,
"dimensions": QuoteBasisDimensions,
"volumetricWeight": 987.65,
"weight": 987.65
}
RateSortingEnum
Values
| Enum Value | Description |
|---|---|
|
|
Lowest transit time first; carriers without transit-time data are listed last |
|
|
Cheapest first |
|
|
Most expensive first |
Example
"FASTEST"
Recipient
RecipientAddressCreateInput
Description
Input type for recipient address used for shipment creation.
Fields
| Input Field | Description |
|---|---|
addressLine1 - String
|
Address line 1. |
addressLine2 - String
|
Address line 2. |
addressLine3 - String
|
Address line 3. |
city - String!
|
City. |
country - String!
|
Country. |
countryCode - String
|
Country code in ISO 3166-1 alpha-2 format. |
county - String
|
County. |
postcode - String
|
Postcode. |
Example
{
"addressLine1": "abc123",
"addressLine2": "xyz789",
"addressLine3": "xyz789",
"city": "xyz789",
"country": "xyz789",
"countryCode": "xyz789",
"county": "xyz789",
"postcode": "xyz789"
}
RecipientContactCreateInput
Description
Input type for recipient contact used for shipment creation.
Fields
| Input Field | Description |
|---|---|
companyName - String
|
Company name. Either company name OR first and last name is required. |
email - String
|
Email address. |
firstname - String
|
First name. Either first and last name OR company name is required. |
lastname - String
|
Last name. Either first and last name OR company name is required. |
phone - String
|
Phone number. |
Example
{
"companyName": "abc123",
"email": "abc123",
"firstname": "abc123",
"lastname": "abc123",
"phone": "xyz789"
}
RecipientCreateInput
Description
Input type for recipient details used for shipment creation.
Fields
| Input Field | Description |
|---|---|
address - RecipientAddressCreateInput!
|
Recipient address. |
contact - RecipientContactCreateInput!
|
Recipient contact. |
Example
{
"address": RecipientAddressCreateInput,
"contact": RecipientContactCreateInput
}
RecipientLogistics
Description
Customer-provided logistics company details when using recipient-logistics delivery option.
Example
{
"companyName": "xyz789",
"email": "abc123",
"phone": "xyz789"
}
RecipientLogisticsInput
Description
Input for customer-provided logistics company details when using recipient-logistics.
Example
{
"companyName": "abc123",
"email": "xyz789",
"phone": "abc123"
}
Rule
Fields
| Field Name | Description |
|---|---|
exclusions - RuleExclusions
|
Optional product exclusion criteria. Products matching any criterion are skipped during rule evaluation. |
type - String
|
|
value - Float
|
Example
{
"exclusions": RuleExclusions,
"type": "xyz789",
"value": 123.45
}
RuleExclusions
Example
{
"categories": ["xyz789"],
"extraAttributes": ["abc123"],
"skus": ["abc123"]
}
SelectedRate
Description
The selected service and rate for a shipment
Fields
| Field Name | Description |
|---|---|
costs - Costs
|
Cost breakdown for the selected service (may include client-specific overrides) |
deliveryCompany - DeliveryCompany
|
Selected delivery company. Null for external/pickup rates. |
fulfillmentType - FulfillmentType
|
How this rate is fulfilled (carrier|external|pickup). Defaults to carrier for legacy rates. |
negotiatedCosts - Costs
|
Original costs based on carrier negotiated rates (before any client-specific overrides). Used for invoice reconciliation to compare against carrier invoices. Absent when no carrier agreement is known (plugin-provided rates, unconfirmed carriers, legacy shipments) — this field never falls back to costs. |
priceComponents - [PricingComponent]
|
The producer’s own itemisation for the selected service, stage-mixed by construction: file-based rates carry pre-multiplier net legs beside a final-gross VAT line, while API carriers carry the carrier’s figures rather than the buyer’s. It does NOT sum to finalPrice and is not a decomposition of it — the multiplier, the minimum-price floor and the rounding increment all land afterwards and appear in no component. Read one component; never reconcile the sum. |
quoteBasis - QuoteBasis
|
Physical inputs (parcels/destination) this rate was priced for. Server-written; absent for legacy/non-carrier rates. |
rating - Float
|
Rating of the selected service |
serviceCode - String
|
Selected service code |
serviceName - String
|
Selected service name |
transitTime - TransitTime
|
Delivery time information |
Example
{
"costs": Costs,
"deliveryCompany": DeliveryCompany,
"fulfillmentType": "CARRIER",
"negotiatedCosts": Costs,
"priceComponents": [PricingComponent],
"quoteBasis": QuoteBasis,
"rating": 987.65,
"serviceCode": "abc123",
"serviceName": "abc123",
"transitTime": TransitTime
}
SelectedRateInput
Description
Input for selecting a shipping rate. Can reference available rates (by serviceCode) or provide complete rate data directly
Fields
| Input Field | Description |
|---|---|
costs - CostsInput
|
Optional cost breakdown. If not provided, will be fetched from available rates based on serviceCode |
deliveryCompany - DeliveryCompanyIDOrSlugInput
|
The carrier providing the service (by ID or slug). Required when fulfillmentType is carrier (the default); omit for external/pickup. |
fulfillmentType - FulfillmentType
|
How this rate is fulfilled. Defaults to carrier when omitted. Use external for an unmappable courier or pickup for collect-from-store; both omit deliveryCompany. |
priceComponents - [PricingComponentInput]
|
Optional detailed breakdown of price components. If not provided, will be fetched from available rates based on serviceCode. Stored as provenance only: the server never sums these to derive or check costs.finalPrice, so a set that does not add up to the price is recorded, not rejected. |
serviceCode - String
|
The specific service code to select from the available rates. Required for carrier rates; for external/pickup use serviceName for the display label. |
serviceId - String
|
Exact-reference selection: the Service.id of the quote to select from this shipment's rates (must belong to the named carrier). When it resolves, the server-held quote is used verbatim and any client-sent costs are ignored; when absent or unresolvable, selection falls back to serviceCode. |
serviceName - String
|
Optional service name. If not provided, will use serviceCode or fetch from available rates |
transitTime - TransitTimeInput
|
Optional delivery time information. If not provided, will be fetched from available rates based on serviceCode |
Example
{
"costs": CostsInput,
"deliveryCompany": DeliveryCompanyIDOrSlugInput,
"fulfillmentType": "CARRIER",
"priceComponents": [PricingComponentInput],
"serviceCode": "xyz789",
"serviceId": "abc123",
"serviceName": "xyz789",
"transitTime": TransitTimeInput
}
Service
Description
A carrier service option with pricing details
Fields
| Field Name | Description |
|---|---|
costs - Costs
|
Cost breakdown for this service |
id - String
|
Stable identifier of this rate object within its shipment. Send it back as selectedRate.serviceId to select this exact quote. |
priceComponents - [PricingComponent]
|
The producer’s own itemisation, stage-mixed by construction: file-based rates carry pre-multiplier net legs beside a final-gross VAT line, while API carriers carry the carrier’s figures rather than the buyer’s. It does NOT sum to finalPrice and is not a decomposition of it — the multiplier, the minimum-price floor and the rounding increment all land afterwards and appear in no component. Read one component; never reconcile the sum. |
serviceCode - String
|
Carrier-specific service code (e.g. FEDEX_GROUND, UPS_NEXT_DAY_AIR) |
serviceName - String
|
Human-readable service name |
transitTime - TransitTime
|
Delivery time information |
Example
{
"costs": Costs,
"id": "xyz789",
"priceComponents": [PricingComponent],
"serviceCode": "xyz789",
"serviceName": "xyz789",
"transitTime": TransitTime
}
Shipment
Fields
| Field Name | Description |
|---|---|
_id - ObjectID
|
Shipment's id. |
auditLog - [ShipmentAuditEntry!]
|
Append-only activity log of everything done to this shipment after it left "new" status, newest first. |
availableRates - [DeliveryRate]
|
Available delivery rates from all carriers with their services |
buyerNotes - String
|
Buyer's notes. |
checkout - ShipmentCheckout
|
How and where the customer placed the order (checkout flow, express flag, entry-point page). Set by the storefront plugin at order creation; null for manually-created or pre-tracking shipments. |
checkoutCompletedAt - DateTime
|
The date and time when the shipment completed checkout. Null for manually-created shipments. |
codCollectible - CodCollectible!
|
What the courier would collect at the door if the label were minted now, with the provenance of that figure. Null is impossible — an unresolvable collectible reports UNRESOLVABLE rather than 0. Once a label exists, codDeclaration is what it actually says. |
codDeclaration - CodDeclaration
|
What the carrier was told to collect, frozen at label creation and cleared on cancellation. Compare against codCollectible to detect an order edited after its label was printed — the courier will still ask for this amount. |
costSummary - CostSummary
|
Pircel's own catalog+quote view of the order. See CostSummary — it is not the buyer's money. |
createdAt - DateTime
|
The date and time when the shipment was created. |
documentUpload - DocumentUploadEligibility!
|
Whether this shipment can take a document upload, and why not when it cannot. Answered by the same predicate the upload endpoint uses, so a rendered control and an accepted upload cannot disagree. reason is the error code the endpoint would return. |
effectiveDate - DateTime
|
The shipment date used for sorting/filtering: checkoutCompletedAt, falling back to createdAt for shipments that never completed checkout. Derived field — safe for client-side sorting. |
eshop - Eshop
|
Reference to the eshop that created this shipment. |
freeShipping - ShipmentFreeShipping
|
Free shipping tracking information when a free shipping promotion was applied to this shipment |
geniki - GenikiFields
|
Geniki delivery company specific fields |
isB2BInvoice - Boolean
|
Indicates if the shipment is for a B2B invoice (true) or B2C invoice (false). False by default. |
notificationsSent - [NotificationSent]
|
Array tracking which email notifications have been sent for this shipment. |
orderAmounts - OrderAmounts
|
The order totals as the seller stated them, ingested verbatim. Absent on shipments created before the amounts-first contract, and on any order whose originator sent none. |
orderId - String
|
The unique order id |
otherDocuments - [OtherDocument]
|
Additional documents related to the shipment, like invoices. |
parcels - [Parcel]
|
List of parcels in this shipment, each with their own dimensions, weights, and product distribution. |
paymentMethod - ShipmentPaymentMethodEnum
|
Customer's payment method. |
pickupAddress - PickupAddress
|
The address where the package should be picked up from. |
pickupDate - Date
|
Date "YYYY-MM-DD" that the delivery company should receive the package from the shop. Defaults to today |
products - [Product]
|
List of products in the shipment. |
productsQuantity - Int
|
Products quantity. |
recipient - Recipient!
|
Recipient details including address and contact information. |
recipientLogistics - RecipientLogistics
|
Customer-provided logistics company details when using recipient-logistics delivery option. |
requiresShipping - Boolean
|
Whether any part of this order is shipped. Resolved by the server from the order lines, or from the value the integration supplied. When false, no rates were requested and costSummary.deliveryCost is zero. |
returnShipmentVoucher - ShipmentVoucher
|
Shipment-level RETURN voucher (master tracking number for the reverse-logistics shipment) for carriers that issue one. Independent lifecycle from shipmentVoucher. |
selectedRate - SelectedRate
|
The selected service and rate for this shipment |
senderNotes - String
|
Sender's notes. |
shipmentPurpose - ShipmentPurposeEnum
|
The purpose of the shipment. |
shipmentVoucher - ShipmentVoucher
|
Shipment-level FORWARD voucher (master tracking number) for carriers that issue one. Null for carriers that only return per-piece vouchers. Use this as the canonical handle for shipment-level operations (tracking polling, pickup creation, cascade cancellation). The reverse-logistics counterpart lives on returnShipmentVoucher. |
shipper - Shipper
|
Shipper details including address and contact information. |
shippingRegionType - ShippingRegionTypeEnum
|
The type of shipping region. |
status - ShipmentStatusEnum
|
Transction's status. |
trackingDetails - TrackingDetails
|
Tracking details for the shipment. |
unassociatedVouchers - [UnassociatedVoucher!]
|
Vouchers returned by the carrier that the adapter could not confidently associate with a specific parcel. Should be empty for healthy shipments; a non-empty list indicates an adapter mapping problem worth auditing. |
unavailableRates - [DeliveryRate]
|
Carriers that could not price this destination (errored or returned no service). Kept separate from availableRates so clients never treat them as selectable or as a €0 option. |
vatDetails - VatDetails
|
VAT preferences and information for this shipment. |
Example
{
"_id": "5e5677d71bdc2ae76344968c",
"auditLog": [ShipmentAuditEntry],
"availableRates": [DeliveryRate],
"buyerNotes": "abc123",
"checkout": ShipmentCheckout,
"checkoutCompletedAt": "2007-12-03T10:15:30Z",
"codCollectible": CodCollectible,
"codDeclaration": CodDeclaration,
"costSummary": CostSummary,
"createdAt": "2007-12-03T10:15:30Z",
"documentUpload": DocumentUploadEligibility,
"effectiveDate": "2007-12-03T10:15:30Z",
"eshop": Eshop,
"freeShipping": ShipmentFreeShipping,
"geniki": GenikiFields,
"isB2BInvoice": false,
"notificationsSent": [NotificationSent],
"orderAmounts": OrderAmounts,
"orderId": "xyz789",
"otherDocuments": [OtherDocument],
"parcels": [Parcel],
"paymentMethod": "AFTERPAY_CLEARPAY",
"pickupAddress": PickupAddress,
"pickupDate": "2007-12-03",
"products": [Product],
"productsQuantity": 123,
"recipient": Recipient,
"recipientLogistics": RecipientLogistics,
"requiresShipping": true,
"returnShipmentVoucher": ShipmentVoucher,
"selectedRate": SelectedRate,
"senderNotes": "abc123",
"shipmentPurpose": "GIFT",
"shipmentVoucher": ShipmentVoucher,
"shipper": Shipper,
"shippingRegionType": "DOMESTIC",
"status": "CANCELED",
"trackingDetails": TrackingDetails,
"unassociatedVouchers": [UnassociatedVoucher],
"unavailableRates": [DeliveryRate],
"vatDetails": VatDetails
}
ShipmentAuditChange
ShipmentAuditEntry
Fields
| Field Name | Description |
|---|---|
_id - ID!
|
|
actor - User
|
The user who performed the action (null for api-key / system actors) |
actorType - AuditActorTypeEnum!
|
Which kind of caller performed the action |
changes - [ShipmentAuditChange!]
|
Per-field before/after values for field-edit events (empty otherwise) |
createdAt - DateTime!
|
When the action was performed |
event - ShipmentAuditEventEnum!
|
The kind of change this entry records |
metadata - JSON
|
Free-form event context (e.g. created/canceled voucher codes) |
summary - String
|
Short human-readable description of the event |
Example
{
"_id": 4,
"actor": User,
"actorType": "ADMIN",
"changes": [ShipmentAuditChange],
"createdAt": "2007-12-03T10:15:30Z",
"event": "ADDRESS_CHANGED",
"metadata": {},
"summary": "xyz789"
}
ShipmentAuditEventEnum
Description
The kinds of events recorded in a shipment audit log entry. Field-edit events carry changes; the rest carry metadata.
Values
| Enum Value | Description |
|---|---|
|
|
The recipient shipping country changed during checkout (see changes) |
|
|
The shipment was finalized at checkout (carrier, service and delivery cost in metadata) |
|
|
The products/parcels of an order-bound shipment changed (see changes) — surfaced because a bound order should not have its contents mutated |
|
|
A manual cost override was applied or changed |
|
|
The shipment was added to a carrier pickup list |
|
|
Individual selected-rate price components were overridden (modifyShipmentRatePricing) |
|
|
The selected delivery company / service rate changed |
|
|
The shipment was canceled |
|
|
One or more editable shipment fields changed (see changes) |
|
|
The shipment / parcel vouchers were canceled |
|
|
A voucher / label was created for the shipment |
Example
"ADDRESS_CHANGED"
ShipmentCheckout
Description
How and where the customer placed the order: checkout flow/architecture, whether it was an express (accelerated) checkout, and the page it started from. Independent of paymentMethod (how they paid) and source (customer-checkout vs merchant-created).
Fields
| Field Name | Description |
|---|---|
entryPoint - ShipmentCheckoutEntryPointEnum
|
Storefront page the order was initiated from. |
flow - ShipmentCheckoutFlowEnum
|
Storefront checkout flow / architecture the order came through. |
isExpress - Boolean
|
Whether the order used an express / accelerated one-tap wallet checkout (e.g. Apple Pay, Google Pay) that bypasses the standard form. Correlate with paymentMethod to identify the specific wallet. |
Example
{"entryPoint": "CART", "flow": "BLOCK", "isExpress": true}
ShipmentCheckoutEntryPointEnum
Description
The storefront page from which the order was initiated. Most meaningful for express checkouts, which can start outside the checkout page.
Values
| Enum Value | Description |
|---|---|
|
|
Initiated from the cart page. |
|
|
Initiated from the checkout page (the default for the standard, non-express flow). |
|
|
Initiated from the mini-cart / cart drawer. |
|
|
Initiated from a product page (e.g. an express button that skips the cart). |
Example
"CART"
ShipmentCheckoutFlowEnum
Description
The storefront checkout flow / architecture an order came through. Platform-agnostic: each platform maps its surfaces onto these buckets.
Values
| Enum Value | Description |
|---|---|
|
|
Modern native block / component checkout rendered by the platform (WooCommerce Cart & Checkout Blocks, backed by the Store API). |
|
|
Legacy server-rendered native checkout (WooCommerce [woocommerce_checkout] shortcode, Magento Luma one-page, Shopify Liquid theme checkout). |
|
|
Custom / headless frontend that creates the order programmatically through the platform commerce API (WooCommerce Store API, Shopify Storefront/Cart API, Magento PWA GraphQL). |
Example
"BLOCK"
ShipmentCheckoutInput
Description
Checkout provenance for the order: flow/architecture, express flag, and entry-point page. Set by the storefront plugin at order creation.
Fields
| Input Field | Description |
|---|---|
entryPoint - ShipmentCheckoutEntryPointEnum
|
Storefront page the order was initiated from. |
flow - ShipmentCheckoutFlowEnum
|
Storefront checkout flow / architecture the order came through. |
isExpress - Boolean
|
Whether the order used an express / accelerated one-tap wallet checkout that bypasses the standard form. |
Example
{"entryPoint": "CART", "flow": "BLOCK", "isExpress": true}
ShipmentFreeShipping
Description
Free shipping tracking information when a free shipping promotion was applied to a shipment
Fields
| Field Name | Description |
|---|---|
applied - Boolean!
|
Whether free shipping was applied to this shipment |
appliedRegionSource - AppliedRegionSourceEnum
|
Whether the applied free shipping came from a named rule or the rest-of-world fallback |
appliedRuleId - ObjectID
|
Stable reference to the matched rule subdocument; absent when the rest-of-world fallback was used |
appliedRuleName - String
|
Snapshot of the matched rule name (denormalized so historical shipments survive renames or deletions) |
checkoutDisplay - FreeShippingCheckoutDisplayEnum
|
Snapshot of the checkout display mode when free shipping was applied |
codFeeCharged - Float
|
COD fee the customer pays when free shipping is applied with cash-on-delivery payment (0 if no COD or waived) |
defaultCarrier - DeliveryCompany
|
The eshop default carrier used for free shipping, populated from the DB to reflect current carrier state |
discountAmount - Float
|
Amount discounted from the delivery cost (originalCost - codFeeCharged for full free shipping) |
originalCost - Float
|
The shipping cost that would have been charged without free shipping, used for analytics and invoicing |
reason - String
|
Human-readable explanation of why free shipping was applied |
threshold - Float
|
The free shipping threshold at the time this shipment was created |
Example
{
"applied": true,
"appliedRegionSource": "REST_OF_WORLD",
"appliedRuleId": "5e5677d71bdc2ae76344968c",
"appliedRuleName": "xyz789",
"checkoutDisplay": "ALL_CARRIERS",
"codFeeCharged": 123.45,
"defaultCarrier": DeliveryCompany,
"discountAmount": 123.45,
"originalCost": 987.65,
"reason": "xyz789",
"threshold": 123.45
}
ShipmentPaymentMethodEnum
Description
How the customer paid the eshop for the order. Only cash-on-delivery changes carrier behavior (cash is collected at delivery); every other method is prepaid. Use the isCashOnDelivery helper rather than comparing values directly.
Values
| Enum Value | Description |
|---|---|
|
|
Buy now, pay later via Afterpay (Clearpay in the EU/UK). |
|
|
Prepaid via the Amazon Pay wallet. |
|
|
Prepaid via the Apple Pay wallet. |
|
|
Prepaid via Bancontact (Belgium). |
|
|
The customer will pay for the order by bank deposit. |
|
|
The customer will pay for the order by card. |
|
|
The customer will pay for the order by cash on delivery. |
|
|
Prepaid using a gift card balance. |
|
|
Prepaid via the Google Pay wallet. |
|
|
Prepaid via iDEAL bank transfer (Netherlands). |
|
|
Card installments (e.g. δόσεις); settled as a prepaid card payment. |
|
|
Buy now, pay later via Klarna. |
|
|
The customer will not be charged for the order. |
|
|
The customer will pay for the order by PayPal. |
|
|
Prepaid via the Revolut Pay wallet. |
|
|
Prepaid via SEPA credit transfer. |
|
|
Prepaid using store credit / voucher balance. |
Example
"AFTERPAY_CLEARPAY"
ShipmentPurposeEnum
Values
| Enum Value | Description |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Example
"GIFT"
ShipmentSourceEnum
Values
| Enum Value | Description |
|---|---|
|
|
Checkout process |
|
|
Manual entry |
Example
"CHECKOUT"
ShipmentStatusEnum
Values
| Enum Value | Description |
|---|---|
|
|
When the shipment has been canceled. |
|
|
When the customer has completed the checkout process. |
|
|
When the shipment has been manually created. |
|
|
When the shipment is just created and the customer still edit the delivery form |
|
|
When nothing on the order is shipped, such as a download or a service. Terminal: no carrier was quoted and no parcel exists, so the order should be excluded from pickup lists and voucher queues while still counting towards revenue. |
|
|
When a pickup list has been created for the shipment. |
|
|
When a voucher has been canceled for the shipment. |
|
|
Step 1: The shipping label for the shipment has been created. |
|
|
Step 4 (Optional): The shipment is undergoing customs clearance. |
|
|
Step 6: The shipment has been successfully delivered. |
|
|
Exception: The delivery of the shipment has been canceled. |
|
|
Exception: An exception occurred during shipment delivery. |
|
|
Step 3: The shipment is currently in transit. |
|
|
Step 5: The shipment is out for delivery. |
|
|
Step 2: The shipment has been picked up by the delivery company. |
|
|
Exception: The shipment has been returned. |
Example
"CANCELED"
ShipmentTrackingEventStatusEnum
Values
| Enum Value | Description |
|---|---|
|
|
Step 4 (Optional): The shipment is undergoing customs clearance. |
|
|
Step 6: The shipment has been successfully delivered. |
|
|
Exception: The delivery of the shipment has been canceled. |
|
|
Exception: An exception occurred during shipment delivery. |
|
|
Step 3: The shipment is currently in transit. |
|
|
Step 5: The shipment is out for delivery. |
|
|
Step 2: The shipment has been picked up by the delivery company. |
|
|
Exception: The shipment has been returned. |
|
|
Step 1: The shipping label for the shipment has been created. |
Example
"CUSTOMS_CLEARANCE"
ShipmentVoucher
Description
Shipment-level voucher (master tracking number) for carriers that issue one. Null for carriers that only return per-piece vouchers (TCS).
Fields
| Field Name | Description |
|---|---|
code - String!
|
Carrier-assigned shipment-level identifier. May coincide with the lead parcel's tracking number for some carriers (FedEx, UPS) but is conceptually distinct. |
createdAt - DateTime!
|
|
deliveryCompanyReference - String!
|
Shipment-level reference (INTERNAL_SHORT, no piece suffix) stamped in the carrier's shipment-level reference slot. |
merchantReference - String
|
|
status - VoucherStatusEnum!
|
Example
{
"code": "abc123",
"createdAt": "2007-12-03T10:15:30Z",
"deliveryCompanyReference": "abc123",
"merchantReference": "abc123",
"status": "ACTIVE"
}
Shipper
Description
Shipper details including address and contact information.
Example
{
"address": Address,
"addressBookEntry": "5e5677d71bdc2ae76344968c",
"contact": Contact
}
ShipperInput
Description
Input type for shipper details.
Fields
| Input Field | Description |
|---|---|
address - AddressInput
|
Shipper address. |
addressBookEntryId - ObjectID
|
Reference to an address book entry from the Eshop address book. |
contact - ContactInput
|
Shipper contact. |
Example
{
"address": AddressInput,
"addressBookEntryId": "5e5677d71bdc2ae76344968c",
"contact": ContactInput
}
ShippingRegionTypeEnum
Description
Enum representing the type of shipping region.
Values
| Enum Value | Description |
|---|---|
|
|
Shipping within the same country. |
|
|
Shipping between countries in different regions. |
|
|
Shipping between African countries. |
|
|
Shipping between ASEAN member countries. |
|
|
Shipping between Asian countries. |
|
|
Shipping between European countries. |
|
|
Shipping between Middle Eastern countries. |
|
|
Shipping between non-EU European countries. |
|
|
Shipping between North American countries. |
|
|
Shipping between Oceanian countries. |
|
|
Shipping between South American countries. |
|
|
Shipping between USMCA member countries (US, Mexico, Canada). |
|
|
Other shipping region type not covered by other categories. |
Example
"DOMESTIC"
SlaTier
Values
| Enum Value | Description |
|---|---|
|
|
|
|
|
|
|
|
Example
"TIER_1"
StoreConnection
Fields
| Field Name | Description |
|---|---|
_id - ObjectID
|
|
consecutiveFailures - Int
|
Number of consecutive product-cache refresh failures. Resets to 0 on success. When the threshold is reached, status is flipped to ERROR. |
credentialTransport - CredentialTransport
|
How this store accepts its API credentials. Established when the store connects and re-learned if the store stops accepting the header. Read-only; it is a property of the merchant's web server, not a setting. |
expiresAt - DateTime
|
|
externalId - String
|
|
lastFailedAt - DateTime
|
Timestamp of the most recent failed product-cache refresh |
lastSyncedAt - DateTime
|
|
platform - Platform
|
|
pluginVersion - String
|
|
scopes - [StoreConnectionScope]
|
|
status - ConnectionStatus
|
|
storeDomain - String
|
Example
{
"_id": "5e5677d71bdc2ae76344968c",
"consecutiveFailures": 123,
"credentialTransport": "HEADER",
"expiresAt": "2007-12-03T10:15:30Z",
"externalId": "abc123",
"lastFailedAt": "2007-12-03T10:15:30Z",
"lastSyncedAt": "2007-12-03T10:15:30Z",
"platform": "WOOCOMMERCE",
"pluginVersion": "abc123",
"scopes": ["READ_COUPONS"],
"status": "ACTIVE",
"storeDomain": "xyz789"
}
StoreConnectionScope
Values
| Enum Value | Description |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Example
"READ_COUPONS"
String
Description
The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.
Example
"xyz789"
SurchargeType
Description
Types of surcharges
Values
| Enum Value | Description |
|---|---|
|
|
Additional handling surcharge |
|
|
Cash on delivery surcharge |
|
|
Delivery area surcharge |
|
|
Fuel surcharge |
|
|
Other surcharge type |
|
|
Saturday delivery surcharge |
Example
"ADDITIONAL_HANDLING"
TaxModeEnum
Description
How VAT rates are resolved for the charges Pircel prices.
Values
| Enum Value | Description |
|---|---|
|
|
The effective-dated, law-sourced rate table. Requires this profile's accountant-confirmed facts: without confirmedAt every rate resolution fails closed, so a profile switched to LAW without it cannot price at all. |
|
|
Reproduces pre-taxation-module behaviour exactly — zero price movement. The default. ⚠️ Its rate map is Cyprus 19% / Greece 24% and 0% everywhere else, so a legacy eshop charges no VAT on international shipping. |
Example
"LAW"
TaxProfile
Description
How VAT is resolved for the charges Pircel prices (shipping and the COD fee), plus the accountant-confirmed facts law mode requires. Read-only over GraphQL — there is no writer and deliberately so: confirmedAt is an attestation, not a setting, and law-mode resolution fails closed without it. Nothing here describes the eshop's own product tax; that stays with the platform.
Fields
| Field Name | Description |
|---|---|
confirmedAt - DateTime
|
When an accountant confirmed the law-mode facts on this profile. Required for LAW mode — resolution fails closed with law-mode-unconfirmed while it is absent, so LAW without this is a profile that cannot price. Enforced where rates resolve rather than on the document, because the query-level updates that write this profile never run a Mongoose cross-field validator. |
confirmedBy - String
|
Who confirmed the law-mode facts (accountant or owner reference), for the audit trail. |
establishmentCountry - String
|
ISO 3166-1 alpha-2 country the eshop is established in — its merchant of record. Drives origin-rate resolution in law mode. Defaults to GR. |
goodsRateCategory - GoodsRateCategoryEnum
|
VAT rate class of the eshop's goods; only STANDARD is supported today. |
islandEstablishment - String
|
Qualifying Greek island the eshop is established on (Ε.2113/2025 Annex), if any — it grants the reduced 17/9/4 rates on that eshop's supplies in law mode. Accountant-confirmed and never derived from an address: an eshop with an island postcode is not necessarily established there, and the reduced rate belongs to establishment. |
mode - TaxModeEnum
|
Which rate resolution applies. Defaults to LEGACY. |
ossRegistered - Boolean
|
Whether the eshop is registered for the EU One-Stop Shop. When it is, intra-EU B2C sales are taxed at the DESTINATION rate instead of the origin one. |
pricesIncludeVat - Boolean
|
The eshop's declared default for whether its order amounts include VAT — the last rung of the basis ladder, used only when an order carries no per-order tag of its own (orderAmounts.pricesIncludeTax, or the legacy includeVat). A per-shipment tag always wins. Defaults to true, which is why an untagged order from a VAT-exclusive store resolves wrongly unless this is set. |
Example
{
"confirmedAt": "2007-12-03T10:15:30Z",
"confirmedBy": "xyz789",
"establishmentCountry": "xyz789",
"goodsRateCategory": "STANDARD",
"islandEstablishment": "abc123",
"mode": "LAW",
"ossRegistered": true,
"pricesIncludeVat": false
}
TrackingDetails
Fields
| Field Name | Description |
|---|---|
carrierTrackingUrl - String
|
External tracking URL provided by the delivery company |
deliveredAt - DateTime
|
When the shipment was delivered |
deliveryCompany - DeliveryCompany
|
Reference to the delivery company |
eshopTrackingUrl - String
|
Eshop tracking URL |
estimatedDelivery - DateTime
|
Estimated delivery date |
events - [TrackingEvent]
|
List of tracking events |
isActive - Boolean
|
Whether this tracking detail is active |
lastStatus - ShipmentTrackingEventStatusEnum
|
Last tracking status |
lastSyncedAt - DateTime
|
When the tracking information was last synced with carrier |
lastUpdated - DateTime
|
When the tracking information was last updated |
nextPollAt - DateTime
|
When to next poll for tracking updates |
returnToSender - Boolean
|
Whether the shipment is being returned to sender |
slaTier - SlaTier
|
Service level agreement tier |
voucherCode - String
|
The voucher code for this tracking detail |
Example
{
"carrierTrackingUrl": "xyz789",
"deliveredAt": "2007-12-03T10:15:30Z",
"deliveryCompany": DeliveryCompany,
"eshopTrackingUrl": "abc123",
"estimatedDelivery": "2007-12-03T10:15:30Z",
"events": [TrackingEvent],
"isActive": true,
"lastStatus": "CUSTOMS_CLEARANCE",
"lastSyncedAt": "2007-12-03T10:15:30Z",
"lastUpdated": "2007-12-03T10:15:30Z",
"nextPollAt": "2007-12-03T10:15:30Z",
"returnToSender": false,
"slaTier": "TIER_1",
"voucherCode": "xyz789"
}
TrackingEvent
Fields
| Field Name | Description |
|---|---|
deliveryCompany - TrackingEventDeliveryCompany
|
Minimal carrier identity for this tracking event |
description - String
|
Human-readable description of the tracking event |
location - TrackingLocation
|
Location information for the tracking event |
status - ShipmentTrackingEventStatusEnum!
|
Status code or description for the tracking event |
timestamp - DateTime
|
When the tracking event occurred |
Example
{
"deliveryCompany": TrackingEventDeliveryCompany,
"description": "xyz789",
"location": TrackingLocation,
"status": "CUSTOMS_CLEARANCE",
"timestamp": "2007-12-03T10:15:30Z"
}
TrackingEventDeliveryCompany
Description
Minimal carrier identity attached to a public tracking event
Example
{
"_id": "4",
"logo": Logo,
"name": "abc123",
"slug": "xyz789"
}
TrackingLocation
Fields
| Field Name | Description |
|---|---|
address - TrackingLocationAddress
|
|
coordinates - TrackingLocationCoordinates
|
Example
{
"address": TrackingLocationAddress,
"coordinates": TrackingLocationCoordinates
}
TrackingLocationAddress
TrackingLocationCoordinates
TrackingResult
Fields
| Field Name | Description |
|---|---|
parcels - [Parcel!]
|
List of parcels in the shipment |
products - [Product!]
|
List of products in the shipment |
recipient - Recipient!
|
Recipient information for the shipment |
trackingDetails - TrackingDetails!
|
Tracking details for the shipment |
Example
{
"parcels": [Parcel],
"products": [Product],
"recipient": Recipient,
"trackingDetails": TrackingDetails
}
TrackingUrlInformation
Fields
| Field Name | Description |
|---|---|
baseUrl - String
|
|
exampleUrl - String
|
|
parameterName - String
|
|
supportsDeepLink - Boolean
|
|
urlType - TrackingUrlTypeEnum
|
Example
{
"baseUrl": "xyz789",
"exampleUrl": "xyz789",
"parameterName": "xyz789",
"supportsDeepLink": true,
"urlType": "PATH"
}
TrackingUrlTypeEnum
Values
| Enum Value | Description |
|---|---|
|
|
|
|
|
Example
"PATH"
TransitTime
Description
Delivery time information
Example
{
"estimatedDeliveryDate": "2007-12-03",
"guaranteed": false,
"maxDays": 987,
"minDays": 987
}
TransitTimeInput
Description
Input for delivery time information
Example
{
"estimatedDeliveryDate": "2007-12-03",
"guaranteed": false,
"maxDays": 987,
"minDays": 123
}
UnassociatedVoucher
Description
Vouchers returned by the carrier that an adapter could not map to a specific parcel. Loud-failure escape hatch; engineering should audit shipments with non-empty unassociated lists.
Fields
| Field Name | Description |
|---|---|
code - String!
|
|
rawDeliveryCompanyResponse - JSON
|
Original carrier response fragment, kept verbatim for debugging. |
reason - String
|
Why this voucher could not be associated to a parcel. |
status - VoucherStatusEnum!
|
Example
{
"code": "xyz789",
"rawDeliveryCompanyResponse": {},
"reason": "xyz789",
"status": "ACTIVE"
}
User
Fields
| Field Name | Description |
|---|---|
_id - ObjectID
|
Unique identifier for this user account |
email - String
|
User email address |
eshop - Eshop
|
Reference to the e-shop that this user belongs to or manages |
firstname - String
|
User's first name |
lastname - String
|
User's last name |
type - UserTypeEnum
|
User role type (admin, eshop, customer, deliveryCompany) |
Example
{
"_id": "5e5677d71bdc2ae76344968c",
"email": "xyz789",
"eshop": Eshop,
"firstname": "xyz789",
"lastname": "xyz789",
"type": "ADMIN"
}
UserTypeEnum
Values
| Enum Value | Description |
|---|---|
|
|
System administrator with full access to all features and e-shops |
|
|
|
|
|
Delivery company staff member with access to carrier-specific features |
|
|
E-shop owner or staff member with access to their store's shipping operations |
Example
"ADMIN"
ValidateTrackingResult
VatBasis
Description
Whether an amount includes VAT.
Values
| Enum Value | Description |
|---|---|
|
|
No VAT included. |
|
|
VAT included; vatAmount states how much. |
|
|
The rate source declared no basis. NOT a synonym for ex-vat — treat the amount as uncomparable with tagged ones rather than assuming either way. |
Example
"EX_VAT"
VatDetails
Description
VAT (Value Added Tax) information for a service
Fields
| Field Name | Description |
|---|---|
basisSource - String
|
Which signal resolved valueAddedTaxIncluded: "order-tag" (orderAmounts.pricesIncludeTax), "legacy-include-vat" (the includeVat argument), or "eshop-default". Absent on shipments predating the amounts-first contract. |
valueAddedTaxIncluded - Boolean
|
Whether VAT is included in the service prices |
vatRate - Float
|
VAT rate as a percentage (e.g., 24.0 for 24%) |
Example
{
"basisSource": "xyz789",
"valueAddedTaxIncluded": true,
"vatRate": 987.65
}
VoucherCancellationModeEnum
Values
| Enum Value | Description |
|---|---|
|
|
Canceling the shipment-level voucher cancels every parcel voucher in one carrier call (e.g. UPS void by ShipmentIdentificationNumber). |
|
|
Each parcel voucher must be canceled individually (e.g. FedEx). |
|
|
Carrier doesn't support multi-piece shipments, so there is only one voucher to cancel. |
Example
"CASCADE"
VoucherCapabilityScopeEnum
Values
| Enum Value | Description |
|---|---|
|
|
Carrier accepts customer references both at the shipment level and per parcel. |
|
|
Carrier does not accept any customer reference field. |
|
|
Carrier accepts customer references per parcel only. |
|
|
Carrier accepts customer references at the shipment level only. |
Example
"BOTH"
VoucherStatusEnum
Values
| Enum Value | Description |
|---|---|
|
|
Voucher issued by the carrier and currently valid for tracking, pickup, and printing. |
|
|
Voucher voided by user or system action (cancelVoucher mutation, cascade cancellation, re-issue replacement). Terminal. |
|
|
Voucher auto-expired in the carrier's system, typically by exceeding the carrier's printable / usable window. Terminal. |
|
|
Carrier rejected voucher creation. Terminal; a fresh voucher record must be created to retry. |
|
|
Async voucher creation in flight: carrier accepted the request but hasn't returned a tracking number yet. Most carriers respond synchronously and skip this state. |
Example
"ACTIVE"
VoucherTracking
Example
{
"checkpointAction": "abc123",
"checkpointDateTime": "2007-12-03T10:15:30Z",
"checkpointLocation": "abc123",
"checkpointNotes": "abc123",
"code": "xyz789",
"shipmentId": "5e5677d71bdc2ae76344968c"
}