Getting Started

Ordflow API

The Ordflow API allows registered Ordflow customers and integration partners to create shipments and generate shipping labels programmatically.

The API uses JSON for requests and responses.

Base URL

https://api.ordflow.com

All API requests should be sent over HTTPS.

Before you begin

To use the Ordflow API you need:

• An active Ordflow account
• API access enabled for your account
• Valid Ordflow credentials
• A courier/service configured in Ordflow

Authentication is required before calling the Shipment API. See Authentication for details.

Basic workflow

1. Authenticate with Ordflow
2. Receive an access token
3. Create a shipment
4. Ordflow processes the shipment with the configured courier
5. Receive the shipment result and shipping label information

Request format

Requests are sent as JSON.

Content-Type: application/json

Authenticated API requests also include an Ordflow access token. The exact authentication header is covered in the Authentication section.

Shipment API

The initial Ordflow API documentation covers shipment creation:

POST /api/v2/shipments/create

The complete request structure, supported fields, examples, and responses are documented under Shipments → Create Shipments.

Authentication

The Ordflow API uses an access token to authenticate requests.

Use your existing Ordflow account credentials to obtain an access token before calling the Shipments API.

Sign in

POST https://api.ordflow.com/account/sign-in

Headers

Content-Type: application/json

Request body

{
  "email": "your@email.com",
  "password": "your_password"
}

cURL

curl -X POST \
  'https://api.ordflow.com/account/sign-in' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "your@email.com",
    "password": "your_password"
  }'

Successful response

{
  "token": "YOUR_ACCESS_TOKEN"
}

The token value returned in the response is the access token used to authenticate subsequent Ordflow API requests.

After successful authentication, the response contains the access token in the token field.

Using the access token

Include the access token in the x-access-token header on every authenticated API request:

x-access-token: {access_token}

curl -X POST \
  'https://api.ordflow.com/api/v2/shipments/create' \
  -H 'x-access-token: YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'

Authentication errors

If the access token is missing or no longer valid, the request will not be authorized.

Authenticate again using the sign-in endpoint to obtain a new access token.

Security

Use HTTPS for all API requests.

Do not expose your Ordflow password or access token in publicly accessible client-side code, source repositories, or logs.

Create Shipments

POST /api/v2/shipments/create

Creates one or more shipments in a single request.

reference_id is required for every shipment and is used to correlate each shipment in the batch with the corresponding shipment in the response.

There is currently no documented maximum batch size.

The shipments property is required and should normally contain at least one shipment. If an empty shipments array is submitted, Ordflow returns an empty response rather than treating it as an error.

Request example

A complete, minimal public request:

{
  "shipments": [
    {
      "reference_id": "ORDER-10001",
      "sender": {
        "address": {
          "company_name": "Example Store",
          "first_name": "John",
          "last_name": "Seller",
          "country_code": "IL",
          "city": "Tel Aviv",
          "first_line": "10 Example Street",
          "zip_code": "6100000",
          "phone_number": "+972501234567"
        },
        "business_number": "123456789"
      },
      "recipient": {
        "address": {
          "first_name": "Jane",
          "last_name": "Customer",
          "country_code": "US",
          "city": "New York",
          "state": "NY",
          "first_line": "100 Example Avenue",
          "second_line": "Apt 4B",
          "zip_code": "10001",
          "phone_number": "+12125551234"
        }
      },
      "content": {
        "clearance": {},
        "items": [
          {
            "external_id": "ITEM-10001",
            "title": "Cotton T-Shirt",
            "sku": "TSHIRT-BLK-M",
            "hs_code": "610910",
            "price": {
              "currency": "USD",
              "amount": 29.95
            },
            "quantity": 1,
            "weight": {
              "unit": "KG",
              "value": 0.25
            },
            "origin_country_code": "IL"
          }
        ],
        "package": {
          "type": "YourPackaging",
          "dimension": {
            "unit": "CM",
            "length": 30,
            "width": 20,
            "height": 5
          }
        }
      },
      "collection": {
        "drop_off": "None",
        "date": "2026-09-08T00:00:00Z"
      },
      "configuration": {
        "duty": "DDU",
        "purpose": "Commercial"
      },
      "courier": {
        "courier_id": 3,
        "courier_name": "FedEx",
        "service": "International Priority"
      }
    }
  ]
}

Top level

Address

The sender.address and recipient.address objects use the same address rules.

Sender

sender.address is required and follows the address rules above.

Recipient

recipient.address is required and follows the address rules above.

Content

content is required and carries the customs clearance information, the line items and the package:

"content": {
  "clearance": { ... },
  "items": [ ... ],
  "package": { ... }
}

Clearance / IOSS

content.clearance is required. For a normal shipment without VAT / IOSS information it may be an empty object:

"clearance": {}

VAT information is optional and should only be supplied when relevant, for example EU shipments declared under IOSS:

"clearance": {
  "vat": {
    "type": "IOSS",
    "value": "IM3..."
  }
}

Items

content.items is required.

