This API endpoint allows you to access these invoices. To fetch invoices, it is mandatory to pass in two query parameters: * a customer_type which can be either Consignee, ShippingLine or Agent * a customer_general_ledger_id which is a String and represents the General Ledger ID stored in Octopi (and the accounting system) for that Shipping Line or Consignee.

In addition, you can also pass in a parameter called ‘created_during’ to filter and only have access to specific invoices for that customer.

In Octopi, some invoices are generated automatically by the software (triggered by an event such as a gate out for example) or generated manually by a user (by clicking on a button to generate the invoice). When created automatically, the creation_method returned by this API will be AUTO. For invoices generated manually by a user, creation_method is set to MANUAL.

For Bill of Lading pro-formas, it is possible for a pro-forma to be created for all the containers in the Bill Of Lading or for only some of the containers in the Bill Of Lading. To find out which containers were billed for in that pro-forma, there are two arrays called bl_container_ids and bl_container_numbers that return respectively an array of IDs and an array of container numbers for the containers that were billed in this pro-forma.

Supported Formats

json

Errors

Code Description
404 Not found.
400 Invalid request.
500 Server crashed.

Examples

curl "https://app.octopi.co/api/v1/invoices.json" -X GET -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Token token=ADD TOKEN HERE" -d '{"customer_type":"ShippingLine", "customer_general_ledger_id":"ADD SHIPPING LINE ID HERE"}'
  "actions" : {
      "last" : {
         "url" : "https://app.octopi.co/api/v1/invoices.json?page=18",
         "method" : "GET"
      },
      "next" : {
         "url" : "https://app.octopi.co/api/v1/invoices.json?page=2",
         "method" : "GET"
      },
      "previous" : {
         "url" : "https://app.octopi.co/api/v1/invoices.json",
         "method" : "GET"
      },
      "index" : {
         "method" : "GET",
         "url" : "https://app.octopi.co/api/v1/invoices.json"
      }
   }
   "invoices" : [
      {
         "general_ledger_id" : null,
         "taxes_and_fees" : "0.0",
         "id" : 12008,
         "is_proforma": true,
         "paid": false,
         "approved": true,
         "approved_by": "John Doe",
         "created_during" : "voyage",
         "creation_method": "manual",
         "line_items" : [
            {
               "quantity" : 1,
               "currency" : "USD",
               "total" : "100.0",
               "description" : "Crane Fee",
               "billed_by" : "unit",
               "billed_per" : "move",
               "amount" : 100.0,
               "item" : "REFN1231",
               "tariff_general_ledger_id" : "REFN1231",
               "container": "MAEU1312311"
            },
            {
               "description" : "Stevedoring Fee",
               "billed_by" : "unit",
               "total" : "50.0",
               "quantity" : 1,
               "currency" : "USD",
               "item" : "REFN1232",
               "tariff_general_ledger_id" : "REFN1232",
               "billed_per" : "move",
               "amount" : "50.0",
               "container": "MAEU1312311"
            },
            ,
            {
               "description" : "Extra Fee",
               "billed_by" : "unit",
               "total" : "50.0",
               "quantity" : 1,
               "currency" : "USD",
               "item" : "REFN1230",
               "tariff_general_leger_id" : "REFN1230",
               "billed_per" : "move",
               "amount" : "30.0",
               "container": "MAEU1010101"
            }
         ],
         "totals_by_container": {
           "MAEU1312311": 150.0,
           "MAEU1010101": 30.0
         },
         "subtotal" : "49240.0",
         "customer" : {
            "id" : 49,
            "address" : "",
            "general_ledger_id" : "123",
            "email" : "",
            "name" : "DEMO LINE",
            "contact_person" : "",
            "phone" : ""
         },
         "voyage" : {
            "id" : 1033,
            "vessel" : {
               "imo_number" : "9252876",
               "name" : "NADJA",
               "vessel_type" : "container_ship"
            },
            "number" : "115"
         },
         "truck_visit": {
            "id": 520155,
            "truck": {
                "id": 2826,
                "license_plate": "CESF51",
                "trucking_company_id": 118,
                "active": true,
                "allowed_until": null
            },
            "truck_driver": {
                "id": 23897,
                "number": null,
                "license_number": "N/A",
                "firstname": "Anier",
                "lastname": "Venega",
                "twic": null,
                "active": true
            },
            "gated_in_at": "2019-05-10T23:47:25Z",
            "gated_out_at": "2019-05-11T00:00:58Z"
         },
         "total" : "49240.0",
         "created_at" : "2016-11-28T19:01:41.936-05:00"
      },
      {
         "general_ledger_id" : null,
         "taxes_and_fees" : "0.0",
         "id" : 12008,
         "is_proforma": true,
         "paid": false,
         "approved": false,
         "approved_by": null,
         "created_during" : "payment",
         "creation_method": "auto",
         "line_items" : [
            {
               "quantity" : 1,
               "currency" : "USD",
               "total" : "100.0",
               "description" : "Crane Fee",
               "billed_by" : "unit",
               "billed_per" : "move",
               "amount" : 100.0,
               "item" : "REFN1231",
               "tariff_general_ledger_id" : "REFN1231",
               "container": "MAEU1312311"
            }
         ],
         "subtotal" : "49240.0",
         "customer" : {
            "id" : 49,
            "address" : "",
            "general_ledger_id" : "123",
            "email" : "",
            "name" : "IMPORTER ONE",
            "contact_person" : "",
            "phone" : ""
         },
         "bol_segment" : {
            "id": 1034,
            "bl_number" : "1033",
            "containers": ["BSIU9028942", "AMLU5506569"]
         },
         "bill_of_lading" : {
            "id": 1034,
            "bl_number" : "1033",
            "containers": ["BSIU9028942", "AMLU5506569"]
         },
         "bl_container_ids": [2131, 1231],
         "bl_container_numbers": ["BSIU9028942", "AMLU5506569"],
         "total" : "500.0",
         "created_at" : "2016-11-28T19:01:41.936-05:00"
      }
   ]
}

