Orders & logistics

When you move to Ultineo with years of sales recorded in another system, these endpoints let your migration or sync tool bring the whole history into your shop — customers, orders with their lines, payments, shipments, carrier claims, refused parcels, refunds, returns, loyalty wallet movements and support requests with their messages — keeping the original dates, then read back any record to check it.

Every import follows the shared contract described in Your first API call: an items list, an optional dry_run, and a line-by-line report. Every record is recognised by its external_id — its reference in your former system — so sending it again updates it instead of creating a duplicate.

Endpoints

Import in this order, because each record refers to the previous ones: customers, then orders, then payments and shipments, then refunds, returns, carrier claims, refused parcels, wallet movements and support requests. A record that refers to one not imported yet is refused, with a reason naming the missing reference.

What every resource shares

• Dates (created_at, placed_at, shipped_at…) are Unix timestamps in seconds. The created_at you send is kept as the record's original date and is never changed by a later import. When you leave it out, most resources use the closest date they know, such as the order's date.
• Links to other records use their external_id: customer_external_id, order_external_id, shipment_external_id, and so on.
• Statuses are checked against the exact values listed below, in lower case. A record withdrawn in your workspace keeps its status: an import never brings it back, and a notice says so.
• Reading a record: GET with ?external_id= (its reference in your former system) or ?id= (its identifier in your shop). With neither, the call answers 400; a record that is not in your shop answers 404.

Customers

A customer is a buyer of your shop, with a billing and a delivery address. Import customers first: every other record of this page refers to them.

Import customers

POST /v1/customer/import

Each address holds line1, line2 (up to 190 characters), city (up to 120), postal_code (up to 30), state (up to 120) and country_iso — a two-letter country code such as fr.

curl https://api.ultineo.com/v1/customer/import \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "C1001",
        "created_at": 1717236000,
        "first_name": "Claire",
        "last_name": "Martin",
        "email": "claire.martin@example.com",
        "email_verified": true,
        "phone": "+33 6 12 34 56 78",
        "delivery": {
          "line1": "12 rue des Lilas",
          "line2": "",
          "city": "Lyon",
          "postal_code": "69003",
          "state": "",
          "country_iso": "fr"
        }
      }
    ]
  }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "resource": "customer",
    "dry_run": false,
    "data": [
      { "index": 0, "external_id": "C1001", "action": "created", "id": "cust_c3e9a1074b5d28f6e0a7", "code": null, "title": null, "reason": null, "notice": ["blank billing initialized from delivery"] }
    ],
    "created": 1,
    "updated": 0,
    "unchanged": 0,
    "refused": 0,
    "total": 1
  }
}

Read a customer

GET /v1/customer/import

With neither, the call answers 400 Name the customer to read: ?external_id=… or /v1/customer/cust_….; an unknown customer answers 404 Customer not found.

curl "https://api.ultineo.com/v1/customer/import?external_id=C1001" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "cust_c3e9a1074b5d28f6e0a7",
    "object": "customer",
    "external_id": "C1001",
    "status": "activated",
    "type": "individual",
    "first_name": "Claire",
    "last_name": "Martin",
    "name": "Claire Martin",
    "company": "",
    "email": "claire.martin@example.com",
    "email_verified": true,
    "phone": "+33 6 12 34 56 78",
    "has_password": false,
    "note": "",
    "billing": { "line1": "12 rue des Lilas", "line2": "", "city": "Lyon", "postal_code": "69003", "state": "", "country_iso": "fr" },
    "delivery": { "line1": "12 rue des Lilas", "line2": "", "city": "Lyon", "postal_code": "69003", "state": "", "country_iso": "fr" },
    "created_at": 1717236000,
    "updated_at": 1791745200
  }
}

The password itself is never returned; has_password says whether one is set.

Orders

An order is imported with all its lines in one item, and keeps its original dates. Totals are stored as you send them and are never recalculated: when the total does not match the articles, delivery and discount amounts, the report tells you in amount_check.

