Freight Invoices

Freight invoices represent a request for a booking party (typically a shipper) to provide payment to a service provider (typically a carrier) for a service, such as the successful delivery of a shipment or completion of a transportation order. A freight invoice will only ever be linked to a single service object (typically a shipment), but multiple freight invoices can exist for a given service object.

In the case of Shipwell's API, the existence of a freight invoice means either:

  • A service provider has completed a service and is requesting payment
  • A booking party has identified a service as completed and wishes to record their intent to pay the service provider

Create a Freight Invoice for a Shipment

Freight invoices can be created in several ways:

  • By the carrier submitting an EDI 210 to Shipwell via a previously established relationship
  • By the service provider pressing the Generate Freight Invoice button on the Shipwell platform
  • By the booking party pressing the Generate Freight Invoice button on the Shipwell platform to record the receipt of an invoice.
  • By API by either of the parties mentioned above

Freight Invoices are created for Shipments using the POST /invoicing/shipments/{shipmentId}/freight-invoices/ endpoint. When calling this endpoint, you can choose to include a list of specific line items or default to all of the line items on the shipment.

Example request
curljavascriptpythonjava
Copy
Copied
curl --location --request POST 'https://sandbox-api.shipwell.com/v2/invoicing/shipments/{shipmentId}/freight-invoices' \
--header 'Authorization: YOUR_AUTHORIZATION_HEADER' \
--form 'data="{\"invoice_number\":\"12345\",\"due_date_term\":{\"id\":\"30 Days\",\"label\":\"30 Days\",\"date\":\"2023-01-29\"},
    \"due_date\":\"2023-01-29\",\"charge_line_items\":[{\"category\":\"LH\",\"description\":\"Line Haul\",\"quantity\":\"1\",
    \"unit_amount\":{\"value\":\"1700\",\"currency\":\"USD\"},\"add_to_invoice\":true}],\"role\":\"SERVICE_PROVIDER\",
    \"shipment_document_ids\":[\"{shipmentDocId1}\", \"{shipmentDocId2}\"]}"'
Copy
Copied
const form = new FormData();
const payload = {
       "invoice_number":"12345",
       "due_date_term":{
          "id":"30 Days",
          "label":"30 Days",
          "date":"2023-01-29"
       },
       "due_date":"2023-01-29",
       "charge_line_items":[
          {
             "category":"LH",
             "description":"Line Haul",
             "quantity":"1",
             "unit_amount":{
                "value":"1700",
                "currency":"USD"
             },
             "add_to_invoice":true
          }
       ],
       "role":"SERVICE_PROVIDER",
       "shipment_document_ids":[
          "{shipmentDocId1}",
          "{shipmentDocId2}"
       ]
};
form.append("data", JSON.stringify(payload));

const shipmentId = "YOUR_shipmentId_PARAMETER";
const basePath = "/v2";
const hostPath = "sandbox-api.shipwell.com";
const resp = await fetch(
  `https://${hostPath}${basePath}/invoicing/shipments/${shipmentId}/freight-invoices/`,
  {
    method: "POST",
    headers: {
      "Authorization": "YOUR_AUTHORIZATION_HEADER"
    },
    body: form
  }
);

const data = await resp.json();
console.log(data);
Copy
Copied
import json
import requests

shipment_id = "YOUR_shipmentId_PARAMETER"
base_path = "/v2"
host_path = "sandbox-api.shipwell.com"
target_url = (
    "https://"
    + host_path
    + base_path
    + "/invoicing/shipments/"
    + shipment_id
    + "/freight-invoices/"
)

headers = {"Content-Type": "multipart/form-data", "Authorization": "YOUR_AUTHORIZATION_HEADER"}

payload = {
    "invoice_number": "12345",
    "due_date_term": {"id": "30 Days", "label": "30 Days", "date": "2023-01-29"},
    "due_date": "2023-01-29",
    "charge_line_items": [
        {
            "category": "LH",
            "description": "Line Haul",
            "quantity": "1",
            "unit_amount": {"value": "1700", "currency": "USD"},
            "add_to_invoice": True,
        }
    ],
    "role": "SERVICE_PROVIDER",
    "shipment_document_ids": ["{shipmentDocId1}", "{shipmentDocId2}"],
}

multipart_data = {
    "data": (None, json.dumps(payload)),
}

