DOCSEARCHbyAlgolia
Submit Docs

Shipmondo API

website·Indexed 32 days ago

https://shipmondo.dev

OpenAPI 3.0.1 specification for the Shipmondo API, providing the technical schema, component definitions, request/response structures, and endpoint parameters for service integration.

Tokens
27.4K
Snippets
190
Records
221
Agent score
12%

What's inside Shipmondo

  1. WaybillNoBase64 data structure

    v3
    The WaybillNoBase64 object provides detailed information about a waybill, including its reference, carrier, and the associated parties involved in the shipment (sender, receiver, loading, and delivery). It also links to a shipment ID.
    {
  "id": 23,
  "reference": "CS000000000NO",
  "carrier_code": "bring",
  "created_at": "2018-06-16T06:25:44.557Z",
  "sender": { "name": "...", "address1": "...", "zipcode": "...", "city": "...", "country_code": "..." },
  "receiver": { "name": "...", "address1": "...", "zipcode": "...", "city": "...", "country_code": "..." },
  "loading": { "name": "...", "address1": "...", "zipcode": "...", "city": "...", "country_code": "...", "date": "..." },
  "delivery": { "name": "...", "address1": "...", "zipcode": "...", "city": "...", "country_code": "..." },
  "shipment": { "id": 123456 }
}

  2. Define OrderLine properties for Shipmondo sales orders

    v3
    The OrderLine object represents an individual line item within a sales order. It includes details about the product (SKU, name, variant), pricing (unit price, VAT, discounts), and logistics (weight, barcode, bin location). For shipments requiring customs declarations, the customs_commodity_code and customs_description fields are used.
    {
  "id": 1234,
  "line_type": "item", // Options: item, shipping, discount, gift_card, payment_fee, duty
  "item_sku": "TS001-WH",
  "item_name": "T-Shirt",
  "quantity": "2.0",
  "unit_price_excluding_vat": "800.0",
  "currency_code": "DKK",
  "unit_weight": 2000,
  "customs_commodity_code": "123456",
  "customs_description": "Example contents"
}

  3. Shipment object schema and properties

    v3

    The Shipment object contains comprehensive details about a shipment, including participants, parcels, and logistics instructions. Key properties include:

    • Participants: receiver (ShipmentReceiver), sender (ShipmentSender), and bill_to (ShipmentBillTo).
    • Parcels: An array of Parcel objects (minimum 1 item).
    • Customs & Trade: customs (CustomsResponse) and paperless_trade (boolean), which removes the need for physical proforma invoices if true.
    • Logistics: service_point (ShipmentServicePoint), pick_up (PickUp), and waybill_reference (bulk waybill reference).
    • Source Tracking: source_id (integer) and source_type (enum: manual, imported, fulfillment, return, repurchase, api, address_book).
    • Return Tracking: return_shipment_id and origin_shipment_id for managing return flows.
    • Insurance: Use carrier_insurance (CarrierInsurance). The insurance object is deprecated.
    • Labelless: labelless_code provides a code to be written on the parcel if supported by the carrier.
    • Scheduling: pickup_details and delivery_details allow specifying dates, time windows (from/to in HH:MM:SS), and specific instructions.

  4. Shipmondo Waybill object schema

    v3
    The Waybill object represents a bulk waybill used for carrier shipments. It contains details about the carrier, the current status (open or closed), and address information for the sender, receiver, loading point, and delivery point.
    {
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "reference": { "type": "string", "description": "Carrier's reference of the bulk waybill." },
    "status": { "type": "string", "enum": ["open", "closed"] },
    "carrier_code": { "type": "string" },
    "customer_number": { "type": "string" },
    "created_at": { "type": "string", "format": "date-time" },
    "sender": { "type": "object", "properties": { "name": { "type": "string" }, "address1": { "type": "string" }, "address2": { "type": "string" }, "zipcode": { "type": "string" }, "city": { "type": "string" }, "country_code": { "type": "string" } } },
    "receiver": { "type": "object", "properties": { "name": { "type": "string" }, "address1": { "type": "string" }, "address2": { "type": "string" }, "zipcode": { "type": "string" }, "city": { "type": "string" }, "country_code": { "type": "string" } } },
    "loading": { "type": "object", "properties": { "name": { "type": "string" }, "address1": { "type": "string" }, "address2": { "type": "string" }, "zipcode": { "type": "string" }, "city": { "type": "string" }, "country_code": { "type": "string" }, "date": { "type": "string", "format": "date-time" } } },
    "delivery": { "type": "object", "properties": { "name": { "type": "string" }, "address1": { "type": "string" }, "address2": { "type": "string" }, "zipcode": { "type": "string" }, "city": { "type": "string" } } }
  }
}

  5. Shipmondo API General Information

    v3
    The Shipmondo API (v3) is the official interface for integrating with Shipmondo services. It uses Basic Authentication for security. An official PHP SDK is available on GitHub.
    # Official PHP SDK