Import orders

POST /v1/order/import

Each entry of items:

An order is saved with all its lines or not at all: one invalid line refuses the whole order. Lines you leave out of a later import are kept.

Each accepted entry of the report adds:

curl https://api.ultineo.com/v1/order/import \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "ORD-10458",
        "customer_external_id": "C1001",
        "order_number": "10458",
        "status": "delivered",
        "currency": "EUR",
        "channel": "online",
        "articles_amount": "459.00",
        "delivery_amount": "0.00",
        "discount_amount": "15.00",
        "total_amount": "444.00",
        "discount_code": "SPRING15",
        "placed_at": 1781258400,
        "delivered_at": 1781431200,
        "items": [
          { "external_id": "ORD-10458-1", "sku": "IP13-128-MID", "name": "iPhone 13 128 GB Midnight", "grade": "very_good", "quantity": 1, "unit_price": "459.00", "line_total": "459.00" }
        ]
      }
    ]
  }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "resource": "order",
    "dry_run": false,
    "data": [
      {
        "index": 0,
        "external_id": "ORD-10458",
        "action": "created",
        "id": "ordr_5e0a8c2f71d94b36e1c8",
        "code": null,
        "title": null,
        "reason": null,
        "notice": [],
        "items": { "created": 1, "updated": 0, "unchanged": 0 },
        "items_detail": [
          { "external_id": "ORD-10458-1", "action": "created", "id": "oitm_8a3f0e6c2d1b47e95c20" }
        ],
        "amount_check": null
      }
    ],
    "created": 1,
    "updated": 0,
    "unchanged": 0,
    "refused": 0,
    "total": 1
  }
}

Read an order

GET /v1/order/import

With neither, the call answers 400 Missing required parameter: external_id.; an unknown order answers 404 Order not found.

curl "https://api.ultineo.com/v1/order/import?external_id=ORD-10458" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "ordr_5e0a8c2f71d94b36e1c8",
    "object": "order",
    "external_id": "ORD-10458",
    "project": "proj_5a91c7e03d2b48f6a1e9",
    "status": "activated",
    "commercial_status": "delivered",
    "reference": "10458",
    "customer": "cust_c3e9a1074b5d28f6e0a7",
    "customer_external_id": "C1001",
    "si_code": "",
    "currency": "EUR",
    "channel": "online",
    "articles_amount": "459.00",
    "delivery_amount": "0.00",
    "discount_amount": "15.00",
    "discount_code": "SPRING15",
    "total_amount": "444.00",
    "note": "",
    "placed_at": 1781258400,
    "delivered_at": 1781431200,
    "ship_before_at": 0,
    "created_at": 1781258400,
    "updated_at": 1791745200,
    "items": [
      {
        "id": "oitm_8a3f0e6c2d1b47e95c20",
        "object": "order_item",
        "external_id": "ORD-10458-1",
        "status": "activated",
        "product": "prod_a81f3c6e0b2d49e7c5f0",
        "sku": "IP13-128-MID",
        "name": "iPhone 13 128 GB Midnight",
        "grade": "very_good",
        "serial": "",
        "quantity": 1,
        "unit_price": "459.00",
        "line_total": "459.00",
        "delivery_amount": "0.00",
        "warranty_amount": "0.00",
        "currency": "EUR",
        "created_at": 1781258400,
        "updated_at": 1791745200
      }
    ]
  }
}

commercial_status is the order's commercial status; status is the state of the record itself. ship_before_at is the shipping deadline your shop computes; it is read-only.

Payments

A payment settles an order. Its gateway (the payment processor) and its method (how the buyer paid) are two separate fields.

Import payments

POST /v1/payment/import