response = requests.post(target_url, headers=headers, files=multipart_data)
data = response.json()
print(data)
Copy
Copied
import java.io.IOException;
import okhttp3.MultipartBody;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

OkHttpClient client = new OkHttpClient();

String shipmentId = "YOUR_shipmentId_PARAMETER";
String basePath = "";
String hostPath = "sandbox-api.shipwell.com";
String targetUrl = "https://" +
  host_path +
  base_path +
  "/invoicing/shipments/" +
  shipment_id +
  "/freight-invoices/";

RequestBody requestBody = new MultipartBody.Builder()
  .setType(MultipartBody.FORM)
  .addFormDataPart("data", "{\\\"invoice_number\\\":\\\"12345\\\"," +
    "\\\"due_date_term\\\":{\\\"id\\\":\\\"30 Days\\\"," +
    "\\\"label\\\":\\\"30 Days\\\",\\\"date\\\":\\\"2023-01-29\\\"}," +
    "\\\"due_date\\\":\\\"2023-01-29\\\",\\\"charge_line_items\\\":[{\\\"category\\\":\\\"LH\\\"," +
    \\\"description\\\":\\\"Line Haul\\\",\\\"quantity\\\":\\\"1\\\"," +
    "\\\"unit_amount\\\":{\\\"value\\\":\\\"1700\\\",\\\"currency\\\":\\\"USD\\\"}," +
    "\\\"add_to_invoice\\\":true}],\\\"role\\\":\\\"SERVICE_PROVIDER\\\"," +
    \\\"shipment_document_ids\\\":[\\\"{shipmentDocId1}\\\", \\\"{shipmentDocId2}\\\"]}")
  .build();

Request request = new Request.Builder()
  .url(targetUrl)
  .post(requestBody)
  .header("Authorization", "YOUR_AUTHORIZATION_HEADER")
  .build();

