Creating Your First Order

This guide walks you through creating your first delivery order using the Paysera Delivery API.

Prerequisites

Before you begin, ensure you have:

✅ Active Paysera account with delivery service enabled
✅ Project credentials (project_id and sign_password)
✅ Configured warehouse/pickup location
✅ Understanding of MAC authentication (see API Fundamentals)

Order Creation Process

The typical order creation workflow:

Step 1: Get Available Shipment Methods

First, retrieve available shipment methods for your route.

Request:

GET /rest/v1/shipment-methods?project_id=123456&from_country_code=LT&to_country_code=LT
Authorization: MAC id="123456", ts="1700574800", nonce="abc123", mac="..."

Response:

{
  "_embedded": {
    "shipment-methods": [
      {
        "id": 1,
        "code": "courier",
        "title": "Courier delivery",
        "enabled": true
      },
      {
        "id": 2,
        "code": "parcel_machine",
        "title": "Parcel machine",
        "enabled": true
      }
    ]
  }
}

Step 2: Get Available Shipment Gateways

Get available courier services (gateways) for your route.

Request:

GET /rest/v1/shipment-gateways?project_id=123456&from_country_code=LT&to_country_code=LT&shipment_method_code=courier
Authorization: MAC id="123456", ts="1700574800", nonce="abc123", mac="..."

Response:

{
  "_embedded": {
    "shipment-gateways": [
      {
        "id": 10,
        "code": "dpd",
        "title": "DPD",
        "enabled": true,
        "type": "courier"
      },
      {
        "id": 15,
        "code": "venipak",
        "title": "Venipak",
        "enabled": true,
        "type": "courier"
      }
    ]
  }
}

Step 3: Create Delivery Order

Now create your delivery order with all required information.

Request:

POST /rest/v1/orders
Content-Type: application/json
Authorization: MAC id="123456", ts="1700574800", nonce="abc123", mac="..."

Request Body:

{
  "project_id": 123456,
  "order_id": "ORD-2025-001",
  "eshop_order_id": "SHOP-12345",
  "shipment_gateway_code": "dpd",
  "shipment_method_code": "courier",
  "sender": {
    "name": "My Store Warehouse",
    "phone": "+37060000001",
    "email": "warehouse@mystore.com",
    "country_code": "LT",
    "city": "Vilnius",
    "street": "Warehouse Street 1",
    "postal_code": "01001"
  },
  "receiver": {
    "name": "John Doe",
    "phone": "+37060000002",
    "email": "john@example.com",
    "country_code": "LT",
    "city": "Kaunas",
    "street": "Customer Street 10-5",
    "postal_code": "44001"
  },
  "shipments": [
    {
      "weight": 2500,
      "width": 20,
      "height": 15,
      "length": 30
    }
  ],
  "notes": "Handle with care - fragile items"
}

Response:

{
  "id": 789456,
  "number": "DEL-789456",
  "project_id": 123456,
  "order_id": "ORD-2025-001",
  "eshop_order_id": "SHOP-12345",
  "status": "draft",
  "shipment_gateway_code": "dpd",
  "shipment_method_code": "courier",
  "tracking_code": null,
  "created_at": "2025-11-21T10:00:00+00:00",
  "updated_at": "2025-11-21T10:00:00+00:00",
  "sender": {
    "name": "My Store Warehouse",
    "phone": "+37060000001",
    "email": "warehouse@mystore.com",
    "country_code": "LT",
    "city": "Vilnius",
    "street": "Warehouse Street 1",
    "postal_code": "01001"
  },
  "receiver": {
    "name": "John Doe",
    "phone": "+37060000002",
    "email": "john@example.com",
    "country_code": "LT",
    "city": "Kaunas",
    "street": "Customer Street 10-5",
    "postal_code": "44001"
  },
  "shipments": [
    {
      "weight": 2500,
      "width": 20,
      "height": 15,
      "length": 30
    }
  ]
}

Order Status

The order is created in draft status. You can still edit it before generating the label.

Step 4: Generate Shipping Label

Generate a shipping label for your order.

Request:

POST /rest/v1/orders/789456/label
Authorization: MAC id="123456", ts="1700574800", nonce="abc123", mac="..."

Response:

{
  "id": 789456,
  "number": "DEL-789456",
  "status": "label_generated",
  "tracking_code": "PS123456789LT",
  "label_url": "https://delivery-api.paysera.com/rest/v1/orders/789456/label"
}

Status Change

After label generation, the order status changes to label_generated and a tracking code is assigned.

Step 5: Download Shipping Label

Download the generated label as a PDF file.

Request:

GET /rest/v1/orders/789456/label
Authorization: MAC id="123456", ts="1700574800", nonce="abc123", mac="..."
Accept: application/pdf

Response:

Binary PDF file content.

Step 6: Create Manifest and Call Courier

Generate a manifest and schedule courier pickup.

Request:

POST /rest/v1/orders/789456/manifest
Authorization: MAC id="123456", ts="1700574800", nonce="abc123", mac="..."

Response:

{
  "id": 789456,
  "status": "manifest_generated",
  "tracking_code": "PS123456789LT",
  "manifest_url": "https://delivery-api.paysera.com/rest/v1/orders/789456/manifest"
}

Courier Call

When you generate a manifest, the courier is automatically called for pickup at your warehouse during business hours.

Step 7: Track Your Order

