Create return shipment

TypeScript

import { Configuration, ShipmentsApi } from "@zippendo/sdk"

const api = new ShipmentsApi(new Configuration({ accessToken: process.env.ZIPPENDO_API_TOKEN }))
const result = await api.createReturnShipment({ orgId: "...", shipmentId: "..." })

import os
import zippendo

config = zippendo.Configuration(access_token=os.environ["ZIPPENDO_API_TOKEN"])
with zippendo.ApiClient(config) as client:
    result = zippendo.ShipmentsApi(client).create_return_shipment("...", "...")

<?php
$config = Zippendo\Sdk\Configuration::getDefaultConfiguration()->setAccessToken(getenv("ZIPPENDO_API_TOKEN"));
$api = new Zippendo\Sdk\Api\ShipmentsApi(new GuzzleHttp\Client(), $config);
$result = $api->createReturnShipment("...", "...");

client := zippendo.NewAPIClient(zippendo.NewConfiguration())
ctx := context.WithValue(context.Background(), zippendo.ContextAccessToken, os.Getenv("ZIPPENDO_API_TOKEN"))
result, _, err := client.ShipmentsAPI.CreateReturnShipment(ctx, "...", "...").Execute()

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.zippendo.com/orgs/{orgId}/shipments/{shipmentId}/create-return', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "shp_4d9e7a2f",
  "reference": "ORDER-1042",
  "parties": [
    {
      "type": "receiver",
      "name": "Anna Jensen",
      "address1": "Vesterbrogade 12",
      "postalCode": "1620",
      "city": "København V",
      "countryCode": "DK",
      "attributes": [],
      "attention": "Reception",
      "address2": "2. sal",
      "email": "[email protected]",
      "phone": "+4520123456"
    }
  ],
  "type": "outbound",
  "carrierSettings": {
    "carrierId": "car_pn_001",
    "productId": "prod_mypack_home",
    "services": [
      "A7"
    ],
    "additionalParameters": {
      "notificationEmail": "[email protected]"
    }
  },
  "parcels": [
    {
      "weight": 2.5,
      "weightUnit": "kg",
      "dimensions": {
        "length": 30,
        "width": 20,
        "height": 15
      },
      "orderLines": [
        {
          "quantity": 2,
          "id": "ol_9c1d2e3f",
          "orderLineId": "clz9k2f0a0004abcd3456qrst",
          "sku": "SKU-1024",
          "description": "Wool sweater, navy",
          "unitPrice": 299.95,
          "currency": "DKK",
          "vatPercent": 25,
          "location": "A-12-3",
          "countryOfOrigin": "DK",
          "hsCode": "61101100",
          "tarrifNumber": "61101100"
        }
      ],
      "id": "prc_5a6b7c8d",
      "trackingNumber": "00370724710000012345",
      "trackingUrl": "https://tracking.postnord.com/00370724710000012345",
      "labelFreeCode": "AB12CD34",
      "qrCodeLink": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
      "qrCodeDataUri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
      "qrCodeUrl": "https://qr.bring.com/label-free/AB12CD34.png"
    }
  ],
  "termOfTrade": "DAP",
  "errors": [],
  "status": "pending",
  "orgId": "org_1a2b3c4d",
  "logs": [],
  "activities": [],
  "createdAt": "2026-06-22T14:30:00.000Z",
  "updatedAt": "2026-06-22T14:30:00.000Z",
  "addressId": "addr_7e8f9a0b",
  "servicePointId": "sp_pn_4521",
  "pickupDetails": {
    "date": "2026-06-22",
    "from": "08:00:00",
    "to": "16:00:00",
    "instruction": "Ring the bell at the loading dock."
  },
  "documents": [
    {
      "id": "doc_8f3a2b1c",
      "shipmentId": "shp_4d9e7a2f",
      "documentType": "label",
      "format": "pdf",
      "content": "JVBERi0xLjQKJeLjz9MKMS...",
      "size": "100X150",
      "createdAt": "2026-06-22T14:30:00.000Z",
      "updatedAt": "2026-06-22T14:30:00.000Z"
    }
  ],
  "tracking": {
    "url": "https://tracking.postnord.com/00370724710000012345",
    "number": "00370724710000012345",
    "labelFreeCode": "AB12CD34",
    "qrCodeLink": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
    "qrCodeDataUri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
    "qrCodeUrl": "https://qr.bring.com/label-free/AB12CD34.png"
  },
  "orderId": "ord_5e6f7a8b",
  "shippingRuleId": "rule_3c4d5e6f",
  "shippingRule": {
    "id": "rule_3c4d5e6f",
    "name": "Domestic standard",
    "carrierId": "car_pn_001",
    "productId": "prod_mypack_home",
    "services": [
      "A7"
    ],
    "addressId": "addr_7e8f9a0b",
    "returnShippingRuleId": "rule_return_01",
    "autoCreateReturnShipment": false,
    "autoPrintLabels": true,
    "autoPrintDocuments": false,
    "labelPrinterId": "prn_label_01",
    "documentPrinterId": "prn_doc_01"
  },
  "labelPrinterId": "prn_label_01",
  "documentPrinterId": "prn_doc_01"
}