curl https://api.ultineo.com/v1/payment/import \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "PAY-77120",
        "order_external_id": "ORD-10458",
        "created_at": 1781258460,
        "status": "paid",
        "amount": "444.00",
        "fee_amount": "6.66",
        "currency": "EUR",
        "method": "card",
        "gateway": "stripe",
        "reference": "pi_3PZ0d2KJ8nA1",
        "paid_at": 1781258460
      }
    ]
  }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "resource": "payment",
    "dry_run": false,
    "data": [
      { "index": 0, "external_id": "PAY-77120", "action": "created", "id": "paym_2b7d9e04c1a35f8e6d91", "code": null, "title": null, "reason": null, "notice": [] }
    ],
    "created": 1,
    "updated": 0,
    "unchanged": 0,
    "refused": 0,
    "total": 1
  }
}

Read a payment

GET /v1/payment/import

With neither, the call answers 400 Name the payment to read: ?external_id=… or /v1/payment/paym_….; an unknown payment answers 404 Payment not found.

curl "https://api.ultineo.com/v1/payment/import?external_id=PAY-77120" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "paym_2b7d9e04c1a35f8e6d91",
    "object": "payment",
    "external_id": "PAY-77120",
    "status": "paid",
    "order_id": "ordr_5e0a8c2f71d94b36e1c8",
    "order_external_id": "ORD-10458",
    "amount": "444.00",
    "fee_amount": "6.66",
    "refunded_amount": "0.00",
    "currency": "EUR",
    "method": "card",
    "gateway": "stripe",
    "reference": "pi_3PZ0d2KJ8nA1",
    "session_reference": "",
    "paid_at": 1781258460,
    "created_at": 1781258460,
    "updated_at": 1791745200
  }
}

Shipments

A shipment is a parcel sent for an order, with its carrier and tracking number. Its status follows its dates: delivered once delivered_at is set, shipped once shipped_at is set, pending otherwise.

Import shipments

POST /v1/shipment/import

curl https://api.ultineo.com/v1/shipment/import \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "SHP-20931",
        "order_external_id": "ORD-10458",
        "carrier_name": "Colissimo",
        "tracking_number": "6A23456789012",
        "recipient_name": "Claire Martin",
        "shipped_at": 1781334000,
        "delivered_at": 1781431200
      }
    ]
  }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "resource": "shipment",
    "dry_run": false,
    "data": [
      { "index": 0, "external_id": "SHP-20931", "action": "created", "id": "ship_9c1e5a7f02d34b86e0a3", "code": null, "title": null, "reason": null, "notice": [] }
    ],
    "created": 1,
    "updated": 0,
    "unchanged": 0,
    "refused": 0,
    "total": 1
  }
}

Read a shipment

GET /v1/shipment/import

With neither, the call answers 400 Missing required parameter: external_id.; an unknown parcel answers 404 Shipment not found.

curl "https://api.ultineo.com/v1/shipment/import?external_id=SHP-20931" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "ship_9c1e5a7f02d34b86e0a3",
    "object": "shipment",
    "external_id": "SHP-20931",
    "status": "delivered",
    "order": "ordr_5e0a8c2f71d94b36e1c8",
    "carrier_name": "Colissimo",
    "tracking_number": "6A23456789012",
    "recipient_name": "Claire Martin",
    "note": "",
    "shipped_at": 1781334000,
    "delivered_at": 1781431200,
    "created_at": 1781334000,
    "updated_at": 1791745200
  }
}

Carrier claims

A carrier claim is a dispute opened with the carrier about a parcel — lost, damaged, held by customs or not collected.

Import carrier claims

POST /v1/shipment/claim

Note — If your shop has never opened its Claims page, the import answers 422 and asks you to open that page once in your workspace, then replay the batch.

curl https://api.ultineo.com/v1/shipment/claim \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "CLM-0081",
        "shipment_external_id": "SHP-20931",
        "type": "damaged",
        "status": "open",
        "reference": "COL-2026-55102",
        "opened_at": 1781517600
      }
    ]
  }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "resource": "shipment_claim",
    "dry_run": false,
    "data": [
      { "index": 0, "external_id": "CLM-0081", "action": "created", "id": "clai_4f8b2d6e01a93c75e2b0", "code": null, "title": null, "reason": null, "notice": [] }
    ],
    "created": 1,
    "updated": 0,
    "unchanged": 0,
    "refused": 0,
    "total": 1
  }
}

