Managing Freight Invoices

Shipwell enables the management of freight invoices including the generation or upload of invoice documents and related information.

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 may be created in several ways by utilizing the Shipwell user interface or the API.

Supported Invoice Upload and API File Formats

The following file formats are supported for invoice processing via UI or API upload: PDF, TIFF, PNG, JPG

Create a Freight Invoice via API

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 host = "sandbox-api.shipwell.com";
const resp = await fetch(
  `https://${host}${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 = "sandbox-api.shipwell.com"
target_url = (
    "https://"
    + host
    + 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 host = "sandbox-api.shipwell.com";
String targetUrl = "https://" +
  host +
  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":[
      
   ]
}

Creating a freight invoice by performing a HTTP POST to 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.

Create a Freight Invoice via UI Upload

Shipwell supports extracting invoice information using machine learning and computer vision and running it through Settlement First Pass Match when a company or carrier uploads an invoice as a document (e.g. PDF, PNG, JPG). These uploaded invoices can be sent via Shipwell's web interface, mobile application, or via API.

Once an invoice has been received then the information is processed, run through Settlement First Pass Match, and the results displayed within Shipwell in under 30 seconds. Uploaded invoice information extracted includes the following when available:

  • Invoice #
  • Invoiced Total
  • Carrier Name
  • Carrier Due Date

The In-App Uploaded Invoice capability must be turned on for customers (aka shippers) and the carriers they wish to use it (contact customer support or your account representative to enable the functionality).

Note

Customers may also share the carrier-oriented How-To: In-App Uploaded Invoice knowledgebase article with their carriers. This article and accompanying video follow a carrier-centric perspective of in-app uploaded invoices.

Either the customer (aka shipper) or the carrier may upload an invoice (in one of the supported file formats, i.e. PDF, PNG, TIFF, JPG) on a shipment.

This upload is performed by navigating to the documents section for a shipment within that shipment in the web-app or mobile and uploading an invoice. Click/tap the document Upload button and icon to select and upload an invoice document/file.

Upload invoice button

The customer or user uploading the invoice needs to select Invoice as the upload type to enable invoice processing.

Set upload type as invoice

Note

The document type for an uploaded invoice must be set to Invoice for automated processing and Settlement First Pass Match to occur.

Once this occurs, and the customer has In-App Uploaded Invoice functionality enabled in their account, then the invoice will be processed. The information in the screenshots below is extracted after the invoice is run through Settlement First Pass Match is displayed both in the Invoices Received section or card in the UI and the Settlement Dashboard for invoice recipients. This information will also be displayed within the Invoices Sent section or card for the carrier.

Extracted and processed invoice data from document 1

Extracted and processed invoice data from document 2

Then the invoice would be processed according any exception review and payment procedures.

Create a Freight Invoice via UI Web App Generation

An invoice may be generated in the Shipwell app by completing the necessary information and generating an invoice from within the Shipwell web application.

Shipwell allows user to create in-app generated invoices without being connected to a Financial Management System. Once an in-app generated invoice has been created then it is run through Settlement First Pass Match and the results displayed within Shipwell. This support includes:

  • In-App Generated Invoices
    • Users with permission can generate invoices within Shipwell for their customer on the Shipment Details page. This permission is set up by user or by company.
  • Store Invoice Data
    • In-app generated invoices are stored within Shipwell
  • First Pass Match
    • Shipwell performs Settlement First Pass Match comparing the in-app generated invoice received against what is expected and identifies differences. Learn more about First Pass Match here .
  • Display Invoice Data
    • In-app generated invoice key information is taken and displayed within the Settlement Dashboard and within the Invoices Received / Invoices Received cards within the Shipment Details page
  • Generate Invoice PDF
    • An invoice PDF of the in-app generated invoice will be generated and stored in the shipment and settlement documents
  • New Invoice Emails and Notifications
    • Send an email (with invoice attached) and in-app notification to in-app generated invoice recipient as long as the parties have Invoice Activity turned on in their Profile & Preferences settings
Note

Contact your Shipwell customer support representative if you are interested in setting up In-App Generated Invoices for carriers to create invoices themselves or if you are interested in generating In-App Generated Invoices for your customers.

To generate an invoice within Shipwell, a user with permissions and access to this functionality will navigate to the Financials tab on the Shipment Details of the shipment they wish to generate an invoice for.

Create invoice button

Then click or tap the + Create Invoice button. This will trigger the open of the Create New Invoice modal. The user will then add details related to the invoice such as:

  • Invoice Info (Invoice #, Due Date, Message to Customer)
  • Financials (Pre-populated with shipment financials)
  • Documents (Pre-populated with shipment documents but more can be added)
  • Remit To

Create invoice modal

After filling out items related to the invoice that are needed for generating the invoice, then the user will click or tap Send and it will generate the invoice that will be stored in the shipment documents along with sending an email and in-app notification to the shipment representatives for the shipment.

Example Generated Freight Invoice

Example

Example generated invoice

Each invoice sent will display high-level invoice information within the Settlement Dashboard on the appropriate tab.

Invoice grid or list

Each invoice sent will display high-level invoice information, as available, in the Invoices Received and Invoices Sent cards in the Financials tab on the Shipment Details page.

Users can click or tap the Docs icon (document or clipboard with a document) and open the settlement documents identified for that particular invoice.

Invoices received

Invoices sent

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 host = "sandbox-api.shipwell.com";

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

const targetUrl = `https://${host}${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 = "sandbox-api.shipwell.com"
target_url = (
    "https://"
    + host
    + 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 host = "sandbox-api.shipwell.com";
String targetUrl = "https://" +
  host +
  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 host = "sandbox-api.shipwell.com";
const targetUrl = `https://${host}${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 = "sandbox-api.shipwell.com"
target_url = (
    "https://"
    + host
    + 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 host = "sandbox-api.shipwell.com";
String targetUrl = "https://" +
  host +
  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
}

Updating a freight invoice by performing an HTTP PUT to the update 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.

Freight Invoice State Diagram

State Diagram

Freight Invoice Statuses

Name Description
RECEIVED Represents that an invoice has been received and indicates the invoice has been received but has not been through the First Pass Match process.
PASSED Represents an invoice that has passed the Settlement First Pass Match process or a user has indicated that the invoice has PASSED.
EXCEPTION Represents an invoice that has been identified as having one or more exceptions via the Settlement First Pass Match process based on a customer's Settlement configurations.
APPROVED Represents an invoice that has been identified as APPROVED. This status is often used when an invoice has been initially identified as an EXCEPTION, but that it has been manually overridden by a user. However, some customers will have every invoice reviewed and marked as APPROVED once the review has occurred.
SCHEDULED Represents an invoice that has been scheduled for payment.
PAID Represents an invoice that has been identified as paid.
VOIDED Represents an invoice that has been voided or canceled by the invoicing party.
REJECTED Represents an invoice that has been rejected by the party receiving the invoice.
DISPUTED Represents an invoice that has been disputed by the party receiving the invoice.
RESOLVED Represents the status of an invoice that has been originally marked as DISPUTED and then has been marked as RESOLVED to indicate the dispute has been resolved. Note that First Pass Match will automatically be triggered on invoices marked as RESOLVED and if there are no freight invoice exceptions then it will be PASSED or if there are it will be EXCEPTION.

Freight Invoice Sub-Statuses

The following are freight invoice sub-statuses that occur when a freight invoice has a top-level status of EXCEPTION.

Copy
Copied
   "status": "EXCEPTION",
   "sub_statuses": [
      "WRONG_AMOUNT",
      "WRONG_PARTY"  
   ]

The freight invoice exception sub-statuses may be triggered and added to a freight invoice depending on the customer's Settlement configurations:

Name Description
NOT_DELIVERED Represents an invoice received for a shipment that does not have a DELIVERED or RECONCILED shipment status.
WRONG_PARTY Represents an invoice from a party that does not match the name of the carrier on the shipment.
WRONG_AMOUNT Represents an invoice received that has an amount invoiced that is greater or lower than the invoice to shipment financial Settlement exception threshold.
ALREADY_PAID Represents an invoice that has multiple active invoices received for the same shipment. The first active invoice received will not have this exception sub-status. Invoices that are in CANCELLED or REJECTED status are not counted as active invoices.
MISSING_DOC Represents a freight invoice that has one or more required documents missing.
NOT_MATCHED This status is not currently leveraged but is reserved for future use.
OTHER This status is not currently leveraged but is reserved for future use.
Note

Exception sub-statuses remain on the freight invoice until they are resolved. Users cannot manually resolve but this must be resolved wherein the exception does not exist. Exception sub-statuses are not automatically updated once the freight invoice's status is in PASSED, APPROVED, SCHEDULED, PAID, REJECTED, or CANCELLED.

Copyright © Shipwell 2024. All right reserved.