{
  "title": "Logistics API",
  "description": "Partners can place orders for products (terminals and other accessories) from Surfboard. As a partner, you can provide a product catalog containing a range of product options for merchants to choose from.",
  "endpoints": [
    {
      "fragment": "Create Shipment",
      "method": "POST",
      "link": "API_URL/partners/:partnerId/merchants/:merchantId/shipment"
    },
    {
      "fragment": "Get Shipment Status",
      "method": "GET",
      "link": "API_URL/partners/:partnerId/merchants/:merchantId/shipment/:orderId"
    },
    {
      "fragment": "List Manufactured Hardware",
      "method": "GET",
      "link": "API_URL/partners/:partnerId/manufactured-hardware"
    },
    {
      "fragment": "Change Merchant for Terminal",
      "method": "POST",
      "link": "API_URL/partners/:partnerId/change-merchant"
    },
    {
      "fragment": "Ship Manufactured Hardware",
      "method": "POST",
      "link": "API_URL/partners/:partnerId/merchants/:merchantId/ship-hardware"
    },
    {
      "fragment": "Ship Terminals in Bulk",
      "method": "POST",
      "link": "API_URL/partners/:partnerId/logistics/orders"
    },
    {
      "fragment": "Fetch Partner Orders",
      "method": "GET",
      "link": "API_URL/partners/:partnerId/logistics/orders"
    },
    {
      "fragment": "Create Return",
      "method": "POST",
      "link": "API_URL/partners/:partnerId/logistics/returns"
    },
    {
      "fragment": "Get Returns",
      "method": "GET",
      "link": "API_URL/partners/:partnerId/logistics/returns"
    },
    {
      "fragment": "Fetch Merchant Orders",
      "method": "GET",
      "link": "API_URL/merchants/:merchantId/logistics/orders"
    }
  ],
  "apis": [
    {
      "heading": "Create Shipment",
      "description": "Creates a shipment order for terminals and other accessories. Use this API to initiate an order to ship terminals and other accessories to merchants.",
      "reqParams": [
        {
          "name": "shippingAddress",
          "type": "object",
          "mandatory": false,
          "description": "Input the shipping address for the products. If no address is specified, the merchant's address will be used as the default shipping address.",
          "reqParams": [
            {
              "name": "name",
              "type": "string",
              "mandatory": true,
              "description": "Full name of the receiver for the shipment."
            },
            {
              "name": "addressLine1",
              "type": "string",
              "mandatory": true,
              "description": "The first line of the receiver's address."
            },
            {
              "name": "addressLine2",
              "type": "string",
              "mandatory": false,
              "description": "The second line of the receiver's address."
            },
            {
              "name": "addressLine3",
              "type": "string",
              "mandatory": false,
              "description": "The third line of the receiver's address."
            },
            {
              "name": "city",
              "type": "string",
              "mandatory": true,
              "description": "City of the receiver"
            },
            {
              "name": "countryCode",
              "type": "string",
              "mandatory": true,
              "description": "Two-letter ISO country code of the receiver, in uppercase."
            },
            {
              "name": "postalCode",
              "type": "string",
              "mandatory": true,
              "description": "Postal code of the receiver."
            },
            {
              "name": "phoneNumber",
              "type": "object",
              "mandatory": false,
              "description": "Contact number of the receiver in code and number format.",
              "reqParams": [
                {
                  "name": "code",
                  "type": "string",
                  "mandatory": true,
                  "description": "International dialing code identifying the country or region."
                },
                {
                  "name": "number",
                  "type": "string",
                  "mandatory": true,
                  "description": "Phone number."
                }
              ]
            },
            {
              "name": "email",
              "type": "string",
              "mandatory": false,
              "description": "Email address of the receiver."
            },
            {
              "name": "deliveryInstruction",
              "type": "string",
              "mandatory": false,
              "description": "Delivery instructions for the carrier."
            }
          ]
        },
        {
          "name": "lineItems",
          "type": "array",
          "mandatory": true,
          "description": "An array of products to be shipped.",
          "reqParams": [
            {
              "name": "productId",
              "type": "string",
              "mandatory": true,
              "description": "The SurfboardProductId of the product or group of products. This is unique to the partner."
            },
            {
              "name": "quantity",
              "type": "number",
              "mandatory": true,
              "description": "Number of products or group of products to be shipped."
            },
            {
              "name": "billingPlanId",
              "type": "string",
              "mandatory": false,
              "description": "Optional billing plan for the product or group of products chosen. If omitted, default plan will be chosen."
            },
            {
              "name": "replacementFor",
              "type": "string",
              "mandatory": false,
              "description": "If this line item is placed as part of a replacement for an existing device, then the terminalId of the original device needs to be specified. We will supply the merchant with a waybill to return the old device. They can reuse the box which the new terminal comes in."
            }
          ]
        }
      ],
      "resParams": [
        {
          "name": "status",
          "type": "string",
          "mandatory": true,
          "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.."
        },
        {
          "name": "data",
          "type": "object",
          "mandatory": true,
          "description": "Response data",
          "resParams": [
            {
              "name": "orderId",
              "type": "string",
              "mandatory": true,
              "description": "Order ID for the order."
            }
          ]
        },
        {
          "name": "message",
          "type": "string",
          "mandatory": true,
          "description": "A message that describes the status of the request."
        }
      ],
      "method": "POST",
      "path": "/partners/:partnerId/merchants/:merchantId/shipment",
      "examples": {
        "request": {
          "headers": [
            {
              "name": "Content-Type",
              "value": "application/json"
            },
            {
              "name": "API-KEY",
              "value": "YOUR_API_KEY"
            },
            {
              "name": "API-SECRET",
              "value": "YOUR_API_SECRET"
            },
            {
              "name": "MERCHANT-ID",
              "value": "YOUR_MERCHANT_ID"
            }
          ],
          "body": "{\n\t\"shippingAddress\": {\n\t\t\"name\": \"John Doe\",\n\t\t\"addressLine1\": \"Main Street 123\",\n\t\t\"addressLine2\": \"Building C\",\n\t\t\"addressLine3\": \"Building C\",\n\t\t\"city\": \"Stockholm\",\n\t\t\"countryCode\": \"SE\",\n\t\t\"postalCode\": \"123 45\",\n\t\t\"phoneNumber\": {\n\t\t\t\"code\": \"46\",\n\t\t\t\"number\": \"771890089\"\n\t\t},\n\t\t\"email\": \"developer@test.se\",\n\t\t\"deliveryInstruction\": \"XXX\"\n\t},\n\t\"lineItems\": [\n\t\t{\n\t\t\t\"productId\": \"12345\",\n\t\t\t\"quantity\": 1\n\t\t}\n\t]\n}"
        },
        "response": [
          {
            "code": 201,
            "response": "\n{\n\t\"status\": \"SUCCESS\",\n\t\"data\": {\n\t\t\"orderId\": \"81376ad8ebedf80310\"\n\t},\n\t\"message\": \"Order for shipping terminal successfully created\"\n}"
          }
        ]
      }
    },
    {
      "heading": "Get Shipment Status",
      "description": "Retrieves the status of the shipment order. Use this API to get the shipment status of ordered terminals and other accessories.",
      "reqParams": [],
      "resParams": [
        {
          "name": "status",
          "type": "string",
          "mandatory": true,
          "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.."
        },
        {
          "name": "data",
          "type": "object",
          "mandatory": true,
          "description": "Response data",
          "resParams": [
            {
              "name": "orderStatus",
              "type": "string",
              "description": "Describes the status of the shipment order for terminals and accessories. The possible values are: ",
              "possibleValues": [
                {
                  "value": "ORDER_PLACED",
                  "description": "The order has been successfully placed."
                },
                {
                  "value": "ORDER_SHIPPED",
                  "description": "The order has been shipped and is in transit."
                },
                {
                  "value": "ORDER_COMPLETED",
                  "description": "The order has been successfully fulfilled and completed."
                },
                {
                  "value": "ORDER_PENDING_FOR_STOCK",
                  "description": "The order is pending processing due to stock availability."
                }
              ]
            },
            {
              "name": "trackingUrl",
              "type": "string",
              "description": "The tracking url of the shipment."
            },
            {
              "name": "trackingCode",
              "type": "string",
              "description": "The carrier's tracking code for the shipment."
            },
            {
              "name": "deliveryPartner",
              "type": "string",
              "description": "The partner or carrier responsible for delivering the shipment."
            },
            {
              "name": "packages",
              "type": "array",
              "description": "Specifies information about the products included in the shipment.",
              "resParams": [
                {
                  "name": "productId",
                  "type": "string",
                  "description": "The SurfboardProductId of the product or group of products. This is unique to the partner"
                },
                {
                  "name": "serialNumber",
                  "type": "string",
                  "description": "Serial number of the device."
                }
              ]
            }
          ]
        },
        {
          "name": "message",
          "type": "string",
          "mandatory": true,
          "description": "A message that describes the status of the request."
        }
      ],
      "method": "GET",
      "path": "/partners/:partnerId/merchants/:merchantId/shipment/:orderId",
      "examples": {
        "request": {
          "headers": [
            {
              "name": "Content-Type",
              "value": "application/json"
            },
            {
              "name": "API-KEY",
              "value": "YOUR_API_KEY"
            },
            {
              "name": "API-SECRET",
              "value": "YOUR_API_SECRET"
            },
            {
              "name": "MERCHANT-ID",
              "value": "YOUR_MERCHANT_ID"
            }
          ]
        },
        "response": [
          {
            "code": 200,
            "response": "\n{\n\t\"status\": \"SUCCESS\",\n\t\"data\": {\n\t\t\"orderStatus\": \"ORDER_PENDING_FOR_STOCK\",\n\t\t\"trackingUrl\": \"\",\n\t\t\"trackingCode\": \"\",\n\t\t\"deliveryPartner\": \"DHL\",\n\t\t\"packages\": [\n\t\t\t{\n\t\t\t\t\"productId\": \"817361bb0a23400701\",\n\t\t\t\t\"serialNumber\": \"\"\n\t\t\t}\n\t\t]\n\t},\n\t\"message\": \"Order status fetched successfully\"\n}"
          }
        ]
      }
    },
    {
      "heading": "List Manufactured Hardware",
      "description": "Retrieves the terminals and devices Surfboard has manufactured for a partner, together with their hardware, network, and software details. Narrow the results by serial number, terminal, device model or vendor, or the merchant a device is assigned to, and sort the list to build inventory reports or reconcile your device fleet.",
      "pagination": true,
      "query": "Page through results with the `x-page-number` request header. The total number of matching devices is returned in the `x-total-items` response header.",
      "reqParams": [
        {
          "name": "serialNo",
          "type": "string",
          "mandatory": false,
          "description": "Return only the device with this hardware serial number."
        },
        {
          "name": "terminalId",
          "type": "string",
          "mandatory": false,
          "description": "Return only the device provisioned as this terminal."
        },
        {
          "name": "deviceModel",
          "type": "string",
          "mandatory": false,
          "description": "Return only devices of this model, for example Surfpad."
        },
        {
          "name": "deviceVendor",
          "type": "string",
          "mandatory": false,
          "description": "Return only devices from this hardware vendor."
        },
        {
          "name": "merchantId",
          "type": "string",
          "mandatory": false,
          "description": "Return only devices currently assigned to this merchant."
        },
        {
          "name": "sortBy",
          "type": "string",
          "mandatory": false,
          "description": "The field to order the results by.",
          "possibleValues": [
            {
              "value": "createdAt",
              "description": "Sort by the date the device record was created."
            },
            {
              "value": "serialNo",
              "description": "Sort by hardware serial number."
            },
            {
              "value": "status",
              "description": "Sort by the device's current lifecycle status."
            }
          ]
        },
        {
          "name": "sortOrder",
          "type": "string",
          "mandatory": false,
          "description": "The direction to sort the results in.",
          "possibleValues": [
            {
              "value": "ASC",
              "description": "Sort in ascending order."
            },
            {
              "value": "DESC",
              "description": "Sort in descending order."
            }
          ]
        }
      ],
      "resParams": [
        {
          "name": "status",
          "type": "string",
          "mandatory": true,
          "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'."
        },
        {
          "name": "data",
          "type": "array",
          "mandatory": true,
          "description": "The manufactured devices on the current page.",
          "resParams": [
            {
              "name": "serialNo",
              "type": "string",
              "description": "Hardware serial number of the device."
            },
            {
              "name": "cpuSerialNumber",
              "type": "string",
              "description": "Serial number of the device's CPU."
            },
            {
              "name": "deviceSerialNumber",
              "type": "string",
              "description": "Manufacturer's device serial number."
            },
            {
              "name": "terminalId",
              "type": "string",
              "description": "Identifier of the terminal this device was provisioned as, once activated."
            },
            {
              "name": "merchantId",
              "type": "string",
              "description": "Identifier of the merchant the device is currently assigned to."
            },
            {
              "name": "deviceModel",
              "type": "string",
              "description": "Model of the device, for example Surfpad."
            },
            {
              "name": "deviceVendor",
              "type": "string",
              "description": "Hardware vendor that manufactured the device."
            },
            {
              "name": "osType",
              "type": "string",
              "description": "Operating system running on the device."
            },
            {
              "name": "osVersion",
              "type": "string",
              "description": "Operating system version installed on the device."
            },
            {
              "name": "adminVersion",
              "type": "string",
              "description": "Version of the Surfboard admin application installed on the device."
            },
            {
              "name": "pinpadVersion",
              "type": "string",
              "description": "Version of the PIN pad firmware installed on the device."
            },
            {
              "name": "softwareVersion",
              "type": "string",
              "description": "Version of the payment software installed on the device."
            },
            {
              "name": "imeiNumber",
              "type": "string",
              "description": "IMEI number of the device's cellular modem."
            },
            {
              "name": "imsiNumber",
              "type": "string",
              "description": "IMSI number of the SIM provisioned in the device."
            },
            {
              "name": "uiccid",
              "type": "string",
              "description": "ICCID of the SIM card provisioned in the device."
            },
            {
              "name": "status",
              "type": "string",
              "description": "Current lifecycle status of the device, for example whether it has been manufactured, shipped, or activated."
            },
            {
              "name": "lastOperation",
              "type": "string",
              "description": "The most recent operation performed on the device."
            },
            {
              "name": "manufacturedFor",
              "type": "string",
              "description": "Identifier of the partner the device was manufactured for."
            },
            {
              "name": "shippedTo",
              "type": "string",
              "description": "Identifier of the merchant or destination the device was shipped to."
            },
            {
              "name": "createdAt",
              "type": "string",
              "description": "When the device record was created, in ISO 8601 format."
            },
            {
              "name": "startDate",
              "type": "string",
              "description": "Start of the device's active service period."
            },
            {
              "name": "endDate",
              "type": "string",
              "description": "End of the device's active service period."
            },
            {
              "name": "createdBy",
              "type": "string",
              "description": "Identifier of the user or system that created the device record."
            },
            {
              "name": "createdFrom",
              "type": "string",
              "description": "The source or channel the device record was created from."
            },
            {
              "name": "updatedAt",
              "type": "string",
              "description": "When the device record was last updated, in ISO 8601 format."
            },
            {
              "name": "updatedBy",
              "type": "string",
              "description": "Identifier of the user or system that last updated the device record."
            },
            {
              "name": "updatedFrom",
              "type": "string",
              "description": "The source or channel the device record was last updated from."
            }
          ]
        },
        {
          "name": "message",
          "type": "string",
          "mandatory": true,
          "description": "A message that describes the status of the request."
        }
      ],
      "method": "GET",
      "path": "/partners/:partnerId/manufactured-hardware",
      "new": true,
      "examples": {
        "request": {
          "headers": [
            {
              "name": "API-KEY",
              "value": "YOUR_API_KEY"
            },
            {
              "name": "API-SECRET",
              "value": "YOUR_API_SECRET"
            },
            {
              "name": "x-page-number",
              "value": "1",
              "mandatory": false
            }
          ]
        },
        "response": [
          {
            "code": 200,
            "response": "{\n\t\"status\": \"SUCCESS\",\n\t\"data\": [\n\t\t{\n\t\t\t\"serialNo\": \"TERM001234567\",\n\t\t\t\"cpuSerialNumber\": \"CPU-8841207\",\n\t\t\t\"deviceSerialNumber\": \"DSN-55120983\",\n\t\t\t\"terminalId\": \"816a0ff6bc0fb00404\",\n\t\t\t\"merchantId\": \"m_iWGri3XAyTmkbKYsYtV47\",\n\t\t\t\"deviceModel\": \"Surfpad\",\n\t\t\t\"deviceVendor\": \"Sunmi\",\n\t\t\t\"osType\": \"Android\",\n\t\t\t\"osVersion\": \"11\",\n\t\t\t\"adminVersion\": \"3.4.1\",\n\t\t\t\"pinpadVersion\": \"1.2.0\",\n\t\t\t\"softwareVersion\": \"5.8.2\",\n\t\t\t\"imeiNumber\": \"356938035643809\",\n\t\t\t\"imsiNumber\": \"240080012345678\",\n\t\t\t\"uiccid\": \"8946071512345678901\",\n\t\t\t\"status\": \"SHIPPED\",\n\t\t\t\"manufacturedFor\": \"8113d3f8403b380409\",\n\t\t\t\"shippedTo\": \"m_iWGri3XAyTmkbKYsYtV47\",\n\t\t\t\"createdAt\": \"2026-06-01T09:24:11.000Z\",\n\t\t\t\"startDate\": \"2026-06-02\",\n\t\t\t\"endDate\": \"2027-06-02\"\n\t\t}\n\t],\n\t\"message\": \"Manufactured hardware fetched successfully\"\n}"
          },
          {
            "code": 400,
            "response": "{\n\t\"status\": \"ERROR\",\n\t\"message\": \"Unable to fetch manufactured hardware\"\n}"
          },
          {
            "code": 401,
            "response": "{\n\t\"status\": \"ERROR\",\n\t\"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}"
          }
        ]
      },
      "params": {
        "serialNo": "TERM001234567",
        "terminalId": "816a0ff6bc0fb00404",
        "deviceModel": "Surfpad",
        "deviceVendor": "Sunmi",
        "merchantId": "m_iWGri3XAyTmkbKYsYtV47",
        "sortBy": "createdAt",
        "sortOrder": "DESC"
      }
    },
    {
      "heading": "Change Merchant for Terminal",
      "description": "Reassigns an already-shipped terminal to a different merchant. Use this when a device needs to be moved from one merchant to another, for example when hardware is redeployed across your merchant portfolio.",
      "reqParams": [
        {
          "name": "serialNo",
          "type": "string",
          "mandatory": true,
          "description": "Serial number of the terminal to reassign."
        },
        {
          "name": "targetMerchantId",
          "type": "string",
          "mandatory": true,
          "description": "Identifier of the merchant the terminal should be reassigned to."
        }
      ],
      "resParams": [
        {
          "name": "status",
          "type": "string",
          "mandatory": true,
          "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'."
        },
        {
          "name": "message",
          "type": "string",
          "mandatory": true,
          "description": "A message that describes the status of the request."
        }
      ],
      "method": "POST",
      "path": "/partners/:partnerId/change-merchant",
      "new": true,
      "examples": {
        "request": {
          "headers": [
            {
              "name": "Content-Type",
              "value": "application/json"
            },
            {
              "name": "API-KEY",
              "value": "YOUR_API_KEY"
            },
            {
              "name": "API-SECRET",
              "value": "YOUR_API_SECRET"
            }
          ],
          "body": "{\n\t\"serialNo\": \"TERM001234567\",\n\t\"targetMerchantId\": \"m_iWGri3XAyTmkbKYsYtV47\"\n}"
        },
        "response": [
          {
            "code": 200,
            "response": "{\n\t\"status\": \"SUCCESS\",\n\t\"message\": \"Merchant changed for terminal successfully\"\n}"
          },
          {
            "code": 400,
            "response": "{\n\t\"status\": \"ERROR\",\n\t\"message\": \"Unable to change merchant for the terminal\"\n}"
          },
          {
            "code": 401,
            "response": "{\n\t\"status\": \"ERROR\",\n\t\"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}"
          }
        ]
      }
    },
    {
      "heading": "Ship Manufactured Hardware",
      "description": "Activates and ships a manufactured device to a specific merchant. Provide the device's serial number and the target merchant is taken from the path to hand the terminal over to that merchant.",
      "reqParams": [
        {
          "name": "serialNo",
          "type": "string",
          "mandatory": true,
          "description": "Serial number of the manufactured device to ship and activate for the merchant."
        }
      ],
      "resParams": [
        {
          "name": "status",
          "type": "string",
          "mandatory": true,
          "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'."
        },
        {
          "name": "message",
          "type": "string",
          "mandatory": true,
          "description": "A message that describes the status of the request."
        }
      ],
      "method": "POST",
      "path": "/partners/:partnerId/merchants/:merchantId/ship-hardware",
      "new": true,
      "examples": {
        "request": {
          "headers": [
            {
              "name": "Content-Type",
              "value": "application/json"
            },
            {
              "name": "API-KEY",
              "value": "YOUR_API_KEY"
            },
            {
              "name": "API-SECRET",
              "value": "YOUR_API_SECRET"
            },
            {
              "name": "MERCHANT-ID",
              "value": "YOUR_MERCHANT_ID"
            }
          ],
          "body": "{\n\t\"serialNo\": \"TERM001234567\"\n}"
        },
        "response": [
          {
            "code": 200,
            "response": "{\n\t\"status\": \"SUCCESS\",\n\t\"message\": \"Manufactured hardware shipped successfully\"\n}"
          },
          {
            "code": 400,
            "response": "{\n\t\"status\": \"ERROR\",\n\t\"message\": \"Unable to ship the terminal\"\n}"
          },
          {
            "code": 401,
            "response": "{\n\t\"status\": \"ERROR\",\n\t\"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}"
          }
        ]
      }
    },
    {
      "heading": "Ship Terminals in Bulk",
      "description": "Creates bulk shipment orders for terminals and other accessories to partners. Use this API to initiate orders to ship multiple terminals and accessories in bulk.",
      "reqParams": [
        {
          "name": "shippingAddress",
          "type": "object",
          "mandatory": false,
          "description": "Shipping address for the bulk order.",
          "reqParams": [
            {
              "name": "name",
              "type": "string",
              "mandatory": true,
              "description": "Full name of the receiver for the shipment."
            },
            {
              "name": "addressLine1",
              "type": "string",
              "mandatory": true,
              "description": "The first line of the receiver's address."
            },
            {
              "name": "addressLine2",
              "type": "string",
              "mandatory": false,
              "description": "The second line of the receiver's address."
            },
            {
              "name": "addressLine3",
              "type": "string",
              "mandatory": false,
              "description": "The third line of the receiver's address."
            },
            {
              "name": "city",
              "type": "string",
              "mandatory": true,
              "description": "City of the receiver."
            },
            {
              "name": "countryCode",
              "type": "string",
              "mandatory": true,
              "description": "Two-letter ISO country code of the receiver, in uppercase."
            },
            {
              "name": "postalCode",
              "type": "string",
              "mandatory": true,
              "description": "Postal code of the receiver."
            },
            {
              "name": "phoneNumber",
              "type": "object",
              "mandatory": false,
              "description": "Contact number of the receiver in code and number format.",
              "reqParams": [
                {
                  "name": "code",
                  "type": "string",
                  "mandatory": true,
                  "description": "International dialing code identifying the country or region."
                },
                {
                  "name": "number",
                  "type": "string",
                  "mandatory": true,
                  "description": "Phone number."
                }
              ]
            },
            {
              "name": "email",
              "type": "string",
              "mandatory": false,
              "description": "Email address of the receiver."
            },
            {
              "name": "deliveryInstruction",
              "type": "string",
              "mandatory": false,
              "description": "Delivery instructions for the carrier."
            }
          ]
        },
        {
          "name": "lineItems",
          "type": "array",
          "mandatory": true,
          "description": "An array of products to be shipped in bulk.",
          "reqParams": [
            {
              "name": "productId",
              "type": "string",
              "mandatory": true,
              "description": "The SurfboardProductId of the product or group of products."
            },
            {
              "name": "quantity",
              "type": "number",
              "mandatory": true,
              "description": "Number of products or group of products to be shipped."
            },
            {
              "name": "billingPlanId",
              "type": "string",
              "mandatory": false,
              "description": "Optional billing plan for the product or group of products chosen."
            },
            {
              "name": "replacementFor",
              "type": "string",
              "mandatory": false,
              "description": "If this line item is placed as part of a replacement for an existing device, then the terminalId of the original device needs to be specified."
            }
          ]
        }
      ],
      "resParams": [
        {
          "name": "status",
          "type": "string",
          "mandatory": true,
          "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'."
        },
        {
          "name": "data",
          "type": "object",
          "mandatory": true,
          "description": "Response data",
          "resParams": [
            {
              "name": "orderId",
              "type": "string",
              "mandatory": true,
              "description": "Order ID for the bulk order."
            }
          ]
        },
        {
          "name": "message",
          "type": "string",
          "mandatory": true,
          "description": "A message that describes the status of the request."
        }
      ],
      "method": "POST",
      "path": "/partners/:partnerId/logistics/orders",
      "new": true,
      "examples": {
        "request": {
          "headers": [
            {
              "name": "Content-Type",
              "value": "application/json"
            },
            {
              "name": "API-KEY",
              "value": "YOUR_API_KEY"
            },
            {
              "name": "API-SECRET",
              "value": "YOUR_API_SECRET"
            }
          ],
          "body": "{\n  \"shippingAddress\": {\n    \"name\": \"Jane Smith\",\n    \"addressLine1\": \"456 Business Ave\",\n    \"addressLine2\": \"Floor 2\",\n    \"city\": \"Stockholm\",\n    \"countryCode\": \"SE\",\n    \"postalCode\": \"12345\"\n  },\n  \"lineItems\": [\n    {\n      \"productId\": \"81bddf38fa28380101\",\n      \"quantity\": 5,\n      \"billingPlanId\": \"BP_001\",\n      \"replacementFor\": \"82674cfdf77f500001\"\n    }\n  ]\n}"
        },
        "response": [
          {
            "code": 201,
            "response": "{\n  \"status\": \"SUCCESS\",\n  \"data\": {\n    \"orderId\": \"83992e47b219100f28\"\n  },\n  \"message\": \"Bulk logistic order created successfully\"\n}"
          }
        ]
      }
    },
    {
      "heading": "Fetch Partner Orders",
      "description": "Retrieves all orders placed by a partner for terminals and accessories. Use this API to get the status and details of all orders under a partner.",
      "reqParams": [],
      "resParams": [
        {
          "name": "status",
          "type": "string",
          "mandatory": true,
          "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'."
        },
        {
          "name": "data",
          "type": "array",
          "mandatory": true,
          "description": "Array of order objects.",
          "resParams": [
            {
              "name": "orderId",
              "type": "string",
              "description": "Unique identifier for the order."
            },
            {
              "name": "trackingUrl",
              "type": "string",
              "description": "The tracking URL of the shipment."
            },
            {
              "name": "trackingCode",
              "type": "string",
              "description": "The carrier's tracking code for the shipment."
            },
            {
              "name": "merchantId",
              "type": "string",
              "description": "Identifier of the merchant the order was placed for."
            },
            {
              "name": "deliveryPartner",
              "type": "string",
              "description": "The partner or carrier responsible for delivering the shipment."
            },
            {
              "name": "status",
              "type": "string",
              "description": "Current status of the order."
            },
            {
              "name": "packages",
              "type": "array",
              "description": "Array of package details in the order.",
              "resParams": [
                {
                  "name": "productId",
                  "type": "string",
                  "description": "The SurfboardProductId of the product."
                },
                {
                  "name": "serialNumber",
                  "type": "string",
                  "description": "Serial number of the device."
                }
              ]
            }
          ]
        },
        {
          "name": "message",
          "type": "string",
          "mandatory": true,
          "description": "A message that describes the status of the request."
        }
      ],
      "method": "GET",
      "path": "/partners/:partnerId/logistics/orders",
      "new": true,
      "examples": {
        "request": {
          "headers": [
            {
              "name": "Content-Type",
              "value": "application/json"
            },
            {
              "name": "API-KEY",
              "value": "YOUR_API_KEY"
            },
            {
              "name": "API-SECRET",
              "value": "YOUR_API_SECRET"
            }
          ]
        },
        "response": [
          {
            "code": 200,
            "response": "{\n  \"status\": \"SUCCESS\",\n  \"data\": [\n    {\n      \"orderId\": \"8190422d77e1400428\",\n      \"trackingUrl\": \"\",\n      \"trackingCode\": \"\",\n      \"merchantId\": \"m_iWGri3XAyTmkbKYsYtV47\",\n      \"status\": \"ORDER_CANCELLED\",\n      \"deliveryPartner\": \"DHL\",\n      \"packages\": [\n        {\n          \"productId\": \"817361bb0a23400701\",\n          \"serialNumber\": \"\"\n        }\n      ]\n    },\n    {\n      \"orderId\": \"819118d10a3d900f28\",\n      \"trackingUrl\": \"\",\n      \"trackingCode\": \"\",\n      \"merchantId\": \"m_iWGri3XAyTmkbKYsYtV47\",\n      \"status\": \"ORDER_CANCELLED\",\n      \"deliveryPartner\": \"DHL\",\n      \"packages\": [\n        {\n          \"productId\": \"817361bb0a23400701\",\n          \"serialNumber\": \"\"\n        }\n      ]\n    }\n  ],\n  \"message\": \"Orders fetched successfully\"\n}"
          }
        ]
      }
    },
    {
      "heading": "Create Return",
      "description": "Creates a return request for terminals using the API. This enhanced version allows for more detailed merchant information and multiple return order lines.",
      "reqParams": [
        {
          "name": "merchantInfo",
          "type": "object",
          "mandatory": true,
          "description": "Detailed merchant information for the return request.",
          "reqParams": [
            {
              "name": "name",
              "type": "string",
              "mandatory": true,
              "description": "Name of the merchant."
            },
            {
              "name": "email",
              "type": "string",
              "mandatory": true,
              "description": "Email address of the merchant."
            },
            {
              "name": "phoneNumber",
              "type": "object",
              "mandatory": true,
              "description": "Contact number of the merchant in code and number format.",
              "reqParams": [
                {
                  "name": "code",
                  "type": "string",
                  "mandatory": true,
                  "description": "International dialing code identifying the country or region."
                },
                {
                  "name": "number",
                  "type": "string",
                  "mandatory": true,
                  "description": "Phone number."
                }
              ]
            },
            {
              "name": "addressLine1",
              "type": "string",
              "mandatory": true,
              "description": "First line of the merchant's address."
            },
            {
              "name": "addressLine2",
              "type": "string",
              "mandatory": false,
              "description": "Second line of the merchant's address."
            },
            {
              "name": "addressLine3",
              "type": "string",
              "mandatory": false,
              "description": "Third line of the merchant's address."
            },
            {
              "name": "countryCode",
              "type": "string",
              "mandatory": true,
              "description": "Two-letter ISO country code in uppercase."
            },
            {
              "name": "postalNumber",
              "type": "string",
              "mandatory": true,
              "description": "Postal code of the merchant's address."
            },
            {
              "name": "city",
              "type": "string",
              "mandatory": true,
              "description": "City of the merchant's address."
            }
          ]
        },
        {
          "name": "returnOrderLines",
          "type": "array",
          "mandatory": true,
          "description": "Array of return order line items.",
          "reqParams": [
            {
              "name": "serial",
              "type": "string",
              "mandatory": true,
              "description": "Serial number of the terminal to be returned."
            },
            {
              "name": "merchantId",
              "type": "string",
              "mandatory": false,
              "description": "Unique identifier of the merchant. Provide both merchantId and terminalId for a registered terminal, or omit both to return an unregistered terminal."
            },
            {
              "name": "terminalId",
              "type": "string",
              "mandatory": false,
              "description": "Unique identifier of the terminal. Provide both terminalId and merchantId for a registered terminal, or omit both to return an unregistered terminal."
            },
            {
              "name": "reasonForReturn",
              "type": "string",
              "mandatory": true,
              "description": "Reason for the return.",
              "possibleValues": [
                {
                  "value": "WARRANTY",
                  "description": "The warranty covers issues potentially related to factory defects."
                },
                {
                  "value": "NOT_USING_SERVICE",
                  "description": "Not using service applies when the merchant voluntarily leaves or their partner ends the partnership."
                },
                {
                  "value": "NON_WARRANTY_BROKEN",
                  "description": "Non-warranty broken applies when the terminal is damaged due to misuse or accident."
                },
                {
                  "value": "TECHNICAL_ISSUES",
                  "description": "Technical issues apply when the terminal's software malfunctions."
                },
                {
                  "value": "COMPATIBILITY_ISSUES",
                  "description": "Compatibility issues occur when the terminal doesn't pair with the merchant's POS system."
                }
              ]
            },
            {
              "name": "stopBilling",
              "type": "boolean",
              "mandatory": false,
              "description": "Whether to stop billing for this terminal."
            },
            {
              "name": "comment",
              "type": "string",
              "mandatory": false,
              "description": "Additional comments regarding the return."
            }
          ]
        },
        {
          "name": "deliveryInstruction",
          "type": "string",
          "mandatory": false,
          "description": "Delivery instructions for the carrier."
        }
      ],
      "resParams": [
        {
          "name": "status",
          "type": "string",
          "mandatory": true,
          "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'."
        },
        {
          "name": "data",
          "type": "object",
          "mandatory": true,
          "description": "Response data",
          "resParams": [
            {
              "name": "returnId",
              "type": "number",
              "mandatory": true,
              "description": "ID of the return request."
            }
          ]
        },
        {
          "name": "message",
          "type": "string",
          "mandatory": true,
          "description": "A message that describes the status of the request."
        }
      ],
      "method": "POST",
      "path": "/partners/:partnerId/logistics/returns",
      "new": true,
      "examples": {
        "request": {
          "headers": [
            {
              "name": "Content-Type",
              "value": "application/json"
            },
            {
              "name": "API-KEY",
              "value": "YOUR_API_KEY"
            },
            {
              "name": "API-SECRET",
              "value": "YOUR_API_SECRET"
            }
          ],
          "body": "{\n  \"merchantInfo\": {\n    \"name\": \"Demo Store\",\n    \"email\": \"demo@example.com\",\n    \"phoneNumber\": {\n      \"code\": \"46\",\n      \"number\": \"123456789\"\n    },\n    \"addressLine1\": \"Demo Street 123\",\n    \"addressLine2\": \"Building A\",\n    \"addressLine3\": null,\n    \"city\": \"Stockholm\",\n    \"countryCode\": \"SE\",\n    \"postalNumber\": \"12345\"\n  },\n  \"returnOrderLines\": [\n    {\n      \"serial\": \"TERM001234567\",\n      \"terminalId\": \"816a0ff6bc0fb00404\",\n      \"reasonForReturn\": \"NOT_USING_SERVICE\",\n      \"stopBilling\": true,\n      \"comment\": \"Device not working properly\"\n    }\n  ],\n  \"deliveryInstruction\": \"Please call before delivery\"\n}"
        },
        "response": [
          {
            "code": 201,
            "response": "{\n  \"status\": \"SUCCESS\",\n  \"data\": {\n    \"returnId\": 80\n  },\n  \"message\": \"Return request created successfully\"\n}"
          }
        ]
      }
    },
    {
      "heading": "Get Returns",
      "description": "Retrieves return requests for a specific merchant using the API. Supports filtering by status and provides detailed return information.",
      "pagination": true,
      "query": "To filter returns by status send in `filter` as query param",
      "reqParams": [
        {
          "name": "filter",
          "type": "string",
          "mandatory": false,
          "description": "Filter returns by status.",
          "possibleValues": [
            {
              "value": "APPROVED",
              "description": "Returns that have been approved for processing."
            },
            {
              "value": "CREATED",
              "description": "Returns that have been created but not yet processed."
            }
          ]
        }
      ],
      "resParams": [
        {
          "name": "status",
          "type": "string",
          "mandatory": true,
          "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'."
        },
        {
          "name": "data",
          "type": "array",
          "mandatory": true,
          "description": "Array of return request objects.",
          "resParams": [
            {
              "name": "returnId",
              "type": "number",
              "description": "Unique identifier for the return request."
            },
            {
              "name": "partnerId",
              "type": "string",
              "description": "Unique identifier of the partner."
            },
            {
              "name": "merchantName",
              "type": "string",
              "description": "Name of the merchant."
            },
            {
              "name": "merchantEmail",
              "type": "string",
              "description": "Email address of the merchant."
            },
            {
              "name": "merchantPhone",
              "type": "string",
              "description": "Phone number of the merchant."
            },
            {
              "name": "merchantAddressLine1",
              "type": "string",
              "description": "First line of the merchant's address."
            },
            {
              "name": "merchantAddressLine2",
              "type": "string",
              "description": "Second line of the merchant's address."
            },
            {
              "name": "merchantAddressLine3",
              "type": "string",
              "description": "Third line of the merchant's address."
            },
            {
              "name": "merchantCity",
              "type": "string",
              "description": "City of the merchant's address."
            },
            {
              "name": "merchantPostalNumber",
              "type": "string",
              "description": "Postal code of the merchant's address."
            },
            {
              "name": "merchantCountryCode",
              "type": "string",
              "description": "Country code of the merchant's address."
            },
            {
              "name": "deliveryInstruction",
              "type": "string",
              "description": "Delivery instructions for the return."
            },
            {
              "name": "status",
              "type": "string",
              "description": "Current status of the return request.",
              "possibleValues": [
                {
                  "value": "APPROVED",
                  "description": "The return request has been approved for processing."
                },
                {
                  "value": "CREATED",
                  "description": "The return request has been created but not yet processed."
                }
              ]
            },
            {
              "name": "returnOrderLines",
              "type": "array",
              "description": "Array of return order line items.",
              "resParams": [
                {
                  "name": "returnOrderlineId",
                  "type": "number",
                  "description": "Unique identifier for the return order line."
                },
                {
                  "name": "returnId",
                  "type": "number",
                  "description": "ID of the parent return request."
                },
                {
                  "name": "serial",
                  "type": "string",
                  "description": "Serial number of the terminal."
                },
                {
                  "name": "terminalId",
                  "type": "string",
                  "description": "Unique identifier of the terminal."
                },
                {
                  "name": "merchantId",
                  "type": "string",
                  "description": "Unique identifier of the merchant."
                },
                {
                  "name": "deviceModel",
                  "type": "string",
                  "description": "Model of the device being returned."
                },
                {
                  "name": "reasonForReturn",
                  "type": "string",
                  "description": "Reason for the return."
                },
                {
                  "name": "stopBilling",
                  "type": "boolean",
                  "description": "Whether billing has been stopped for this terminal."
                },
                {
                  "name": "comment",
                  "type": "string",
                  "description": "Additional comments regarding the return."
                },
                {
                  "name": "isUnregistered",
                  "type": "boolean",
                  "description": "Whether this line was created for an unregistered terminal, one with no associated terminal or merchant."
                }
              ]
            }
          ]
        },
        {
          "name": "message",
          "type": "string",
          "mandatory": true,
          "description": "A message that describes the status of the request."
        },
        {
          "name": "totalCount",
          "type": "number",
          "mandatory": true,
          "description": "Total count of return requests matching the criteria."
        }
      ],
      "method": "GET",
      "path": "/partners/:partnerId/logistics/returns",
      "new": true,
      "examples": {
        "request": {
          "headers": [
            {
              "name": "Content-Type",
              "value": "application/json"
            },
            {
              "name": "API-KEY",
              "value": "YOUR_API_KEY"
            },
            {
              "name": "API-SECRET",
              "value": "YOUR_API_SECRET"
            },
            {
              "name": "MERCHANT-ID",
              "value": "YOUR_MERCHANT_ID"
            }
          ]
        },
        "response": [
          {
            "code": 200,
            "response": "{\n  \"status\": \"SUCCESS\",\n  \"data\": [\n    {\n      \"returnId\": 80,\n      \"partnerId\": \"8113d3f8403b380409\",\n      \"merchantName\": \"Demo Store\",\n      \"merchantEmail\": \"demo@example.com\",\n      \"merchantPhone\": \"+46123456789\",\n      \"merchantAddressLine1\": \"Demo Street 123\",\n      \"merchantAddressLine2\": \"Building A\",\n      \"merchantAddressLine3\": \"\",\n      \"merchantCity\": \"Stockholm\",\n      \"merchantPostalNumber\": \"12345\",\n      \"merchantCountryCode\": \"SE\",\n      \"deliveryInstruction\": \"Please call before delivery\",\n      \"status\": \"CREATED\",\n      \"returnOrderLines\": [\n        {\n          \"returnOrderlineId\": 78,\n          \"returnId\": 80,\n          \"serial\": \"TERM001234567\",\n          \"terminalId\": \"816a0ff6bc0fb00404\",\n          \"merchantId\": \"m_iWGri3XAyTmkbKYsYtV47\",\n          \"deviceModel\": \"Surfpad\",\n          \"reasonForReturn\": \"NOT_USING_SERVICE\",\n          \"stopBilling\": true,\n          \"comment\": \"Device not working properly\",\n          \"isUnregistered\": false\n        }\n      ]\n    }\n  ],\n  \"message\": \"Return requests gotten successfully\"\n}"
          }
        ]
      }
    },
    {
      "heading": "Fetch Merchant Orders",
      "description": "Retrieves all orders placed for a specific merchant. Use this API to get the status and details of all orders for a particular merchant.",
      "reqParams": [],
      "resParams": [
        {
          "name": "status",
          "type": "string",
          "mandatory": true,
          "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'."
        },
        {
          "name": "data",
          "type": "array",
          "mandatory": true,
          "description": "Array of order objects for the merchant.",
          "resParams": [
            {
              "name": "orderId",
              "type": "string",
              "description": "Unique identifier for the order."
            },
            {
              "name": "trackingUrl",
              "type": "string",
              "description": "The tracking URL of the shipment."
            },
            {
              "name": "trackingCode",
              "type": "string",
              "description": "The carrier's tracking code for the shipment."
            },
            {
              "name": "status",
              "type": "string",
              "description": "Current status of the order."
            },
            {
              "name": "deliveryPartner",
              "type": "string",
              "description": "The partner or carrier responsible for delivering the shipment."
            },
            {
              "name": "packages",
              "type": "array",
              "description": "Array of package details in the order.",
              "resParams": [
                {
                  "name": "productId",
                  "type": "string",
                  "description": "The SurfboardProductId of the product."
                },
                {
                  "name": "serialNumber",
                  "type": "string",
                  "description": "Serial number of the device."
                }
              ]
            }
          ]
        },
        {
          "name": "message",
          "type": "string",
          "mandatory": true,
          "description": "A message that describes the status of the request."
        }
      ],
      "method": "GET",
      "path": "/merchants/:merchantId/logistics/orders",
      "new": true,
      "examples": {
        "request": {
          "headers": [
            {
              "name": "Content-Type",
              "value": "application/json"
            },
            {
              "name": "API-KEY",
              "value": "YOUR_API_KEY"
            },
            {
              "name": "API-SECRET",
              "value": "YOUR_API_SECRET"
            },
            {
              "name": "MERCHANT-ID",
              "value": "YOUR_MERCHANT_ID"
            }
          ]
        },
        "response": [
          {
            "code": 200,
            "response": "{\n  \"status\": \"SUCCESS\",\n  \"data\": [\n    {\n      \"orderId\": \"8190422d77e1400428\",\n      \"trackingUrl\": \"\",\n      \"trackingCode\": \"\",\n      \"status\": \"ORDER_CANCELLED\",\n      \"deliveryPartner\": \"DHL\",\n      \"packages\": [\n        {\n          \"productId\": \"817361bb0a23400701\",\n          \"serialNumber\": \"\"\n        }\n      ]\n    },\n    {\n      \"orderId\": \"819118d10a3d900f28\",\n      \"trackingUrl\": \"\",\n      \"trackingCode\": \"\",\n      \"status\": \"ORDER_CANCELLED\",\n      \"deliveryPartner\": \"DHL\",\n      \"packages\": [\n        {\n          \"productId\": \"817361bb0a23400701\",\n          \"serialNumber\": \"\"\n        }\n      ]\n    }\n  ],\n  \"message\": \"Orders fetched successfully\"\n}"
          }
        ]
      }
    }
  ]
}