Read a carrier claim

GET /v1/shipment/claim

With neither, the call answers 400 Missing required parameter: external_id.; an unknown claim answers 404 Claim not found.

curl "https://api.ultineo.com/v1/shipment/claim?external_id=CLM-0081" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "clai_4f8b2d6e01a93c75e2b0",
    "object": "shipment_claim",
    "external_id": "CLM-0081",
    "status": "open",
    "shipment": "ship_9c1e5a7f02d34b86e0a3",
    "order": "ordr_5e0a8c2f71d94b36e1c8",
    "type": "damaged",
    "reference": "COL-2026-55102",
    "note": "",
    "opened_at": 1781517600,
    "settled_at": 0,
    "created_at": 1781517600,
    "updated_at": 1791745200
  }
}

Refused parcels

A refused parcel is a shipment the recipient refused, on its way back to your warehouse.

Import refused parcels

POST /v1/shipment/refused

Note — If your shop has never opened its Refused page, the import answers 422 and asks you to open that page once in your workspace, then replay the batch.

curl https://api.ultineo.com/v1/shipment/refused \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "REF-0042",
        "shipment_external_id": "SHP-20931",
        "status": "warehouse_received",
        "return_number": "RET-55871",
        "refused_at": 1781431200,
        "received_at": 1781690400
      }
    ]
  }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "resource": "shipment_refused",
    "dry_run": false,
    "data": [
      { "index": 0, "external_id": "REF-0042", "action": "created", "id": "refu_7a0c3e9b51d24f68a0e7", "code": null, "title": null, "reason": null, "notice": [] }
    ],
    "created": 1,
    "updated": 0,
    "unchanged": 0,
    "refused": 0,
    "total": 1
  }
}

Read a refused parcel

GET /v1/shipment/refused

With neither, the call answers 400 Missing required parameter: external_id.; an unknown refusal answers 404 Refusal not found.

curl "https://api.ultineo.com/v1/shipment/refused?external_id=REF-0042" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "refu_7a0c3e9b51d24f68a0e7",
    "object": "shipment_refused",
    "external_id": "REF-0042",
    "status": "warehouse_received",
    "shipment": "ship_9c1e5a7f02d34b86e0a3",
    "order": "ordr_5e0a8c2f71d94b36e1c8",
    "return_number": "RET-55871",
    "note": "",
    "refused_at": 1781431200,
    "received_at": 1781690400,
    "created_at": 1781431200,
    "updated_at": 1791745200
  }
}

Refunds

A refund returns money to the buyer for an order, optionally against one of its payments.

Import refunds

POST /v1/refund/import

Note — The item field reason is the reason for the refund. Do not confuse it with the reason of a refused entry in the import report.

Important — A refund above zero that is not a mistake counts against its payment. That payment must be paid or refunded, the refund's currency must be the payment's, and all the refunds of one payment, pending ones included, cannot exceed it. Otherwise the entry is refused with 422 and a reason such as Total refunds, including pending refunds, cannot exceed the original payment.

curl https://api.ultineo.com/v1/refund/import \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "RFD-3307",
        "order_external_id": "ORD-10458",
        "payment_external_id": "PAY-77120",
        "amount": "40.00",
        "currency": "EUR",
        "reason": "commercial_gesture",
        "status": "finished",
        "refunded_at": 1781604000
      }
    ]
  }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "resource": "refund",
    "dry_run": false,
    "data": [
      { "index": 0, "external_id": "RFD-3307", "action": "created", "id": "rfnd_0e6b4a2c93f15d78b4c1", "code": null, "title": null, "reason": null, "notice": [] }
    ],
    "created": 1,
    "updated": 0,
    "unchanged": 0,
    "refused": 0,
    "total": 1
  }
}