{
  "external_id": "ITEM-10001",
  "title": "Cotton T-Shirt",
  "sku": "TSHIRT-BLK-M",
  "hs_code": "610910",
  "price": {
    "currency": "USD",
    "amount": 29.95
  },
  "quantity": 1,
  "weight": {
    "unit": "KG",
    "value": 0.25
  },
  "origin_country_code": "IL"
}

Package

content.package is required. type and dimension are both required.

"package": {
  "type": "YourPackaging",
  "dimension": {
    "unit": "CM",
    "length": 30,
    "width": 20,
    "height": 5
  }
}

Collection

collection is required. For public API shipment creation use:

"collection": {
  "drop_off": "None",
  "date": "2026-09-08T00:00:00Z"
}

Configuration

configuration is required.

"configuration": {
  "duty": "DDU",
  "purpose": "Commercial"
}

Courier

courier selects the courier and service. Courier / service combinations have their own rules — some are direct integrations, others are routed through an Ordflow courier-service / provider and additionally require courier_service.

Basic shape

"courier": {
  "courier_id": 3,
  "courier_name": "FedEx",
  "service": "International Priority"
}

Provider-backed shape

"courier": {
  "courier_id": 11,
  "courier_name": "Pylon",
  "service": "MYNEXP",
  "courier_service": {
    "id": 1,
    "name": "Mailog"
  }
}

Courier service providers

These provider IDs are fixed:

• Pylon – courier_service is required and must use { "id": 1, "name": "Mailog" }.
• BPost – courier_service is required and must use { "id": 1, "name": "Mailog" }.
• Israel Post – courier_service is required and must use { "id": 2, "name": "Israel Post" }.
• Services routed through Ordflow use { "id": 3, "name": "Ordflow" }.
• For a direct courier integration, courier_service may be omitted unless that courier / service explicitly requires it.

Courier IDs

Known courier services

Use these service values exactly as written. Do not use service values for couriers not listed here.

BPost + IOSS

For BPost, "EShipper" is used for EU shipments declared under IOSS. Supply the IOSS reference in content.clearance.vat (see Clearance / IOSS) and route the courier through Mailog:

{
  "content": {
    "clearance": {
      "vat": {
        "type": "IOSS",
        "value": "IM3..."
      }
    }
  },
  "courier": {
    "courier_id": 5,
    "courier_name": "BPost",
    "service": "EShipper",
    "courier_service": {
      "id": 1,
      "name": "Mailog"
    }
  }
}

Israel Post example

"courier": {
  "courier_id": 7,
  "courier_name": "Israel Post",
  "service": "EMS",
  "courier_service": {
    "id": 2,
    "name": "Israel Post"
  }
}

Pylon / Mailog example

"courier": {
  "courier_id": 11,
  "courier_name": "Pylon",
  "service": "MYNEXP",
  "courier_service": {
    "id": 1,
    "name": "Mailog"
  }
}

Response

The response contains one result object for each shipment submitted in the request batch. Use reference_id to correlate each response item with the corresponding shipment in the request.

A failed shipment may return no id, no shipment_code and no label / invoice, but it still includes the original reference_id and notifications that describe the failure.

Success response example

{
  "shipments": [
    {
      "id": 123456,
      "reference_id": "ORDER-10001",
      "shipment_label": "<base64-label-data>",
      "shipment_invoice": null,
      "shipment_code": "1Z9999999999999999",
      "shipment_date": "2026-09-08",
      "pickup_confirmation": null,
      "pickup_date": null,
      "pickup_start_time": null,
      "pickup_end_time": null,
      "courier": {
        ...
      },
      "properties": null,
      "notifications": [
        {
          "severity": 0,
          "message": "Shipment created successfully",
          "source": 2,
          "Code": 0
        }
      ]
    }
  ]
}

The message and Code values above are illustrative only. Do not assume a specific message string or that Code is 0 for every successful shipment.

Response fields

courier carries the courier information associated with the created shipment, and properties carries additional shipment or courier-specific properties returned when applicable. Their exact response structures are not documented yet and will be added once confirmed.

Base64 files

shipment_label and shipment_invoice are byte arrays in the backend response and are therefore serialized in JSON as Base64-encoded strings. The file type depends on the courier.

"shipment_label": "JVBERi0xLjQK..."

Notifications

Each shipment result has its own notifications array. Inspect it for success confirmation or failure reasons.

{
  "severity": 0,
  "message": "Shipment created successfully",
  "source": 2,
  "Code": 0
}

Code uses an uppercase C in the current public JSON contract — document and read it exactly as Code.

Notification severity

ERROR and FAILURE represent error conditions in the current notification model. No further business meaning is implied beyond the enum names.

Notification source

Correlating batch responses

When creating multiple shipments in one request, do not rely on response array position alone. Use reference_id to match each response shipment with the corresponding requested shipment. This is one of the primary reasons reference_id is required.

Failed shipments

A failed shipment can still appear in the shipments response array. One shipment failing does not mean the caller should infer that the others failed — each shipment has its own result and its own notifications. For a failed shipment:

• reference_id still identifies the original request
• id may be null
• shipment_code may be null
• label / invoice may be null
• notifications should be inspected for the failure reason

