Shipments
A shipment against an order. Can be sent nested in POST /orders or created on its own afterwards; both go through the same code path. A quote cannot ship.
The object#
| Field | Type | Description |
|---|---|---|
| idread-only | integer | NolaPro id. |
| orderid | integer | Orderid. Id only. |
| carrierserviceid | integer | Carrier service the shipment goes out by. |
| carrierservice | string(100) | Code for the referenced carrierservice, instead of the id. |
| shipdate | string | When it went out. |
| locationid | integer | Inventory location to receive into. |
| location | string(20) | The locationcode of the referenced inventorylocations, instead of the id. Send this or locationid, not both unless they agree. |
| entrydate | string | When the record was created. |
| lastchangedateread-only | string | Last modification. Drives modifiedsince. |
| shiptoid | integer | Shiptoid. Id only. |
| voucherid | integer | Voucherid. Id only. |
| voucher | string(50) | The voucher of the referenced gltransactions, instead of the id. Send this or voucherid, not both unless they agree. |
| cancel | boolean | Cancelled. Always a boolean on the wire, whatever integer width the column uses (D23). |
| invoiceid | integer | Invoiceid. Id only. |
| invoice | string(30) | The invoicenumber of the referenced invoices, instead of the id. Send this or invoiceid, not both unless they agree. |
| externalid | string(100) | Your own key. Scoped to your company. |
Endpoints#
Packages in a shipment, with their tracking numbers.
Parcel-level detail: what went in which box, what it weighed, what the carrier charged, and the tracking number. This is where tracking numbers live. The order-level audit trail records that a shipment happened; the number a customer types into a carrier's site is here, per package - which matters because one shipment is often several boxes with several numbers.
Requires scope shipments:read.
| Name | In | Type | Notes |
|---|---|---|---|
| idrequired | path | integer | The shipment id. |
| Status | Code | Meaning |
|---|---|---|
| 422 | unknown_value | No such parent record in this company. |
curl \ 'https://acme.nolapro.com/!/api/v2/shipments/104/packages' \ -H 'Authorization: Bearer $NP_TOKEN'
$ch = curl_init('https://acme.nolapro.com/!/api/v2/shipments/104/packages'); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NP_TOKEN')], CURLOPT_RETURNTRANSFER => true, ]); $res = json_decode(curl_exec($ch), true);
import os, requests r = requests.get( "https://acme.nolapro.com/!/api/v2/shipments/104/packages", headers={"Authorization": f"Bearer {os.environ['NP_TOKEN']}"}, ) r.raise_for_status()
const res = await fetch( 'https://acme.nolapro.com/!/api/v2/shipments/104/packages', { method: 'GET', headers: { Authorization: `Bearer ${process.env.NP_TOKEN}` }, } ); const data = await res.json();
using System.Net.Http.Json; var token = Environment.GetEnvironmentVariable("NP_TOKEN"); using var http = new HttpClient(); http.DefaultRequestHeaders.Add("Authorization", "Bearer " + token); var res = await http.GetAsync( "https://acme.nolapro.com/!/api/v2/shipments/104/packages"); res.EnsureSuccessStatusCode();
Create many.
Requires scope shipments:write.
| Name | In | Type | Notes |
|---|---|---|---|
| Field | Type | Description |
|---|---|---|
| orderidrequired | integer | The order being shipped against. |
| externalid | string(100) | Your own identifier for this record. Stored verbatim and returned on reads; GET /<resource>?externalid=... finds it again. |
| linesrequired | array of object | What is going out. Each line ships against an order line and cannot exceed what is left on it. |
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | The request was malformed. |
| 422 | cannot_ship_quote | The order is still a quote, so nothing is committed to ship. |
| 422 | rule_violation | NolaPro refused the document. message carries its reason. |
| 422 | shipqty_exceeds_remaining | More than qtyorder - qtyship was sent. |
| 422 | unknown_value | A reference did not resolve in this company. |
curl -X POST \ 'https://acme.nolapro.com/!/api/v2/shipments/batch' \ -H 'Authorization: Bearer $NP_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: your-unique-key' \ -d '[ { "orderid": 104, "externalid": "crm-8842", "lines": [ { "orderlineid": 104, "quantity": "3.000000" } ] } ]'
$ch = curl_init('https://acme.nolapro.com/!/api/v2/shipments/batch'); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NP_TOKEN')], CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS => json_encode([ [ 'orderid' => 104, 'externalid' => 'crm-8842', 'lines' => [ [ 'orderlineid' => 104, 'quantity' => '3.000000', ], ], ], ]), ]); $res = json_decode(curl_exec($ch), true);
import os, requests r = requests.post( "https://acme.nolapro.com/!/api/v2/shipments/batch", headers={"Authorization": f"Bearer {os.environ['NP_TOKEN']}"}, json=[ { "orderid": 104, "externalid": "crm-8842", "lines": [ { "orderlineid": 104, "quantity": "3.000000", }, ], }, ], ) r.raise_for_status()
const res = await fetch( 'https://acme.nolapro.com/!/api/v2/shipments/batch', { method: 'POST', headers: { Authorization: `Bearer ${process.env.NP_TOKEN}` }, body: JSON.stringify([ { orderid: 104, externalid: "crm-8842", lines: [ { orderlineid: 104, quantity: "3.000000", }, ], }, ]), } ); const data = await res.json();
using System.Net.Http.Json; var token = Environment.GetEnvironmentVariable("NP_TOKEN"); using var http = new HttpClient(); http.DefaultRequestHeaders.Add("Authorization", "Bearer " + token); var body = new[] { new { orderid = 104, externalid = "crm-8842", lines = new[] { new { orderlineid = 104, quantity = "3.000000", }, }, }, }; var req = new HttpRequestMessage(HttpMethod.Post, "https://acme.nolapro.com/!/api/v2/shipments/batch") { Content = JsonContent.Create(body), }; req.Headers.Add("Idempotency-Key", "your-unique-key"); var res = await http.SendAsync(req); res.EnsureSuccessStatusCode();
{
"results": [
{
"index": 1,
"status": 1
}
]
}
List shipments.
Requires scope shipments:read.
| Name | In | Type | Notes |
|---|---|---|---|
| locationid | query | string | Restrict to one locationid. |
| orderid | query | string | Restrict to one orderid. |
| invoiceid | query | string | Restrict to one invoiceid. |
| cancel | query | string | Defaults to false. Pass true or any. |
| modifiedsince | query | string | RFC 3339 UTC timestamp. Returns only records changed since then, including cancelled ones - so cancel defaults to any rather than false when this is used. The response carries _meta.synced_through; store it and send it back next time. |
| externalid | query | string | Exact match on your own key. |
| include | query | string | Comma-separated extras to embed. Only custom_fields is available: the extra fields this install has defined on the record. Off by default, and an unrecognised value is refused rather than ignored. See Conventions. |
| Status | Code | Meaning |
|---|---|---|
| 403 | insufficient_scope | Token lacks read scope. |
curl \ 'https://acme.nolapro.com/!/api/v2/shipments' \ -H 'Authorization: Bearer $NP_TOKEN'
$ch = curl_init('https://acme.nolapro.com/!/api/v2/shipments'); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NP_TOKEN')], CURLOPT_RETURNTRANSFER => true, ]); $res = json_decode(curl_exec($ch), true);
import os, requests r = requests.get( "https://acme.nolapro.com/!/api/v2/shipments", headers={"Authorization": f"Bearer {os.environ['NP_TOKEN']}"}, ) r.raise_for_status()
const res = await fetch( 'https://acme.nolapro.com/!/api/v2/shipments', { method: 'GET', headers: { Authorization: `Bearer ${process.env.NP_TOKEN}` }, } ); const data = await res.json();
using System.Net.Http.Json; var token = Environment.GetEnvironmentVariable("NP_TOKEN"); using var http = new HttpClient(); http.DefaultRequestHeaders.Add("Authorization", "Bearer " + token); var res = await http.GetAsync( "https://acme.nolapro.com/!/api/v2/shipments"); res.EnsureSuccessStatusCode();
Create.
Requires scope shipments:write.
| Name | In | Type | Notes |
|---|---|---|---|
| Field | Type | Description |
|---|---|---|
| orderidrequired | integer | The order being shipped against. |
| externalid | string(100) | Your own identifier for this record. Stored verbatim and returned on reads; GET /<resource>?externalid=... finds it again. |
| linesrequired | array of object | What is going out. Each line ships against an order line and cannot exceed what is left on it. |
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | A required field was missing. |
| 422 | cannot_ship_quote | The order is still a quote, so nothing is committed to ship. |
| 422 | rule_violation | NolaPro refused the document. message carries its reason. |
| 422 | shipqty_exceeds_remaining | More than qtyorder - qtyship was sent. |
| 422 | unknown_value | A reference did not resolve in this company. |
curl -X POST \ 'https://acme.nolapro.com/!/api/v2/shipments' \ -H 'Authorization: Bearer $NP_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: your-unique-key' \ -d '{ "orderid": 104, "externalid": "crm-8842", "lines": [ { "orderlineid": 104, "quantity": "3.000000" } ] }'
$ch = curl_init('https://acme.nolapro.com/!/api/v2/shipments'); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NP_TOKEN')], CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS => json_encode([ 'orderid' => 104, 'externalid' => 'crm-8842', 'lines' => [ [ 'orderlineid' => 104, 'quantity' => '3.000000', ], ], ]), ]); $res = json_decode(curl_exec($ch), true);
import os, requests r = requests.post( "https://acme.nolapro.com/!/api/v2/shipments", headers={"Authorization": f"Bearer {os.environ['NP_TOKEN']}"}, json={ "orderid": 104, "externalid": "crm-8842", "lines": [ { "orderlineid": 104, "quantity": "3.000000", }, ], }, ) r.raise_for_status()
const res = await fetch( 'https://acme.nolapro.com/!/api/v2/shipments', { method: 'POST', headers: { Authorization: `Bearer ${process.env.NP_TOKEN}` }, body: JSON.stringify({ orderid: 104, externalid: "crm-8842", lines: [ { orderlineid: 104, quantity: "3.000000", }, ], }), } ); const data = await res.json();
using System.Net.Http.Json; var token = Environment.GetEnvironmentVariable("NP_TOKEN"); using var http = new HttpClient(); http.DefaultRequestHeaders.Add("Authorization", "Bearer " + token); var body = new { orderid = 104, externalid = "crm-8842", lines = new[] { new { orderlineid = 104, quantity = "3.000000", }, }, }; var req = new HttpRequestMessage(HttpMethod.Post, "https://acme.nolapro.com/!/api/v2/shipments") { Content = JsonContent.Create(body), }; req.Headers.Add("Idempotency-Key", "your-unique-key"); var res = await http.SendAsync(req); res.EnsureSuccessStatusCode();
{
"orderid": 104,
"shipdate": "2026-08-01"
}
Retrieve one record.
Requires scope shipments:read.
| Name | In | Type | Notes |
|---|---|---|---|
| idrequired | path | integer | The record id. |
| include | query | string | Comma-separated extras to embed. Only custom_fields is available: the extra fields this install has defined on the record. Off by default, and an unrecognised value is refused rather than ignored. See Conventions. |
| Status | Code | Meaning |
|---|---|---|
| 404 | not_found | No record with that id. |
curl \ 'https://acme.nolapro.com/!/api/v2/shipments/104' \ -H 'Authorization: Bearer $NP_TOKEN'
$ch = curl_init('https://acme.nolapro.com/!/api/v2/shipments/104'); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NP_TOKEN')], CURLOPT_RETURNTRANSFER => true, ]); $res = json_decode(curl_exec($ch), true);
import os, requests r = requests.get( "https://acme.nolapro.com/!/api/v2/shipments/104", headers={"Authorization": f"Bearer {os.environ['NP_TOKEN']}"}, ) r.raise_for_status()
const res = await fetch( 'https://acme.nolapro.com/!/api/v2/shipments/104', { method: 'GET', headers: { Authorization: `Bearer ${process.env.NP_TOKEN}` }, } ); const data = await res.json();
using System.Net.Http.Json; var token = Environment.GetEnvironmentVariable("NP_TOKEN"); using var http = new HttpClient(); http.DefaultRequestHeaders.Add("Authorization", "Bearer " + token); var res = await http.GetAsync( "https://acme.nolapro.com/!/api/v2/shipments/104"); res.EnsureSuccessStatusCode();
{
"orderid": 104,
"carrierserviceid": 104,
"carrierservice": "Example carrierservice",
"shipdate": "2026-08-01T14:22:05Z",
"locationid": 104,
"location": "Example location"
}
Update.
Requires scope shipments:write.
| Name | In | Type | Notes |
|---|---|---|---|
| idrequired | path | integer | The record id. |
| Field | Type | Description |
|---|---|---|
| carrierserviceid | integer | Carrier service the shipment goes out by. |
| shipdate | string | When it went out. |
| externalid | string(100) | Your own identifier for this record. |
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | The request was malformed. |
| 404 | not_found | No such record, or it belongs to another company. |
| 409 | stale_record | If-Match did not match; someone else changed it first. |
| 422 | rule_violation | NolaPro refused the change. message carries its reason. |
curl -X PATCH \ 'https://acme.nolapro.com/!/api/v2/shipments/104' \ -H 'Authorization: Bearer $NP_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: your-unique-key' \ -d '{ "carrierserviceid": 104, "shipdate": "2026-08-01" }'
$ch = curl_init('https://acme.nolapro.com/!/api/v2/shipments/104'); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NP_TOKEN')], CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'PATCH', CURLOPT_POSTFIELDS => json_encode([ 'carrierserviceid' => 104, 'shipdate' => '2026-08-01', ]), ]); $res = json_decode(curl_exec($ch), true);
import os, requests r = requests.patch( "https://acme.nolapro.com/!/api/v2/shipments/104", headers={"Authorization": f"Bearer {os.environ['NP_TOKEN']}"}, json={ "carrierserviceid": 104, "shipdate": "2026-08-01", }, ) r.raise_for_status()
const res = await fetch( 'https://acme.nolapro.com/!/api/v2/shipments/104', { method: 'PATCH', headers: { Authorization: `Bearer ${process.env.NP_TOKEN}` }, body: JSON.stringify({ carrierserviceid: 104, shipdate: "2026-08-01", }), } ); const data = await res.json();
using System.Net.Http.Json; var token = Environment.GetEnvironmentVariable("NP_TOKEN"); using var http = new HttpClient(); http.DefaultRequestHeaders.Add("Authorization", "Bearer " + token); var body = new { carrierserviceid = 104, shipdate = "2026-08-01", }; var req = new HttpRequestMessage(HttpMethod.Patch, "https://acme.nolapro.com/!/api/v2/shipments/104") { Content = JsonContent.Create(body), }; req.Headers.Add("Idempotency-Key", "your-unique-key"); var res = await http.SendAsync(req); res.EnsureSuccessStatusCode();
Cancel.
Requires scope shipments:cancel.
| Name | In | Type | Notes |
|---|---|---|---|
| idrequired | path | integer | The record id. |
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | The request was malformed. |
| 409 | cannot_cancel | Something already depends on this document - a payment, a shipment, an invoice. |
| 409 | shipment_already_invoiced | The shipment has been invoiced; the customer has been billed for it. |
| 422 | unknown_value | No such record in this company. |
curl -X DELETE \ 'https://acme.nolapro.com/!/api/v2/shipments/104' \ -H 'Authorization: Bearer $NP_TOKEN'
$ch = curl_init('https://acme.nolapro.com/!/api/v2/shipments/104'); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NP_TOKEN')], CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'DELETE', ]); $res = json_decode(curl_exec($ch), true);
import os, requests r = requests.delete( "https://acme.nolapro.com/!/api/v2/shipments/104", headers={"Authorization": f"Bearer {os.environ['NP_TOKEN']}"}, ) r.raise_for_status()
const res = await fetch( 'https://acme.nolapro.com/!/api/v2/shipments/104', { method: 'DELETE', headers: { Authorization: `Bearer ${process.env.NP_TOKEN}` }, } ); const data = await res.json();
using System.Net.Http.Json; var token = Environment.GetEnvironmentVariable("NP_TOKEN"); using var http = new HttpClient(); http.DefaultRequestHeaders.Add("Authorization", "Bearer " + token); var req = new HttpRequestMessage(HttpMethod.Delete, "https://acme.nolapro.com/!/api/v2/shipments/104"); var res = await http.SendAsync(req); res.EnsureSuccessStatusCode();
Invoice this shipment.
Not available through the API yet. The single-shipment branch of arorder2invoice.php terminates the request with its own page output, so this cannot be served as JSON without changing page code. Invoice the whole order with POST /orders/{id}/invoice, which is live. This endpoint answers 501 in the meantime.
Requires scope invoices:write.
| Name | In | Type | Notes |
|---|---|---|---|
| idrequired | path | integer | |
| Field | Type | Description |
|---|---|---|
| invoicedate | string | Invoice date. Defaults to what NolaPro would use. |
| Status | Code | Meaning |
|---|---|---|
| 404 | not_found | No shipment with that id. |
| 409 | shipment_already_invoiced | The shipment is cancelled, or already invoiced. |
| 422 | nothing_to_invoice | Nothing on the shipment is billable. |
curl -X POST \ 'https://acme.nolapro.com/!/api/v2/shipments/104/invoice' \ -H 'Authorization: Bearer $NP_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: your-unique-key' \ -d '{ "invoicedate": "2026-08-02" }'
$ch = curl_init('https://acme.nolapro.com/!/api/v2/shipments/104/invoice'); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NP_TOKEN')], CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS => json_encode([ 'invoicedate' => '2026-08-02', ]), ]); $res = json_decode(curl_exec($ch), true);
import os, requests r = requests.post( "https://acme.nolapro.com/!/api/v2/shipments/104/invoice", headers={"Authorization": f"Bearer {os.environ['NP_TOKEN']}"}, json={ "invoicedate": "2026-08-02", }, ) r.raise_for_status()
const res = await fetch( 'https://acme.nolapro.com/!/api/v2/shipments/104/invoice', { method: 'POST', headers: { Authorization: `Bearer ${process.env.NP_TOKEN}` }, body: JSON.stringify({ invoicedate: "2026-08-02", }), } ); const data = await res.json();
using System.Net.Http.Json; var token = Environment.GetEnvironmentVariable("NP_TOKEN"); using var http = new HttpClient(); http.DefaultRequestHeaders.Add("Authorization", "Bearer " + token); var body = new { invoicedate = "2026-08-02", }; var req = new HttpRequestMessage(HttpMethod.Post, "https://acme.nolapro.com/!/api/v2/shipments/104/invoice") { Content = JsonContent.Create(body), }; req.Headers.Add("Idempotency-Key", "your-unique-key"); var res = await http.SendAsync(req); res.EnsureSuccessStatusCode();
{
"orderstatus": "quote"
}
Packing slip as a PDF
The packing slip for the shipment: what is in the boxes, without prices.
Answers application/pdf, not JSON. Because the body is binary it cannot be carried inside a /batch results array; asking for it there returns 415 not_batchable.
Requires scope shipments:read.
| Name | In | Type | Notes |
|---|---|---|---|
| idrequired | path | integer | The record id. |
curl \ 'https://acme.nolapro.com/!/api/v2/shipments/104/pdf' \ -H 'Authorization: Bearer $NP_TOKEN'
$ch = curl_init('https://acme.nolapro.com/!/api/v2/shipments/104/pdf'); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NP_TOKEN')], CURLOPT_RETURNTRANSFER => true, ]); $res = json_decode(curl_exec($ch), true);
import os, requests r = requests.get( "https://acme.nolapro.com/!/api/v2/shipments/104/pdf", headers={"Authorization": f"Bearer {os.environ['NP_TOKEN']}"}, ) r.raise_for_status()
const res = await fetch( 'https://acme.nolapro.com/!/api/v2/shipments/104/pdf', { method: 'GET', headers: { Authorization: `Bearer ${process.env.NP_TOKEN}` }, } ); const data = await res.json();
using System.Net.Http.Json; var token = Environment.GetEnvironmentVariable("NP_TOKEN"); using var http = new HttpClient(); http.DefaultRequestHeaders.Add("Authorization", "Bearer " + token); var res = await http.GetAsync( "https://acme.nolapro.com/!/api/v2/shipments/104/pdf"); res.EnsureSuccessStatusCode();
Box labels as a PDF
Shipping labels for the cartons in this shipment, laid out for a label printer.
Answers application/pdf, not JSON. Because the body is binary it cannot be carried inside a /batch results array; asking for it there returns 415 not_batchable.
Requires scope shipments:read.
| Name | In | Type | Notes |
|---|---|---|---|
| idrequired | path | integer | The record id. |
curl \ 'https://acme.nolapro.com/!/api/v2/shipments/104/boxlabels' \ -H 'Authorization: Bearer $NP_TOKEN'
$ch = curl_init('https://acme.nolapro.com/!/api/v2/shipments/104/boxlabels'); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NP_TOKEN')], CURLOPT_RETURNTRANSFER => true, ]); $res = json_decode(curl_exec($ch), true);
import os, requests r = requests.get( "https://acme.nolapro.com/!/api/v2/shipments/104/boxlabels", headers={"Authorization": f"Bearer {os.environ['NP_TOKEN']}"}, ) r.raise_for_status()
const res = await fetch( 'https://acme.nolapro.com/!/api/v2/shipments/104/boxlabels', { method: 'GET', headers: { Authorization: `Bearer ${process.env.NP_TOKEN}` }, } ); const data = await res.json();
using System.Net.Http.Json; var token = Environment.GetEnvironmentVariable("NP_TOKEN"); using var http = new HttpClient(); http.DefaultRequestHeaders.Add("Authorization", "Bearer " + token); var res = await http.GetAsync( "https://acme.nolapro.com/!/api/v2/shipments/104/boxlabels"); res.EnsureSuccessStatusCode();