try (Response response = client.newCall(request).execute()) {
  if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
  response.body().string();
}
Example response
Copy
Copied
{
   "created_at":"2022-12-31T00:15:33.027550+00:00",
   "updated_at":"2022-12-31T00:15:33.027550+00:00",
   "id":"01GNJRHA53R3A8CQWKBHFHPRWE",
   "invoice_source":"SHIPWELL_WEB",
   "charge_line_items":[
      {
         "created_at":"2022-12-31T00:15:33.033535+00:00",
         "updated_at":"2022-12-31T00:15:33.033535+00:00",
         "id":"01GNJRHA59D92E3V94V0ZF8H3A",
         "description":"LH",
         "unit_amount":{
            "value":"1700.0000",
            "currency":"USD"
         },
         "quantity":"1.00",
         "category":"LH"
      }
   ],
   "total_amount":{
      "value":"1700.00",
      "currency":"USD"
   },
   "currency":"USD",
   "invoiceable":{
      "id":"4c36cfc6-e0a0-44f7-8eab-5351e4766f11",
      "type":"V2_SHIPMENT",
      "reference_number":"K3RZD4"
   },
   "service_provider_name":"DAS'sCarrier",
   "stops":[
      {
         "created_at":"2022-12-31T00:15:33.042916+00:00",
         "updated_at":"2022-12-31T00:15:33.042916+00:00",
         "id":"01GNJRHA5JJ6EE2GGQWS2YN0HE",
         "country":"US",
         "line_1":"333 E Wonderview Ave",
         "line_2":null,
         "line_3":null,
         "locality":"Estes Park",
         "postal_code":"80517",
         "region":"CO",
         "company_name":"DAS'sPickup",
         "reasons":[
            "LOAD"
         ],
         "sequence_number":0
      },
      {
         "created_at":"2022-12-31T00:15:33.047202+00:00",
         "updated_at":"2022-12-31T00:15:33.047202+00:00",
         "id":"01GNJRHA5QZ60MW4REBFBAZF9C",
         "country":"US",
         "line_1":"742 E Evergreen St",
         "line_2":null,
         "line_3":null,
         "locality":"Springfield",
         "postal_code":"65803",
         "region":"MO",
         "company_name":"DAS's1stDropoff",
         "reasons":[
            "UNLOAD"
         ],
         "sequence_number":1
      }
   ],
   "product_line_items":[
      {
         "created_at":"2022-12-31T00:15:33.038167+00:00",
         "updated_at":"2022-12-31T00:15:33.038167+00:00",
         "id":"01GNJRHA5E4GCPWY9B21BVREC5",
         "description":"DASDry",
         "quantity":"5",
         "packaging":"PLT",
         "weight":{
            "unit":"LB",
            "value":"700.0"
         }
      }
   ],
   "remit_to":null,
   "bill_to":null,
   "external_id":null,
   "invoice_number":"12345",
   "due_date":"2023-01-29",
   "notes":null,
   "generated_by":"SERVICE_PROVIDER",
   "documents":[
      {
         "created_at":"2022-12-31T00:15:33.499562+00:00",
         "updated_at":"2022-12-31T00:15:33.499562+00:00",
         "id":"01GNJRHAKVMYBJDTSKHZYC2AEM",
         "document_type":"BOL",
         "description":"Bill of Lading",
         "public_url":"https://s3.us-west-2.amazonaws.com/dev.settlements.shipwell.com/documents/01GNJRHA53R3A8CQWKBHFHPRWE/shipments/4c36cfc6-e0a0-44f7-8eab-5351e4766f11/Bill_of_Lading_7kkbgd.pdf?AWSAccessKeyId=ASIA2GXP6XGYHNM3RCWG&Signature=aiXxmvAEC1sGskSDWFDkJLcom%2FE%3D&x-amz-security-token=IQoJb3JpZ2luX2VjEDgaCXVzLXdlc3QtMiJHMEUCIGrpW6f%2FVpnRkb1thSdXa9Yh%2BY6FDQYzGKoXk0UW5XXyAiEAr3UEoYOPgo9Q8PVpRwMdRj0zMGy%2FtGYC1LCEKUP4h8gq5gMIgf%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FARADGgw3MDE2NTY2NDQwMTYiDI%2BfigOOaVPqGOu9Vyq6A371tdBa8tnrb69TAVBrRN3uEG397w%2FhQ5CBXnOv52LdEA4H%2FkRhu0bvgnHmjikN9LDyy5W5NmpUWBuItbeBCM0%2B35JZfrn%2BaW%2FniOgFYEPKmzRXhlpsVWPovAgrg0dmiCJv8xFAoVul3FPDvyPRvWouxYOiaDeh4lJ5JDhHxiFZB8HVO07D%2BszFrpTyACMwGQKYf71b8eOqniaRJTE2oYcE%2BZTiUgZZCLxU%2BuaLUF2JZ32hyZs4a%2B%2Baf4odvUMRqJBjluU0%2BQhZ%2FoDo1ZCNkbF9ZciBOvnBH8OVqfK5DrfntvQDHMyqyCW5PfIGj8X%2BcvRG0gOB484cVXEaf%2BabGRK9sJe%2BsVIYZ19%2FHjSIXtqCQtGSX1q2GlBmaRGCarrGkyMDF%2FPDYHsmO3uGEOkSyB7WrZcIa11e2KrrIGaF1MmnxoXlCgk0oGI3r0phUeqenPGeQLGFjG7jUhV9iONIuSCF5H9rD6QU08MOnVLhD2LLsxf9qfn3VVMxtpN64KJZ7mEN5n8n6xKFsrEdyyuypT6VasD%2BXWCn8dxaeYASdx%2FbHON5efc8ZnHQqgE1okd5I1Lt%2F2i9w1gUnwgw0%2Fm9nQY6pQFRSkA6K7NtpvTH0jdWqyR25cypn%2BtDpz6bflV6VQedZ2OX6N6kE5v3HYsNBNq%2F6ehxWu5rkA0ODRMrhtTAtqLcegBmjiuC2EAaWZShWmiEJtV8pWxy%2BIAo0r6cin8hfS9fbr5%2Ba2eFP4hO%2FQZ5XKrY1DCnnOgRUb45iw2ZKn9cK0szRoqk90hAdfMYrqqWsKLLPLRqhbY3HECmWqXvH3jFtjJ5uZ8%3D&Expires=1672447539"
      },
      {
         "created_at":"2022-12-31T00:15:38.808045+00:00",
         "updated_at":"2022-12-31T00:15:38.808045+00:00",
         "id":"01GNJRHFSR6DWHV78132168PB9",
         "document_type":"INVOICE",
         "description":"System-generated PDF representation of Freight Invoice",
         "public_url":"https://s3.us-west-2.amazonaws.com/dev.settlements.shipwell.com/documents/01GNJRHA53R3A8CQWKBHFHPRWE/freight-invoice-01GNJRHA53R3A8CQWKBHFHPRWE_J1I4tf.pdf?AWSAccessKeyId=ASIA2GXP6XGYHNM3RCWG&Signature=t3uZ%2BKO4wIj11FClaJ7mK%2F9wpi0%3D&x-amz-security-token=IQoJb3JpZ2luX2VjEDgaCXVzLXdlc3QtMiJHMEUCIGrpW6f%2FVpnRkb1thSdXa9Yh%2BY6FDQYzGKoXk0UW5XXyAiEAr3UEoYOPgo9Q8PVpRwMdRj0zMGy%2FtGYC1LCEKUP4h8gq5gMIgf%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FARADGgw3MDE2NTY2NDQwMTYiDI%2BfigOOaVPqGOu9Vyq6A371tdBa8tnrb69TAVBrRN3uEG397w%2FhQ5CBXnOv52LdEA4H%2FkRhu0bvgnHmjikN9LDyy5W5NmpUWBuItbeBCM0%2B35JZfrn%2BaW%2FniOgFYEPKmzRXhlpsVWPovAgrg0dmiCJv8xFAoVul3FPDvyPRvWouxYOiaDeh4lJ5JDhHxiFZB8HVO07D%2BszFrpTyACMwGQKYf71b8eOqniaRJTE2oYcE%2BZTiUgZZCLxU%2BuaLUF2JZ32hyZs4a%2B%2Baf4odvUMRqJBjluU0%2BQhZ%2FoDo1ZCNkbF9ZciBOvnBH8OVqfK5DrfntvQDHMyqyCW5PfIGj8X%2BcvRG0gOB484cVXEaf%2BabGRK9sJe%2BsVIYZ19%2FHjSIXtqCQtGSX1q2GlBmaRGCarrGkyMDF%2FPDYHsmO3uGEOkSyB7WrZcIa11e2KrrIGaF1MmnxoXlCgk0oGI3r0phUeqenPGeQLGFjG7jUhV9iONIuSCF5H9rD6QU08MOnVLhD2LLsxf9qfn3VVMxtpN64KJZ7mEN5n8n6xKFsrEdyyuypT6VasD%2BXWCn8dxaeYASdx%2FbHON5efc8ZnHQqgE1okd5I1Lt%2F2i9w1gUnwgw0%2Fm9nQY6pQFRSkA6K7NtpvTH0jdWqyR25cypn%2BtDpz6bflV6VQedZ2OX6N6kE5v3HYsNBNq%2F6ehxWu5rkA0ODRMrhtTAtqLcegBmjiuC2EAaWZShWmiEJtV8pWxy%2BIAo0r6cin8hfS9fbr5%2Ba2eFP4hO%2FQZ5XKrY1DCnnOgRUb45iw2ZKn9cK0szRoqk90hAdfMYrqqWsKLLPLRqhbY3HECmWqXvH3jFtjJ5uZ8%3D&Expires=1672447540"
      }
   ],
   "status":"REVIEWING",
   "sub_statuses":[
      
   ]
}