https://github.com/shipmondo/shipmondo_php_sdk

  6. Prepare a document for direct upload in Shipmondo

    v3
    Use the /documents/upload endpoint to prepare a document for direct upload. This is a prerequisite step before the document can be used in other API requests. For detailed implementation, refer to the Shipmondo Direct Upload guide.
    curl -X POST "https://app.shipmondo.com/api/public/v3/documents/upload" \
     -H "Authorization: Basic <credentials>" \
     -H "Content-Type: application/json" \
     -d '{"schema": "PrepareDirectUploadRequest"}'

  7. Authenticate Shipmondo API requests using Basic Auth

    v3
    The Shipmondo API uses HTTP Basic Authentication. You must provide an API username and API key, which can be found in your Shipmondo account under Settings > Integrations > API. The credentials must be base64-encoded and passed in the Authorization header.
    Authorization: Basic <base64-encoded-username:api-key>

  8. Request a Carrier setup file

    v3

    The GET /setups/carriers endpoint allows you to request a Carrier setup file. The response indicates the current status of the request:

    • REQUESTED: The file has been requested.
    • IN_PROGRESS: The file is being generated.
    • COMPLETED: The file is ready for download via the provided url before the expires_at timestamp.
    // Example response when file is ready
{
  "status": "COMPLETED",
  "url": "https://example.com/carrier_setup_file",
  "expires_at": "2021-01-01T00:00:00Z"
}

  9. Authenticate Shipmondo API requests using a Frontend Key

    v3
    Certain endpoints support authentication via a delivery checkout key. This key must be passed as a query parameter named frontend_key.
    GET /endpoint?frontend_key=YOUR_DELIVERY_CHECKOUT_KEY

  10. Understand Shipping Product and Service models

    v3

    Shipmondo uses a tiered system for shipping options:

    • ShippingProduct: The main shipping product (e.g., "Shop Delivery"). It includes details on availability (own_agreement_available), customs requirements, service point availability, and expected transit time. It also specifies required_fields and optional_fields needed to book a shipment.
    • ShippingProductService: Specific services associated with a product (e.g., "Email notification"). These have their own code, id, and specific required_fields (e.g., receiver_email).
    • WeightInterval: Defines weight brackets (in grams) using from_weight and to_weight to determine pricing or availability.

  11. Update or remove existing OrderLines

    v3
    To update an existing order line, provide the id of the line in the order_lines array. If no id is provided, a new line will be created. To remove an existing line, set the quantity to 0 during the update process.

  12. Prepare a direct file upload

    v3
    To upload a file directly, first send a PrepareDirectUploadRequest. This request requires the file name, byte size, content type (currently only application/pdf is supported), and a checksum calculated as a base64 encoded MD5 hash. The API responds with a signed_id and a direct_upload object containing the target URL and required HTTP headers.
    // Request
{
  "file_name": "test_file.pdf",
  "byte_size": 15584,
  "checksum": "ptCgPrKd1VRBr2hOeYNRWQ==",
  "content_type": "application/pdf"
}

// Response
{
  "signed_id": "eyJf(...)",
  "direct_upload": {
    "url": "https://app.shipmondo.com/active_storage/eyJf(...)",
    "headers": {
      "Content-Type": "application/pdf"
    }
  }
}