Check the status of your order at any time.

Request:

GET /rest/v1/orders/789456
Authorization: MAC id="123456", ts="1700574800", nonce="abc123", mac="..."

Response:

{
  "id": 789456,
  "number": "DEL-789456",
  "status": "in_transit",
  "tracking_code": "PS123456789LT",
  "sender": { ... },
  "receiver": { ... },
  "shipments": [ ... ],
  "created_at": "2025-11-21T10:00:00+00:00",
  "updated_at": "2025-11-21T11:30:00+00:00"
}

Order Status Flow

Your order will go through these statuses:

Status	Description	Actions Available
`draft`	Order created	Edit, Delete, Generate Label
`in_progress`	Being processed	Generate Label
`label_generated`	Label ready	Download Label, Create Manifest, Reset to Draft
`manifest_generated`	Courier called	Download Manifest
`in_transit`	Being delivered	Track
`delivered`	Successfully delivered	View
`returned`	Returned to sender	View
`cancelled`	Cancelled	View

Complete Example Flow

Here's a complete example showing all steps together:

1. Create Order

POST /rest/v1/orders
Authorization: MAC id="123456", ts="...", nonce="...", mac="..."
Content-Type: application/json

{
  "project_id": 123456,
  "order_id": "ORD-2025-001",
  "shipment_gateway_code": "dpd",
  "shipment_method_code": "courier",
  "sender": { ... },
  "receiver": { ... },
  "shipments": [ ... ]
}

Response: { "id": 789456, "status": "draft" }

2. Generate Label

POST /rest/v1/orders/789456/label
Authorization: MAC id="123456", ts="...", nonce="...", mac="..."

Response: { "status": "label_generated", "tracking_code": "PS123456789LT" }

3. Download Label

GET /rest/v1/orders/789456/label
Authorization: MAC id="123456", ts="...", nonce="...", mac="..."

Response: PDF file

4. Create Manifest

POST /rest/v1/orders/789456/manifest
Authorization: MAC id="123456", ts="...", nonce="...", mac="..."

Response: { "status": "manifest_generated" }

5. Track Order

GET /rest/v1/orders/789456
Authorization: MAC id="123456", ts="...", nonce="...", mac="..."

Response: Current order status and details

Important Field Descriptions

Shipments Array

Each shipment in the shipments array represents one package:

{
  "weight": 2500,    // Weight in grams
  "width": 20,       // Width in cm
  "height": 15,      // Height in cm
  "length": 30       // Length in cm
}

Contact Information

Both sender and receiver must include:

phone - In E.164 format (e.g., +37060000001)
email - Valid email address
country_code - ISO 3166-1 alpha-2 (e.g., LT, LV, EE)
postal_code - Valid postal code for the country

Common Errors

Invalid Phone Format

{
  "error": "invalid_parameters",
  "error_description": "Validation failed",
  "errors": [
    {
      "field": "receiver.phone",
      "message": "Phone number must be in E.164 format"
    }
  ]
}

Solution: Use format +[country_code][number], e.g., +37060000001

Invalid Gateway

{
  "error": "invalid_parameters",
  "error_description": "Invalid shipment gateway",
  "errors": [
    {
      "field": "shipment_gateway_code",
      "message": "Gateway 'invalid' not available for this route"
    }
  ]
}

Solution: Use Step 2 to get available gateways for your route.

Weight Exceeds Limit

{
  "error": "invalid_parameters",
  "errors": [
    {
      "field": "shipments[0].weight",
      "message": "Weight exceeds maximum allowed for this gateway"
    }
  ]
}

Solution: Split into multiple shipments or choose a different gateway.

Next Steps

Now that you've created your first order, explore more features:

API Examples - More request/response examples
API Reference - Complete endpoint documentation
FAQ - Common questions and solutions

Authentication Implementation

Remember, all examples above show MAC authentication headers in simplified form.

For complete working implementation in JavaScript, PHP, and Python, see:

API Fundamentals - Authentication

Support

Need help with complex integrations?

Contact: tech_support@paysera.com

Order Creation Process​

Step 1: Get Available Shipment Methods​

Step 2: Get Available Shipment Gateways​

Step 3: Create Delivery Order​

Step 4: Generate Shipping Label​

Step 5: Download Shipping Label​

Step 6: Create Manifest and Call Courier​

Step 7: Track Your Order​

Order Status Flow​

Complete Example Flow​

1. Create Order​

2. Generate Label​

3. Download Label​

4. Create Manifest​

5. Track Order​

Important Field Descriptions​

Shipments Array​

Contact Information​

Common Errors​

Invalid Phone Format​

Invalid Gateway​

Weight Exceeds Limit​

Next Steps​

Authentication Implementation​

Support​

Order Creation Process

Step 1: Get Available Shipment Methods

Step 2: Get Available Shipment Gateways

Step 3: Create Delivery Order

Step 4: Generate Shipping Label

Step 5: Download Shipping Label

Step 6: Create Manifest and Call Courier

Step 7: Track Your Order

Order Status Flow

Complete Example Flow

1. Create Order

2. Generate Label

3. Download Label

4. Create Manifest

5. Track Order

Important Field Descriptions

Shipments Array

Contact Information

Common Errors

Invalid Phone Format

Invalid Gateway

Weight Exceeds Limit

Next Steps

Authentication Implementation

Support