{
  "error": "Bad Request",
  "message": "Failed to create address",
  "code": "CARRIER_GLS_WRONG_ADDRESS"
}

{
  "error": "Bad Request",
  "message": "Failed to create address",
  "code": "CARRIER_GLS_WRONG_ADDRESS"
}

{
  "error": "Bad Request",
  "message": "Failed to create address",
  "code": "CARRIER_GLS_WRONG_ADDRESS"
}

POST

orgs

{orgId}

shipments

{shipmentId}

create-return

TypeScript

import { Configuration, ShipmentsApi } from "@zippendo/sdk"

const api = new ShipmentsApi(new Configuration({ accessToken: process.env.ZIPPENDO_API_TOKEN }))
const result = await api.createReturnShipment({ orgId: "...", shipmentId: "..." })

import os
import zippendo

config = zippendo.Configuration(access_token=os.environ["ZIPPENDO_API_TOKEN"])
with zippendo.ApiClient(config) as client:
    result = zippendo.ShipmentsApi(client).create_return_shipment("...", "...")

<?php
$config = Zippendo\Sdk\Configuration::getDefaultConfiguration()->setAccessToken(getenv("ZIPPENDO_API_TOKEN"));
$api = new Zippendo\Sdk\Api\ShipmentsApi(new GuzzleHttp\Client(), $config);
$result = $api->createReturnShipment("...", "...");

client := zippendo.NewAPIClient(zippendo.NewConfiguration())
ctx := context.WithValue(context.Background(), zippendo.ContextAccessToken, os.Getenv("ZIPPENDO_API_TOKEN"))
result, _, err := client.ShipmentsAPI.CreateReturnShipment(ctx, "...", "...").Execute()

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.zippendo.com/orgs/{orgId}/shipments/{shipmentId}/create-return', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "shp_4d9e7a2f",
  "reference": "ORDER-1042",
  "parties": [
    {
      "type": "receiver",
      "name": "Anna Jensen",
      "address1": "Vesterbrogade 12",
      "postalCode": "1620",
      "city": "København V",
      "countryCode": "DK",
      "attributes": [],
      "attention": "Reception",
      "address2": "2. sal",
      "email": "[email protected]",
      "phone": "+4520123456"
    }
  ],
  "type": "outbound",
  "carrierSettings": {
    "carrierId": "car_pn_001",
    "productId": "prod_mypack_home",
    "services": [
      "A7"
    ],
    "additionalParameters": {
      "notificationEmail": "[email protected]"
    }
  },
  "parcels": [
    {
      "weight": 2.5,
      "weightUnit": "kg",
      "dimensions": {
        "length": 30,
        "width": 20,
        "height": 15
      },
      "orderLines": [
        {
          "quantity": 2,
          "id": "ol_9c1d2e3f",
          "orderLineId": "clz9k2f0a0004abcd3456qrst",
          "sku": "SKU-1024",
          "description": "Wool sweater, navy",
          "unitPrice": 299.95,
          "currency": "DKK",
          "vatPercent": 25,
          "location": "A-12-3",
          "countryOfOrigin": "DK",
          "hsCode": "61101100",
          "tarrifNumber": "61101100"
        }
      ],
      "id": "prc_5a6b7c8d",
      "trackingNumber": "00370724710000012345",
      "trackingUrl": "https://tracking.postnord.com/00370724710000012345",
      "labelFreeCode": "AB12CD34",
      "qrCodeLink": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
      "qrCodeDataUri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
      "qrCodeUrl": "https://qr.bring.com/label-free/AB12CD34.png"
    }
  ],
  "termOfTrade": "DAP",
  "errors": [],
  "status": "pending",
  "orgId": "org_1a2b3c4d",
  "logs": [],
  "activities": [],
  "createdAt": "2026-06-22T14:30:00.000Z",
  "updatedAt": "2026-06-22T14:30:00.000Z",
  "addressId": "addr_7e8f9a0b",
  "servicePointId": "sp_pn_4521",
  "pickupDetails": {
    "date": "2026-06-22",
    "from": "08:00:00",
    "to": "16:00:00",
    "instruction": "Ring the bell at the loading dock."
  },
  "documents": [
    {
      "id": "doc_8f3a2b1c",
      "shipmentId": "shp_4d9e7a2f",
      "documentType": "label",
      "format": "pdf",
      "content": "JVBERi0xLjQKJeLjz9MKMS...",
      "size": "100X150",
      "createdAt": "2026-06-22T14:30:00.000Z",
      "updatedAt": "2026-06-22T14:30:00.000Z"
    }
  ],
  "tracking": {
    "url": "https://tracking.postnord.com/00370724710000012345",
    "number": "00370724710000012345",
    "labelFreeCode": "AB12CD34",
    "qrCodeLink": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
    "qrCodeDataUri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
    "qrCodeUrl": "https://qr.bring.com/label-free/AB12CD34.png"
  },
  "orderId": "ord_5e6f7a8b",
  "shippingRuleId": "rule_3c4d5e6f",
  "shippingRule": {
    "id": "rule_3c4d5e6f",
    "name": "Domestic standard",
    "carrierId": "car_pn_001",
    "productId": "prod_mypack_home",
    "services": [
      "A7"
    ],
    "addressId": "addr_7e8f9a0b",
    "returnShippingRuleId": "rule_return_01",
    "autoCreateReturnShipment": false,
    "autoPrintLabels": true,
    "autoPrintDocuments": false,
    "labelPrinterId": "prn_label_01",
    "documentPrinterId": "prn_doc_01"
  },
  "labelPrinterId": "prn_label_01",
  "documentPrinterId": "prn_doc_01"
}

