API docs by Redocly

The Ocean Package (Public API) (2.0.0)

Download OpenAPI specification:

Terms of Service

An API to track reusable packages and their shipping processes.

package management

Assign a package

Assign a package to an organization based on metadata. If the package is already assigned, it returns the existing package ID. If no package is available, it returns an error. If the no_assign flag is set, it will not assign a package even if one is available.

Authorizations:
ApiKeyAuth
path Parameters
organization_id
required
string <typeid> ^organization_[0-7][0-9a-hjkmnpq-tv-z]{25}$|^...
Example: organization_01jtn797z8fvfrz7af5hbft5w2

Organization ID. Use @current for your organization.

Request Body schema:
required

Request body

metadata
required
string
no_assign
boolean
Default: false
package_size_id
string <typeid> ^package_size_[0-7][0-9a-hjkmnpq-tv-z]{25}$

Responses

Request samples

Content type
{
  • "metadata": "48733e8106f85ec59a9cb716fadfa2fd",
  • "no_assign": false,
  • "package_size_id": "package_size_01jtn797z8fvfrz7af5hbft5w2"
}

Response samples

Content type
application/json
{
  • "assigned": true,
  • "package_id": "package_01jtn797z8fvfrz7af5hbft5w2"
}

organizations

Assign a package

Assign a package to an organization based on metadata. If the package is already assigned, it returns the existing package ID. If no package is available, it returns an error. If the no_assign flag is set, it will not assign a package even if one is available.

Authorizations:
ApiKeyAuth
path Parameters
organization_id
required
string <typeid> ^organization_[0-7][0-9a-hjkmnpq-tv-z]{25}$|^...
Example: organization_01jtn797z8fvfrz7af5hbft5w2

Organization ID. Use @current for your organization.

Request Body schema:
required

Request body

metadata
required
string
no_assign
boolean
Default: false
package_size_id
string <typeid> ^package_size_[0-7][0-9a-hjkmnpq-tv-z]{25}$

Responses

Request samples

Content type
{
  • "metadata": "48733e8106f85ec59a9cb716fadfa2fd",
  • "no_assign": false,
  • "package_size_id": "package_size_01jtn797z8fvfrz7af5hbft5w2"
}

Response samples

Content type
application/json
{
  • "assigned": true,
  • "package_id": "package_01jtn797z8fvfrz7af5hbft5w2"
}

Get a package

Retrieve a package by its ID.

Authorizations:
ApiKeyAuth
path Parameters
organization_id
required
string <typeid> ^organization_[0-7][0-9a-hjkmnpq-tv-z]{25}$|^...
Example: organization_01jtn797z8fvfrz7af5hbft5w2

Organization ID. Use @current for your organization.

package_id
required
string <typeid> ^package_[0-7][0-9a-hjkmnpq-tv-z]{25}$
Example: package_01jtn797z8fvfrz7af5hbft5w2

Package ID

Responses

Response samples

Content type
application/json
{
  • "circulation_duration": 3600,
  • "defect": {},
  • "id": "package_01jtn797z8fvfrz7af5hbft5w2",
  • "last_activity_at": "2019-08-24T14:15:22Z",
  • "location": "warehouse",
  • "metadata": "48733e8106f85ec59a9cb716fadfa2fd",
  • "organization_tag": "STD",
  • "package_size_id": "package_size_01jtn797z8fvfrz7af5hbft5w2",
  • "sequential_id": 100,
  • "shipment_count": 1,
  • "shipments": [
    ],
  • "status": "defect"
}

Report package defect

Report a defect in a package. NOTE: application/x-www-form-urlencoded and application/json ARE supported if you only want to send the reason.

Authorizations:
ApiKeyAuth
path Parameters
organization_id
required
string <typeid> ^organization_[0-7][0-9a-hjkmnpq-tv-z]{25}$|^...
Example: organization_01jtn797z8fvfrz7af5hbft5w2

Organization ID. Use @current for your organization.

package_id
required
string <typeid> ^package_[0-7][0-9a-hjkmnpq-tv-z]{25}$
Example: package_01jtn797z8fvfrz7af5hbft5w2

Package ID

Request Body schema: multipart/form-data
required

Report package defect request

image
string <binary>
reason
string

Responses

Response samples

Content type
application/json
{}

Create a package shipment

Create a new shipment for a package.