Params

Param name Description
q
optional

q stands for query. It allows you to search by invoice general ledger ID or total.

Validations:

  • Must be String

line_items_q
optional

line_items_q stands for line item query. It allows you to search invoices by line items description.

Validations:

  • Must be String

customer_type
optional

The type of customer.

Validations:

  • Must be one of: ShippingLine, Consignee, Agent.

customer_general_ledger_id
optional

The General Ledger ID for the customer. You must include a customer_type if you include a customer_general_ledger_id.

Validations:

  • Must be String

created_during
optional

Filter invoices based on when they were created. Can be one of ‘payment’, ‘gate_out’, ‘gate_in’, ‘tally’, etc…

Validations:

  • Must be String

creation_method
optional

Filter invoices by creation method. One of auto or manual.

Validations:

  • Must be String

missing_general_ledger_id
optional

Set to true to return all invoices that do not have a general ledger ID

Validations:

  • Must be String

currency
optional

Filter invoices by currency

Validations:

  • Must be String

bill_of_lading_number
optional

Filter invoices by Bill of Lading Number

Validations:

  • Must be String

bill_of_lading_id
optional

Filter invoices by Bill of Lading ID

Validations:

  • Must be String

tariff_id
optional

Filter invoices by tariff

Validations:

  • Must be String

container_id
optional

Filter invoices by container/cargo ID

Validations:

  • Must be String

container_number
optional

Filter invoices by container number

Validations:

  • Must be String

voyage_id
optional

Filter invoices by voyage ID

Validations:

  • Must be String

voyage_number
optional

Filter invoices by voyage number

Validations:

  • Must be String

truck_visit_id
optional

Filter invoices by truck visit ID

Validations:

  • Must be Integer

paid
optional

Filter for paid invoices by setting to true. Or set to false to get all unpaid invoices. If absent, Octopi will return both paid and unpaid invoices.

Validations:

  • Must be String

is_proforma
optional

Filter for proforma invoices by setting to true. Or set to false to return all invoices that are not proformas. If absent, Octopi will return all invoices: proforma or not.

Validations:

  • Must be String

approved
optional

Filter for approved invoices by setting to true. Or set to false to get all not approved invoices. If absent, Octopi will return both approved and not approved invoices.

Validations:

  • Must be String

page
optional

Specify which page of results to fetch. This value defaults to 1.

Validations:

  • Must be Integer

per
optional

The number of items to be displayed. This value defaults to 10 and accepts a maximum of 100.

Validations:

  • Must be Integer