{
  "error": "Bad Request",
  "message": "Failed to create address",
  "code": "CARRIER_GLS_WRONG_ADDRESS"
}

{
  "error": "Bad Request",
  "message": "Failed to create address",
  "code": "CARRIER_GLS_WRONG_ADDRESS"
}

{
  "error": "Bad Request",
  "message": "Failed to create address",
  "code": "CARRIER_GLS_WRONG_ADDRESS"
}

Authorizations

Authorization

string

header

required

JWT access token or API token (prefixed with zipp_)

Path Parameters

orgId

string

required

Organization identifier.

Example:

"org_1a2b3c4d"

shipmentId

string

required

Shipment identifier.

Example:

"shp_4d9e7a2f"

Response

Default Response

string

required

Unique shipment identifier.

Example:

"shp_4d9e7a2f"

reference

string

required

Customer-facing shipment reference.

Example:

"ORDER-1042"

parties

object[]

required

Parties involved in the shipment (sender, receiver, etc.).

Show child attributes

type

enum<string>

required

Direction of the shipment relative to the organization.

Available options:

outbound,

inbound

Example:

"outbound"

carrierSettings

object

required

Show child attributes

parcels

object[]

required

Parcels included in the shipment.

Show child attributes

termOfTrade

string

default:DAP

required

Incoterm governing the shipment.

Example:

"DAP"

errors

object[]

required

Carrier errors recorded for the shipment.

Show child attributes

status

enum<string>

required

Lifecycle status of the shipment.

Available options:

draft,

pending,

processing,

dispatched,

partly_dispatched,

error,

cancelled,

on_hold

Example:

"pending"

orgId

string

required

Owning organization identifier.

Example:

"org_1a2b3c4d"

logs

object[]

required

Request/response logs captured during carrier interactions.

Show child attributes

activities

object[]

required

Chronological activity history of the shipment.

Show child attributes

createdAt

string

required

Timestamp when the shipment was created.

Example:

"2026-06-22T14:30:00.000Z"

updatedAt

string

required

Timestamp when the shipment was last updated.

Example:

"2026-06-22T14:30:00.000Z"

addressId

string | null

Sender address identifier.

Example:

"addr_7e8f9a0b"

servicePointId

string | null

Selected service point ID.

Example:

"sp_pn_4521"

pickupDetails

object | null

Show child attributes

documents

object[]

Documents generated for the shipment (labels, invoices).

Show child attributes

tracking

object | null

Show child attributes

orderId

string | null

Associated order identifier.

Example:

"ord_5e6f7a8b"

shippingRuleId

string | null

Applied shipping rule identifier.

Example:

"rule_3c4d5e6f"

shippingRule

object | null

Show child attributes

labelPrinterId

string | null

Printer assigned for labels on this shipment.

Example:

"prn_label_01"

documentPrinterId

string | null

Printer assigned for documents on this shipment.

Example:

"prn_doc_01"

Overview

SDKs

MCP server

System

Tokens

Orgs

Brands

Addresses

Carriers

Rules

Quotes

Shipments

Orders

Order Channels

Carrier Catalog

Billing

Webhooks

Create return shipment

Authorizations

Path Parameters

Response