Authorizations:
ApiKeyAuth
path Parameters
organization_id
required
string <typeid> ^organization_[0-7][0-9a-hjkmnpq-tv-z]{25}$|^...
Example: organization_01jtn797z8fvfrz7af5hbft5w2

Organization ID. Use @current for your organization.

package_id
required
string <typeid> ^package_[0-7][0-9a-hjkmnpq-tv-z]{25}$
Example: package_01jtn797z8fvfrz7af5hbft5w2

Package ID

Request Body schema:
required

Shipment request

sanity
boolean

Opt-into sanity checks which cover some common errors (double scans, fast scans, etc.)

source
string <uri>

Who performed the scan. Should be an URI. If you have multiple scanners, you can include the scanner ID here.

timestamp
string <date-time>
object (TrackingInformation)

Optional tracking information for the shipment

type
required
string (PackageShipmentType)
Enum: "inbound" "outbound"

Responses

Request samples

Content type
{
  • "sanity": true,
  • "source": "urn:mustermann-logistics:scan",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "tracking": {
    },
  • "type": "inbound"
}

Response samples

Content type
application/json
{
  • "id": "package_shipment_01jtn797z8fvfrz7af5hbft5w2"
}

packages

Get a package

Retrieve a package by its ID.

Authorizations:
ApiKeyAuth
path Parameters
organization_id
required
string <typeid> ^organization_[0-7][0-9a-hjkmnpq-tv-z]{25}$|^...
Example: organization_01jtn797z8fvfrz7af5hbft5w2

Organization ID. Use @current for your organization.

package_id
required
string <typeid> ^package_[0-7][0-9a-hjkmnpq-tv-z]{25}$
Example: package_01jtn797z8fvfrz7af5hbft5w2

Package ID

Responses

Response samples

Content type
application/json
{
  • "circulation_duration": 3600,
  • "defect": {},
  • "id": "package_01jtn797z8fvfrz7af5hbft5w2",
  • "last_activity_at": "2019-08-24T14:15:22Z",
  • "location": "warehouse",
  • "metadata": "48733e8106f85ec59a9cb716fadfa2fd",
  • "organization_tag": "STD",
  • "package_size_id": "package_size_01jtn797z8fvfrz7af5hbft5w2",
  • "sequential_id": 100,
  • "shipment_count": 1,
  • "shipments": [
    ],
  • "status": "defect"
}

Report package defect

Report a defect in a package. NOTE: application/x-www-form-urlencoded and application/json ARE supported if you only want to send the reason.

Authorizations:
ApiKeyAuth
path Parameters
organization_id
required
string <typeid> ^organization_[0-7][0-9a-hjkmnpq-tv-z]{25}$|^...
Example: organization_01jtn797z8fvfrz7af5hbft5w2

Organization ID. Use @current for your organization.

package_id
required
string <typeid> ^package_[0-7][0-9a-hjkmnpq-tv-z]{25}$
Example: package_01jtn797z8fvfrz7af5hbft5w2

Package ID

Request Body schema: multipart/form-data
required

Report package defect request

image
string <binary>
reason
string

Responses

Response samples

Content type
application/json
{}

Create a package shipment

Create a new shipment for a package.

Authorizations:
ApiKeyAuth
path Parameters
organization_id
required
string <typeid> ^organization_[0-7][0-9a-hjkmnpq-tv-z]{25}$|^...
Example: organization_01jtn797z8fvfrz7af5hbft5w2

Organization ID. Use @current for your organization.

package_id
required
string <typeid> ^package_[0-7][0-9a-hjkmnpq-tv-z]{25}$
Example: package_01jtn797z8fvfrz7af5hbft5w2

Package ID

Request Body schema:
required

Shipment request

sanity
boolean

Opt-into sanity checks which cover some common errors (double scans, fast scans, etc.)

source
string <uri>

Who performed the scan. Should be an URI. If you have multiple scanners, you can include the scanner ID here.

timestamp
string <date-time>
object (TrackingInformation)

Optional tracking information for the shipment

type
required
string (PackageShipmentType)
Enum: "inbound" "outbound"

Responses

Request samples

Content type
{
  • "sanity": true,
  • "source": "urn:mustermann-logistics:scan",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "tracking": {
    },
  • "type": "inbound"
}

Response samples

Content type
application/json
{
  • "id": "package_shipment_01jtn797z8fvfrz7af5hbft5w2"
}