API Request Examples

Complete request and response examples for common Delivery API operations.

Authentication Required

All API requests require MAC (Message Authentication Code) authentication using your project_id and sign_password.

For complete authentication implementation with working code examples in JavaScript, PHP, and Python, see API Fundamentals - Authentication.

The examples below show HTTP request/response structures. You must add proper MAC authentication headers to all requests.

Base URL

https://delivery-api.paysera.com/rest/v1

Common Examples

1. Create Delivery Order

Request:

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

{
  "project_id": 123456,
  "order_id": "ORD-123456",
  "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
    }
  ]
}

Response:

{
  "id": 789456,
  "number": "DEL-789456",
  "project_id": 123456,
  "order_id": "ORD-123456",
  "status": "draft",
  "shipment_gateway_code": "dpd",
  "tracking_code": null,
  "created_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"
  }
}

---

2. Get Order Details

Request:

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

Response:

{
  "id": 789456,
  "number": "DEL-789456",
  "project_id": 123456,
  "order_id": "ORD-123456",
  "status": "label_generated",
  "shipment_gateway_code": "dpd",
  "tracking_code": "PS123456789LT",
  "created_at": "2025-11-21T10:00:00+00:00",
  "updated_at": "2025-11-21T10:15:00+00:00",
  "sender": { ... },
  "receiver": { ... },
  "shipments": [ ... ]
}

---

3. List Orders

Request:

GET /rest/v1/orders?limit=20&offset=0&projects[]=123456
Authorization: MAC id="123456", ts="1700574800", nonce="abc123", mac="..."

Response:

{
  "_links": {
    "self": {"href": "/rest/v1/orders?limit=20&offset=0"},
    "next": {"href": "/rest/v1/orders?limit=20&offset=20"}
  },
  "_embedded": {
    "orders": [
      {
        "id": 789456,
        "number": "DEL-789456",
        "status": "delivered",
        "tracking_code": "PS123456789LT",
        "created_at": "2025-11-21T10:00:00+00:00"
      },
      {
        "id": 789455,
        "number": "DEL-789455",
        "status": "in_transit",
        "tracking_code": "PS123456788LT",
        "created_at": "2025-11-20T15:30:00+00:00"
      }
    ]
  },
  "total": 150,
  "limit": 20,
  "offset": 0
}

---

4. Generate Label

Request:

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

Response:

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

---

5. Download Label

Request:

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

Response:

Binary PDF file content.

---

6. Get Available Shipment Methods

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:

{
  "_links": {
    "self": {"href": "/rest/v1/shipment-methods?project_id=123456"}
  },
  "_embedded": {
    "shipment-methods": [
      {
        "id": 1,
        "code": "courier",
        "title": "Courier delivery",
        "enabled": true
      },
      {
        "id": 2,
        "code": "parcel_machine",
        "title": "Parcel machine",
        "enabled": true
      }
    ]
  }
}

---

7. Get Available Shipment Gateways

Request:

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

Response:

{
  "_embedded": {
    "shipment-gateways": [
      {
        "id": 10,
        "code": "dpd",
        "title": "DPD",
        "enabled": true,
        "type": "courier"
      },
      {
        "id": 11,
        "code": "omniva",
        "title": "Omniva",
        "enabled": true,
        "type": "parcel_machine"
      }
    ]
  }
}

---

8. Get Parcel Machines

Request:

GET /rest/v1/parcel-machines?city=Vilnius&country=LT&shipment_gateway_code=omniva
Authorization: MAC id="123456", ts="1700574800", nonce="abc123", mac="..."

Response:

{
  "_embedded": {
    "parcel-machines": [
      {
        "id": "VNO001",
        "title": "Omniva Akropolis",
        "address": "Ozo g. 25",
        "city": "Vilnius",
        "postal_code": "08217",
        "country_code": "LT",
        "coordinates": {
          "latitude": 54.7127,
          "longitude": 25.2614
        }
      }
    ]
  }
}

---

9. Update Order

Request:

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

{
  "receiver": {
    "name": "John Doe Updated",
    "phone": "+37060000003",
    "email": "john.updated@example.com",
    "country_code": "LT",
    "city": "Kaunas",
    "street": "New Street 15",
    "postal_code": "44002"
  }
}

Response:

{
  "id": 789456,
  "number": "DEL-789456",
  "status": "draft",
  "receiver": {
    "name": "John Doe Updated",
    "phone": "+37060000003",
    "email": "john.updated@example.com",
    "country_code": "LT",
    "city": "Kaunas",
    "street": "New Street 15",
    "postal_code": "44002"
  },
  "updated_at": "2025-11-21T11:00:00+00:00"
}

---

10. Delete Order

Request:

DELETE /rest/v1/orders/{order_id}
Authorization: MAC id="123456", ts="1700574800", nonce="abc123", mac="..."

Response:

HTTP/1.1 204 No Content

---

Order Statuses

Orders go through these status transitions:

Status	Description
draft	Order created, not yet confirmed
in_progress	Order confirmed, awaiting label generation
label_generated	Label generated, ready for shipment
manifest_generated	Manifest created, courier called
in_transit	Package is being delivered
delivered	Package delivered successfully
returned	Package returned to sender
cancelled	Order cancelled

---

Error Responses

All API errors return a JSON response with error details:

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

Common error codes:

• invalid_request - Malformed request
• invalid_parameters - Validation errors
• invalid_scope - Resource belongs to different project
• not_found - Resource not found
• invalid_state - Invalid state transition

---

Next Steps

• API Fundamentals - Authentication implementation
• API Reference - Complete endpoint documentation
• FAQ - Common questions

Support

Need help with complex integrations?

Contact: tech_support@paysera.com