Hitting this endpoint will generate a Freight Invoice Created event. Users in accounts integrated with Webhooks can receive these events if they are either the booking party or service provider on the invoice.

View all Freight Invoices for a Shipment

You can see all Freight Invoices associated with a specific shipment by using the GET /freight-invoices?invoiceable_id={shipmentId} endpoint.

Example request
curljavascriptpythonjava
Copy
Copied
curl --location --request GET 'https://sandbox-api.shipwell.com/freight-invoices?invoiceable_id={shipmentId}' \
    --header 'Authorization: YOUR_AUTHORIZATION_HEADER'
Copy
Copied
const shipmentId = "YOUR_shipmentId_PARAMETER";
const basePath = "";
const hostPath = "sandbox-api.shipwell.com";

const query = new URLSearchParams({
  invoiceable_id: shipmentId,
}).toString();

const targetUrl = `https://${hostPath}${basePath}/freight-invoices?${query}`;

const resp = await fetch(
  targetUrl,
  {
    method: "GET",
    headers: {
      "Authorization": "YOUR_AUTHORIZATION_HEADER"
    },
  }
);

const data = await resp.json();
console.log(data);
Copy
Copied
import requests

shipment_id = "YOUR_shipmentId_PARAMETER"
base_path = ""
host_path = "sandbox-api.shipwell.com"
target_url = (
    "https://"
    + host_path
    + base_path
    + "/freight-invoices"
)