Read a refund

GET /v1/refund/import

With neither, the call answers 400 Missing required parameter: external_id.; an unknown refund answers 404 Refund not found.

curl "https://api.ultineo.com/v1/refund/import?external_id=RFD-3307" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "rfnd_0e6b4a2c93f15d78b4c1",
    "object": "refund",
    "external_id": "RFD-3307",
    "status": "finished",
    "order": "ordr_5e0a8c2f71d94b36e1c8",
    "payment": "paym_2b7d9e04c1a35f8e6d91",
    "customer": "",
    "reason": "commercial_gesture",
    "amount": "40.00",
    "currency": "EUR",
    "note": "",
    "refunded_at": 1781604000,
    "created_at": 1781604000,
    "updated_at": 1791745200
  }
}

Order returns

An order return is an item a customer sends back — a withdrawal, a warranty case or a wrong item — and how it was resolved.

Import order returns

POST /v1/order-return/import

curl https://api.ultineo.com/v1/order-return/import \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "RTN-1190",
        "order_external_id": "ORD-10458",
        "customer_external_id": "C1001",
        "order_item_external_id": "ORD-10458-1",
        "type": "withdrawal",
        "resolution": "refund",
        "status": "received",
        "carrier_name": "Colissimo",
        "tracking_number": "8R00112233445",
        "received_at": 1781776800
      }
    ]
  }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "resource": "order_return",
    "dry_run": false,
    "data": [
      { "index": 0, "external_id": "RTN-1190", "action": "created", "id": "ortn_6d2a0f8c41e93b57d1a8", "code": null, "title": null, "reason": null, "notice": [] }
    ],
    "created": 1,
    "updated": 0,
    "unchanged": 0,
    "refused": 0,
    "total": 1
  }
}

Read an order return

GET /v1/order-return/import

With neither, the call answers 400 Missing required parameter: external_id.; an unknown return answers 404 Order return not found.

curl "https://api.ultineo.com/v1/order-return/import?external_id=RTN-1190" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "ortn_6d2a0f8c41e93b57d1a8",
    "object": "order_return",
    "external_id": "RTN-1190",
    "status": "received",
    "type": "withdrawal",
    "resolution": "refund",
    "customer": "cust_c3e9a1074b5d28f6e0a7",
    "order": "ordr_5e0a8c2f71d94b36e1c8",
    "order_item": "oitm_8a3f0e6c2d1b47e95c20",
    "support_request": "",
    "serial": "",
    "carrier_name": "Colissimo",
    "tracking_number": "8R00112233445",
    "label_url": "",
    "received_at": 1781776800,
    "completed_at": 0,
    "created_at": 1781776800,
    "updated_at": 1791745200
  }
}

Customer wallet

A wallet movement is a line of a customer's loyalty wallet: points earned on a purchase, a referral or a review, or points spent.

Import wallet movements

POST /v1/customer-wallet/import

curl https://api.ultineo.com/v1/customer-wallet/import \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "WAL-55210",
        "customer_external_id": "C1001",
        "order_external_id": "ORD-10458",
        "points": "44.4",
        "reason": "purchase",
        "status": "credited",
        "earned_at": 1781431200
      }
    ]
  }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "resource": "customer_wallet",
    "dry_run": false,
    "data": [
      { "index": 0, "external_id": "WAL-55210", "action": "created", "id": "cwal_3b9e1d7a05c42f86e3d2", "code": null, "title": null, "reason": null, "notice": [] }
    ],
    "created": 1,
    "updated": 0,
    "unchanged": 0,
    "refused": 0,
    "total": 1
  }
}

Read a wallet movement

GET /v1/customer-wallet/import

With neither, the call answers 400 Missing required parameter: external_id.; an unknown movement answers 404 Wallet entry not found.