Batch failure example

{
  "shipments": [
    {
      "id": 123456,
      "reference_id": "ORDER-10001",
      "shipment_code": "1Z9999999999999999",
      "notifications": [
        {
          "severity": 0,
          "message": "Shipment created successfully",
          "source": 2,
          "Code": 0
        }
      ]
    },
    {
      "id": null,
      "reference_id": "ORDER-10002",
      "shipment_label": null,
      "shipment_invoice": null,
      "shipment_code": null,
      "shipment_date": null,
      "notifications": [
        {
          "severity": 3,
          "message": "Example shipment creation error",
          "source": 2,
          "Code": 1000
        }
      ]
    }
  ]
}

The failure message and Code (1000) above are illustrative only and are not a defined error contract.

Delete Shipments

POST /api/v2/shipments/cancel

Cancel one or more existing shipments by Ordflow shipment ID. This endpoint supports batch cancellation.

Deleting a shipment cancels the existing Ordflow shipment and, where applicable, its associated courier / pickup operation. It does not permanently delete database records.

This endpoint requires the same Ordflow authentication used by the other API endpoints — see Authentication.

Request

The request body is a JSON array of Ordflow shipment IDs. Do not wrap the array in another object.

[
  123456,
  123457,
  123458
]

Correct

[
  123456,
  123457
]

Incorrect

{
  "shipment_ids": [
    123456,
    123457
  ]
}

Request field

For batch cancellation, send multiple shipment IDs in the request array.

Ownership

Ordflow verifies that the requested shipments belong to the authenticated user's current company / branch. If one or more shipments do not belong to the authenticated branch, the API returns 403 Forbidden with an unauthorized-request error.

Do not send CompanyId or BranchId in the request — they are derived from the authenticated Ordflow user / token.

Request example

POST /api/v2/shipments/cancel

Request body:

[
  123456,
  123457
]

Response

The endpoint returns an array of response objects. Each object has a data value and a notifications array:

{
  "data": ...,
  "notifications": [
    {
      "severity": 0,
      "message": "...",
      "source": 2,
      "Code": 0
    }
  ]
}

data is documented generically for now because the exact cancellation payload can depend on the cancellation result.

Success response example

[
  {
    "data": null,
    "notifications": [
      {
        "severity": 0,
        "message": "Shipment cancelled successfully",
        "source": 2,
        "Code": 0
      }
    ]
  }
]

The message, Code and data values above are illustrative only. Do not assume these exact values are returned — this example will be updated after real cancellation testing.

Response fields

Notifications

notifications uses the same contract as the Create Shipments response. Code has an uppercase C in the current API contract.

Notification severity

Notification source

Batch behavior

Multiple shipment IDs can be submitted in one request. The API performs cancellation through Ordflow's shipment / pickup cancellation process and returns the cancellation response data and notifications. No maximum number of shipment IDs is defined yet.

HTTP status codes

Relationship to Create Shipments

The IDs supplied to Delete Shipments are the id values returned by Create Shipments.

Create response:

{
  "id": 123456,
  "reference_id": "ORDER-10001"
}

Delete / cancel request:

[
  123456
]

Errors

Ordflow APIs can report errors at two levels:

• HTTP errors indicate that the request itself could not be processed.
• Operation notifications describe the result of an individual shipment operation.

For batch operations, some shipments may succeed while others fail.

A 200 OK response does not necessarily mean that every shipment in the batch was successful. Always inspect the notifications array for each shipment result, and use reference_id to correlate each response item with the original shipment in the request.

HTTP errors

HTTP status codes describe whether the overall API request could be processed.

Operation notifications

Shipment operations return a notifications array. Each notification contains:

{
  "severity": 3,
  "message": "Example error message",
  "source": 2,
  "Code": 1000
}

The message and Code above are examples only — they are not documented Ordflow error codes.

The JSON property is Code with an uppercase C. Read it exactly this way.

Severity

ERROR and FAILURE indicate unsuccessful operation results. No further meaning is implied beyond the enum names.

Source

Batch example

One successful shipment and one failed shipment in the same response. The notification messages and codes are illustrative examples only.

{
  "shipments": [
    {
      "id": 123456,
      "reference_id": "ORDER-10001",
      "notifications": [
        {
          "severity": 0,
          "message": "Example success message",
          "source": 2,
          "Code": 0
        }
      ]
    },
    {
      "id": null,
      "reference_id": "ORDER-10002",
      "notifications": [
        {
          "severity": 3,
          "message": "Example shipment error",
          "source": 2,
          "Code": 1000
        }
      ]
    }
  ]
}

This example shows that:

• the HTTP request can succeed while individual results differ
• each shipment result must be checked separately
• reference_id identifies which requested shipment the result belongs to

Handling responses

For batch shipment operations:

1. Check the HTTP status first.
2. If the request was processed, inspect each result individually.
3. Use reference_id to match the result to the submitted shipment.
4. Inspect notifications.
5. Treat ERROR or FAILURE notifications as unsuccessful shipment operations.