headers = {
    "Authorization": "YOUR_AUTHORIZATION_HEADER"
}

query_params = {
    "invoiceable_id": shipment_id
}

response = requests.get(target_url, headers=headers, params=query_params)
data = response.json()
print(data)
Copy
Copied
import java.io.IOException;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

OkHttpClient client = new OkHttpClient();

String shipmentId = "YOUR_shipmentId_PARAMETER";
String basePath = "";
String hostPath = "sandbox-api.shipwell.com";
String targetUrl = "https://" +
  host_path +
  base_path +
  "/freight-invoices" +
  "?invoiceable_id=" +
  shipment_id;

Request request = new Request.Builder()
  .url(targetUrl)
  .header("Authorization", "YOUR_AUTHORIZATION_HEADER")
  .build();

try (Response response = client.newCall(request).execute()) {
  if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
  response.body().string();
}
Example response
Copy
Copied
{
  "data": [
    {
      "bill_to": {
        "contact_email": "user@example.com",
        "contact_phone": "string",
        "contact_phone_number": "string",
        "country": "st",
        "created_at": "2019-08-24T14:15:22Z",
        "entity_type": "INDIVIDUAL",
        "id": "string",
        "line_1": "string",
        "line_2": "string",
        "line_3": "string",
        "locality": "string",
        "name": "string",
        "postal_code": "string",
        "region": "str",
        "updated_at": "2019-08-24T14:15:22Z"
      },
      "booking_party_tenant_id": "string",
      "charge_line_items": [
        {
          "category": "string",
          "created_at": "2019-08-24T14:15:22Z",
          "custom_data": {},
          "description": "string",
          "id": "string",
          "quantity": "string",
          "unit_amount": {
            "currency": "USD",
            "value": "string"
          },
          "updated_at": "2019-08-24T14:15:22Z"
        }
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "currency": "USD",
      "custom_data": {
        "property1": null,
        "property2": null
      },
      "documents": [
        {
          "created_at": "2019-08-24T14:15:22Z",
          "description": "string",
          "document_type": "string",
          "id": "string",
          "public_url": "http://example.com",
          "updated_at": "2019-08-24T14:15:22Z"
        }
      ],
      "due_date": "2019-08-24",
      "external_id": "string",
      "generated_by": "SERVICE_PROVIDER",
      "id": "string",
      "invoice_number": "string",
      "invoice_source": "CARRIER_GENERATED",
      "invoiceable": {
        "id": "string",
        "reference_number": "string",
        "total_amount": {
          "currency": "USD",
          "value": "string"
        },
        "type": "V2_SHIPMENT"
      },
      "notes": "string",
      "processed_total": {
        "currency": "USD",
        "value": "string"
      },
      "product_line_items": [
        {
          "created_at": "2019-08-24T14:15:22Z",
          "custom_data": {},
          "description": "string",
          "id": "string",
          "packaging": "BAG",
          "quantity": "string",
          "updated_at": "2019-08-24T14:15:22Z",
          "weight": {
            "unit": "LB",
            "value": "string"
          }
        }
      ],
      "remit_to": {
        "contact_email": "user@example.com",
        "contact_phone": "string",
        "contact_phone_number": "string",
        "country": "st",
        "created_at": "2019-08-24T14:15:22Z",
        "entity_type": "INDIVIDUAL",
        "id": "string",
        "line_1": "string",
        "line_2": "string",
        "line_3": "string",
        "locality": "string",
        "name": "string",
        "postal_code": "string",
        "region": "str",
        "updated_at": "2019-08-24T14:15:22Z"
      },
      "service_provider_id": "string",
      "service_provider_name": "string",
      "status": "RECEIVED",
      "stops": [
        {
          "company_name": "string",
          "country": "st",
          "created_at": "2019-08-24T14:15:22Z",
          "id": "string",
          "line_1": "string",
          "line_2": "string",
          "line_3": "string",
          "locality": "string",
          "postal_code": "string",
          "reasons": "LOAD",
          "region": "str",
          "sequence_number": 0,
          "updated_at": "2019-08-24T14:15:22Z"
        }
      ],
      "sub_statuses": [
        {
          "created_at": "2019-08-24T14:15:22Z",
          "description": "string",
          "id": "string",
          "sub_status": "NOT_DELIVERED",
          "updated_at": "2019-08-24T14:15:22Z"
        }
      ],
      "total_amount": {
        "currency": "USD",
        "value": "string"
      },
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ],
  "count": 1,
  "total_count": 2,
  "links": {
    "next": "https://sandbox-api.shipwell.com/freight-invoices?page=2",
    "prev": null,
    "first": "https://sandbox-api.shipwell.com/freight-invoices?page=1",
    "last": "https://sandbox-api.shipwell.com/freight-invoices?page=2"
  }
}

Update the status of a Freight Invoice

The status field of a Freight Invoice can be updated using the PUT /freight-invoices/{invoice_id}/status endpoint. There are several restrictions on what status a Freight Invoice can be updated to depending on the requestor's role on the invoice (booking party vs. service provider):

A booking party can only update a Freight Invoice to one of the following statuses:

  • PASSED (note: typically handled by the Shipwell First Pass Match Rules Engine, but available as an override)
  • APPROVED
  • DISPUTED
  • RESOLVED (note: this is only available when a freight invoice is in DISPUTED status)
  • SCHEDULED
  • PAID
  • REJECTED (note: an invoice that has already been SCHEDULED or PAID cannot be REJECTED)

A service provider can only update a Freight Invoice to the following status:

  • RESOLVED (note: this is only available when a freight invoice is in DISPUTED status)
  • VOIDED (note: an invoice that has already been SCHEDULED or PAID cannot be VOIDED)
Example request
curljavascriptpythonjava
Copy
Copied
curl -i -X PUT \
  'https://sandbox-api.shipwell.com/freight-invoices/{invoice_id}/status' \
  -H 'Authorization: YOUR_AUTHORIZATION_HEADER' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "APPROVED"
  }'
Copy
Copied
const payload = {
    "status": "APPROVED",
};

const shipmentId = "YOUR_shipmentId_PARAMETER";
const basePath = "";
const hostPath = "sandbox-api.shipwell.com";
const targetUrl = `https://${hostPath}${basePath}/freight-invoices/${invoiceId}/status`;
const resp = await fetch(
  targetUrl,
  {
    method: "PUT",
    headers: {
      "Authorization": "YOUR_AUTHORIZATION_HEADER",
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
  }
);

const data = await resp.json();
console.log(data);
Copy
Copied
import requests

invoice_id = "YOUR_shipmentId_PARAMETER"
base_path = ""
host_path = "sandbox-api.shipwell.com"
target_url = (
    "https://"
    + host_path
    + base_path
    + "/freight-invoices/"
    + invoice_id
    + "/status"
)

headers = {
    "Authorization": "YOUR_AUTHORIZATION_HEADER",
    "Content-Type": "application/json",
}

payload = {
    "status": "APPROVED",
}

response = requests.put(target_url, headers=headers, json=payload)
data = response.json()
print(data)
Copy
Copied
import java.io.IOException;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

OkHttpClient client = new OkHttpClient();
String shipmentId = "YOUR_shipmentId_PARAMETER";
String basePath = "";
String hostPath = "sandbox-api.shipwell.com";
String targetUrl = "https://" +
  host_path +
  base_path +
  "/freight-invoices/" +
  invoice_id +
  "/status";

String requestBody = "{\"status\": \"APPROVED\"}";

Request request = new Request.Builder()
  .url(targetUrl)
  .put(requestBody)
  .header("Authorization", "YOUR_AUTHORIZATION_HEADER")
  .header("Content-Type", "application/json")
  .build();

try (Response response = client.newCall(request).execute()) {
  if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
  response.body().string();
}
Example response
Copy
Copied
{
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "id": "string",
  "custom_data": {},
  "invoice_source": "CARRIER_GENERATED",
  "charge_line_items": [],
  "currency": "USD",
  "invoiceable": null,
  "service_provider_name": "string",
  "stops": [],
  "product_line_items": [],
  "remit_to": null,
  "bill_to": null,
  "external_id": "string",
  "invoice_number": "string",
  "due_date": "2019-08-24",
  "notes": "string",
  "generated_by": "SERVICE_PROVIDER",
  "documents": [],
  "status": "RECEIVED",
  "sub_statuses": [],
  "processed_total": null
}

Hitting this endpoint will generate a Freight Invoice Status Updated event. Users in accounts integrated with Webhooks can receive these events if they are the booking party or service provider on the invoice.

State Diagram State Diagram

Copyright © Shipwell 2023. All right reserved.