curl "https://api.ultineo.com/v1/customer-wallet/import?external_id=WAL-55210" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "cwal_3b9e1d7a05c42f86e3d2",
    "object": "customer_wallet_entry",
    "external_id": "WAL-55210",
    "status": "credited",
    "customer": "cust_c3e9a1074b5d28f6e0a7",
    "order": "ordr_5e0a8c2f71d94b36e1c8",
    "reason": "purchase",
    "points": "44.4000",
    "note": "",
    "earned_at": 1781431200,
    "created_at": 1781431200,
    "updated_at": 1791745200
  }
}

Support requests

A support request is a customer's question or after-sales case, imported with its thread of messages.

Import support requests

POST /v1/support-request/import

Topics of the order category: package_not_arrived, missing_item, missing_accessory, wrong_model, cancel_order, item_problem, withdrawal, customs_invoice, voucher_refund, delivery, delivery_problem, payment, refund, claim, returned_item, account, order_general, other.

Topics of the device category: slow, no_start, blocking, photo_video, no_flash, screen_color, screen_flash, screen_pixels, battery, battery_80, no_charge, cable, no_sound_call, geolocation, screen_lock, screen_fixed, network, vibrator, black_screen, scratched, button, not_listed.

Each entry of messages:

A request is saved with all its messages or not at all. Messages you leave out of a later import are kept.

Each accepted entry of the report adds messages (the number of messages created, updated and unchanged) and messages_detail (one entry per message: its external_id, action and id).

curl https://api.ultineo.com/v1/support-request/import \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "SUP-4402",
        "customer_external_id": "C1001",
        "order_external_id": "ORD-10458",
        "category": "device",
        "topic": "battery",
        "status": "closed",
        "message": "The battery drains faster than expected.",
        "created_at": 1782036000,
        "answered_at": 1782046800,
        "messages": [
          { "external_id": "SUP-4402-1", "author": "shop", "text": "Thank you, a prepaid return label is on its way.", "created_at": 1782046800 }
        ]
      }
    ]
  }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "resource": "support_request",
    "dry_run": false,
    "data": [
      {
        "index": 0,
        "external_id": "SUP-4402",
        "action": "created",
        "id": "sprq_1c7e3a9f50b24d68c1e5",
        "code": null,
        "title": null,
        "reason": null,
        "notice": [],
        "messages": { "created": 1, "updated": 0, "unchanged": 0 },
        "messages_detail": [
          { "external_id": "SUP-4402-1", "action": "created", "id": "spmg_8e2b0d4a61f37c95e2b4" }
        ]
      }
    ],
    "created": 1,
    "updated": 0,
    "unchanged": 0,
    "refused": 0,
    "total": 1
  }
}

Read a support request

GET /v1/support-request/import

With neither, the call answers 400 Missing required parameter: external_id.; an unknown request answers 404 Support request not found.

curl "https://api.ultineo.com/v1/support-request/import?external_id=SUP-4402" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "sprq_1c7e3a9f50b24d68c1e5",
    "object": "support_request",
    "external_id": "SUP-4402",
    "project": "proj_5a91c7e03d2b48f6a1e9",
    "status": "closed",
    "category": "device",
    "topic": "battery",
    "customer": "cust_c3e9a1074b5d28f6e0a7",
    "order": "ordr_5e0a8c2f71d94b36e1c8",
    "order_item": "",
    "message": "The battery drains faster than expected.",
    "answered_at": 1782046800,
    "created_at": 1782036000,
    "updated_at": 1791745200,
    "messages": [
      {
        "id": "spmg_8e2b0d4a61f37c95e2b4",
        "object": "support_message",
        "external_id": "SUP-4402-1",
        "status": "activated",
        "author": "shop",
        "text": "Thank you, a prepaid return label is on its way.",
        "created_at": 1782046800,
        "updated_at": 1791745200
      }
    ]
  }
}

The thread is returned in date order, including the messages written in your workspace (their external_id is empty).

Note — These endpoints do not list, search or delete records, and do not trigger actions: cancelling an order, issuing a refund, creating a shipping label or contacting a carrier are done in your workspace.