# Authentication
Source: https://docs.shipstream.io/global-api/authentication
Authentication (is the caller who they say they are?) and authorization (are they allowed to do this?) are handled by passing a [JWT](https://jwt.io/) (JSON Web Token) in the `Authorization` header of the request. The token is signed with a secret key using a strong encryption algorithm, and the server verifies the signature to ensure the token is valid and to identify the caller.
See [Find Your URL](/home/find-your-url) for information on finding the correct URL to use for your ShipStream instance.
The JWT token is typically obtained by creating a [Custom Global Integration](https://help.shipstream.io/article/15i0ut0c8e-global-integrations#custom_integrations) in the Admin UI. Once the token is obtained, it should be included in the `Authorization` header of every request to the API which requires authentication.
The `Authorization` header should be formatted as follows:
```http theme={null}
Authorization: Bearer {jwt_token}
```
Where `{jwt_token}` is the actual JWT token string.
The server will validate the token and extract the user's identity and permissions from it. If the token is valid, the request will be processed; if not, a "401 Unauthorized" error response will be returned indicating that authentication failed.
#### Danger, Will Robinson!
The JWT token should be kept secure and not shared with anyone. Paste it into your system's secure storage and generate a new one if you think it has been compromised or you need additional tokens for other systems.
## Inspecting Tokens
To inspect the contents of a JWT token, you can use online tools such as [jwt.io](https://jwt.io/) or libraries that decode JWTs. The token consists of three parts: header, payload, and signature, separated by dots (`.`). The header and payload are Base64Url encoded JSON objects, while the signature is used to verify the integrity of the token. You can extract the payload to glean useful information such as:
* `aud`: The ShipStream WMS instance base url for which the token is intended.
* `exp`: The expiration time of the token, typically a Unix timestamp.
* `iat`: The issued-at time of the token, also a Unix timestamp.
## Expiration and Renewal
JWTs may have an expiration time to limit their validity period. When a token expires, the user must obtain a new token. The expiration time can be adjusted based on security requirements. Before making a request, you can decode the JWT token to check its expiration time (`exp`) to ensure it is still valid.
# Get Handling Class by code
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/handling-classes/by-code/{code}/get
GET /v1/inventory/handling-classes/by-code/{code}
Returns a Handling Class by its stable immutable code. Add
`fields=conditions,conditions_readable` when loading the class for editing.
# List Handling Class condition fields
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/handling-classes/condition-fields/get
GET /v1/inventory/handling-classes/condition-fields
Returns the server-owned Product condition catalogue for Handling Class editor clients.
Load this catalogue when opening an editor; it is not repeated in each Handling Class
response. Fields with a `value_source` use the advertised bounded search endpoint, while
Product Profiles are returned as a finite inline option map.
# List Handling Classes
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/handling-classes/get
GET /v1/inventory/handling-classes
Returns Handling Classes and their current asynchronous classification state. Request
`fields=conditions,conditions_readable` when a client needs the canonical condition
definition for editing.
# Create Handling Class
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/handling-classes/post
POST /v1/inventory/handling-classes
Creates a Warehouse-scoped Handling Class. When `code` is omitted or blank, ShipStream
generates one from the name. Classification is scheduled after the save commits. Add
`fields=conditions,conditions_readable` to include canonical conditions in the created
resource.
# Delete Handling Class
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/handling-classes/{id}/delete
DELETE /v1/inventory/handling-classes/{id}
Deletes a Handling Class. Returns `422` with `used_by.slotting_rules` and
`used_by.replenishment_policies` counts while either dependency exists.
On success, the endpoint returns `200 OK` with an empty response body.
# Get Handling Class
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/handling-classes/{id}/get
GET /v1/inventory/handling-classes/{id}
Returns one `HandlingClass` by its numeric ID. Add
`fields=conditions,conditions_readable` when loading the class for editing.
# Update Handling Class
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/handling-classes/{id}/put
PUT /v1/inventory/handling-classes/{id}
Partially updates a Handling Class. `code` is immutable and is not accepted. Changes to
conditions, sort order, or Warehouse assignments schedule asynchronous reclassification
after commit.
On success, the endpoint returns `200 OK` with an empty response body.
# List active hold reasons
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/hold-reasons/get
GET /v1/inventory/hold-reasons
Returns the active hold-reason tree as a flat list of parent (system) reasons; each parent
inlines its user-defined child reasons via the `children` array. Schema enforces a single
nesting level — child reasons never carry a `children` key.
Cross-merchant by design (no website scoping). System reasons are always returned; user-defined
reasons are returned regardless of which merchant created them.
See the **Inventory Hold System** documentation for hold semantics.
# Create user-defined hold reason
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/hold-reasons/post
POST /v1/inventory/hold-reasons
Creates a new user-defined child hold reason under an existing top-level system reason.
System fields (`is_system`, `reason_id`, `parent_code`, `parent_reason_id`) are
server-controlled and must not be included in the request body.
The `code` must be unique, match `^[a-z0-9_]+$`, and be ≤ 64 characters.
The `parent.id` must reference a top-level system reason.
# Delete user-defined hold reason
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/hold-reasons/{id}/delete
DELETE /v1/inventory/hold-reasons/{id}
Deletes a user-defined `HoldReason` specified by an `id` path parameter. System reasons
cannot be deleted. User reasons that are referenced by existing holds also cannot be
deleted (returns 422).
# Update hold reason
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/hold-reasons/{id}/put
PUT /v1/inventory/hold-reasons/{id}
Partially updates a `HoldReason` specified by an `id` path parameter. Per-field constraints
differ between system and user-defined reasons — see each property's description below.
# List / search inventory holds
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/holds/get
GET /v1/inventory/holds
Returns a list of `Hold` objects. Cross-merchant by design — filter by `merchant_id` or
`product_id`/`sku` to scope to a specific merchant.
# Place location-level Hold
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/holds/location/post
POST /v1/inventory/holds/location
Places an inventory hold on the specified location for the given reason. A hold freezes the
entire location: its on-shelf inventory becomes held — excluded from available and advertised
quantity and unavailable for allocation — until the hold is released.
Partial holds are not supported. `qty` is optional; when supplied it must equal the location's
full on-shelf quantity at the time of the call, or the request returns 422. When omitted, the
whole location is held.
# Place lot-level Hold (with optional BOM cascade)
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/holds/lot/post
POST /v1/inventory/holds/lot
Places holds on every active putaway location currently carrying the named lot.
`cascade_bom=false` (default) — the engine's `Hold::placeByLot` path. Each affected location
gets a location-scope `stock_hold` row with `parent_hold_id=NULL`.
`cascade_bom=true` — the engine's `Hold::cascadeLotHold` path. The hold cascades through the
BOM lineage discovered via `work_lot_input` / `work_component_lot`. The response carries
`cascade.release_mode` as a hint for downstream tooling, but cascaded holds must currently be
freed per-id via `POST /v1/inventory/holds/{id}/release` using
`origin.created_origin_hold_ids ∪ cascade.child_hold_ids`.
**Do not blindly release `origin.root_hold_ids`** — those may include pre-existing roots
from a prior `cascadeLotHold` call that this call attached children to, and releasing them
would also release siblings the current caller did not place.
# Release all active Holds on Lot
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/holds/lot/{lot_id}/release/post
POST /v1/inventory/holds/lot/{lot_id}/release
Releases every active `stock_hold` row whose `lot_id` matches the path parameter, regardless
of reason. Useful for "lift quarantine on lot X" workflows.
**Cascaded lot release is not currently supported.** Sending `release_cascaded=true` returns
a 400 RequestNotValid. To free a cascaded hold tree, release each child via
`POST /v1/inventory/holds/{id}/release`.
For cascaded holds (placed via `holdLot` with `cascade_bom=true`), release per-id using
`origin.created_origin_hold_ids ∪ cascade.child_hold_ids` from the original `holdLot`
response.
# Get one Hold by ID
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/holds/{id}/get
GET /v1/inventory/holds/{id}
Returns a single `Hold` object specified by a hold `id` path parameter.
# Release one Hold by ID
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/holds/{id}/release/post
POST /v1/inventory/holds/{id}/release
Releases a single active `stock_hold` row by its `id`.
# List total inventory levels
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/levels/total/get
GET /v1/inventory/levels/total
Returns a list of `TotalLevel` objects showing aggregated inventory quantities
across all warehouses for each product.
This endpoint provides a system-wide view of inventory, combining quantities
from all warehouses where products are stocked.
# List warehouse inventory levels
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/levels/warehouse/get
GET /v1/inventory/levels/warehouse
Retrieve inventory levels grouped by warehouse for each product. This endpoint returns
warehouse-specific inventory data with quantity information per product per warehouse.
# List Location Tags
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/location-tags/get
GET /v1/inventory/location-tags
Returns a list of `LocationTag` objects.
Soft-deleted tags are excluded unless the request filters on `is_deleted`, in which case
the filter alone decides which tags are returned.
# Create Location Tag
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/location-tags/post
POST /v1/inventory/location-tags
Creates a new `LocationTag` according to the request body. The `name` must be unique among
live location tags; deleting a tag renames it with a suffix, so a deleted tag's original
name is immediately reusable.
# Delete Location Tag
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/location-tags/{id}/delete
DELETE /v1/inventory/location-tags/{id}
Soft-deletes a `LocationTag` specified by its `id` path parameter. The tag row is kept so that
locations already carrying it continue to display it; only new assignments are prevented. The
tag's `name` gains a `(Deleted ID: n)` suffix, freeing the original name for reuse.
Because nothing is removed, a tag in use by locations deletes successfully — this operation
never reports a conflict. Reverse it with `PUT {"is_deleted": false}`. Deleting an
already-deleted tag is a no-op.
# Get one Location Tag
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/location-tags/{id}/get
GET /v1/inventory/location-tags/{id}
Returns a single `LocationTag` object specified by its `id` path parameter. Soft-deleted tags
remain readable here.
# Update Location Tag
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/location-tags/{id}/put
PUT /v1/inventory/location-tags/{id}
Partially updates a `LocationTag` specified by its `id` path parameter. Only the properties
present in the request body are changed.
Setting `is_deleted` restores or soft-deletes the tag, which also rewrites its `name`: a
soft-delete appends a `(Deleted ID: n)` suffix and a restore strips it. A restore fails with
`422` when the reclaimed name has since been taken by another tag.
# List Product condition values
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/product-condition-values/get
GET /v1/inventory/product-condition-values
Returns a bounded prefix search of raw values for a Product condition field. Use the field,
minimum query length, and maximum result count advertised by the condition catalogue. Results
include disabled simple Products because saved Profile conditions must remain editable.
# Get Product Profile by code
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/product-profiles/by-code/{code}/get
GET /v1/inventory/product-profiles/by-code/{code}
Returns a Product Profile by its stable immutable external code. Add
`fields=conditions,conditions_readable` when loading the Profile for editing.
# List Product Profile condition fields
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/product-profiles/condition-fields/get
GET /v1/inventory/product-profiles/condition-fields
Returns the server-owned Product condition catalogue for editor clients. Load this catalogue
when opening an editor; it is not repeated in each Product Profile response. Fields with a
`value_source` use the advertised bounded search endpoint instead of an inline option list.
# List Product Profiles
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/product-profiles/get
GET /v1/inventory/product-profiles
Returns Product Profiles and their current asynchronous classification state. Request
`fields=conditions,conditions_readable` when a client needs the canonical condition
definition for editing.
# Create Product Profile
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/product-profiles/post
POST /v1/inventory/product-profiles
Creates a Product Profile. When `code` is omitted or blank, ShipStream generates one from
the name. Classification is scheduled after the save commits. Add
`fields=conditions,conditions_readable` to include canonical conditions in the created
resource.
# Delete Product Profile
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/product-profiles/{id}/delete
DELETE /v1/inventory/product-profiles/{id}
Deletes a Product Profile. Returns `422` with `used_by.slotting_rules`,
`used_by.replenishment_policies`, and `used_by.handling_classes` counts while any dependency exists.
On success, the endpoint returns `200 OK` with an empty response body.
# Get Product Profile
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/product-profiles/{id}/get
GET /v1/inventory/product-profiles/{id}
Returns one `ProductProfile` by its numeric ID. Add
`fields=conditions,conditions_readable` when loading the Profile for editing.
# List Product Profile member Products
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/product-profiles/{id}/products/get
GET /v1/inventory/product-profiles/{id}/products
Returns the current materialized Product membership. The request does not evaluate conditions;
after creating a Profile or changing its conditions, poll it until classification is
`up_to_date`. Product changes are classified through a separate asynchronous changelog, so a
recently changed Product may not immediately enter or leave this member set. The default page
size is 50 and the maximum is 250.
# Update Product Profile
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/product-profiles/{id}/put
PUT /v1/inventory/product-profiles/{id}
Partially updates a Product Profile. `code` is immutable and is not accepted. A conditions
change schedules asynchronous reclassification after commit.
On success, the endpoint returns `200 OK` with an empty response body.
# Create Product or Packaging
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/products/post
POST /v1/inventory/products
Creates a new `Product` or `PackagingFeature` in ShipStream according to the request body.
# List all Products and Packaging
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/products/{type}/get
GET /v1/inventory/products/{type}
Returns a list of [Products](https://help.shipstream.io/article/8b9rvho130-products) (SKUs) or [Packaging Features](https://help.shipstream.io/article/cxyprn6ysa-packaging-features)
specified by the `type` path parameter and according to the request body.
# Get Product Classifications
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/products/{type}/{id}/classifications/get
GET /v1/inventory/products/{type}/{id}/classifications
Returns the Product's current materialized Product Profile memberships and per-Warehouse
Handling Class assignments. Classification is eventually consistent: Product changes flow
through an asynchronous changelog and typically converge within a couple of minutes, and no
per-Product freshness signal exists. The Handling Class `classification.status` covers only
Handling Class definition changes (conditions and Warehouse assignments); it does not reflect
pending Product-triggered reclassification.
Only enabled `normal` Products are classified: a disabled or packaging Product returns empty
`product_profiles` and a NULL `handling_class` for every Warehouse it is stocked in. A NULL
Handling Class means the Product is stocked in that Warehouse but has no assigned class —
either no Handling Class conditions matched or the Product is not classifiable. A Warehouse
appears only when the Product is stocked there and the Warehouse has at least one Handling
Class.
# Get Product or Packaging
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/products/{type}/{id}/get
GET /v1/inventory/products/{type}/{id}
Returns a single `Product` or `Packaging*` object specified by its `id` & `type` path parameter.
# Update Product or Packaging
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/products/{type}/{id}/put
PUT /v1/inventory/products/{type}/{id}
Updates a `Product` in ShipStream specified by its `id` path parameter and according to the request body.
# List Slot Types
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/slot-types/get
GET /v1/inventory/slot-types
Returns a list of `SlotType` objects.
The default field set is the small one embedded on `Location` responses (`id`, `name`,
`is_pickable`); request `fields=all` for the management fields such as `sort_order`,
`patterns` and the capacity measurements.
# Create Slot Type
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/slot-types/post
POST /v1/inventory/slot-types
Creates a new `SlotType` according to the request body. The `name` must be unique.
Measurements are stored in the instance's base unit; a value submitted with a different
`unit` is converted first. Setting `is_fixed_capacity` to `true` requires all three slot
dimensions to be present and greater than zero.
# Delete Slot Type
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/slot-types/{id}/delete
DELETE /v1/inventory/slot-types/{id}
Deletes a `SlotType` specified by its `id` path parameter.
A slot type that is assigned to any location cannot be deleted and returns `422` with a
`used_by` detail reporting how many locations are in the way. Deleting the last
non-pickable slot type is also refused with `422`, because every warehouse needs one.
# Get one Slot Type
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/slot-types/{id}/get
GET /v1/inventory/slot-types/{id}
Returns a single `SlotType` object specified by its `id` path parameter.
# Update Slot Type
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/slot-types/{id}/put
PUT /v1/inventory/slot-types/{id}
Partially updates a `SlotType` specified by its `id` path parameter. Only the properties
present in the request body are changed; sending `patterns` replaces the whole list.
Changing the slot dimensions or `is_fixed_capacity` queues the affected locations for
capacity recalculation, so a change is not reflected in utilization figures until those
jobs run.
# List all Warehouses
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/get
GET /v1/inventory/warehouses
Returns a list of `Warehouse` objects.
Please see [Warehouses](https://help.shipstream.io/article/ny45i1gqf2-warehouses) in our user documentation for more information.
# Create Warehouse
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/post
POST /v1/inventory/warehouses
Creates a new `Warehouse` in ShipStream according to the request body.
# Delete Warehouse
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/delete
DELETE /v1/inventory/warehouses/{id}
Deletes a `Warehouse` specified by its `id` path parameter.
# Get one Warehouse
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/get
GET /v1/inventory/warehouses/{id}
Returns a single `Warehouse` object specified by its `id` path parameter.
# List Location Profiles
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/location-profiles/get
GET /v1/inventory/warehouses/{id}/location-profiles
Returns Location Profiles of one warehouse specified by its `id` path parameter, with
publication status, revision snapshots, the ordered match definition, and live usage
counts.
The response `meta` carries the warehouse-level membership repair freshness
(`membership_status`, `membership_current`, `membership_repaired_at`).
The `match` clauses keep selected Location Tags and Slot Types as compact `{type, id}`
references. For an editor, request `fields=location_tags,slot_types` together with
`fields:location_tags=name,color` and `fields:slot_types=name,is_pickable` to resolve
only those direct selections through `included`.
# Create Location Profile
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/location-profiles/post
POST /v1/inventory/warehouses/{id}/location-profiles
Creates a Location Profile in the warehouse specified by its `id` path parameter and starts
materializing its membership.
Always returns `202 Accepted`: the profile exists immediately, but its member locations are
resolved asynchronously. Poll the resource until `status` is `ready` before referencing it
from a Slotting Rule. A Replenishment Policy may reference it earlier, but remains
disqualified until the profile is ready.
# Delete Location Profile
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/location-profiles/{profile_id}/delete
DELETE /v1/inventory/warehouses/{id}/location-profiles/{profile_id}
Deletes the Location Profile identified by the `id` and `profile_id` path parameters, along
with its revisions, match clauses and materialized membership.
A profile that any Slotting Rule, Replenishment Policy, or published Replenishment result
still references cannot be deleted. The request is refused with `422` and stable
`used_by.slotting_rules`, `used_by.replenishment_policies`, and
`used_by.published_replenishment_results` details reporting how many of each stand in the way.
Remove live Rule and Policy references;
after a Policy moves away, the Warehouse Replenishment index must publish again before its
previous result rows release the profile. There is no force or cascade variant.
# Get Location Profile
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/location-profiles/{profile_id}/get
GET /v1/inventory/warehouses/{id}/location-profiles/{profile_id}
Returns one `LocationProfile` of one warehouse specified by the `id` and `profile_id`
path parameters. `match` is the latest intended definition — the pending revision's
clauses while a rebuild is in flight, otherwise the published revision's.
The response `meta` carries the warehouse-level membership repair freshness
(`membership_status`, `membership_current`, `membership_repaired_at`).
The `match` clauses keep selected Location Tags and Slot Types as compact `{type, id}`
references. For an editor, request `fields=location_tags,slot_types` together with
`fields:location_tags=name,color` and `fields:slot_types=name,is_pickable` to resolve
only those direct selections through `included`.
# List Location Profile member Locations
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/location-profiles/{profile_id}/locations/get
GET /v1/inventory/warehouses/{id}/location-profiles/{profile_id}/locations
Returns full `Location` objects from the resolved membership of one `LocationProfile`.
The response supports the same field selection, filtering, sorting, and cursor paging as
the Warehouse Locations endpoint. Membership is read from the ready active revision, and
`meta.profile_revision_id` identifies the exact revision that supplied the page.
A profile without a ready active revision has no resolved member set and responds with
`422` instead of an empty collection; a ready profile with zero members is a genuine
empty set and responds with an empty collection. Cursor continuation is available only
when sorting by `id`; other sorts return the bounded page without cursor links.
# Update Location Profile
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/location-profiles/{profile_id}/put
PUT /v1/inventory/warehouses/{id}/location-profiles/{profile_id}
Updates the Location Profile identified by the `id` and `profile_id` path parameters. Only
the properties present in the body are applied.
Omitting `match` keeps the saved definition; send `match: []` to mean "every non-temporary
location in the warehouse" explicitly.
Returns `202 Accepted` when the request started a new materialization, and `200 OK` when
the definition was unchanged and a published revision is already serving the profile. An
unchanged definition submitted while a build is still in flight also returns `202`, because
the submitted definition has not published yet. During a replacement, `status` may remain
`ready` because the previous revision still serves consumers. Poll `pending_revision` instead:
successful publication is complete when it becomes `null`, while a failed replacement remains
present with a `failed` status.
# Rebuild Location Profile
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/location-profiles/{profile_id}/rebuild/post
POST /v1/inventory/warehouses/{id}/location-profiles/{profile_id}/rebuild
Re-materializes the current definition of the Location Profile identified by the `id` and
`profile_id` path parameters, under a fresh revision. The definition itself is unchanged.
Use this to retry a `failed` build, or to force a full re-scan when locations changed in a
way the incremental pipeline could not observe. The profile keeps serving its published
revision, if it has one, until the rebuild finishes.
A successful request returns `202 Accepted`. A ready profile remains `ready` while the replacement builds,
so poll `pending_revision` rather than the top-level `status`. Successful publication is
complete when `pending_revision` becomes `null`; a failed rebuild remains present there with
a `failed` status. A second rebuild request is rejected with `422 Unprocessable Entity` while
the pending revision is still `building`; wait for that build to settle before retrying.
A profile that has never had a definition saved cannot be rebuilt — there is nothing to
re-run, and treating it as the all-locations definition would silently make it match every
location in the warehouse. Send a `PUT` with an explicit `match` instead.
# Batch update Locations
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/locations/batch/post
POST /v1/inventory/warehouses/{id}/locations/batch
Creates or updates a `Location` collection specified by a warehouse `id` path parameter and according to the request body.
# List all Locations
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/locations/get
GET /v1/inventory/warehouses/{id}/locations
Returns a list of `Location` objects specified by a warehouse `id` path parameter.
# Create Location
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/locations/post
POST /v1/inventory/warehouses/{id}/locations
Creates a new `Location` specified by a warehouse `id` and according to the request body.
# Batch Update Location Tags
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/locations/tags/post
POST /v1/inventory/warehouses/{id}/locations/tags
Adds, removes or replaces `LocationTag` assignments on many locations at once, mirroring the
admin location grid's tag mass actions.
Every referenced location must exist in the warehouse. A tag that has been soft-deleted
cannot be newly assigned, but `add` and `remove` leave an already-assigned deleted tag in
place on locations the operation does not affect. `replace` is stricter: a soft-deleted tag
may not appear in a `replace` payload at all, even if every targeted location already
carries it.
# Delete Location
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/locations/{location_id}/delete
DELETE /v1/inventory/warehouses/{id}/locations/{location_id}
Deletes an existing Location specified by the warehouse `id` and `location_id` path parameters.
# Get one Location
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/locations/{location_id}/get
GET /v1/inventory/warehouses/{id}/locations/{location_id}
Returns a single `Location` object specified by the warehouse `id` and `location_id` path parameters.
# Update Location
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/locations/{location_id}/put
PUT /v1/inventory/warehouses/{id}/locations/{location_id}
Updates a `Location` specified by the warehouse `id` and `location_id` path parameters and according to the request body.
# Get Location by Label
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/locationsByLabel/{label}/get
GET /v1/inventory/warehouses/{id}/locationsByLabel/{label}
Returns a single `Location` object specified by the warehouse `id` and location `label` path parameters.
# Update Warehouse
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/put
PUT /v1/inventory/warehouses/{id}
Updates a `Warehouse` specified by its `id` path parameter and according to the request body.
# Rebuild Replenishment Index
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/replenishment-index/rebuild/post
POST /v1/inventory/warehouses/{id}/replenishment-index/rebuild
Durably requests a rebuild of the Warehouse's Replenishment Index. Repeated requests coalesce
into one pending generation, so retrying a request that may not have landed is safe; the
published report keeps serving its current generation until the new one publishes.
A `soft` request lets a build already in progress finish and publish. A `force` request marks
a running build superseded — it stops without publishing and the fresh generation recomputes
everything from scratch, so repeated `force` requests at intervals shorter than a full build
defer publication indefinitely. `force` is for an explicit operator-initiated full
recalculation; automation should default to `soft`.
A successful request returns `202 Accepted` with the `requested_generation` this request
coalesced into. Poll `/v1/inventory/warehouses/{id}/replenishment-index/status` until
`published_generation` is greater than or equal to that number (the report's
`meta.published_generation` carries the same value), then read the report at
`/v1/inventory/warehouses/{id}/replenishment-report`. If `status` reads `failed`, the server
retries automatically and alerts operators on persistent failure — `last_error` carries a
classified failure summary; stop polling after an hour and escalate rather than wait
indefinitely.
# Get Replenishment Index Status
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/replenishment-index/status/get
GET /v1/inventory/warehouses/{id}/replenishment-index/status
Returns the rebuild lifecycle of the Warehouse's published Replenishment Index: the requested,
building, and published generations, whether the published generation satisfies the newest
request, and failure diagnostics.
Poll this endpoint until `generation_current` is `true` and `status` is `idle`, then read the
published report at `/v1/inventory/warehouses/{id}/replenishment-report` — its `meta` carries
the same `published_generation`, `generation_current`, and `generation_published_at` values.
A Warehouse that has never had a rebuild requested returns NULL `status` and NULL generations;
only an unknown Warehouse is `404`.
# List Policies
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/replenishment-policies/get
GET /v1/inventory/warehouses/{id}/replenishment-policies
Returns the Replenishment Policy configurations of one warehouse specified by
its `id` path parameter, in evaluation order. Calculated per-Product output is
available from the Replenishment Report endpoint.
Product subjects keep their writable ID fields. An editor can additionally
request `fields=merchants,product_profiles,handling_classes` with narrow
nested fields such as `fields:product_profiles=name,code` to resolve only
the selected objects through `included`. Load complete choice lists from
their owning paged endpoints with similarly narrow fields:
- `/v1/system/merchants?fields=code,name,status` (active by default);
- `/v1/inventory/product-profiles?fields=name,code`;
- `/v1/inventory/handling-classes?fields=name,code&filter=warehouse_id:{id}`;
- `/v1/inventory/warehouses/{id}/location-profiles?fields=name,status&filter=status:ready`.
Load configured demand-period choices once from
`/v1/inventory/warehouses/{id}/replenishment-policies/options`.
Paging with `cursor_start` or `cursor_end` requires an explicit `id` or `-id`
sort: the cursor is a range over the identifier, which the default evaluation
order does not follow. A default-ordered listing therefore reports `has_more`
without continuation links; to enumerate a collection larger than one page,
request `sort=id` (or raise `limit`).
# List Policy Options
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/replenishment-policies/options/get
GET /v1/inventory/warehouses/{id}/replenishment-policies/options
Returns the configured Product Velocity periods that may be selected when
creating or editing a Replenishment Policy in the warehouse specified by
`id`. Load these measured-small options once when opening the editor; they
are not repeated in every Policy resource.
Repeated configured day lengths are returned once, in first-configured
order, matching the existing Admin selector.
# Create Policy
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/replenishment-policies/post
POST /v1/inventory/warehouses/{id}/replenishment-policies
Creates a Replenishment Policy in the warehouse specified by its `id` path
parameter.
A Policy created without `is_active` is inactive: it is not evaluated and no
Replenishment rebuild is requested. Creating an active Policy invalidates the
warehouse's published Replenishment results and requests a rebuild, so the
report catches up asynchronously.
# Delete Policy
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/replenishment-policies/{policy_id}/delete
DELETE /v1/inventory/warehouses/{id}/replenishment-policies/{policy_id}
Deletes the Replenishment Policy identified by the `id` and `policy_id` path
parameters, along with its Merchant, Product Profile, and Handling Class
selections.
A Policy that already has computed Replenishment results cannot be deleted —
the published report still refers to it. The request is refused with `422` and a
`used_by.published_replenishment_results` detail containing the blocking row count;
deactivate the Policy, let the warehouse rebuild, then delete it. Deleting an
active Policy changes what the index would produce, so it requests a rebuild.
# Get Policy
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/replenishment-policies/{policy_id}/get
GET /v1/inventory/warehouses/{id}/replenishment-policies/{policy_id}
Returns one `ReplenishmentPolicy` of one warehouse specified by the `id` and
`policy_id` path parameters.
`qualification_reason` is derived on read and reports why the Policy currently
falls through during evaluation. The three published counts are `null` until the
warehouse publishes a Replenishment generation.
To resolve the current editor selections, add
`fields=merchants,product_profiles,handling_classes` and request only direct
display fields such as `fields:merchants=code,name,status`. The writable ID
properties remain the mutation contract, and selected relationships never
recursively expand their own relationships.
# Update Policy
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/replenishment-policies/{policy_id}/put
PUT /v1/inventory/warehouses/{id}/replenishment-policies/{policy_id}
Updates the Replenishment Policy identified by the `id` and `policy_id` path
parameters. Only the properties present in the body are applied; an absent one
keeps its stored value.
Changing a property that affects evaluation — the subject, Location Profile,
DOI band, demand period, activity, or precedence — invalidates the warehouse's
published Replenishment results and requests a rebuild. Renaming a Policy does
not. There is no response body.
# List Report Rows
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/replenishment-report/get
GET /v1/inventory/warehouses/{id}/replenishment-report
Returns published Replenishment Report rows for one warehouse specified by its `id` path parameter.
Each row snapshots the effective Replenishment Policy and Location Profile, the exact profile
revision used for aggregation, quantity/DOI/shortfall results, and the calculation time.
The response `meta` identifies the published generation and whether it satisfies the latest rebuild
request. Clients paging through a report should restart if `published_generation` changes between pages.
Each row's `computed_at` is the per-product quantity-freshness contract.
A report screen can additionally request `fields=policy,location_profile`
with selected direct fields such as `fields:policy=name,is_active` and
`fields:location_profile=name,status,member_count`. The referenced objects
are then returned once through `included`; their own relationships remain
available from the owning Policy and Location Profile endpoints.
Paging with `cursor_start` or `cursor_end` requires the default `id` or `-id` sort: the cursor
is a range over the identifier, which the other sort orders do not follow. A listing under any
other sort therefore reports `has_more` without continuation links; to enumerate more than one
page, use the default `id` or `-id` sort.
# List Slotting Conflicts
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/slotting-conflicts/get
GET /v1/inventory/warehouses/{id}/slotting-conflicts
Returns cursor-paged Slotting Rules whose latest durable conflict result is
positive in the referenced Warehouse. Rule conflict fields are written by
asynchronous conflict detection.
`meta.status` describes current conflict-check queue activity. It is an
operational signal, not a durable generation or point-in-time freshness
guarantee. A detector commit can occur between reading the page, aggregate
counts, and status, so clients should refresh after queued or processing
work settles.
# List Slotting Rule Sets
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/slotting-rule-sets/get
GET /v1/inventory/warehouses/{id}/slotting-rule-sets
Returns Slotting Rule Sets of one warehouse with current Rule counts and
the latest recorded conflict results. Rule counts reflect current child
Rules. Conflict fields may change after asynchronous Slotting processing
completes.
# Create Slotting Rule Set
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/slotting-rule-sets/post
POST /v1/inventory/warehouses/{id}/slotting-rule-sets
Creates an inactive Slotting Rule Set in the referenced warehouse. Add its
Rules before activating it with the update endpoint.
# Delete Slotting Rule Set
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/slotting-rule-sets/{rule_set_id}/delete
DELETE /v1/inventory/warehouses/{id}/slotting-rule-sets/{rule_set_id}
Deletes a Slotting Rule Set and its child Rules from the referenced
warehouse.
On success, the endpoint returns `200 OK` with an empty response body.
# Duplicate Slotting Rule Set
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/slotting-rule-sets/{rule_set_id}/duplicate/post
POST /v1/inventory/warehouses/{id}/slotting-rule-sets/{rule_set_id}/duplicate
Creates an inactive copy in the requested target Warehouse. The copy uses
the source name with a ` (Copy)` suffix and copies the description and
Rules.
A same-Warehouse copy reuses each Rule's ready Location Profile. For a
different Warehouse, typed Zone and Rack criteria are removed, unavailable
Handling Classes are omitted, and equivalent target Location Profiles are
reused or materialized before the response is returned. CEL/script criteria
are copied unchanged and must be reviewed before activation. `meta.warnings`
names Rules whose target definition became broader.
The response includes the standard `SlottingRuleSet` fields. The normal
additive `fields` parameter is accepted for consistency with other resource
endpoints.
# Get Slotting Rule Set
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/slotting-rule-sets/{rule_set_id}/get
GET /v1/inventory/warehouses/{id}/slotting-rule-sets/{rule_set_id}
Returns one Slotting Rule Set identified by the warehouse `id` and
`rule_set_id` path parameters.
# Update Slotting Rule Set
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/slotting-rule-sets/{rule_set_id}/put
PUT /v1/inventory/warehouses/{id}/slotting-rule-sets/{rule_set_id}
Partially updates a Slotting Rule Set. Omitted properties keep their saved
values. Activating or deactivating a Set schedules the existing Slotting
follow-up work after the update commits.
On success, the endpoint returns `200 OK` with an empty response body.
# List Slotting Rules
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/slotting-rule-sets/{rule_set_id}/rules/get
GET /v1/inventory/warehouses/{id}/slotting-rule-sets/{rule_set_id}/rules
Returns cursor-paged Rules belonging to one Rule Set in the referenced
warehouse. Product subjects keep their writable ID fields. An editor can
additionally request `fields=merchants,product_profiles,handling_classes`
with minimal nested fields such as `fields:product_profiles=name,code` to
resolve only the selected objects through `included`. Load complete choice
lists from their owning paged endpoints rather than from every Rule row.
Conflict fields are the latest durable asynchronous detector result.
# Create Slotting Rule
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/slotting-rule-sets/{rule_set_id}/rules/post
POST /v1/inventory/warehouses/{id}/slotting-rule-sets/{rule_set_id}/rules
Creates a Rule in the referenced Warehouse Rule Set. Hard Rules use
`require` or `forbid` and omit `strength`; soft Rules use `prefer` or
`discourage` and require a strength. The existing Slotting lifecycle
schedules any required asynchronous recalculation after the save commits.
# Delete Slotting Rule
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/slotting-rule-sets/{rule_set_id}/rules/{rule_id}/delete
DELETE /v1/inventory/warehouses/{id}/slotting-rule-sets/{rule_set_id}/rules/{rule_id}
Deletes a Rule from the referenced Warehouse Rule Set. Existing Slotting
lifecycle handling removes derived rows and schedules any required
asynchronous recalculation after the delete commits.
On success, the endpoint returns `200 OK` with an empty response body.
# Get Slotting Rule
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/slotting-rule-sets/{rule_set_id}/rules/{rule_id}/get
GET /v1/inventory/warehouses/{id}/slotting-rule-sets/{rule_set_id}/rules/{rule_id}
Returns one Rule identified by its warehouse, owning Rule Set, and Rule ID.
A Rule outside either parent scope is not returned. To resolve the current
editor selections, add `fields=merchants,product_profiles,handling_classes`
and request only display fields such as `fields:merchants=code,name,status`.
The writable ID properties remain the mutation contract.
# Update Slotting Rule
Source: https://docs.shipstream.io/global-api/endpoint/v1/inventory/warehouses/{id}/slotting-rule-sets/{rule_set_id}/rules/{rule_id}/put
PUT /v1/inventory/warehouses/{id}/slotting-rule-sets/{rule_set_id}/rules/{rule_id}
Partially updates a Rule in the referenced Warehouse Rule Set. Omitted
properties retain their saved values. Empty subject lists clear those
selectors. Hard Rules omit `strength`; soft Rules require it.
On success, the endpoint returns `200 OK` with an empty response body.
# List all Deliveries
Source: https://docs.shipstream.io/global-api/endpoint/v1/receiving/{type}/get
GET /v1/receiving/{type}
Returns a list of `ASN`, `RMA`, or `Other` objects specified by the `type` path parameter.
# Get one Delivery
Source: https://docs.shipstream.io/global-api/endpoint/v1/receiving/{type}/{id}/get
GET /v1/receiving/{type}/{id}
Returns a single `ASN`, `RMA`, or `Other` object specified by its `type` & `id` path parameters.
# List all Orders
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/orders/get
GET /v1/shipping/orders
Returns a list of `Order` objects.
To find an order by its unique ID (increment ID), use the filter:
`filter[]=unique_id:eq:1100000042`
# Method not allowed
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/orders/massUpdate/get
GET /v1/shipping/orders/massUpdate
GET method is not allowed for this endpoint. Use POST instead.
# Mass update orders
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/orders/massUpdate/post
POST /v1/shipping/orders/massUpdate
Updates a batch of orders specified by and according to the request body.
# Get one Order
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/orders/{id}/get
GET /v1/shipping/orders/{id}
Returns a single `Order` object specified by an order `id` path parameter.
# List all Retailers
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/retailers/get
GET /v1/shipping/retailers
Returns a list of `Retailer` objects. Archived retailers are excluded by default. Use `archived=true` to include them.
# Create Retailer
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/retailers/post
POST /v1/shipping/retailers
Creates a new `Retailer`.
# Delete Retailer
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/retailers/{id}/delete
DELETE /v1/shipping/retailers/{id}
Archives a `Retailer` specified by its `id` path parameter. The row is soft-deleted by setting status to `archived`.
# Get one Retailer
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/retailers/{id}/get
GET /v1/shipping/retailers/{id}
Returns a single `Retailer` object specified by a retailer `id` path parameter.
# List Retailer Identifiers
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/retailers/{id}/identifiers/get
GET /v1/shipping/retailers/{id}/identifiers
Returns a list of `RetailerIdentifier` objects under the given Retailer.
# Create Retailer Identifier
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/retailers/{id}/identifiers/post
POST /v1/shipping/retailers/{id}/identifiers
Creates a new `RetailerIdentifier` under the given Retailer.
# Delete Retailer Identifier
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/retailers/{id}/identifiers/{identifier_id}/delete
DELETE /v1/shipping/retailers/{id}/identifiers/{identifier_id}
Hard-deletes a `RetailerIdentifier` under the given Retailer. The parent Retailer is unaffected.
# Get one Retailer Identifier
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/retailers/{id}/identifiers/{identifier_id}/get
GET /v1/shipping/retailers/{id}/identifiers/{identifier_id}
Returns a single `RetailerIdentifier` under the given Retailer.
# Update Retailer Identifier
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/retailers/{id}/identifiers/{identifier_id}/put
PUT /v1/shipping/retailers/{id}/identifiers/{identifier_id}
Updates a `RetailerIdentifier` under the given Retailer.
# List Retailer Merchant Settings
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/retailers/{id}/merchant-settings/get
GET /v1/shipping/retailers/{id}/merchant-settings
Returns a list of `RetailerMerchantSetting` objects under the given Retailer.
# Create Retailer Merchant Setting
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/retailers/{id}/merchant-settings/post
POST /v1/shipping/retailers/{id}/merchant-settings
Creates a new `RetailerMerchantSetting` under the given Retailer. Only one row may exist per (retailer, merchant) pair.
# Delete Retailer Merchant Setting
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/retailers/{id}/merchant-settings/{setting_id}/delete
DELETE /v1/shipping/retailers/{id}/merchant-settings/{setting_id}
Hard-deletes a `RetailerMerchantSetting` under the given Retailer. The parent Retailer is unaffected.
# Get one Retailer Merchant Setting
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/retailers/{id}/merchant-settings/{setting_id}/get
GET /v1/shipping/retailers/{id}/merchant-settings/{setting_id}
Returns a single `RetailerMerchantSetting` under the given Retailer.
# Update Retailer Merchant Setting
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/retailers/{id}/merchant-settings/{setting_id}/put
PUT /v1/shipping/retailers/{id}/merchant-settings/{setting_id}
Updates a `RetailerMerchantSetting` under the given Retailer. The `merchant` cannot be changed.
# Update Retailer
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/retailers/{id}/put
PUT /v1/shipping/retailers/{id}
Updates a `Retailer` specified by its `id` path parameter and according to the request body.
# List Retailer Routing Guides
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/retailers/{id}/routing-guides/get
GET /v1/shipping/retailers/{id}/routing-guides
Returns a list of `RetailerRoutingGuide` objects under the given Retailer.
# Create Retailer Routing Guide
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/retailers/{id}/routing-guides/post
POST /v1/shipping/retailers/{id}/routing-guides
Creates a new `RetailerRoutingGuide` from base64-encoded file content.
Allowed extensions: pdf, doc, docx, xls, xlsx, csv, txt.
Maximum decoded file size: 20 MB.
# Delete Retailer Routing Guide
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/retailers/{id}/routing-guides/{guide_id}/delete
DELETE /v1/shipping/retailers/{id}/routing-guides/{guide_id}
Hard-deletes a `RetailerRoutingGuide` and removes the linked storage file. The parent Retailer is unaffected.
# Get Retailer Routing Guide file content
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/retailers/{id}/routing-guides/{guide_id}/file/get
GET /v1/shipping/retailers/{id}/routing-guides/{guide_id}/file
Returns the routing-guide file body wrapped as JSON. `file_content` is
base64-encoded; clients decode it locally.
# Get one Retailer Routing Guide
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/retailers/{id}/routing-guides/{guide_id}/get
GET /v1/shipping/retailers/{id}/routing-guides/{guide_id}
Returns a single `RetailerRoutingGuide` (metadata only — use `/file` for content).
# Update Retailer Routing Guide metadata
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/retailers/{id}/routing-guides/{guide_id}/put
PUT /v1/shipping/retailers/{id}/routing-guides/{guide_id}
Updates `title` and/or `description` only. `file_name` / `file_content` in the body
return `400`; delete and re-create the guide to replace the file.
# List Retailer Ship-To Locations
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/retailers/{id}/ship-to-locations/get
GET /v1/shipping/retailers/{id}/ship-to-locations
Returns a list of `RetailerShipToLocation` objects under the given Retailer.
# Create Retailer Ship-To Location
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/retailers/{id}/ship-to-locations/post
POST /v1/shipping/retailers/{id}/ship-to-locations
Creates a new `RetailerShipToLocation`. If `is_default=true`, sibling defaults under
the same Retailer are atomically unset.
# Delete Retailer Ship-To Location
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/retailers/{id}/ship-to-locations/{location_id}/delete
DELETE /v1/shipping/retailers/{id}/ship-to-locations/{location_id}
Hard-deletes a `RetailerShipToLocation`. The parent Retailer is unaffected.
# Get one Retailer Ship-To Location
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/retailers/{id}/ship-to-locations/{location_id}/get
GET /v1/shipping/retailers/{id}/ship-to-locations/{location_id}
Returns a single `RetailerShipToLocation` under the given Retailer.
# Update Retailer Ship-To Location
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/retailers/{id}/ship-to-locations/{location_id}/put
PUT /v1/shipping/retailers/{id}/ship-to-locations/{location_id}
Updates a `RetailerShipToLocation`. If the resulting `is_default=true`, sibling
defaults under the same Retailer are atomically unset.
# List all Shipments
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/shipments/get
GET /v1/shipping/shipments
Returns a list of `Shipment` objects.
# Get one Shipment
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/shipments/{id}/get
GET /v1/shipping/shipments/{id}
Returns a single `Shipment` object specified by a shipment `id` path parameter.
# Pack Shipment
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/shipments/{id}/pack/post
POST /v1/shipping/shipments/{id}/pack
This endpoint can be used in multiple modes of operation and in all cases operates on a `Shipment` specified by its `id` path parameter.
The available modes are:
1. Pack and Label: Create packages for a shipment and complete packing (create label if supported) in one step.
2. Pack Only: Create packages for a shipment without completing packing.
3. Complete Packing: Complete the packing of a shipment (creates a label if supported) in the "packing" status which was previously packed with the second mode.
Additionally, many of the parameters are optional, in which case the system will attempt to intelligently determine the best course of action based on the current state of the shipment and its contents. For example, if the Shipment has a Packing Solution and no package details are provided, the system will assume the containers specified by the Packing Solution were used and thus create the packages accordingly.
# Pick Shipment
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/shipments/{id}/pick/post
POST /v1/shipping/shipments/{id}/pick
Completes some or all picks for the `Shipment` specified by its `id` path parameter.
# Process Shipment
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/shipments/{id}/process/post
POST /v1/shipping/shipments/{id}/process
Processes a `Shipment`, specified by its `id` path parameter, in the “new” status so that it is reserved
to specific stock locations and is ready to be picked.
# Get Shipment Reservations
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/shipments/{id}/reservations/get
GET /v1/shipping/shipments/{id}/reservations
Returns the assigned reservations (pick locations) for a shipment in Picking status.
Reservations represent the specific warehouse locations where items should be picked
from to fulfill this shipment. This endpoint is only available for shipments with
status "picking".
# Mark Shipment as Shipped
Source: https://docs.shipstream.io/global-api/endpoint/v1/shipping/shipments/{id}/shipped/post
POST /v1/shipping/shipments/{id}/shipped
Marks a `Shipment` in the "packed" status as shipped, specified by its `id` path parameter.
# List all Merchants
Source: https://docs.shipstream.io/global-api/endpoint/v1/system/merchants/get
GET /v1/system/merchants
Returns a list of `Merchant` objects sorted ascending by `id` unless specified otherwise.
# Healthcheck
Source: https://docs.shipstream.io/global-api/endpoint/v1/system/status/get
GET /v1/system/status
Endpoint that is inexpensive and can be used to determine things like:
- The API is "up" or some other status
- The request has valid authentication or not
- What version of the software is running
- If there are any ongoing notices or issues reported
- The oldest API version supported
- The newest API version supported
# List all User Roles
Source: https://docs.shipstream.io/global-api/endpoint/v1/system/userRoles/{type}/get
GET /v1/system/userRoles/{type}
Returns a list of `UserRole` objects specified by its `type` path parameter.
# Delete User Role
Source: https://docs.shipstream.io/global-api/endpoint/v1/system/userRoles/{type}/{id}/delete
DELETE /v1/system/userRoles/{type}/{id}
Deletes an existing `UserRole` specified by its `type` and `id` path parameters.
# Get one User Role
Source: https://docs.shipstream.io/global-api/endpoint/v1/system/userRoles/{type}/{id}/get
GET /v1/system/userRoles/{type}/{id}
Returns a single `UserRole` object specified by its `type` and `id` path parameters.
# Update one User Role
Source: https://docs.shipstream.io/global-api/endpoint/v1/system/userRoles/{type}/{id}/put
PUT /v1/system/userRoles/{type}/{id}
Update an existing User Role by internal ID.
# List all Users
Source: https://docs.shipstream.io/global-api/endpoint/v1/system/users/{type}/get
GET /v1/system/users/{type}
Returns a list of `User` objects of a specified user `type` path parameter.
# Delete User
Source: https://docs.shipstream.io/global-api/endpoint/v1/system/users/{type}/{id}/delete
DELETE /v1/system/users/{type}/{id}
Deletes an existing `User` specified by its `type` and `id` path parameters.
# Get one User
Source: https://docs.shipstream.io/global-api/endpoint/v1/system/users/{type}/{id}/get
GET /v1/system/users/{type}/{id}
Returns a single `User` object specified by its `type` and `id` path parameters.
# Update one User
Source: https://docs.shipstream.io/global-api/endpoint/v1/system/users/{type}/{id}/put
PUT /v1/system/users/{type}/{id}
Updates an existing `User` specified by its `type` and `id` path parameters and according to the request body.
# Filtering Syntax
Source: https://docs.shipstream.io/global-api/filtering-syntax
When collections can be filtered you may pass one or more `filter` query parameters. The syntax for these filters
is described below.
## Basic Syntax (Equals)
The most basic filter is of the form `key:value` where `key` is the name of the field to filter by and `value`
is a literal string or integer. This basic filter applies the logic "where equals ''".
| Query | Description |
| ------------------------- | ------------------------------------------- |
| `?filter=id:15` | id equals 15 |
| `?filter=status:complete` | status equals 'complete' |
| `?filter=is_active:true` | boolean values `true` and `false` supported |
Multiple filters can be specified in which case they are combined with a logical `AND` operation.
| Query | Description |
| -------------------------------------- | ----------------------------------------- |
| `?filter=id:15&filter=status:complete` | id equals 15 AND status equals 'complete' |
*This basic syntax can be mixed with the advanced syntax described below.*
## Advanced Syntax
The advanced syntax is of the form `key` where `key` is the field name and `` is a valid JSON5 encoded
object or array of objects. These objects can define a broad variety of conditions defined further below.
There is no `:` between the `key` and the ``!
| Query | Description |
| ------------------- | ------------------ |
| `?filter=id{gt:15}` | id greater than 15 |
### AND Logic
Multiple conditions can be applied with `AND` logic for the same key by specifying multiple keys in the same JSON5 object.
| Query | Description |
| ------------------------- | ----------------------------------- |
| `?filter=id{gt:15,lt:50}` | id greater than 15 AND less than 50 |
### OR Logic
Multiple conditions can be applied with `OR` logic for the same key by specifying an array of objects.
| Query | Description |
| ----------------------------- | ---------------------------------- |
| `?filter=id[{lt:15},{gt:50}]` | id less than 15 OR greater than 50 |
### Combined AND and OR logic
Both `AND` and `OR` logic can be used in the same filter.
| Query | Description |
| ------------------------------------------ | ------------------------------------------------------------------ |
| `?filter=weight[{gt:1,lt:50},{null:true}]` | weight is either greater than 1 AND less than 50 OR weight is null |
### Multiple filters with advanced and simple syntax mixed
`?filter=goods_type:NORMAL&filter=name[{start:"Box of"},{end:"CASE"}]&filter=id{gt:15}`
### Conditions
The following keys may be used within the JSON5 object to apply the described conditions.
| key | Condition | Examples | Comment |
| ------- | --------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| eq | Equal to | `{eq:5}`
`{eq:"John Doe"}`
`{eq:true}` | |
| neq | Not equal to | `{neq:5}`
`{neq:"John Doe"}`
`{eq:true}` | |
| gt | Greater than | `{gt:5}` | |
| lt | Less than | `{lt:5}` | |
| gteq | Greater than or equal | `{gteq:5}` | |
| lteq | Less than or equal | `{lteq:5}` | |
| from | From date or date-time | `{from:"2021-11-17"}`
`{from:"2021-11-17T14:32:44Z"}` | Specifying a date for a date-time value will be equivalent to "greater than or equal to YYYY-MM-DDT00:00:00Z" (inclusive) |
| to | To date or date-time | `{to:"2021-11-17"}`
`{to:"2021-11-17T14:32:44Z"}` | Specifying a date for a date-time value will be equivalent to "less than or equal to YYYY-MM-DDT23:59:59Z" (inclusive) |
| start | Starts with | `{start:"John"}` | Prefix match (like `John*`) |
| end | Ends with | `{end:"Doe"}` | Suffix match (like `*Doe`) |
| contain | Contains anywhere | `{contain:"Baker"}` | Anywhere match (like `*Baker*`) |
| regex | Matches regular expression | `{regex:"^A.+Z$"}` | See [MySQL Regular Expression Syntax](https://dev.mysql.com/doc/refman/8.0/en/regexp.html#regexp-syntax) |
| iregex | Matches regular expression (case insensitive) | `{regex:"^A.+Z$"}` | See [MySQL Regular Expression Syntax](https://dev.mysql.com/doc/refman/8.0/en/regexp.html#regexp-syntax) |
| in | Equals a value in the set | `{in:[1,2,3,4]}`
`{in:["canceled","processing"]}` | |
| nin | Not equal to any value in the set | `{nin:[1,2,3,4]}`
`{nin:["canceled","processing"]}` | |
| null | Value is or is not NULL | `{null:true}`
`{null:false}` | |
| empty | Value is or is not NULL or equal to an empty string | `{empty:true}`
`{empty:false}` | `true` is equivalent to `{eq:""},{null:true}` and `false` is equivalent to `{neq:"",null:false}` |
String values must be `"double-quoted"` or `'single-quoted'`.
# Editing Handling Class Conditions
Source: https://docs.shipstream.io/global-api/handling-class-conditions
Build and save Handling Class conditions using the Global API metadata catalogue.
Handling Classes classify Products asynchronously and can refer to Product Profiles. A list or
detail response returns the compact class summary by default. Load the condition definition only
when a user opens the editor.
## Load a Handling Class for editing
Request the canonical condition tree and its readable expression explicitly. The two nested
field parameters resolve the direct Warehouse and Product Profile references without loading
their own relationships:
```http Request theme={null}
GET /api/global/v1/inventory/handling-classes/18?fields=conditions,conditions_readable&fields:warehouses=name&fields:referenced_product_profiles=name
```
```json Response theme={null}
{
"resource": {
"type": "HandlingClass",
"id": 18,
"name": "Heavy Oversized",
"code": "heavy_oversized",
"sort_order": 30,
"warehouses": [
{ "type": "Warehouse", "id": 1 },
{ "type": "Warehouse", "id": 2 }
],
"conditions": {
"or": [
{
"and": [
{
">=": [
{ "var": "weight" },
{ "value": 70, "unit": "lb", "base_value": 70 }
]
},
{
"contains_any": [
{ "var": "product_profiles" },
[31]
]
}
]
}
]
},
"referenced_product_profiles": [
{ "type": "ProductProfile", "id": 31 }
],
"conditions_readable": "((present(weight) && weight >= 70.0) && (present(product_profiles) && (31 in product_profiles)))",
"matched_count": 127,
"classification": {
"status": "up_to_date",
"indexed_at": "2026-08-04T10:05:00Z"
},
"created_at": "2026-07-18T11:20:00Z",
"updated_at": "2026-08-04T10:05:00Z"
},
"included": {
"Warehouse": [
{ "type": "Warehouse", "id": 1, "name": "Los Angeles Fulfillment Center" },
{ "type": "Warehouse", "id": 2, "name": "Dallas Fulfillment Center" }
],
"ProductProfile": [
{ "type": "ProductProfile", "id": 31, "name": "Oversized Furniture" }
]
},
"meta": {
"processing_time": 0.0092
}
}
```
`type` and `id` are always present in an included resource, so request only the additional fields
the control displays. For a grid that needs only Handling Class data, omit both nested field
parameters; the compact references remain available and ShipStream does not load the related
Warehouse or Product Profile records. List responses bulk-load each requested related type once
for the page rather than once per Handling Class.
## Build the editor from metadata
Call [List Handling Class condition fields](/global-api/endpoint/v1/inventory/handling-classes/condition-fields/get)
when the editor loads. The response describes the shared Product fields and the additional
`product_profiles` selector. Product Profile options are a finite ID-to-name map; save their numeric
IDs in `product_profiles` condition values.
Fields such as SKU and Product name advertise a `value_source` instead of embedding every Product.
After the operator types at least two characters, call the advertised endpoint with a bounded limit:
```http Request theme={null}
GET /api/global/v1/inventory/product-condition-values?field=sku&q=FURN-&limit=50
```
```json Response theme={null}
{
"options": [
{
"value": "FURN-CHAIR-OAK",
"label": "FURN-CHAIR-OAK — Oak Dining Chair"
},
{
"value": "FURN-TABLE-6FT",
"label": "FURN-TABLE-6FT — Six Foot Dining Table"
}
],
"meta": {
"processing_time": 0.0067
}
}
```
The lookup returns simple Products only and at most 50 options. Do not preload the full Product
catalogue. If another selector needs Product data, request the Product endpoint with a bounded
`limit` and only the fields the control displays; see [Selecting Fields](/global-api/selecting-fields).
## Save and poll classification
Send the edited condition tree to the Handling Class update endpoint. Omitted fields remain
unchanged.
```http Request theme={null}
PUT /api/global/v1/inventory/handling-classes/18
Content-Type: application/json
{
"conditions": {
"or": [
{
"and": [
{
">=": [
{ "var": "weight" },
{ "value": 80, "unit": "lb" }
]
},
{
"contains_any": [
{ "var": "product_profiles" },
[31]
]
}
]
}
]
}
}
```
The update returns `200` with no response body. Poll the Handling Class until
`classification.status` becomes `up_to_date`. While work is pending, the status may be `queued` or
`processing`; a failed classification reports `failed`.
Condition values store Product Profile IDs. The `referenced_product_profiles` response field
exposes the same dependencies as `{ "type": "ProductProfile", "id": ... }` references. Add
`fields:referenced_product_profiles=name` when the editor needs their labels; the matching
shallow objects are returned in `included.ProductProfile`.
# Introduction
Source: https://docs.shipstream.io/global-api/introduction
Welcome to the reference documentation for the ShipStream WMS Global API.
The "Global" API is meant for organization-level access to all of your ShipStream data, typically focused on operational needs. For access which is
limited to the data belonging to a *single* merchant, such as is common for shopping cart integrations, please use the [Merchant API](/merchant-api/introduction) instead.
#### Danger, Will Robinson!
Do not provide Global API access tokens to your merchants, as it will allow them to access data from all of your other merchants!
# Getting Started
Please familiarize yourself with the common features of the API to maximize the value of its capabilities. These
features are designed to allow you to gain easy access to the data you need as efficiently as possible. The advanced
field selection, filtering and sorting features provide a high degree of flexibility while being easy to consume.
The ShipStream WMS Global API is a RESTful API that allows you to interact with your ShipStream data programmatically. It supports standard HTTP methods such as `GET`, `POST`, `PUT`, and `DELETE`. We currently do not provide official SDKs, but you can use any HTTP client to interact with the API. Additionally, the API adheres to the [OpenAPI 3.0.4 specification](https://spec.openapis.org/oas/v3.0.4.html), allowing you to generate client libraries in just about any common programming language and use a large number of [Open API tools](https://openapi.tools/).
See [Find Your URL](/home/find-your-url) for information on finding the correct URL to use for your ShipStream instance.
## Reference Files
As the OpenAPI specs are very detailed and there are many endpoints, we have split the OpenAPI spec into several files to make them easier to consume and navigate. There are also different versions of the OpenAPI spec available, depending on your needs.
The files are available at the following urls:
* Release (recommended): `https://openapi.shipstream.io/global/release-{version}/{reference}`
* Latest (always the latest release): `https://openapi.shipstream.io/global/latest/{reference}`
* Nightly (latest development version): `https://openapi.shipstream.io/global/nightly/{reference}`
Where `{version}` is the release version with hyphens (e.g. `2025-5`), and `{reference}` is one of the following:
* `combined.json`: The complete OpenAPI specification for the Global API, combining all of the below references into one.
* `system.json`: Provides information on system operations, including system status, users, and merchants.
* `inventory.json`: Contains endpoints related to inventory management, such as products, locations, and stock levels.
* `receiving.json`: Covers endpoints for managing receiving operations (ASNs and RMAs).
* `shipping.json`: Covers endpoints for shipping operations (orders and shipments).
Example: [https://openapi.shipstream.io/global/latest/combined.json](https://openapi.shipstream.io/global/latest/combined.json)
# Paging Parameters
Source: https://docs.shipstream.io/global-api/paging-parameters
The total result set for a query may exceed the maximum number of items allowed in a single response. This limit is
typically 100 items by default but can be increased to up to 1000 items in most cases by providing a value for the
`limit` query parameter.
If the number of items matching the query (see [filtering syntax](/global-api/filtering-syntax)) is greater than the
`limit`, the response object's `has_more` property will have the value `true` and the `next` property will be a string
which is the API URI providing the next "page" of items for the same query. These properties can be used to easily and
efficiently traverse the full result set one page at a time without missing items or traversing the same item twice as
can happen when using offsets due to race conditions.
The following pseudo-code example demonstrates how you can traverse a full result set one page at a time using
`has_more` and `next` properties of the response:
```js theme={null}
let uri = '/api/global/v1/inventory/products?limit=1000&filter=is_active{eq:true}'
do {
let result = fetch(uri)
doSomething(result.collection)
uri = result.next
} while (result.has_more)
```
## Previous Page
Similarly to `next`, a `previous` property is included in the response when the result has a previous page. This can be
used to traverse backwards in a result set. When traversing backwards (which uses `cursor_end`) the `has_more` property
in the response will be false when there are no more pages in the "previous" direction.
## Metadata
The query parameters `cursor_start` and `cursor_end` are used to implement the basic paging mechanism, but these
parameters are specified automatically in the URI which is returned in the `next` and `previous` properties
respectively and so do **not** need to be provided manually. However, the appropriate values of these fields for the
next and previous pages of results are also returned in the response's `meta` object with the properties `cursor_start`
and `cursor_end` respectively. These can be used in case you prefer or need to construct the URIs for paging on your own.
### Count
If the query includes `count=1` then the `meta` object will also include a total count which can be useful for predicting
the total number of pages in a query result. The count is not included by default since in some edge cases it can have
an impact on performance and is many times not required by the implementation.
## Example
First page:
```http Request theme={null}
GET /api/global/v1/inventory/products?count=1&limit=10
```
```json Response theme={null}
{
"collection": [
{...},
{...},
{...},
{...},
{...},
{...},
{...},
{...},
{...},
{...}
],
"has_more": true,
"next": "/api/global/v1/inventory/products?count=1&cursor_start=11",
"previous": null,
"meta": {
"processing_time": 0.2312367235115
"cursor_start": 11,
"cursor_end": null,
"count": 15
}
}
```
Second page:
```http Request theme={null}
GET /api/global/v1/inventory/products?count=1&limit=10&cursor_start=11
```
```json Response theme={null}
{
"collection": [
{...},
{...},
{...},
{...},
{...}
],
"has_more": false,
"next": null,
"previous": "/api/global/v1/inventory/products?count=1&cursor_end=11",
"meta": {
"processing_time": 0.2312367235115
"cursor_start": null,
"cursor_end": 11,
"count": 15
}
}
```
#### Sorting
See [sorting syntax](/global-api/sorting-syntax) for more info on sorting the result set.
# Editing Product Profile Conditions
Source: https://docs.shipstream.io/global-api/product-profile-conditions
Build and save Product Profile conditions using the Global API metadata catalogue.
Product Profiles classify Products asynchronously. A list or detail response returns the compact
Profile summary by default. Load the condition definition only when a user opens the editor.
## Load a Profile for editing
Request the canonical condition tree and its readable expression explicitly:
```http Request theme={null}
GET /api/global/v1/inventory/product-profiles/26?fields=conditions,conditions_readable
```
```json Response theme={null}
{
"resource": {
"type": "ProductProfile",
"id": 26,
"name": "Lightweight Parcel",
"code": "lightweight_parcel",
"conditions": {
"or": [
{
"and": [
{
"<=": [
{ "var": "weight" },
{ "value": 15, "unit": "lb", "base_value": 15 }
]
},
{
"==": [
{ "var": "status" },
1
]
}
]
}
]
},
"conditions_readable": "((present(weight) && weight <= 15.0) && (present(status) && status == 1))",
"matched_count": 482,
"classification": {
"status": "up_to_date",
"indexed_at": "2026-08-04T09:15:00Z"
},
"created_at": "2026-07-14T09:12:05Z",
"updated_at": "2026-08-04T09:15:00Z"
},
"included": {},
"meta": {
"processing_time": 0.0081
}
}
```
## Build the editor from metadata
Call [List Product Profile condition fields](/global-api/endpoint/v1/inventory/product-profiles/condition-fields/get)
when the editor loads. The response describes each field's label, type, allowed operators, value
conversion, finite options, and measurement units. It also provides the CEL help URL for advanced
expressions.
Fields such as SKU and Product name advertise a `value_source` instead of embedding every Product.
After the operator types at least two characters, call the advertised endpoint with a bounded limit:
```http Request theme={null}
GET /api/global/v1/inventory/product-condition-values?field=sku&q=KIT-&limit=50
```
```json Response theme={null}
{
"options": [
{
"value": "KIT-BLK-L",
"label": "KIT-BLK-L — Black Fulfillment Kit, Large"
},
{
"value": "KIT-BLK-M",
"label": "KIT-BLK-M — Black Fulfillment Kit, Medium"
}
],
"meta": {
"processing_time": 0.0064
}
}
```
The lookup returns simple Products only and at most 50 options. Do not preload the full Product
catalogue. When another selector needs Product data, use the Product endpoint's compact default
projection, add only optional fields that the selector displays, and use a bounded `limit`; see
[Selecting Fields](/global-api/selecting-fields).
## Save and poll classification
Send the edited condition tree to the Profile update endpoint. Omitted fields remain unchanged.
```http Request theme={null}
PUT /api/global/v1/inventory/product-profiles/26
Content-Type: application/json
{
"conditions": {
"or": [
{
"and": [
{
"<=": [
{ "var": "weight" },
{ "value": 20, "unit": "lb" }
]
},
{
"==": [
{ "var": "status" },
1
]
}
]
}
]
}
}
```
The update returns `200` with no response body. Poll the Profile until
`classification.status` becomes `up_to_date`. While work is pending, the status may be `queued` or
`processing`; a failed classification reports `failed`.
References in condition metadata use their stable field values. Elsewhere in the Global API,
related resources use `{ "type": "...", "id": ... }` references. Match both `type` and `id`
when resolving those references from `included`.
# Response Codes and Errors
Source: https://docs.shipstream.io/global-api/response-codes-errors
A `4xx` HTTP response code should be returned for all application level errors and the response should always contain a
JSON-encoded body.
If any non `2xx` HTTP response code is returned then the request will have been fully rolled back and should have no impact on any data.
```json title="JSON Schema" theme={null}
{
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The type of error.",
"enum": ["application"]
},
"message": {
"type": "string",
"description": "An error message."
},
"details": {
"type": "array",
"description": "May provide more specific error details if available.",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "The JSON path or other identifier for the key or parameter which is related to the error. "
},
"message": {
"type": "string",
"description": "A descriptive error message relating specifically to the `key` given."
}
},
"required": ["key","message"]
}
}
},
"required": ["type","message"]
}
}
},
"required": ["errors"]
}
```
# HTTP Response Codes
The different types of errors which may occur in the application (excluding any network or routing errors)
typically belong to one of the following HTTP response codes:
* [400 Bad Request](#400-bad-request)
* [401 Unauthorized](#401-unauthorized)
* [404 Not Found](#404-not-found)
* [405 Not Allowed](#405-not-allowed)
* [409 Conflict](#409-conflict)
* [412 Not Supported](#412-not-supported)
* [422 Unprocessable](#422-unprocessable)
* [500 Internal Error](#500-internal-error)
* [503 Service Unavailable](#503-service-unavailable)
* [Other 5xx Errors](#other-5xx-errors)
Examples for each of these response codes are provided below.
## 400 Bad Request
The server cannot or will not process the request due to something that is perceived to be a client error.
### Request Not Valid
```json Response Example theme={null}
{
"errors": [
{
"type": "parameters",
"message": "The supplied parameters are invalid.",
"details": [
{
"key": "sort",
"message": "Only two sort orders are allowed."
}
]
}
]
}
```
### Parse Error
The server was not able to parse the request body or the decoded request body was not the proper data type.
```json Response Example theme={null}
{
"errors": [
{
"type": "parser",
"message": "There was an error parsing the request.",
"details": [
{
"key": "json",
"message": "Syntax error."
}
]
}
]
}
```
### OpenAPI Validation
Before the server begins to process the request it will validate the full request against the OpenAPI spec.
Specifically, the parts of the request which are validated are:
* Headers
* Cookies
* Body
* Query
* Path
* Security Scheme
Any failure in validation against the OpenAPI spec will result in an `openapi` type error with the `details`
describing which step failed validation in the `key` and a `message` describing the failure.
```json Response Example theme={null}
{
"errors": [
{
"type": "openapi",
"message": "Request message failed OpenAPI spec validation.",
"details": [
{
"key": "invalid_query_args",
"message": "Parameter 'sort' has invalid value"
}
]
}
]
}
```
## 401 Unauthorized
The request requires user authentication. If the request lacks valid credentials, the server will respond with a "401 Unauthorized" error.
```json Response Example theme={null}
{
"errors": [
{
"type": "unauthorized",
"message": "Invalid Global API Access Token: Token is expired.",
"details": [
{
"key": "",
"message": "The request requires valid user authentication."
}
]
}
]
}
```
## 404 Not Found
The server can not find the requested resource. In the context of this API, this will mean that the endpoint is valid but the resource itself does not exist or a resource that was referenced in the request does not exist.
```json Response Example theme={null}
{
"errors": [
{
"type": "not_found",
"message": "The server could not find the requested resource."
}
]
}
```
## 405 Not Allowed
The request method is known by the server but is not supported by the target resource.
```json Response Example theme={null}
{
"errors": [
{
"type": "not_allowed",
"message": "The target resource does not support the requested method."
}
]
}
```
## 409 Conflict
Errors that do not fit one of the other response types may use this response code.
```json Response Example theme={null}
{
"errors": [
{
"type": "generic",
"message": "Unknown error"
}
]
}
```
## 412 Not Supported
The request is known by the server but a required feature may be disabled or it is not supported by the
requested API version.
```json Response Example theme={null}
{
"errors": [
{
"type": "not_supported",
"message": "The requested resource is not supported in the API version specified. Please update to the latest version."
}
]
}
```
## 422 Unprocessable
The request encountered an anticipated error during processing.
```json Response Example theme={null}
{
"errors": [
{
"type": "unable_to_process",
"message": "There was an error processing the request.",
"details": [
{
"key": "validation",
"message": "A user with the same user name or email already exists."
}
]
}
]
}
```
Additional errors encountered may be given the type "application" and will typically include a more detailed
`message` but not a `details` array.
```json Response Example theme={null}
{
"errors": [
{
"type": "application",
"message": "Shipment cannot be deleted in its current status: Packing"
}
]
}
```
## 500 Internal Error
An unexpected/internal error is an indication that something went wrong, possibly indicating a bug or a
temporary service interruption. Although these errors should be exceedingly rare, you should anticipate that
they may occur as these errors will likely not be returned in a JSON-encoded format.
## 503 Service Unavailable
The server is not ready to handle the request. Common causes are a server that is down for maintenance or that is overloaded.
## Other 5xx errors
Any other `5xx` range errors are likely due to a network or routing issue and should be temporary and will likely not have a predictable response format.
# Selecting Fields
Source: https://docs.shipstream.io/global-api/selecting-fields
The ShipStream Global API adheres to REST API principles, but provides advanced features for selecting which
fields to return in the response, similar in a way to GraphQL APIs.
## Optional Fields
To provide the fastest possible response times while not limiting the scope of the API,
some endpoints do not return all documented fields unless they are requested using an additional
query parameter called `fields` or one prefixed with `fields:`. These "optional" fields are
denoted in the field descriptions in the API reference with the text `Optional Field`.
**Example requesting optional fields `qty_locked` and `is_pickable`:**
```http Request theme={null}
GET /api/global/v1/inventory/locations?fields=qty_locked,is_pickable
```
To request that *all* optional fields be returned, a shortcut keyword `all` may be used. However, it
is recommended to request only the fields you need, to reduce processing time and conserve bandwidth.
**Example requesting all location fields (including all optional fields):**
```http Request theme={null}
GET /api/global/v1/inventory/locations?fields=all
```
The `fields` parameter adds optional fields to the resource's normal root fields. It does not remove
the normal fields. Parameters prefixed with `fields:` select fields for referenced resources in
`included`; they do not change the root resource.
For grids and selectors, keep the compact default projection, add only optional fields displayed by
the client, and use a bounded `limit`. For example, a Product selector that needs only the default
identity fields does not need a `fields` parameter:
```http Request theme={null}
GET /api/global/v1/inventory/products/simple?limit=50
```
Note that when a property which references another model is added using `fields`, either
explicitly or implied with `all`, only the "reference" to that object (an object with `type`
and `id`) is added to the response. However, the referenced objects including all or some of their
properties can also be added to the response to avoid additional round-trips to fetch them.
Please read the "Including Referenced Objects" section below for more info.
The `all` keyword will not automatically include all fields of referenced objects as well. I.e. its behavior
is not recursive.
## Including Referenced Objects
For your convenience, and to potentially save a large number of round-trips, you can have the API return
object data for objects that are referenced by `type` and `id` in the same response. This object data
for additionally included objects is added to the `included` property of the response by requesting one
or more fields of the referenced objects. The `included` property is an object of lists with a key for each
included object `type` which contains a list of included objects of that type.
The corresponding query parameter for including referenced objects will be the path of the reference to the
object from the top-level object as if it was included inline and prefixed with `fields:`.
**Example requesting a collection of locations as well as the `sku` and `name` of every location's `product`:**
```http Request theme={null}
GET /api/global/v1/inventory/locations?fields:product=sku,name
```
The response in this example would look like this:
```json Response theme={null}
{
"collection": [
{
"type": "Location",
"id": 442,
"...": "...",
"product": {
"type": "Product",
"id": 33
}
}
],
"included": {
"Product": [
{
"type": "Product",
"id": 33,
"sku": "ABC",
"name": "ABC Widget"
}
]
}
}
```
If the same object is referenced multiple times by different fields or items, it will still only be included once
so no data is duplicated.
### Basic and Optional Fields
For your convenience, since some fields are fairly ubiquitous, you may use the `basic` keyword
as a value of the parameter to imply that all non-optional fields shall be returned.
**Example requesting all basic (non-optional) fields of the referenced `Product` object:**
```http Request theme={null}
GET /api/global/v1/inventory/locations?fields:product=basic
```
As with the top-level objects, referenced objects may also contain fields denoted as `Optional Field`
in the descriptions and these will not be returned when requesting `basic`, but may be listed
individually or implied using `all` to return all basic *and* optional fields.
**Example requesting a mix of basic and optional fields of the referenced `Product` object:**
```http Request theme={null}
GET /api/global/v1/inventory/locations?fields:product=basic,weight,dimensions
```
**Example requesting all fields of the referenced `Product` object:**
```http Request theme={null}
GET /api/global/v1/inventory/locations?fields:product=all
```
### Deeply-Referenced Fields
The `all` keyword only implies that the *first* level of fields shall be returned and deeply-referenced fields are
not implied but **can** be included in many cases as well. For example, since a `Location` references a `Product` using
a property called `product` and the `Product` references a `Merchant` using a property called `merchant`, you can
request that the `Merchant` data be included in the response using `fields:product.merchant`.
**Example requesting all top-level fields as well as all fields of a referenced object and a deeply-referenced object:**
```http Request theme={null}
GET /api/global/v1/inventory/locations?fields=all&fields:product=all&fields:product.merchant=all
```
You will need to de-reference the field data client-side by searching the `included` object for the matching
`type` and then searching the list of objects for the matching `id`.
For example, the response for the above query may have this shape (irrelevant fields replaced with "..." for simplicity):
```json Response theme={null}
{
"collection": [
{
"type": "Location",
"id": 442,
"...": "...",
"product": {
"type": "Product",
"id": 33
}
},
{
"type": "Location",
"id": 444,
"...": "...",
"product": {
"type": "Product",
"id": 33
}
}
],
"included": {
"Product": [
{
"type": "Product",
"id": 33,
"...": "...",
"merchant": {
"type": "Merchant",
"id": 2
}
}
],
"Merchant": [
{
"type": "Merchant",
"id": 2,
"name": "ACME, Inc.",
"code": "acme",
"...": "..."
}
]
}
}
```
# Sorting Syntax
Source: https://docs.shipstream.io/global-api/sorting-syntax
When querying collections, the default sort order will typically be by `id` in descending order. However, you can choose
a different sort order by specifying the `sort` query parameter with one of the field names listed in the endpoint
description. You may specify a secondary sort order by specifying the `sort` value as a comma-separated list of the
field names to use for sorting.
Field names prefixed with `-` will be sorted in **descending** order by the given field, otherwise the result will be
sorted in **ascending** order by the given field.
**Example:**
To sort first by `priority` in descending order and then by `name` in ascending order:
```http Request Query theme={null}
?sort=-priority,name
```
The paging cursor parameters (`cursor_start` and `cursor_end`) are designed to provide consistent results and response
times and so they only support sorting by either `id` (ascending) or `-id` (descending).
```http Request Query theme={null}
?sort=id&cursor_start=38712
```
#### Paging
See [paging parameters](/global-api/paging-parameters) for more information on paging large result sets.
# Versions
Source: https://docs.shipstream.io/global-api/versions
We strive to make maintaining an API integration with ShipStream as easy as possible while not limiting our ability to
make improvements. There are two "versions" in the Global API: the "major" version number is indicated in the url
(such as `/api/global/v1/...` for version 1) and the "minor" version is specified by the client in either a header
or query parameter.
**Example**
```http Request theme={null}
GET /api/global/v1/orders
Host: example.shipstream.app
Authorization: Bearer ...
X-ShipStream-API-Version: 2024-10
```
```bash cURL theme={null}
curl --header "Authorization: Bearer ..." \
--header "X-ShipStream-API-Version: 2024-10" \
--url https://example.shipstream.app/api/global/v1/orders
```
In this example the major version is `v1` and the minor version is `2024-10`.
# Major Version
The endpoints of a major version indicated in the url path (e.g. `v1`) will always remain backward-compatible, if
possible, and breaking changes should only be introduced by adding a new version so that the old version is left unchanged.
New endpoints will often be added to the **current** version **without** incrementing the version number, so new major versions should
be infrequent. Each version is like a namespace and multiple versions may be available in which case you should always
use the newest that provides the functionality you need.
## Beta Version
The `/api/global/beta` namespace may used to provide new functionality that is still simmering, with the expectation that it
will be added to the latest version in the future. This will hopefully require you to just change `beta` to `v1`, for example, when the
functionality is declared to be finalized.
# Minor Version
The minor version should be specified in every request with a `X-ShipStream-API-Version` header or a `version=` query parameter.
This should be chosen as the year and month of the latest version at the time the integration is developed.
If a version header or query parameter is not provided, the latest version will be assumed! To ensure the best stability,
you should **always** specify a minor version.
The latest recognized version will only be updated whenever a breaking change is made, such as if a field's type must
be modified or a field was renamed or removed. This version number will be used to maintain backwards compatibility for
a limited time so that minor changes can be introduced without duplicating the API with a new major version each time, or
otherwise hampering the ability to make changes.
**For example**, if the field `foo` needs to be changed from an integer to a string, the API docs will be updated to reflect
that a string is returned, and the latest recognized version will be updated to the current year and month. Any API
requests for an older version will return the integer, and any API requests for a newer version will return a string.
The API response will include a header named `X-ShipStream-API-Version` which contains the effective version for the given request.
## Validation
If an invalid version number is specified in the request, a `400` error will be thrown and the error message will indicate
the latest tagged version. Specifying a future date is not allowed, since you can't predict what changes will potentially
be made in the future.
## Deprecation
If the requested version is deprecated or no longer supported, a `X-ShipStream-API-Version-Error` header will be added to the response.
We strongly recommend that your integrations check for this error header and log an internal error so that you are notified automatically
if your API is running a deprecated or unsupported version.
# Find Your URL
Source: https://docs.shipstream.io/home/find-your-url
Your ShipStream WMS instance base URL is always the website that you log into, but without a path.
For example, if you log in at `https://your-company.shipstream.app/admin/login`, then your base URL would
be `https://your-company.shipstream.app`.
Examples:
* `https://your-company.shipstream.app` for ShipStream subdomains
* `https://your.custom-domain.com` for whitelabeled 3PLs
Therefore, the **full** url for your APIs would be:
* **Merchant API**: `https://your-company.shipstream.app/api/jsonrpc`
* **Global API**: `https://your-company.shipstream.app/api/global/...` where `...` is the path the the specific endpoint such as `v1/system/status`
```http Full Global API example theme={null}
https://your-company.shipstream.app/api/global/v1/system/status
```
The Global API OpenAPI spec is written such that the `servers.url` should already include `/api/global` and the endpoint paths then begin with `/v1/...`.
# Get Started
Source: https://docs.shipstream.io/home/index
Welcome to the **ShipStream Developer Center**!
This site is primarily for developers looking to integrate with the ShipStream WMS APIs. If you are looking for user documentation, please visit our [Knowledge Base](https://help.shipstream.io).
ShipStream offers two main APIs: the **[Global API](/global-api/introduction)** and the **[Merchant API](/merchant-api/introduction)**. Understanding their differences is crucial for choosing the right integration path.
## Global API vs. Merchant API
### Global API
The Global API is designed for 3PLs (Third-Party Logistics providers) or for managing warehouse operations. It provides comprehensive access to operational data and allows for broad management across multiple merchants.
**Use Cases for Global API:**
* Syncing data for all merchants into an external centralized sytstem.
* Obtaining operational data for reporting across all merchants.
* Performing daily operations outside of the Admin UI or Scanner UI.
* Integrating with ERPs (Enterprise Resource Planning) and WESs (Warehouse Execution Systems).
### Merchant API
The Merchant API is tailored for individual merchants to synchronize their e-commerce platforms, shopping carts, and other systems with their ShipStream WMS (Warehouse Management System) instance. This is ideal for merchants who work with a 3PL using ShipStream or those who self-fulfill.
**Use Cases for Merchant API:**
* Syncing shopping cart data (orders, tracking, inventory) for a single merchant.
* Creating ASNs (Advance Shipment Notifications) when resupply purchase orders are en-route.
* Integrating with e-commerce platforms and marketplaces.
* Custom workflows to modify order data or respond to shipment or tracking events.
## Obtaining API Credentials
To access either API, you will need to obtain API credentials. Please refer to the following documentation pages for detailed instructions:
* [Global API Access Tokens](https://help.shipstream.io/article/15i0ut0c8e-global-integrations#creating_a_global_api_access_token)
* [Merchant API Users and Roles](https://help.shipstream.io/article/7alo6rt6gn-api-system)
# Authentication
Source: https://docs.shipstream.io/merchant-api/authentication
Learn about the authentication methods for the Merchant API.
The preferred authentication method is to use HTTP Basic Auth with the API key username and password when making calls to the `call` method.
See [Find Your URL](/home/find-your-url) for information on finding the correct URL to use for your ShipStream instance.
# HTTP Basic Auth
```bash title="HTTP Basic Auth Example" theme={null}
curl -X POST https://apiuser:password@example.shipstream.app/api/jsonrpc \
-d '{"jsonrpc":2.0,"id":1234,"method":"call","params":[null,"warehouse.list",[]]}'
```
In this case, the `session_id` parameter to the `call` method (the first element of the `params` array) should be `null`.
# Session Login
`login(username, api_key)`
Another method is to use the `login` JSON-RPC method to obtain a session ID and use this session ID for subsequent requests to the `call` method.
The session ID can then be used as the first array element of the `params` parameter for subsequent requests to `call`.
The session ID will expire after 24 hours at which time you will need to use `login` again. Do not call `login` before each request, instead consider
using the HTTP Basic Auth method described above.
## `login()` Parameters
The API user's username.
The API user's API key (password).
## Return Value
Upon a successful login, the result will be a session ID which is a 32-character hexadecimal string.
## Login Example
```json Request theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "login",
"params" : [
"username",
"password"
]
}
```
```json Response theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"result" : "be1c13ed4e03f0ed7f1e4053dfff9658"
}
```
An example response for if the session is expired:
```json Session Expired theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : {
"code" : -32005,
"message" : "Session expired. Try to relogin."
}
}
```
## Error Codes
| code | message |
| ---- | ------------------------------ |
| 2 | Access denied. |
| 6 | Required parameter is missing. |
# Bill of Materials
Source: https://docs.shipstream.io/merchant-api/bom
A Bill of Materials (BOM) defines a relationship between one SKU and a set of component SKUs. For instance, a SKU "Widget-A" could be made up of of three components "Component-A", "Component-B", "Component-C". Placing an order for SKU "Widget-A" would result in "Component-A", "Component-B", "Component-C" automatically being fulfilled in it's place.
BOMs can also define relationships between similar products in different pack/case sizes. For example if "ProductA-12" is a case of 12 single products, and "ProductA-1" is 1 single product from a case of "ProductA-12", then a BOM relationship could be created to allow orders for "ProductA-1" to be fulfilled by splitting a case of "ProductA-12", which would avoid having dedicated inventory for "ProductA-1".
## Methods
* [bom.search](#bom-search)
* [bom.create](#bom-create)
* [bom.update](#bom-update)
* [bom.delete](#bom-delete)
***
## Entity Properties
* [BOM](#bom-properties)
* [BOM Component](#bom-component-properties)
***
## `bom.search`
`bom.search(null|object $filters = null, null|array $options = null)`
Retrieve list of BOMs.
### Parameters
* `null` - Retrieve list of all BOMs.
* `object` - Retrieve list of BOMs using specified [Search Filters](/merchant-api/search-filters).
Allowed properties for filtering: "product\_bom\_id", "sku", "name", "yield\_qty", "is\_kit\_on\_demand", "is\_kit\_to\_stock", "assembly\_instructions", "priority".
* `null` - No options will be applied.
* `object` - Apply specified [Search Options](/merchant-api/search-options).
### Return Value
An array of objects. Each object will contain [Bom Properties](#bom-properties).
### Example Request
Get list of BOMs for one product SKU:
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"bom.search",
[
{
"sku" : { "eq" : "product2" }
}
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : [
{
"product_bom_id" : 73,
"name" : "Build Product2",
"sku" : "product2",
"yield_qty" : 1,
"is_kit_on_demand" : 1,
"is_kit_to_stock" : 0,
"assembly_instructions" : "",
"priority" : 0,
"components" : [
{
"bom_child_id" : 211,
"product_bom_id" : 73,
"sku" : "product2_PartA",
"qty" : 1
},
{
"bom_child_id" : 212,
"product_bom_id" : 73,
"sku" : "product2_PartB",
"qty" : 1
}
]
}
]
}
```
### Error Codes
| code | message |
| ---- | ------------------------------------------------ |
| 104 | Invalid filters given. Details in error message. |
***
## `bom.create`
`bom.create (object $bomData)`
Create new BOM.
### Parameters
BOM data.
### Return Value
BOM object if successful.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"bom.create",
[
{
"name" : "Build Product2",
"sku" : "product2",
"yield_qty" : 1,
"is_kit_on_demand" : 1,
"assembly_instructions" : "",
"priority" : 0,
"components" : [
{
"sku" : "product2_PartA",
"qty" : 1
},
{
"sku" : "product2_PartB",
"qty" : 1
}
]
}
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : {
"product_bom_id" : 73,
"name" : "Build Product2",
"sku" : "product2",
"yield_qty" : 1,
"is_kit_on_demand" : 1,
"is_kit_to_stock" : 0,
"assembly_instructions" : "",
"priority" : 0,
"components" : [
{
"bom_child_id" : 211,
"product_bom_id" : 73,
"sku" : "product2_PartA",
"qty" : 1
},
{
"bom_child_id" : 212,
"product_bom_id" : 73,
"sku" : "product2_PartB",
"qty" : 1
}
]
}
}
```
### Error Codes
| code | message |
| ---- | --------------------------------------------- |
| 102 | Invalid data given. Details in error message. |
| 105 | Product does not exist. |
***
## `bom.update`
`bom.update (int $bomId, object $bomData)`
Update BOM data.
### Parameters
BOM ID.
BOM data.
Allowed properties for update are the same as the create method.
### Return Value
`true` if BOM was successfully updated.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"bom.update",
[
"73",
{
"is_kit_on_demand" : 0
}
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : true
}
```
***
## `bom.delete`
`bom.delete (int $bomId)`
Delete a BOM. A BOM can only be deleted if it is not currently in use by any sales orders or deliveries.
### Parameters
BOM ID.
### Return Value
`true` if BOM was successfully deleted.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"bom.delete",
[
"73"
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : true
}
```
### Error Codes
| code | message |
| ---- | ------------------- |
| 101 | BOM does not exist. |
## Entity Properties
### BOM Properties
An automatically generated unique identifier for a BOM.
A descriptive name to indicate what action a BOM will take.
The product SKU that will be substituted by the BOM components.
The number of product units produced by the BOM. A positive integer.
If this option is true, order items will automatically be substituted by the BOM during warehouse allocation. Allowed: "1" - TRUE, "0" - FALSE
If this option is true, the BOM will be available for use with a Work Order. Allowed: "1" - TRUE, "0" - FALSE
Instructions for assembling the BOM.
If multiple BOMs are defined for a SKU, then they will be processed in ascending order of this field. An integer.
A list of [BOM component objects](#bom-component-properties).
### BOM Component Properties
An automatically generated unique identifier for a BOM component.
The unique identifier of the parent BOM of the component item.
The product SKU of the component.
The quantity of the component item consumed by the BOM. A positive integer.
# Brand
Source: https://docs.shipstream.io/merchant-api/brand
ShipStream has full support for having multiple brands under one merchant account. Use this API endpoint to retrieve your list of Brands and their corresponding codes which are required for submitting orders to a specific brand.
For legacy purposes the "brands" are sometimes referred to as "stores".
## Methods
* [store.list](#store-list)
***
## Entity Properties
* [Store](#store-properties)
***
## `store.list`
`store.list()`
Retrieve stores list.
### Parameters
The method is used without parameters.
### Return Value
An array of objects with store information.
### Example Request
Retrieve stores information:
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"store.list",
[]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : [
{
"store_id" : 1,
"code" : "default",
"name" : "Default Store View",
"sort_order" : 0,
"is_active" : 1
}
]
}
```
## Entity Properties
### Store Properties
The internal store ID.
The "Code" property.
The "Name" property.
The "Sort Order" property.
Flag whether store is active.
# Delivery
Source: https://docs.shipstream.io/merchant-api/delivery
A delivery is an inbound shipment of your product to RSF. It could be an "ASN" (Advanced Shipment Notification), an "RMA" (Return Merchandise Authorization) or an "Other Delivery" (anything other than an ASN or RMA). They are all processed similarly regardless of which type of delivery is specified. Processing involves the general stages of "Accepting" the container from the carrier and weighing it, "Processing" the containers to align what was expected with what was actually received, "Putting Away" the processed inventory and "Committing" the put-away inventory to the available inventory. "Accepting" stage results with "Accepted" or "Ready To Process" delivery status. If the delivery has items on it before it is accepted, "Ready To Process" status is set and "Accepted" status skipped. Most of these steps happen automatically depending on the merchant's configuration and whether or not there are any exceptions (discrepancies between expected and received).
## Methods
* [delivery.search](#delivery-search)
* [delivery.create](#delivery-create)
* [delivery.labels](#delivery-labels)
* [delivery.gallery](#delivery-gallery)
* [delivery.update](#delivery-update)
* [delivery.close](#delivery-close)
* [delivery.commit](#delivery-commit)
* [delivery.cancel](#delivery-cancel)
* [delivery.void](#delivery-void)
***
## Entity Properties
* [Delivery](#delivery-properties)
* [Delivery Item](#delivery-item-properties)
* [Delivery Item Lot](#delivery-item-lot-properties)
* [Delivery Label](#delivery-label-properties)
* [Delivery Label Package](#delivery-label-package-properties)
* [Delivery Label Address](#delivery-label-address-properties)
* [Container](#container-properties)
* [Container Content](#container-content-properties)
* [Container Content Lot](#container-content-lot-properties)
* [Exception](#exception-properties)
* [Gallery](#gallery-properties)
* [Photo](#photo-properties)
* [Device Info](#device-info-properties)
* [Media Info](#media-info-properties)
***
## `delivery.search`
`delivery.search(null|object $filters, array $options = [])`
Retrieve list of deliveries. Filtration could be applied.
### Parameters
* `null` - Retrieve list of all deliveries.
* `object` - Retrieve list of deliveries using specified [Search Filters](/merchant-api/search-filters).
Allowed properties for filtering: "delivery\_id", "increment\_id", "warehouse\_id", "merchant\_ref", "merchant\_status", "total\_skus", "delivery\_type", "status", "sender\_name", "expected\_delivery", "expected\_containers", "sender\_ref", "sender\_ref\_alt", "created\_at", "updated\_at", "comments", "tracking\_numbers".
* `null` - No options will be applied.
* `object` - Apply specified [Search Options](/merchant-api/search-options).
### Return Value
An array of objects. Each object will contain [Delivery Properties](#delivery-properties).
### Example Request
Get delivery for one delivery id:
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"delivery.search",
[
{
"delivery_id" : {
"eq" : 1
}
},
[]
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : {
"results" : [
{
"delivery_id" : 1,
"warehouse_id" : 1,
"increment_id" : "1000036",
"delivery_type" : "asn",
"state" : "complete",
"status" : "put_away",
"progress" : 100,
"total_skus" : 2,
"sender_name" : "Microsoft",
"carrier_name" : "FedEx",
"expected_delivery" : "2014-06-26",
"expected_containers" : 2,
"delivered_at" : "2014-07-21T08:52:56+00:00",
"ready_to_process_at" : "2014-07-21T08:52:56+00:00",
"processed_at" : "2014-07-21T09:22:36+00:00",
"putaway_at" : "2014-07-21T11:24:05+00:00",
"completed_at" : null,
"comments" : null,
"merchant_ref" : null,
"merchant_status" : null,
"sender_ref" : null,
"sender_ref_alt" : null,
"num_containers" : 2,
"num_labels" : 1,
"total_container_weight" : null,
"total_container_weight_unit" : null,
"total_product_weight" : null,
"total_product_weight_unit" : null,
"special_requirements" : null,
"auto_commit" : 2,
"auto_close" : 2,
"created_at" : "2014-06-26T13:47:47+00:00",
"updated_at" : "2014-06-26T14:09:30+00:00",
"items" : [
{
"delivery_item_id" : 1,
"delivery_id" : 1,
"product_id" : 214,
"qty" : 1,
"qty_expected" : 0,
"qty_received" : 1,
"qty_shortage" : 0,
"qty_overage" : 5,
"qty_processed" : 1,
"qty_putaway" : 1,
"qty_committed" : 0,
"sku" : "product2",
"item_ref" : "ref_123456",
"lots" : [
{
"lot_id" : 25,
"qty_received" : 1,
"qty_shortage" : 0,
"qty_overage" : 5,
"qty_processed" : 1,
"qty_putaway" : 1,
"qty_committed" : 0
}
]
},
{
"delivery_item_id" : 2,
"delivery_id" : 1,
"product_id" : 213,
"qty" : 1,
"qty_expected" : 0,
"qty_received" : 1,
"qty_shortage" : 0,
"qty_overage" : 0,
"qty_processed" : 1,
"qty_putaway" : 1,
"qty_committed" : 0,
"sku" : "product1",
"item_ref" : null,
"lots" : []
}
],
"containers" : [
{
"container_id" : 1,
"delivery_id" : 1,
"container_type_id" : 1,
"damage_type" : "none",
"weight_discrepancy" : "none",
"tare_weight" : 1,
"tare_weight_unit" : "lb",
"weight" : 8,
"weight_unit" : "lb",
"weighed_at" : "2014-06-26T13:49:04+00:00",
"weighed_by" : 1,
"contents" : [
{
"delivery_item_id": 1,
"qty_counted": 6,
"qty_shortage": 0,
"lots": [
{
"lot_id": 25,
"qty_counted": 6,
"qty_shortage": 0
}
]
}
],
"notes" : null
},
{
"container_id" : 2,
"delivery_id" : 1,
"container_type_id" : 1,
"damage_type" : "none",
"weight_discrepancy" : "none",
"tare_weight" : 1,
"tare_weight_unit" : "lb",
"weight" : 3,
"weight_unit" : "lb",
"weighed_at" : "2014-06-26T13:49:15+00:00",
"weighed_by" : 1,
"contents" : [
{
"delivery_item_id": 2,
"qty_counted": 1,
"qty_shortage": 0,
"lots": []
}
],
"notes" : null
}
],
"exceptions" : [
{
"delivery_exception_id" : 1,
"delivery_id" : 1,
"delivery_item_id" : 1,
"container_id" : 2,
"lot_id" : null,
"status" : "pending",
"sign" : 1,
"reason" : "overage_counted",
"comment" : null,
"qty" : 5
}
]
}
],
"totalCount" : 1,
"numPages" : 1
}
}
```
### Error Codes
| code | message |
| ---- | ------------------------------------------------ |
| 101 | Invalid filters given. Details in error message. |
***
## `delivery.create`
`delivery.create(number $deliveryType, object $data, null|array $items = null)`
Create delivery.
### Parameters
Delivery type. Allowed: "asn", "rma", "other".
Delivery data. See [Delivery Properties](#delivery-properties).
* `null` - Create delivery without items.
* `array` - Array of objects with two properties: "sku" and "qty".
### Return Value
Delivery information.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"delivery.create",
[
"asn",
{
"warehouse_id" : 1,
"auto_commit" : 2,
"auto_close" : 2,
"sender_name" : "Bill Gates",
"carrier_name" : "FedEx",
"expected_delivery" : "2014-07-31",
"merchant_ref" : "Inv 12345"
},
[
{
"sku" : "product1",
"qty" : 5,
"item_ref" : "ref_123456"
},
{
"sku" : "product2",
"qty" : 1
}
]
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : {
"delivery_id" : 4,
"increment_id" : "1000039",
"delivery_type" : "asn",
"state": "new",
"status": "new",
"progress": 0,
"total_skus": 1,
"sender_name" : "Bill Gates",
"carrier_name" : "FedEx",
"expected_delivery" : "2014-07-31",
"delivered_at": null,
"ready_to_process_at": null,
"processed_at": null,
"putaway_at": null,
"completed_at": null,
"comments": null,
"merchant_ref" : 12345,
"merchant_status": null,
"sender_ref": null,
"sender_ref_alt": null,
"num_containers": null,
"num_labels": 0,
"total_container_weight": null,
"total_container_weight_unit": null,
"total_product_weight": null,
"total_product_weight_unit": null,
"special_requirements": null,
"auto_commit": 2,
"auto_close": 2,
"created_at" : "2014-07-31T14:10:00+00:00",
"updated_at" : "2014-07-31T14:10:00+00:00",
"warehouse_id" : 1
}
}
```
### Error Codes
| code | message |
| ---- | ------------------------------------------------------ |
| 107 | Error creating the delivery. Details in error message. |
***
## `delivery.labels`
`delivery.labels(string $incrementId, null|array $fields = [])`
Retrieve list of labels for the given delivery.
### Parameters
Delivery increment id
* `null` - Basic label data.
* `array` - Array of fields. Allowed: "packages", "destination\_address", "origin\_address"
### Return Value
An array of objects. Each object will contain [Delivery Label Properties](#delivery-label-properties).
### Example Request
Get labels for the delivery:
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"delivery.labels",
[
"1000055",
[
"packages",
"destination_address",
"origin_address"
]
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result": [
{
"label_id": "8",
"delivery_id": "26",
"warehouse_id": "1",
"status": "valid",
"shipping_label": "ups_03",
"created_at": "2021-01-20T10:03:55+00:00",
"updated_at": "2021-01-20T10:04:01+00:00",
"packages": [
{
"warehouse_id": "1",
"label_id": "8",
"carrier": "ups",
"weight": "18.000",
"weight_unit": "lb",
"dimensions": {
"length": "10.000",
"width": "11.000",
"height": "12.000"
},
"dimension_unit": "in",
"tracking": [
{
"number": "1Z49R7V89024431506",
"description": "UPS Ground"
}
],
"package_items": [
{
"delivery_item_id": 2,
"sku": "O-VS-Oregano-p3",
"quantity": "4.000"
},
{
"delivery_item_id": 3,
"sku": "O-VS-Mint-p2",
"quantity": "4.000"
},
{
"delivery_item_id": 5,
"sku": "VS-Bags-p1",
"quantity": "4.000"
}
]
}
],
"destination_address": {
"region": "New York",
"postcode": "13088",
"lastname": "Marquez",
"street": "4616 Crossroads Park Dr",
"city": "Liverpool",
"email": null,
"telephone": "865-971-4663",
"firstname": "Sherlock",
"company": null,
"classification": "com",
"is_valid": null,
"country": "US"
},
"origin_address": {
"region": "New York",
"postcode": "10036",
"lastname": "Gates",
"street": "11 Times Square",
"city": "New York",
"email": null,
"telephone": "212.245.2100",
"firstname": "Bill",
"company": "Microsoft",
"classification": null,
"is_valid": null,
"country": "US"
}
},
{
"label_id": "9",
"delivery_id": "26",
"warehouse_id": "1",
"status": "valid",
"carrier": "ups",
"created_at": "2021-01-20T10:04:23+00:00",
"updated_at": "2021-01-20T10:04:26+00:00",
"packages": [
{
"warehouse_id": "1",
"label_id": "9",
"carrier": "ups",
"weight": "27.000",
"weight_unit": "lb",
"dimensions": {
"length": "10.000",
"width": "11.000",
"height": "12.000"
},
"dimension_unit": "in",
"tracking": [
{
"number": "1Z49R7V89021837511",
"description": "UPS Ground"
}
],
"package_items": [
{
"delivery_item_id": 2,
"sku": "O-VS-Oregano-p3",
"quantity": "6.000"
},
{
"delivery_item_id": 3,
"sku": "O-VS-Mint-p2",
"quantity": "6.000"
},
{
"delivery_item_id": 5,
"sku": "VS-Bags-p1",
"quantity": "6.000"
}
]
}
],
"destination_address": {
"region": "New York",
"postcode": "13088",
"lastname": "Marquez",
"street": "4616 Crossroads Park Dr",
"city": "Liverpool",
"email": null,
"telephone": "865-971-4663",
"firstname": "Sherlock",
"company": null,
"classification": "com",
"is_valid": null,
"country": "US"
},
"origin_address": {
"region": "New York",
"postcode": "10036",
"lastname": "Gates",
"street": "11 Times Square",
"city": "New York",
"email": null,
"telephone": "212.245.2100",
"firstname": "Bill",
"company": "Microsoft",
"classification": null,
"is_valid": null,
"country": "US"
}
}
]
}
```
### Error Codes
| code | message |
| ---- | ---------------------------------- |
| 100 | Requested delivery does not exist. |
***
## `delivery.gallery`
`delivery.gallery(string $incrementId, string|null $updatedSince = null)`
Retrieve the gallery structure and photos for a delivery, including all child galleries for containers, container items, exceptions.
### Parameters
The delivery increment ID.
Optional. Filter galleries by update date. Only galleries updated since this date will be returned. Format: "YYYY-MM-DD HH:MM:SS".
### Return Value
An object containing [Gallery Properties](#gallery-properties) for the delivery gallery, with nested children galleries and associated photos.
### Example Request
Get complete gallery structure for a delivery:
```json title="Request" theme={null}
{
"jsonrpc": 2.0,
"id": 1234,
"method": "call",
"params": [
"95847bf590ea11c6a67d3a429ab14c61",
"delivery.gallery",
[
"11000008"
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"result": {
"gallery_id": 205,
"entity_type": "delivery",
"entity_id": 8,
"photo_count": 0,
"updated_at": "2025-09-25T10:32:51+00:00",
"photos": [],
"children": [
{
"gallery_id": 227,
"entity_type": "delivery_container",
"entity_id": 22,
"photo_count": 1,
"updated_at": "2025-09-25T10:32:51+00:00",
"photos": [
{
"original_url": "http://magentohost/cdn-cgi/image/original/development/gallery/delivery_container/22/45784f473e9f3375f2e3fb1430cb8863f03a32bf.webp",
"thumbnail_url": "http://magentohost/cdn-cgi/image/fit=inside,width=250/development/gallery/delivery_container/22/45784f473e9f3375f2e3fb1430cb8863f03a32bf.webp",
"caption": null,
"taken_at": null,
"device_info": null,
"media_info": {
"size": 77702,
"width": 2133,
"height": 1200,
"original_size": 159551,
"was_converted": false,
"original_width": 2560,
"size_formatted": "75.9KB",
"original_height": 1440,
"original_filename": "photo_12_1755888907743.png",
"processed_filename": "45784f473e9f3375f2e3fb1430cb8863f03a32bf.webp",
"original_size_formatted": "155.8KB"
},
"created_at": "2025-09-25T10:32:51+00:00"
}
],
"children": [
{
"gallery_id": 0,
"entity_type": "container_item",
"entity_id": 36,
"photo_count": 0,
"updated_at": null,
"photos": [],
"children": []
}
]
},
{
"gallery_id": 225,
"entity_type": "delivery_container",
"entity_id": 23,
"photo_count": 0,
"updated_at": "2025-09-25T10:31:20+00:00",
"photos": [],
"children": [
{
"gallery_id": 226,
"entity_type": "container_item",
"entity_id": 37,
"photo_count": 1,
"updated_at": "2025-09-25T10:31:20+00:00",
"photos": [
{
"original_url": "http://magentohost/cdn-cgi/image/original/development/gallery/container_item/37/5aab80b2ea8d4d9cdfa0eb2b5fd1c4d57805e923.webp",
"thumbnail_url": "http://magentohost/cdn-cgi/image/fit=inside,width=250/development/gallery/container_item/37/5aab80b2ea8d4d9cdfa0eb2b5fd1c4d57805e923.webp",
"caption": null,
"taken_at": null,
"device_info": null,
"media_info": {
"size": 92574,
"width": 1280,
"height": 960,
"original_size": 162469,
"was_converted": false,
"original_width": 1280,
"size_formatted": "90.4KB",
"original_height": 960,
"original_filename": "photo_2025-08-08_17-06-51.jpg",
"processed_filename": "5aab80b2ea8d4d9cdfa0eb2b5fd1c4d57805e923.webp",
"original_size_formatted": "158.7KB"
},
"created_at": "2025-09-25T10:31:20+00:00"
}
],
"children": []
}
]
},
{
"gallery_id": 206,
"entity_type": "delivery_container",
"entity_id": 24,
"photo_count": 0,
"updated_at": "2025-09-25T07:59:22+00:00",
"photos": [],
"children": [
{
"gallery_id": 207,
"entity_type": "container_item",
"entity_id": 38,
"photo_count": 0,
"updated_at": "2025-09-25T07:59:15+00:00",
"photos": [],
"children": []
}
]
},
{
"gallery_id": 219,
"entity_type": "delivery_container",
"entity_id": 25,
"photo_count": 0,
"updated_at": "2025-09-25T07:59:35+00:00",
"photos": [],
"children": [
{
"gallery_id": 220,
"entity_type": "container_item",
"entity_id": 39,
"photo_count": 2,
"updated_at": "2025-09-25T07:59:35+00:00",
"photos": [
{
"original_url": "http://magentohost/cdn-cgi/image/original/development/gallery/container_item/39/b6a6a99adb62aa99ef6171e10d1d7eb4293af006.webp",
"thumbnail_url": "http://magentohost/cdn-cgi/image/fit=inside,width=250/development/gallery/container_item/39/b6a6a99adb62aa99ef6171e10d1d7eb4293af006.webp",
"caption": null,
"taken_at": null,
"device_info": null,
"media_info": {
"size": 185868,
"width": 675,
"height": 1200,
"original_size": 225381,
"was_converted": false,
"original_width": 720,
"size_formatted": "181.5KB",
"original_height": 1280,
"original_filename": "photo_2024-04-25_17-25-28.jpg",
"processed_filename": "b6a6a99adb62aa99ef6171e10d1d7eb4293af006.webp",
"original_size_formatted": "220.1KB"
},
"created_at": "2025-09-25T07:58:57+00:00"
},
{
"original_url": "http://magentohost/cdn-cgi/image/original/development/gallery/container_item/39/b0864b04d9e8ae07cda17ef84d0296a3d1cf3822.webp",
"thumbnail_url": "http://magentohost/cdn-cgi/image/fit=inside,width=250/development/gallery/container_item/39/b0864b04d9e8ae07cda17ef84d0296a3d1cf3822.webp",
"caption": null,
"taken_at": null,
"device_info": null,
"media_info": {
"size": 180020,
"width": 1920,
"height": 1080,
"original_size": 185862,
"was_converted": false,
"original_width": 1920,
"size_formatted": "175.8KB",
"original_height": 1080,
"original_filename": "photo_12_17510867594.jpg",
"processed_filename": "b0864b04d9e8ae07cda17ef84d0296a3d1cf3822.webp",
"original_size_formatted": "181.5KB"
},
"created_at": "2025-09-25T07:58:57+00:00"
}
],
"children": []
}
]
},
{
"gallery_id": 208,
"entity_type": "delivery_container",
"entity_id": 26,
"photo_count": 0,
"updated_at": "2025-09-25T07:59:54+00:00",
"photos": [],
"children": [
{
"gallery_id": 209,
"entity_type": "container_item",
"entity_id": 40,
"photo_count": 2,
"updated_at": "2025-09-25T07:59:54+00:00",
"photos": [
{
"original_url": "http://magentohost/cdn-cgi/image/original/development/gallery/container_item/40/3adce614977d8ca84579d75ce47a6dddf7b5875a.webp",
"thumbnail_url": "http://magentohost/cdn-cgi/image/fit=inside,width=250/development/gallery/container_item/40/3adce614977d8ca84579d75ce47a6dddf7b5875a.webp",
"caption": "ddd",
"taken_at": null,
"device_info": null,
"media_info": {
"size": 85110,
"width": 1065,
"height": 600,
"original_size": 769040,
"was_converted": false,
"original_width": 1065,
"size_formatted": "83.1KB",
"original_height": 600,
"original_filename": "photo_5_1754929459408.png",
"processed_filename": "3adce614977d8ca84579d75ce47a6dddf7b5875a.webp",
"original_size_formatted": "751.0KB"
},
"created_at": "2025-09-25T07:48:08+00:00"
},
{
"original_url": "http://magentohost/cdn-cgi/image/original/development/gallery/container_item/40/c50b84705620840166b8aa20e9b84ab4cd127ed0.webp",
"thumbnail_url": "http://magentohost/cdn-cgi/image/fit=inside,width=250/development/gallery/container_item/40/c50b84705620840166b8aa20e9b84ab4cd127ed0.webp",
"caption": null,
"taken_at": null,
"device_info": null,
"media_info": {
"size": 71640,
"width": 1065,
"height": 600,
"original_size": 778219,
"was_converted": false,
"original_width": 1065,
"size_formatted": "70.0KB",
"original_height": 600,
"original_filename": "photo_16_1754397289147.png",
"processed_filename": "c50b84705620840166b8aa20e9b84ab4cd127ed0.webp",
"original_size_formatted": "760.0KB"
},
"created_at": "2025-09-25T07:48:08+00:00"
}
],
"children": []
}
]
}
]
},
"id": "1234",
"jsonrpc": "2.0"
}
```
### Example Request with Date Filter
Filter galleries by date to get only galleries updated since a specific date:
```json title="Request" theme={null}
{
"jsonrpc": 2.0,
"id": 1234,
"method": "call",
"params": [
"95847bf590ea11c6a67d3a429ab14c61",
"delivery.gallery",
[
"11000008",
"2025-09-25 10:30:00"
]
]
}
```
### Example Response with Date Filter
```json title="Response" theme={null}
{
"result": {
"gallery_id": 205,
"entity_type": "delivery",
"entity_id": 8,
"photo_count": 0,
"updated_at": "2025-09-25T10:32:51+00:00",
"photos": [],
"children": [
{
"gallery_id": 227,
"entity_type": "delivery_container",
"entity_id": 22,
"photo_count": 1,
"updated_at": "2025-09-25T10:32:51+00:00",
"photos": [
{
"original_url": "http://magentohost/cdn-cgi/image/original/development/gallery/delivery_container/22/45784f473e9f3375f2e3fb1430cb8863f03a32bf.webp",
"thumbnail_url": "http://magentohost/cdn-cgi/image/fit=inside,width=250/development/gallery/delivery_container/22/45784f473e9f3375f2e3fb1430cb8863f03a32bf.webp",
"caption": null,
"taken_at": null,
"device_info": null,
"media_info": {
"size": 77702,
"width": 2133,
"height": 1200,
"original_size": 159551,
"was_converted": false,
"original_width": 2560,
"size_formatted": "75.9KB",
"original_height": 1440,
"original_filename": "photo_12_1755888907743.png",
"processed_filename": "45784f473e9f3375f2e3fb1430cb8863f03a32bf.webp",
"original_size_formatted": "155.8KB"
},
"created_at": "2025-09-25T10:32:51+00:00"
}
],
"children": []
},
{
"gallery_id": 225,
"entity_type": "delivery_container",
"entity_id": 23,
"photo_count": 0,
"updated_at": "2025-09-25T10:31:20+00:00",
"photos": [],
"children": [
{
"gallery_id": 226,
"entity_type": "container_item",
"entity_id": 37,
"photo_count": 1,
"updated_at": "2025-09-25T10:31:20+00:00",
"photos": [
{
"original_url": "http://magentohost/cdn-cgi/image/original/development/gallery/container_item/37/5aab80b2ea8d4d9cdfa0eb2b5fd1c4d57805e923.webp",
"thumbnail_url": "http://magentohost/cdn-cgi/image/fit=inside,width=250/development/gallery/container_item/37/5aab80b2ea8d4d9cdfa0eb2b5fd1c4d57805e923.webp",
"caption": null,
"taken_at": null,
"device_info": null,
"media_info": {
"size": 92574,
"width": 1280,
"height": 960,
"original_size": 162469,
"was_converted": false,
"original_width": 1280,
"size_formatted": "90.4KB",
"original_height": 960,
"original_filename": "photo_2025-08-08_17-06-51.jpg",
"processed_filename": "5aab80b2ea8d4d9cdfa0eb2b5fd1c4d57805e923.webp",
"original_size_formatted": "158.7KB"
},
"created_at": "2025-09-25T10:31:20+00:00"
}
],
"children": []
}
]
}
]
},
"id": "1234",
"jsonrpc": "2.0"
}
```
### Example Request for Empty Gallery
Get gallery structure for a delivery without any photos:
```json title="Request" theme={null}
{
"jsonrpc": 2.0,
"id": 1234,
"method" : "call",
"params" : [
"95847bf590ea11c6a67d3a429ab14c61",
"delivery.gallery",
[
"11000013"
]
]
}
```
### Example Response for Empty Gallery
```json title="Response" theme={null}
{
"jsonrpc": 2.0,
"id": 1234,
"result": {
"gallery_id": 0,
"entity_type": "delivery",
"entity_id": 19,
"photo_count": 0,
"updated_at": null,
"children": [
{
"gallery_id": 0,
"entity_type": "delivery_container",
"entity_id": 41,
"photo_count": 0,
"updated_at": null,
"children": [
{
"gallery_id": 0,
"entity_type": "container_item",
"entity_id": 49,
"photo_count": 0,
"updated_at": null,
"children": [],
"photos": []
}
],
"photos": []
}
],
"photos": []
}
}
```
### Error Codes
| code | message |
| ------ | ---------------------------------- |
| -32100 | Requested delivery does not exist. |
***
## `delivery.update`
`delivery.update(string $incrementId, array|null $data = null, array|null $addItems = null, array|null $removeItems = null)`
Update delivery attributes. Add products. Remove products.
### Parameters
Increment ID.
Delivery data. See [Delivery Properties](#delivery-properties).
* `null` - Update delivery without adding items.
* `array` - Array of objects with two properties: "sku" and "qty".
* `null` - Update delivery without removing items.
* `array` - Array of objects with two properties: "sku" and "qty".
### Return Value
`true` if delivery was successfully updated.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"aebdb4cc6f861c79428768923f0eb6a2",
"delivery.update",
[
"10000011",
{
"merchant_ref" : "Inv 12345",
"merchant_status": "new",
"sender_name" : "Bill Gates",
"sender_ref": "100000004",
"sender_ref_alt": "100000001",
"expected_delivery" : "2014-07-31",
"carrier_name": "FedEx",
"auto_commit": 1,
"auto_close": 1,
"comments": "This delivery was updated via API"
},
[
{
"sku": "O-VS-Oregano-p3",
"qty": "6.000",
"item_ref": "ref_456"
}
],
[
{
"sku": "O-VS-Oregano-p3",
"qty": "3.000"
}
]
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"result": true,
"id": "1234",
"jsonrpc": "2.0"
}
```
***
## `delivery.close`
`delivery.close(string $incrementId)`
Close a delivery.
### Parameters
The "Increment ID" property.
### Return Value
`true` if delivery inventory was successfully closed.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"aebdb4cc6f861c79428768923f0eb6a2",
"delivery.close",
[
"11000011"
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"result": true,
"id": "1234",
"jsonrpc": "2.0"
}
```
### Error Codes
| code | message |
| ---- | ------------------------------------------------------------------------------ |
| 115 | Delivery with the specified ID cannot be closed. Details in the error message. |
***
## `delivery.commit`
`delivery.commit(string $incrementId, boolean $close = FALSE)`
Commit delivery inventory.
### Parameters
The "Increment ID" property.
`true` to close the delivery.
### Return Value
`true` if delivery inventory was successfully committed.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"aebdb4cc6f861c79428768923f0eb6a2",
"delivery.commit",
[
"11000011"
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"result": true,
"id": "1234",
"jsonrpc": "2.0"
}
```
### Error Codes
| code | message |
| ---- | --------------------------------------------------------------------------------- |
| 113 | Delivery with the specified ID cannot be committed. Details in the error message. |
***
## `delivery.cancel`
`delivery.cancel(string $incrementId)`
Cancel delivery.
### Parameters
The "Increment ID" property.
### Return Value
`true` if delivery was successfully canceled.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"aebdb4cc6f861c79428768923f0eb6a2",
"delivery.cancel",
[
"11000017"
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"result": true,
"id": "1234",
"jsonrpc": "2.0"
}
```
### Error Codes
| code | message |
| ---- | -------------------------------------------------------------------------------- |
| 112 | Delivery with the specified ID cannot be canceled. Details in the error message. |
***
## `delivery.void`
`delivery.void(string $incrementId)`
Cancel delivery.
### Parameters
The "Increment ID" property.
### Return Value
`true` if delivery was successfully voided.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"aebdb4cc6f861c79428768923f0eb6a2",
"delivery.void",
[
"11000018"
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"result": true,
"id": "1234",
"jsonrpc": "2.0"
}
```
### Error Codes
| code | message |
| ---- | ------------------------------------------------------------------------------ |
| 114 | Delivery with the specified ID cannot be voided. Details in the error message. |
***
## Entity Properties
### Delivery Properties
#### Property Translations: API to UI
| **API** | ASN | RMA | Other |
| :--------------------- | :--------------------- | :------------------------------------ | :--------------------- |
| **sender\_name** | Supplier | Customer Name | Sender |
| **sender\_ref** | Supplier Invoice Ref | (deprecated, use `tracking_numbers` ) | Sender Ref 1 |
| **sender\_ref\_alt** | Supplier Order Ref | Merchant Order # | Sender Ref 2 |
| **tracking\_numbers** | Tracking Numbers | Tracking Numbers | Tracking Numbers |
| **merchant\_ref** | Merchant Ref | Merchant RMA # | Merchant Ref |
| **merchant\_status** | Merchant Status | Merchant Status | Merchant Status |
| **expected\_delivery** | Expected Delivery Date | Authorization Date | Expected Delivery Date |
The internal delivery ID.
The internal warehouse ID.
The "Increment ID" property.
The "Delivery Type" property. Allowed: "asn", "rma", "other".
The "State" property. Allowed: "new", "processing", "putting\_away", "pending\_commit", "complete", "canceled".
The "Status" property. Allowed: "new", "accepting", "accepted", "ready\_to\_process", "processing", "processing\_exception", "processed", "putting\_away", "put\_away", "complete", "canceled", "void".
The "Progress" property. Number from 0 to 100.
Total amount of SKUs.
The "Sender Name" property.
The "Carrier Name" property.
The "Expected Delivery" property.
The "Delivered At" property.
The "Delivered At" property.
The "Processed At" property.
The "Put-Away At" property.
The "Completed At" property.
The "Comments" property.
The "Merchant Reference" property. Uniqueness based on this field is enforced so an error will be given if a delivery with the same merchant\_ref already exists.
The "Merchant Status" property.
The "Sender Reference" property. Do not use this field for RMAs.
The "Sender Reference Alt" property.
The "Tracking Numbers" property.
Number of containers expected to arrive with the delivery. Used to track reconciliation against `num_containers` as the warehouse accepts them.
Number of containers.
Number of labels.
The "Total Container Weight" property.
The unit of measure used for `total_container_weight`. See: [Weight Units](/merchant-api/units-of-measure#weight).
The "Total Product Weight" property.
The unit of measure used for `total_product_weight`. See: [Weight Units](/merchant-api/units-of-measure#weight).
The "Special Requirements" property.
Determines whether inventory will be commited automatically upon put-away completion. 0 - Disabled, 1 - Enabled, 2 - Use default from config
Determines whether the delivery will be closed automatically upon acceptance of the last container. 0 - Disabled, 1 - Enabled, 2 - Use default from config
The "Created At" property in ISO 8601 format. If not available, `null` is returned.
The "Updated At" property in ISO 8601 format. If not available, `null` is returned.
Array of delivery items. See [Delivery Item Properties](#delivery-item-properties).
Array of containers. See [Container Properties](#container-properties).
Array of exceptions. See [Exception Properties](#exception-properties).
### Delivery Item Properties
The internal delivery item ID.
The internal delivery ID.
The internal product ID.
The quantity that was set when the delivery was created or edited.
The quantity that is expected to be received in the future.
The "Received" quantity.
The "Shortage" quantity.
The "Overage" quantity.
The "Processed" quantity.
The "Put-Away" quantity.
The "Committed" quantity.
The "SKU" property.
An external item reference which may be up to 1024 characters.
Array of per-lot quantity breakdowns for this item. See [Delivery Item Lot Properties](#delivery-item-lot-properties). Present only for lot-tracked products; units received without a lot are not decomposed.
### Delivery Item Lot Properties
Each entry breaks down the [Delivery Item](#delivery-item-properties) quantities by lot. Lot metadata (lot number, expiration date, etc.) is not included here — resolve `lot_id` via [inventory.lots](/merchant-api/inventory#inventory-lots) when needed.
The lot ID.
The "Received" quantity attributable to this lot.
The "Shortage" quantity attributable to this lot.
The "Overage" quantity attributable to this lot.
The "Processed" quantity attributable to this lot.
The "Put-Away" quantity attributable to this lot.
The "Committed" quantity attributable to this lot.
### Delivery Label Properties
The internal delivery label ID.
The internal delivery ID.
The internal warehouse ID.
The "Status" property. Allowed: "valid", "void".
See the [Shipping Methods](/merchant-api/shipping-methods) document for a reference. Is not optional.
The "Created At" property in ISO 8601 format.
The "Updated At" property in ISO 8601 format.
Array of delivery label packages. See [Delivery Label Package Properties](#delivery-label-package-properties).
Destination Address. See [Delivery Label Address Properties](#delivery-label-address-properties).
Origination Address. See [Delivery Label Address Properties](#delivery-label-address-properties).
### Delivery Label Package Properties
The ID of the warehouse associated with the package.
The internal delivery label ID.
Carrier code.
The weight of the package.
The unit of measure used for `weight`. See: [Weight Units](/merchant-api/units-of-measure#weight).
The `length`, `width`, and `height` of the package.
The unit of measure used for `length`, `width`, and `height` in `dimensions`. See: [Length Units](/merchant-api/units-of-measure#length).
An array of tracking objects. The "number" property contains the tracking number. The "description" property contains the shipping method name.
An array of items contained in the package. `delivery_item_id` is the unqiue identifier of the related delivery item. `sku` is the package item's SKU. `quantity` is the quantity of the item in the package.
### Delivery Label Address Properties
The "First Name" property.
The "Last Name" property.
The "Company" property.
The street address. Multi-line street addresses will be separated by a newline (`\n`) character. Only two address lines are supported.
The "City" property.
The "Region" property.
The "Postal Code" property. Pass as a string to prevent leading 0s from being dropped.
The "Country" property.
The "Classification" property. Allowed: "res" - residential, "com" - commercial, "po" - post office, "mil" - military, "unk" - unknown.
Flag whether address is valid.
The "Telephone" property.
The "Email" property.
### Container Properties
The internal container ID.
The internal delivery ID.
The "Container Type ID" property.
The "Damage Type" property. Allowed: "none", "noted", "unnoted".
The "Weight Discrepancy" property. Allowed: "none", "shortage\_noted", "shortage\_unnoted", "overage", "unknown".
The "Tare Weight" property.
The unit of measure used for `tare_weight`. See: [Weight Units](/merchant-api/units-of-measure#weight).
The "Weight" property.
The unit of measure used for `weight`. See: [Weight Units](/merchant-api/units-of-measure#weight).
The "Weighed At" property.
The "Weighed By" property.
Array of "content" objects. See [Container Content Properties](#container-content-properties).
The "Notes" property.
### Container Content Properties
The internal delivery item ID.
The "Quantity Counted" property.
The "Quantity Shortage" property.
Array of per-lot counted/shortage breakdowns for this container content. See [Container Content Lot Properties](#container-content-lot-properties). Present only for lot-tracked products.
### Container Content Lot Properties
Each entry breaks down the parent [Container Content](#container-content-properties) quantities by lot.
The lot ID.
The "Quantity Counted" attributable to this lot within this container content.
The "Quantity Shortage" attributable to this lot within this container content.
### Exception Properties
The internal delivery exception ID.
The internal delivery ID.
The internal delivery item ID.
The internal container ID.
The internal lot ID the exception is scoped to, or `null` for exceptions that are not lot-specific.
The "Status" property. Allowed: "new", "pending", "approved", "rejected", "void".
The "Sign" property. Allowed: "-1" - shortage, "1" - overage.
The "Reason" property. Allowed: "overage\_counted", "overage\_unexpected", "shortage\_damaged", "shortage\_missing".
The "Comment" property.
The "Quantity" property.
### Gallery Properties
The internal gallery ID. `0` indicates no gallery exists for this entity.
The type of entity this gallery belongs to. Allowed: "delivery", "delivery\_container", "container\_item", "delivery\_exception".
The internal ID of the entity this gallery belongs to.
The total number of photos in this gallery.
The timestamp when this gallery was last updated. `null` if no photos have been added.
Array of child galleries. See [Gallery Properties](#gallery-properties).
Array of photos in this gallery. See [Photo Properties](#photo-properties).
### Photo Properties
The URL to the original full-size photo.
The URL to the thumbnail version of the photo, resized to fit 250px × 250px.
Optional caption text for the photo.
Time and date in ISO 8601 format when the photo was taken. If not available, `null` is returned.
Information about the device used to take the photo. See [Device Info Properties](#device-info-properties). `null` if not available.
Technical information about the photo file. See [Media Info Properties](#media-info-properties).
The timestamp when the photo was uploaded to the system.
### Device Info Properties
Information about the camera lens used.
The device model that took the photo.
The aperture setting used when taking the photo.
The focal length setting used when taking the photo.
Additional camera settings used when taking the photo.
The ISO setting used when taking the photo.
Information about flash usage when taking the photo.
The shutter speed used when taking the photo.
### Media Info Properties
The processed file size in bytes.
The width of the processed image in pixels.
The height of the processed image in pixels.
The original file size in bytes.
Whether the original file was converted to a different format.
The width of the original image in pixels.
The processed file size formatted as a human-readable string (e.g., "502.3KB", "2.4MB").
The height of the original image in pixels.
The original filename when the photo was uploaded.
The filename after processing.
The original file size formatted as a human-readable string (e.g., "2.4MB").
# Delivery Label
Source: https://docs.shipstream.io/merchant-api/delivery-label
## Methods
* [delivery\_label.info](#delivery-label-info)
* [delivery\_label.search](#delivery-label-search)
* [delivery\_label.create](#delivery-label-create)
* [delivery\_label.void](#delivery-label-void)
***
## Entity Properties
* [Delivery Label](#delivery-label-properties)
* [Delivery Label Package](#delivery-label-package-properties)
* [Delivery Label Address](#delivery-label-address-properties)
***
## `delivery_label.info`
`delivery_label.info (int $labelId, array $fields = [])`
Retrieve delivery label information.
### Parameters
Delivery label internal id
* `null` - Basic label data.
* `array` - Array of fields. Allowed: "packages", "destination\_address", "origin\_address"
### Return Value
An object with [Delivery Label Properties](#delivery-label-properties).
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"12e6f7398eb7a992219477aaa771725d",
"delivery_label.info",
[
"2",
[
"packages",
"destination_address",
"origin_address",
"files"
]
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result": [
{
"label_id": "8",
"delivery_id": "26",
"warehouse_id": "1",
"status": "valid",
"shipping_method": "ups_03",
"created_at": "2021-01-20T10:03:55+00:00",
"updated_at": "2021-01-20T10:04:01+00:00",
"packages": [
{
"warehouse_id": "1",
"label_id": "8",
"carrier": "ups",
"weight": "18.000",
"weight_unit": "lb",
"dimensions": {
"length": "10.000",
"width": "11.000",
"height": "12.000"
},
"dimension_unit": "in",
"tracking": [
{
"number": "1Z49R7V89024431506",
"description": "UPS Ground"
}
],
"package_items": [
{
"delivery_item_id": 2,
"sku": "O-VS-Oregano-p3",
"quantity": "4.000"
},
{
"delivery_item_id": 3,
"sku": "O-VS-Mint-p2",
"quantity": "4.000"
},
{
"delivery_item_id": 5,
"sku": "VS-Bags-p1",
"quantity": "4.000"
}
]
}
],
"destination_address": {
"region": "New York",
"postcode": "13088",
"lastname": "Marquez",
"street": "4616 Crossroads Park Dr",
"city": "Liverpool",
"email": null,
"telephone": "865-971-4663",
"firstname": "Sherlock",
"company": null,
"classification": "com",
"is_valid": null,
"country": "US"
},
"origin_address": {
"region": "New York",
"postcode": "10036",
"lastname": "Gates",
"street": "11 Times Square",
"city": "New York",
"email": null,
"telephone": "212.245.2100",
"firstname": "Bill",
"company": "Microsoft",
"classification": null,
"is_valid": null,
"country": "US"
},
"files": {
"label": {
"type": "pdf",
"data": "base64encoded..."
},
"auxiliary_label": {
"type": "pdf",
"data": "bas64encoded..."
},
"customs_documents": null
}
}
]
}
```
### Error Codes
| code | message |
| ---- | ---------------------------------------- |
| 100 | Requested delivery label does not exist. |
***
## `delivery_label.search`
`delivery_label.search(object|null $filters = [], array|null $options = [], array|null $fields = [])`
An array of objects. Each object will contain [Delivery Label Properties](#delivery-label-properties).
### Parameters
* `null` - Retrieve list of all delivery labels.
* `object` - Retrieve list of delivery labels using specified [Search Filters](/merchant-api/search-filters).
* `null` - No options will be applied.
* `object` - Apply specified [Search Options](/merchant-api/search-options).
* `null` - Basic label data.
* `array` - Array of fields. Allowed: "packages", "destination\_address", "origin\_address"
### Return Value
An array of objects. Each object will contain [Delivery Label Properties](#delivery-label-properties).
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"12e6f7398eb7a992219477aaa771725d",
"delivery_label.search",
[
{ "label_id": { "eq" : "2" } },
{
"limit": 100,
"page": 1
},
[
"packages",
"destination_address",
"origin_address",
"files"
]
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"result": {
"results": [
{
"label_id": "2",
"delivery_id": "22",
"warehouse_id": "1",
"status": "valid",
"shipping_method": "ups_03",
"created_at": "2021-01-18T13:57:25+00:00",
"updated_at": "2021-01-18T13:57:29+00:00",
"packages": [
{
"warehouse_id": "1",
"label_id": "2",
"carrier": "ups",
"weight": "45.000",
"weight_unit": "lb",
"dimensions": {
"length": "10.000",
"width": "11.000",
"height": "12.000"
},
"dimension_unit": "in",
"tracking": [
{
"number": "1Z49R7V89024877071",
"description": "UPS Ground"
}
],
"package_items": [
{
"delivery_item_id": "68",
"sku": "O-VS-Oregano-p3",
"quantity": "10.000"
},
{
"delivery_item_id": "69",
"sku": "O-VS-Mint-p2",
"quantity": "10.000"
},
{
"delivery_item_id": "70",
"sku": "VS-Bags-p1",
"quantity": "10.000"
}
]
}
],
"destination_address": {
"region": "New York",
"postcode": "13088",
"lastname": "Marquez",
"street": "4616 Crossroads Park Dr",
"city": "Liverpool",
"email": null,
"telephone": "865-971-4663",
"firstname": "Sherlock",
"company": null,
"classification": "com",
"is_valid": null,
"country": "US"
},
"origin_address": {
"region": "New York",
"postcode": "10036",
"lastname": "Gates",
"street": "11 Times Square",
"city": "New York",
"email": null,
"telephone": "212.245.2100",
"firstname": "Bill",
"company": "Microsoft",
"classification": null,
"is_valid": null,
"country": "US"
},
"files": {
"label": {
"type": "pdf",
"data": "base64encoded..."
},
"auxiliary_label": {
"type": "pdf",
"data": "bas64encoded..."
},
"customs_documents": null
}
}
],
"totalCount": 1,
"numPages": 1
}
}
```
### Error Codes
| code | message |
| ---- | ------------------------------------------------ |
| 101 | Invalid filters given. Details in error message. |
***
## `delivery_label.create`
`delivery_label.create (string $incrementId, object $address, array $packages, object $options)`
Create a new delivery label.
### Parameters
Delivery # (i.e., the ASN # or RMA # depending on the type)
Destination Address. See [Delivery Label Address Properties](#delivery-label-address-properties).
Array of delivery label packages. See [Delivery Label Package Properties](#delivery-label-package-properties).
Options. See [Delivery Label Options](#delivery-label-options).
### Return Value
An object with [Delivery Label Properties](#delivery-label-properties).
### Example Request
```json title="Request" theme={null}
{
"jsonrpc":2.0,
"id":1234,
"method":"call",
"params":[
"12e6f7398eb7a992219477aaa771725d",
"delivery_label.create",
[
"11000022",
{
"firstname" : "Bill",
"lastname" : "Gates",
"company" : "Microsoft",
"street" : "11 Times Square",
"city" : "New York",
"region" : "NY",
"postcode" : "10036",
"country" : "US",
"telephone" : "212.245.2100"
},
[
{
"weight": "45.000",
"weight_unit": "lb",
"dimensions": {
"length": "10.000",
"width": "11.000",
"height": "12.000"
},
"dimension_unit": "in",
"package_items": [
{
"sku": "O-VS-Oregano-p3",
"quantity": "10.000"
},
{
"sku": "O-VS-Mint-p2",
"quantity": "10.000"
},
{
"sku": "VS-Bags-p1",
"quantity": "10.000"
}
]
}
],
{
"shipping_method":"ups_03",
"return_service_type":"print_or_download"
}
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result": [
{
"label_id": "10",
"delivery_id": "27",
"warehouse_id": "1",
"status": "valid",
"shipping_method": "ups_03",
"created_at": "2021-01-22T13:45:17+00:00",
"updated_at": "2021-01-22T13:45:28+00:00",
"packages": [
{
"warehouse_id": "1",
"label_id": "10",
"carrier": "ups",
"weight": 45,
"weight_unit": "lb",
"dimensions": {
"length": 10,
"width": 11,
"height": 12
},
"dimension_unit": "in",
"tracking": [
{
"number": "1Z49R7V89013598741",
"description": "UPS Ground"
}
],
"package_items": [
{
"delivery_item_id": "81",
"sku": "O-VS-Oregano-p3",
"quantity": 10
},
{
"delivery_item_id": "82",
"sku": "O-VS-Mint-p2",
"quantity": 10
},
{
"delivery_item_id": "83",
"sku": "VS-Bags-p1",
"quantity": 10
}
]
}
],
"destination_address": {
"firstname": "Sherlock",
"lastname": "Marquez",
"telephone": "865-971-4663",
"street": "4616 Crossroads Park Dr",
"city": "Liverpool",
"postcode": "13088",
"classification": "com",
"region": "New York",
"country": "US"
},
"origin_address": {
"firstname": "Bill",
"lastname": "Gates",
"company": "Microsoft",
"street": "11 Times Square",
"city": "New York",
"region": "New York",
"postcode": "10036",
"telephone": "212.245.2100",
"email": null,
"classification": null,
"is_valid": null,
"country": "US"
},
"files": {
"label": {
"type": "pdf",
"data": "base64encoded..."
},
"auxiliary_label": {
"type": "pdf",
"data": "bas64encoded..."
},
"customs_documents": null
}
}
]
}
```
### Error Codes
| code | message |
| ---- | --------------------------------------------------------------- |
| 100 | Requested delivery label does not exist. |
| 101 | Invalid filters given. Details in error message. |
| 102 | Invalid data given. Details in error message. |
| 103 | Cannot void the delivery label. Details in error message. |
| 104 | An unexpected error occurred while creating the delivery label. |
| 105 | Requested delivery does not exist. |
***
## `delivery_label.void`
`delivery_label.void (int $labelId)`
Void delivery label.
### Parameters
Delivery label internal id
### Return Value
`true` if the Delivery Label was voided.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"12e6f7398eb7a992219477aaa771725d",
"delivery_label.void",
[
"8"
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"result": true
}
```
### Error Codes
| code | message |
| ---- | --------------------------------------------------------- |
| 103 | Cannot void the delivery label. Details in error message. |
## Entity Properties
### Delivery Label Properties
The internal delivery label ID.
The internal delivery ID.
The internal warehouse ID.
The "Status" property. Allowed: "valid", "void".
See the [Shipping Methods](/merchant-api/shipping-methods) document for a reference. Is not optional.
The "Created At" property in ISO 8601 format.
The "Updated At" property in ISO 8601 format.
Array of delivery label packages. See [Delivery Label Package Properties](#delivery-label-package-properties).
Destination Address. See [Delivery Label Address Properties](#delivery-label-address-properties).
Origination Address. See [Delivery Label Address Properties](#delivery-label-address-properties).
An object with a label type as the key and the file data as the value. Allowed types: "label", "auxiliary\_label", "customs\_documents".
See [Delivery Label File Properties](#delivery-label-file-properties).
### Delivery Label Package Properties
The ID of the warehouse associated with the package.
The internal delivery label ID.
Carrier code.
The weight of the package.
The unit of measure used for `weight`. See: [Weight Units](/merchant-api/units-of-measure#weight).
The `length`, `width`, and `height` of the package.
The unit of measure used for `length`, `width`, and `height` in `dimensions`. See: [Length Units](/merchant-api/units-of-measure#length).
An array of tracking objects. The "number" property contains the tracking number. The "description" property contains the shipping method name.
An array of items contained in the package. `delivery_item_id` is the unqiue identifier of the related delivery item. `sku` is the package item's SKU. `quantity` is the quantity of the item in the package.
### Delivery Label Address Properties
The "First Name" property.
The "Last Name" property.
The "Company" property.
The street address. Multi-line street addresses will be separated by a newline ("\n") character. Only two address lines are supported.
The "City" property.
The "Region" property.
The "Postal Code" property. Pass as a string to prevent leading 0s from being dropped.
The "Country" property.
The "Classification" property. Allowed: "res" - residential, "com" - commercial, "po" - post office, "mil" - military, "unk" - unknown.
Flag whether address is valid.
The "Telephone" property.
The "Email" property.
### Delivery Label Options
One or more shipping methods. See the [Shipping Methods](/merchant-api/shipping-methods) document for a reference.
The "Return Service Type" property. Allowed: "print\_or\_download", "email\_label".
The "Copy Email To" property. Comma separated emails. Only applicable to "email\_label" Return Service Type.
The "Email Notification Message" property. Only applicable to "email\_label" Return Service Type.
The "Saturday Pickup" property.
The "Declared Value Service" property.
The ID number of a [Third Party Billing Account Group](/merchant-api/third-party-billing-group). If unset or `null`, and a default group is configured, the default group will be used. Set to `0` to disable third party billing.
### Delivery Label File Properties
The "Type" property. Allowed: "pdf".
Base64 encoded file content.
# Enumerations
Source: https://docs.shipstream.io/merchant-api/enumeration
## Methods
* [enumeration.list](#enumeration-list)
* [enumeration.info](#enumeration-info)
***
## Entity Properties
* [Enumeration](#enumeration-properties)
***
## `enumeration.list`
`enumeration.list (int|null $warehouseId)`
Get all enumerations.
### Parameters
Warehouse.
### Return Value
An array of [Enumerations](#enumeration-properties) or an empty array.
### Example Request
Get all enumerations:
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"enumeration.list"
]
}
```
Get all enumerations for warehouse "2":
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"enumeration.list",
[2]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"result" : {
"catalog": {
"goods_type": {
"singular_name": "Goods Type",
"plural_name": "Goods Types",
"data": [
{
"key": "HAZMAT",
"label": "Regulated"
},
{
"key": "LIMITED_QUANTITIES_COMMODITIES",
"label": "Limited Quantities: Consumer Commodity"
},
{
"key": "NORMAL",
"label": "Not Regulated"
}
]
}
},
"shipment": {
"status": {
"singular_name": "Status",
"plural_name": "Statuses",
"data": [
{
"key": "canceled",
"label": "Canceled"
},
{
"key": "shipped",
"label": "Shipped"
},
{
"key": "new",
"label": "New"
},
{
"key": "packed",
"label": "Packed"
},
{
"key": "packing",
"label": "Packing"
},
{
"key": "picked",
"label": "Picked"
},
{
"key": "picking",
"label": "Picking"
},
{
"key": "voided",
"label": "Voided"
}
]
}
}
}
}
```
## `enumeration.info`
`enumeration.info (string $path, int|null $warehouseId)`
Get enumeration info.
### Parameters
Path.
Warehouse.
### Return Value
[Enumeration](#enumeration-properties).
### Example Request
Get enumeration info:
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"enumeration.info",
["catalog/goods_type"]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"result" : {
"singular_name": "Goods Type",
"plural_name": "Goods Types",
"data": [
{
"key": "HAZMAT",
"label": "Regulated"
},
{
"key": "LIMITED_QUANTITIES_COMMODITIES",
"label": "Limited Quantities: Consumer Commodity"
},
{
"key": "NORMAL",
"label": "Not Regulated"
}
]
}
}
```
## Entity Properties
### Enumeration Properties
The singular name.
The plural name.
Depends on merchant flag is only returned when the value is true.
Depends on warehouse flag is only returned when the value is true.
Enumeration data.
# Import
Source: https://docs.shipstream.io/merchant-api/import
## Methods
* [import.search](#import-search)
* [import.info](#import-info)
* [import.create](#import-create)
***
## Entity Properties
* [Import Options](#import-options-properties)
* [Import](#import-properties)
***
## `import.search`
`import.search(null|object $filters, array $options = [])`
Retrieve list of imports. Filtration could be applied.
### Parameters
* `null` - Retrieve list of all imports.
* `object` - Retrieve list of imports using specified [Search Filters](/merchant-api/search-filters).
* `null` - No options will be applied.
* `object` - Apply specified [Search Options](/merchant-api/search-options).
### Return Value
An array of objects. Each object will contain [Import Properties](#import-properties).
### Example Request
Get import details for one import id:
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"import.search",
[
{
"task_id" : {
"eq" : 1
}
},
[]
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : [
{
"task_id" : 1,
"status" : "complete",
"progress" : 100,
"num_records" : 6,
"num_parse_success" : 6,
"num_parse_failures" : 0,
"num_submit_success" : 1,
"num_submit_failures" : 5
}
]
}
```
### Error Codes
| code | message |
| ---- | ------------------------------------------------ |
| 101 | Invalid filters given. Details in error message. |
***
## `import.info`
`import.info (string $taskId, null|object $fields = [])`
Retrieve full order information.
### Parameters
Import unique ID.
* `null` - Retrieve basic import properties.
* `array` - Defined list of properties to retrieve. "records" will add records information which is excluded by default.
### Return Value
Object which contains the specified (or default if no fields parameter was given) [Import Properties](#import-properties).
### Example Request
Get order information for the specified order:
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"import.info",
[
3,
[
"records"
]
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : {
"task_id" : 1,
"status" : "complete",
"progress" : 100,
"num_records" : 6,
"num_parse_success" : 6,
"num_parse_failures" : 0,
"num_submit_success" : 1,
"num_submit_failures" : 5,
"records" : [
{
"entity_id" : "10000045",
"parse_status" : "valid",
"submit_status" : "complete"
}
]
}
}
```
### Error Codes
| code | message |
| ---- | -------------------------------- |
| 100 | Requested import does not exist. |
***
## `import.create`
`import.create (string $data, string $entityType, null|object $options)`
Import data.
### Parameters
base64 encoded string.
Entity type. Allowed: "product", "order", "delivery", "bom".
Apply specified [Import Options](#import-options-properties).
### Return Value
The internal import id.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"import.create",
[
"base64 encoded data",
"order",
{
"handle_duplicates" : "drop",
"send_email_on_complete" : 1,
"email" : "email@example.com",
"hold_orders" : "hold"
}
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : 7
}
```
### Error Codes
| code | message |
| ---- | ----------------------------------------------------------------------- |
| 101 | Invalid filters given. Details in error message. |
| 103 | Invalid file type given. |
| 104 | Invalid file data given. |
| 105 | Internal error occurred. |
| 106 | Internal error occurred while converting the import file to CSV format. |
| 107 | Internal error occurred while scheduling import job. |
## Entity Properties
### Import Options Properties
Handle duplicates. Allowed: "create", "drop", "break".
Flag whether send email on task complete.
Email address to send email after task complete. The email will only be sent if "send\_email\_on\_complete" flag is set to 1.
Order status. Allowed: "hold".
### Import Properties
The internal import ID.
Status. Allowed: "pending", "running", "complete".
Progress percent.
Total number of records.
Number of successfully parsed records.
Number of parse failures.
Number of successfully submitted records.
Number of submit failures.
# Import Formats
Source: https://docs.shipstream.io/merchant-api/import-formats
ShipStream supports importing [orders](/merchant-api/order#ordercreate), [products](/merchant-api/product#product-create), [deliveries](/merchant-api/delivery#delivery-create) and [BOMs](/merchant-api/bom) either via the Merchant Panel or the [Import](/merchant-api/import) API.
The file formats supported are:
* CSV (delimiters are auto-detected)
* Excel (table format the same as Standard CSV)
* JSON Lines (single-line or multi-line JSON objects delimited by newlines)
The file data may be compressed with GZip or BZip2 compression.
The import formats all conform to the respective API '\*.create' methods so please see the documentation for those methods for details about supported field names and values.
## Order - Standard CSV
The header row defines which columns are used and each following line should consist of the order data, SKU and quantity for one order item. If the order contains multiple items they can be specified using additional rows and the order data can be either repeated (it will be ignored) or omitted as long as the 'order\_ref' column is not omitted since it is used to group the order items together.
**See [Order Properties](/merchant-api/order#order-properties) for the supported field names and values.**
To group multi-product orders together for CSV imports either the `unique_id` or the `order_ref` must be supplied unless there is only one order per file. When the `unique_id` is supplied with no `order_ref` then the `unique_id` will be used to group rows. When the `order_ref` is supplied with no `unique_id` then the `order_ref` will be used to group rows. If both `unique_id` and `order_ref` are supplied then the `unique_id` will be used to group rows.
Order Custom Fields can be used in Order Imports. To add an Order Custom Field, add the field's code to the header with a prefix symbol.
There are two types of prefixes:
* Prefix with `#` when the values are identified by "id". See [Enumerated Order Custom Field Options](https://help.shipstream.io/article/0hv4sjkn3d-custom-fields-for-orders#enumerated-order-custom-field-options) article section for how to find the "id".
* Prefix with `@` when the values uploaded are numeric values or text.
Here's an example of how to use these prefixes:
```
"@claim_reasons","@cost_of_goods","@allow_mailer","#claim-reason"
"Damaged in shipping|Did not fit",41.32,true,13
```
For fields that allow multiple values, separate each value with the pipe character `|`.
```csv title="order_import_sample.csv" theme={null}
order_ref,shipping_method,firstname,lastname,company,street1,city,region,postcode,country,telephone,sku,qty,@claim_reasons,@cost_of_goods,@allow_mailer,#claim-reason
123456,ups_01,Bill,Gates,Microsoft,11 Times Square,New York,NY,10036,US,212.245.2100,product1,5,Damaged in shipping|Did not fit,41.32,true,13
123456,,,,,,,,,,,product2,1,,,,
123456,,,,,,,,,,,product3,2,,,,
```
## Order - Standard JSON
Importing orders in JSON format should follow the [order.create](/merchant-api/order#ordercreate) inputs exactly.
```json title="order_import_sample.json" theme={null}
{
"order_ref" : "123456",
"shipping_method" : "ups_01",
"firstname" : "Bill",
"lastname" : "Gates",
"company" : "Microsoft",
"street1" : "11 Times Square",
"city" : "New York",
"region" : "NY",
"postcode" : "10036",
"country" : "US",
"telephone" : "212.245.2100",
"items" : {
"product1" : 2,
"product2" : 3,
"product3" : 1
},
"custom_fields" : {
"claim_reasons" : ["Damaged in shipping", "Did not fit"],
"cost_of_goods" : "41.32",
"allow_mailer" : "true",
"claim_reason" : {"id" : 13}
}
}
```
## Product - Standard CSV
The header row should contain all field names and each following row contains product data. Each row must specify a SKU at minimum.
**See [Product Properties](/merchant-api/product#product-properties) for the supported field names and values.**
If a field supports multiple values such as 'hs\_country\_extension' or 'special\_other' then multiple values can be assigned by specifying values separated by the 'pipe' character: |
The legacy column names `hts_base_code` and `hts_country_code` remain accepted as aliases of the canonical
`hs_base_code` and `hs_country_extension` columns, so saved import templates continue to work. If both a legacy
column and its canonical `hs_*` column are present, the canonical value wins. See the
[Harmonized System code properties](/merchant-api/product#product-properties) for field details.
```csv title="product_import_sample.csv" theme={null}
sku,name,barcode,goods_type,weight,weight_unit,length,width,height,dimension_unit,country_of_manufacture,hs_base_code,hs_country_extension,requires_packaging,can_contain_other_items,allowed_container_styles,valid_containers,disallowed_containers,special_supplies,special_other,unit_qty,backorders,dynamic_allocation,virtual_inventory
"productsku","Product Name","productbarcode","NORMAL","1.75","lb","123","100","28","in","DK","8471.30","US:0010|CA:0020",1,0,"rigid_box|pallet","containerssku1|containerssku2","containerssku3|containerssku4","suppliessku1|suppliessku2","othersku1|othersku2",5,1,2,"optimistic"
```
## Product - Standard JSON
Importing products in JSON format should follow the [product.create](/merchant-api/product#product-create) inputs exactly.
```json title="product_import_sample.json" theme={null}
{
"name" : "Product 3",
"sku" : "product-3",
"barcode" : "product3",
"goods_type" : "NORMAL",
"weight" : 1.75,
"weight_unit" : "lb",
"length" : 123,
"width" : 100,
"height" : 28,
"dimension_unit" : "in",
"country_of_manufacture" : "DK",
"hs_base_code" : "8471.30",
"hs_country_extension" : "US:0010|CA:0020",
"requires_packaging" : 1,
"can_contain_other_items" : 0,
"allowed_container_styles" : [ "rigid_box", "bubble_mailer" ],
"valid_containers" : [ "containersku1", "containersku2" ],
"disallowed_containers" : [ "containersku3", "containersku4" ],
"special_supplies" : [ "supplysku1", "supplysku2" ],
"special_other" : [ "othersku1", "othersku2" ],
"unit_qty" : 5,
"additional_regulatory_info" : "EX1995120111C",
"meets_hazmat_specs" : 1,
"backorders" : 1,
"dynamic_allocation" : 2,
"virtual_inventory" : "optimistic"
}
```
## Delivery - Standard CSV
The "id" field is only used to group multiple lines into a single delivery. If importing a single delivery it can be blank, but if importing multiple deliveries it should be unique for each separate delivery in the CSV file.
When using Delivery Imports the `merchant_ref` values must be unique to the `delivery_type` specified. i.e.: Merchant Ref supplied to three new ASNs should not match former ASNs already in the system, nor the ASNs within the upload file.
Since an import can create multiple items at once the System uses the Merchant Ref to check for duplicates. Example: Upload a file with 10 different ASNs. After importing, the System states that of the ten, five had errors and five successfully imported. Correct those five, whether that is in the file or by adding a SKU to the System, etc. With the corrections made, import the same file but have the System handle duplicates by Dropping them. This way the same file can be reused without accidentally entering a duplicate ASN. Allowing the focus to be on fixing the ASNs that failed instead of needing to also make a new file to import the ASNs.
**See [Delivery Properties](/merchant-api/delivery#delivery-properties) for the supported field names and values.**
```csv title="delivery_import_sample.csv" theme={null}
id,delivery_type,sender_name,carrier_name,expected_delivery,merchant_ref,sender_ref,sku,qty
1,asn,Bill Gates,FedEx,"2014-07-31",12345,333,product1,50
1,,,,,,,product2,100
2,asn,Bill Gates,FedEx,"2014-08-12",12346,339,product3,40
2,,,,,,,product4,200
```
## Delivery - Standard JSON
Importing deliveries in JSON format should follow the [delivery.create](/merchant-api/delivery#delivery-create) inputs exactly.
```json title="delivery_import_sample.json" theme={null}
{
"delivery_type" : "asn",
"sender_name" : "Bill Gates",
"carrier_name" : "FedEx",
"expected_delivery" : "2014-07-31",
"merchant_ref" : "12345",
"sender_ref" : "333",
"items" : [
{
"sku" : "product1",
"qty" : 5
},
{
"sku" : "product2",
"qty" : 1
}
]
}
```
## Bill of Materials - Standard CSV
The "id" field is only used to group multiple lines into a single bill of materials. If importing a single bill of materials it can be blank, but if importing multiple bills of materials it should be unique for each separate bill of materials in the CSV file.
The header row should contain all field names and each following row contains bill of materials data. Each row must specify a SKU at minimum.
**See [BOM Properties](/merchant-api/bom#bom-properties) for the supported field names and values.**
```csv title="bom_import_sample.csv" theme={null}
id,name,sku,yield_qty,is_kit_on_demand,is_kit_to_stock,assembly_instructions,priority,component_sku,component_qty
1,BOM 1,bom1,1,Yes,No,,0,component1,1
1,BOM 1,bom1,1,Yes,No,,0,component2,1
```
## Bill of Materials - Standard JSON
Importing bill of materials in JSON format should follow the [bom.create](/merchant-api/bom#bom-create) inputs exactly.
```json title="bom_import_sample.json" theme={null}
{
"id": "1",
"sku": "bom1",
"name": "BOM 1",
"yield_qty": "1",
"is_kit_on_demand": true,
"is_kit_to_stock": false,
"priority": "0",
"components": [
{
"sku": "component1",
"qty": "1"
},
{
"sku": "component2",
"qty": "1"
}
]
}
```
# Introduction
Source: https://docs.shipstream.io/merchant-api/introduction
Learn the basics of using the Merchant API.
ShipStream exposes all of its API endpoints via HTTP using the JSONRPC protocol. This page explains the general method of authenticating and calling methods. Each method is documented in detail in the additional sections in the sidebar.
See [Find Your URL](/home/find-your-url) for information on finding the correct URL to use for your ShipStream instance.
## Request Format
All requests must be POST requests with the request parameters given as a JSON-encoded string in the POST body.
The JSONRPC protocol version number. Must be "2.0".
A unique identifier for the request that will be included in the response.
The remote procedure to call. This should always be either `login` or `call`.
An array of request parameters specific to the remote procedure being called (see below for details).
## Response Format
The response will be a JSON-encoded string with the following properties:
The JSONRPC protocol version number ("2.0").
The unique identifier that matches the id given in the request.
If there is an error, this will be an object with keys `code` and `message`. See "Error Codes" for a list
of general error codes.
If an error did not occur this will contain the appropriate response data, otherwise this will be empty.
## Error Codes
| code | message | meaning |
| ------ | ---------------- | ----------------------------------------------------------------------------------------------------- |
| -32700 | Parse error | Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text. |
| -32600 | Invalid Request | The JSON sent is not a valid Request object. |
| -32601 | Method not found | The method does not exist / is not available. |
| -32602 | Invalid params | Invalid method parameter(s). |
| -32603 | Internal error | Internal JSON-RPC error. |
The error codes are easier to read if you first multiply by -1 and then subtract 32000. From this point forward, all error
codes mentioned will have this formula already applied to them, but due to the requirement of hte JSONRPC protocol, they
will be reported via the API without the formula applied.
## Calling Methods
`call(session_id, method, arguments)`
The 'call' method requires proper [authentication](/merchant-api/authentication) and is used to call all other API endpoints. These endpoints are detailed in the additional pages in the left sidebar.
### Parameters
The session ID obtained from calling `login()` or `null` if using HTTP Basic Auth. See [Authentication](/merchant-api/authentication).
The API endpoint to call. This always takes the form of `{resource}.{action}`. E.g. `order.info`
The arguments to the API endpoint. If there are no additional arguments, this parameter may be omitted.
### Return Value
The response may be any valid JSON type according to the endpoint which was called.
***
### Error Codes
| code | message |
| ---- | ------------------------------------------------------------------- |
| 2 | Access denied. |
| 3 | Invalid api path. |
| 4 | Resource path is not callable. |
| 5 | Session expired. Try to relogin. |
| ? | Other error codes may be used depending on which method was called. |
# Inventory
Source: https://docs.shipstream.io/merchant-api/inventory
ShipStream tracks each merchant's inventory at all times using the following statuses:
* **Expected** - Listed on open ASNs, RMAs and Other Deliveries that have not yet been received.
* **Processed** - Counted on an ASN, RMA or Other Delivery but not yet put-away.
* **Put-Away** - Has been received on an ASN, RMA or Other Delivery that has not yet been committed to the inventory. If you have auto-commit enabled this should always be 0.
* **Available** - Available for new orders. Backordered amounts are not reflected as a negative Available amount but are tracked separately as "Backordered".
* **Allocated** - Allocated to existing orders but not yet Reserved.
* **Reserved** - Reserved to a specific shelf location and waiting to be picked.
* **Picked** - Picked from the shelves but not yet shipped.
* **Backordered** - Reserved by existing orders but not in stock. Will be automatically converted to Reserved when stock is added. Backordered quantities are not reflected in the Available amount as a negative number.
* **Advertised** - The "Available" quantity plus the virtual BOM quantity. The virtual BOM quantity is controlled by a product's "Virtual Inventory" attribute.
* **Held** - On hand but placed on hold (quarantined, damaged, expired, recalled, etc.). Held inventory remains counted in the on-hand total but is excluded from the Available quantity and cannot be allocated, picked, or packed until the hold is released. See [inventory.holdReasons](#inventory-holdreasons) for the reasons visible to a merchant and [inventory.holdSearch](#inventory-holdsearch) to list individual holds.
Additionally, products have two flags that can be set which will affect whether or not they are retrieved in an inventory request.
* **Status** - Enabled/Disabled - If "Disabled", the product is effectively deleted and will not appear in responses to inventory requests.
* **Visibility** - Visible/Not Visible - If "Not Visible", the product will not appear in the inventory list but may still be ordered via the Merchant Panel.
## Methods
* [inventory.list](#inventory-list)
* [inventory.lots](#inventory-lots)
* [inventory.detailed](#inventory-detailed)
* [inventory.detailed\_packaging](#inventory-detailed-packaging)
* [inventory.holdSearch](#inventory-holdsearch)
* [inventory.holdReasons](#inventory-holdreasons)
***
## Entity Properties
* [Inventory Item](#inventory-item)
* [Inventory Lot](#lot-properties)
* [Inventory Hold](#inventory-hold-properties)
* [Hold Reason](#hold-reason-properties)
***
## `inventory.list`
`inventory.list (string|array|null $skus, int|null $warehouseId, string|null $updatedSince, bool $withHeldBreakdown = false)`
Get inventory levels for one or more products by SKU. If a warehouse is not specified the sum of all warehouse inventories will be returned, otherwise the inventory levels for the specified warehouse will be returned.
Each item includes a `qty_held` quantity. When `withHeldBreakdown` is `true`, each item also includes a `qty_held_by_reason` object that breaks the held quantity down by [hold reason](#inventory-holdreasons).
### Parameters
SKUs. If not specified then inventory for all SKUs will be returned.
* `string` - Get inventory for a single product by SKU.
* `array` - Get inventory for the specified products by SKU.
* `null` - Get inventory for all products.
Warehouse. If not specified, returned values represent sums of all warehouses.
Return only SKUs updated since the time specified in the format `2008-07-01T22:38:07+00:00`.
When `true`, each item is augmented with a `qty_held_by_reason` object keyed by parent (system) [hold reason](#inventory-holdreasons) code. Defaults to `false`, which preserves the legacy response shape and avoids the additional per-call rollup query.
### Return Value
An array of [Inventory Items](#inventory-item) or an empty array if there were no matching SKUs.
### Example Request
Get inventory for two SKUs:
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"inventory.list",
[
["BlueWidget-1","BlueWidget-5"]
]
]
}
```
Get all inventory:
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"inventory.list"
]
}
```
Get all inventory for warehouse "2":
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"inventory.list",
[
null,
2
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"result" : [
{
"sku" : "BlueWidget-1",
"qty_expected" : "0.0000",
"qty_processed" : "0.0000",
"qty_putaway" : "50.0000",
"qty_available" : "22.0000",
"qty_allocated" : "5.0000",
"qty_reserved" : "16.0000",
"qty_picked" : "1.0000",
"qty_held" : "4.0000",
"qty_backordered" : "0.0000",
"qty_advertised" : "22.0000",
"qty_on_hand" : "94.0000"
},
{
"sku" : "BlueWidget-5",
"qty_expected" : "40.0000",
"qty_processed" : "0.0000",
"qty_putaway" : "0.0000",
"qty_available" : "0.0000",
"qty_allocated" : "0.0000",
"qty_reserved" : "2.0000",
"qty_picked" : "0.0000",
"qty_held" : "0.0000",
"qty_backordered" : "5.0000",
"qty_advertised" : "0.0000",
"qty_on_hand" : "2.0000"
}
]
}
```
## `inventory.lots`
`inventory.lots (null|object $filters, array $options = [])`
Retrieve list of lots by filters.
### Parameters
Filters to apply for the search.
* `null` - Retrieve list of all Lots.
* `object` - Retrieve list of Lots using specified "[Search Filters](/merchant-api/search-filters)".
Options to apply for the search.
* `null` - No options will be applied.
* `object` - Apply specified "[Search Options](/merchant-api/search-options)".
### Return Value
An array of objects. Each object will contain [Lot Properties](#lot-properties).
### Example Request
```json theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"inventory.lots",
[
{
"lot_id" : {
"in" : [1, 2]
}
},
[]
]
]
}
```
### Example Response
```json theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"result" : {
"results": [
{
"lot_id": "1",
"lot_number": "2018-07-09",
"origination_date": "2018-07-09",
"expiration_date": "2019-04-07",
"is_active": "1",
"group_value": "2018-07-09",
"created_at": "2018-07-09T19:58:23+00:00",
"sku": "product1",
"name": "product 1",
"locations": [
"location 1"
],
"qty_putaway": "0.0000",
"qty_available": "66.0000",
"qty_reserved": "0.0000",
"qty_held": "10.0000",
"is_on_hold": true
},
{
"lot_id": "2",
"lot_number": "2018-07-09",
"origination_date": "2018-07-09",
"expiration_date": "2019-04-11",
"is_active": "1",
"group_value": "2018-07-09",
"created_at": "2018-07-09T19:59:03+00:00",
"sku": "product2",
"name": "product 2",
"locations": [],
"qty_putaway": "0.0000",
"qty_available": "0.0000",
"qty_reserved": "0.0000",
"qty_held": "0.0000",
"is_on_hold": false
}
],
"totalCount": 2,
"numPages": 1
}
}
```
### Error Codes
| code | message |
| ---- | ---------------------------------- |
| 102 | Unexpected error applying filters. |
## `inventory.detailed`
`inventory.detailed (string|array|null $skus, string|null $updatedSince, bool $withHeldBreakdown = false)`
Get global and per-warehouse inventory levels for one or more products by SKU.
Each item — and each per-warehouse `detailed` entry — includes a `qty_held` quantity. When `withHeldBreakdown` is `true`, each item is additionally augmented with a `qty_held_by_reason` object (held quantity grouped by parent [hold reason](#inventory-holdreasons) code) and, when user-defined sub-reasons exist, a `qty_held_by_user_reason` object that breaks each parent reason down by its user-defined child reasons. Both rollups are reported at the item level only, not per warehouse.
### Parameters
SKUs. If not specified then inventory for all SKUs will be returned.
* `string` - Get inventory for a single product by SKU.
* `array` - Get inventory for the specified products by SKU.
* `null` - Get inventory for all products.
Return only SKUs updated since the time specified in the format `2008-07-01T22:38:07+00:00`.
When `true`, each item is augmented with a `qty_held_by_reason` object and, where applicable, a `qty_held_by_user_reason` object. Defaults to `false`, which preserves the legacy response shape and avoids the additional hold rollup queries.
### Return Value
An array of detailed items inventory, or an empty array if there were no matching SKUs.
### Example Request
```json theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"inventory.detailed",
[
["BlueWidget-1","BlueWidget-5"],
"2014-07-24T18:51:18+00:00",
true
]
]
}
```
### Example Response
The example below was requested with `withHeldBreakdown` set to `true`, so each item includes the `qty_held_by_reason` (and, where user-defined sub-reasons exist, `qty_held_by_user_reason`) rollups. With the default `false`, those two fields are omitted but `qty_held` is still present on every item and warehouse entry.
```json theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"result" : [
{
"sku": "BlueWidget-1",
"qty_expected": "0.0000",
"qty_processed": "0.0000",
"qty_putaway": "0.0000",
"qty_available": "5.0000",
"qty_allocated": "0.0000",
"qty_reserved": "0.0000",
"qty_picked": "2.0000",
"qty_held": "3.0000",
"qty_backordered": "0.0000",
"qty_advertised": "5.0000",
"qty_on_hand": "10.0000",
"qty_held_by_reason": {
"damaged": "2.0000",
"qc_inspection": "1.0000"
},
"qty_held_by_user_reason": {
"qc_inspection": {
"qc_lab_review": "1.0000"
}
},
"detailed": [
{
"warehouse_id": "1",
"qty_expected": "0.0000",
"qty_processed": "0.0000",
"qty_putaway": "0.0000",
"qty_available": "5.0000",
"qty_allocated": "0.0000",
"qty_reserved": "0.0000",
"qty_picked": "2.0000",
"qty_held": "3.0000",
"qty_advertised": "5.0000",
"qty_on_hand": "10.0000"
},
{
"warehouse_id": "2",
"qty_expected": "0.0000",
"qty_processed": "0.0000",
"qty_putaway": "0.0000",
"qty_available": "0.0000",
"qty_allocated": "0.0000",
"qty_reserved": "0.0000",
"qty_picked": "0.0000",
"qty_held": "0.0000",
"qty_advertised": "0.0000",
"qty_on_hand": "0.0000"
},
{
"warehouse_id": "3",
"qty_expected": "0.0000",
"qty_processed": "0.0000",
"qty_putaway": "0.0000",
"qty_available": "0.0000",
"qty_allocated": "0.0000",
"qty_reserved": "0.0000",
"qty_picked": "0.0000",
"qty_held": "0.0000",
"qty_advertised": "0.0000",
"qty_on_hand": "0.0000"
}
]
},
{
"sku": "BlueWidget-5",
"qty_expected": "0.0000",
"qty_processed": "0.0000",
"qty_putaway": "0.0000",
"qty_available": "98.0000",
"qty_allocated": "0.0000",
"qty_reserved": "0.0000",
"qty_picked": "1.0000",
"qty_held": "0.0000",
"qty_backordered": "0.0000",
"qty_advertised": "98.0000",
"qty_on_hand": "99.0000",
"qty_held_by_reason": {},
"detailed": [
{
"warehouse_id": "1",
"qty_expected": "0.0000",
"qty_processed": "0.0000",
"qty_putaway": "0.0000",
"qty_available": "98.0000",
"qty_allocated": "0.0000",
"qty_reserved": "0.0000",
"qty_picked": "1.0000",
"qty_held": "0.0000",
"qty_advertised": "98.0000",
"qty_on_hand": "99.0000"
},
{
"warehouse_id": "2",
"qty_expected": "0.0000",
"qty_processed": "0.0000",
"qty_putaway": "0.0000",
"qty_available": "0.0000",
"qty_allocated": "0.0000",
"qty_reserved": "0.0000",
"qty_picked": "0.0000",
"qty_held": "0.0000",
"qty_advertised": "0.0000",
"qty_on_hand": "0.0000"
},
{
"warehouse_id": "3",
"qty_expected": "0.0000",
"qty_processed": "0.0000",
"qty_putaway": "0.0000",
"qty_available": "0.0000",
"qty_allocated": "0.0000",
"qty_reserved": "0.0000",
"qty_picked": "0.0000",
"qty_held": "0.0000",
"qty_advertised": "0.0000",
"qty_on_hand": "0.0000"
}
]
}
]
}
```
### Error Codes
| code | message |
| ---- | ---------------------------------- |
| 102 | Unexpected error applying filters. |
## `inventory.detailed_packaging`
`inventory.detailed_packaging (string|array|null $skus, string|null $updatedSince, bool $withHeldBreakdown = false)`
Get global and per-warehouse inventory levels for Packaging Features by SKU. This method is similar to `inventory.detailed` but returns only Packaging Feature types (Container, Supplies, and Infill) that can have inventory. Regular products and other Packaging Feature types are excluded from the results.
As with `inventory.detailed`, each item and warehouse entry includes a `qty_held` quantity, and the optional `withHeldBreakdown` parameter adds the item-level `qty_held_by_reason` (and `qty_held_by_user_reason`) rollups.
### Parameters
SKUs. If not specified then inventory for all Packaging Feature SKUs will be returned.
* `string` - Get inventory for a single Packaging Feature by SKU.
* `array` - Get inventory for the specified Packaging Features by SKU.
* `null` - Get inventory for all Packaging Features (Container, Supplies, and Infill).
Return only SKUs updated since the time specified in the format `2008-07-01T22:38:07+00:00`.
When `true`, each item is augmented with a `qty_held_by_reason` object and, where applicable, a `qty_held_by_user_reason` object. Defaults to `false`.
### Return Value
An array of detailed Packaging Feature inventory, or an empty array if there were no matching SKUs. Only Packaging Feature types (Container, Supplies, and Infill) are included in the response.
### Example Request
```json theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"inventory.detailed_packaging",
[
["PB1688","PB16816"],
"2014-07-24T18:51:18+00:00"
]
]
}
```
### Example Response
```json theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"result" : [
{
"sku": "PB1688",
"qty_expected": "50.0000",
"qty_processed": "0.0000",
"qty_putaway": "0.0000",
"qty_available": "150.0000",
"qty_allocated": "0.0000",
"qty_reserved": "0.0000",
"qty_picked": "0.0000",
"qty_held": "0.0000",
"qty_backordered": "0.0000",
"qty_advertised": "150.0000",
"qty_on_hand": "150.0000",
"detailed": [
{
"warehouse_id": "1",
"qty_expected": "50.0000",
"qty_processed": "0.0000",
"qty_putaway": "0.0000",
"qty_available": "100.0000",
"qty_allocated": "0.0000",
"qty_reserved": "0.0000",
"qty_picked": "0.0000",
"qty_held": "0.0000",
"qty_advertised": "100.0000",
"qty_on_hand": "100.0000"
},
{
"warehouse_id": "2",
"qty_expected": "0.0000",
"qty_processed": "0.0000",
"qty_putaway": "0.0000",
"qty_available": "50.0000",
"qty_allocated": "0.0000",
"qty_reserved": "0.0000",
"qty_picked": "0.0000",
"qty_held": "0.0000",
"qty_advertised": "50.0000",
"qty_on_hand": "50.0000"
}
]
},
{
"sku": "PB16816",
"qty_expected": "0.0000",
"qty_processed": "0.0000",
"qty_putaway": "0.0000",
"qty_available": "200.0000",
"qty_allocated": "0.0000",
"qty_reserved": "0.0000",
"qty_picked": "0.0000",
"qty_held": "0.0000",
"qty_backordered": "0.0000",
"qty_advertised": "200.0000",
"qty_on_hand": "200.0000",
"detailed": [
{
"warehouse_id": "1",
"qty_expected": "0.0000",
"qty_processed": "0.0000",
"qty_putaway": "0.0000",
"qty_available": "200.0000",
"qty_allocated": "0.0000",
"qty_reserved": "0.0000",
"qty_picked": "0.0000",
"qty_held": "0.0000",
"qty_advertised": "200.0000",
"qty_on_hand": "200.0000"
}
]
}
]
}
```
### Error Codes
| code | message |
| ---- | ---------------------------------- |
| 102 | Unexpected error applying filters. |
## `inventory.holdSearch`
`inventory.holdSearch (null|object $filters, array $options = [])`
Search the merchant's active and released inventory holds. Results are always scoped to the calling merchant's own inventory — no filter combination can return another merchant's holds. The response is paginated and shaped like [inventory.lots](#inventory-lots): `{ results, totalCount, numPages }`. Each result row includes structured `lot` and `reason` objects alongside the core hold fields.
For privacy, hold rows do not expose internal location identifiers or labels — including inside nested objects. The embedded `lot` object contains no location information. Identify the held inventory using `sku`, `lot.lot_number`, and `reason.code` instead.
### Parameters
Filters to apply to the search. Every key is optional, and unknown keys are rejected. Combine any of:
* `product_id` (integer) — holds on a specific product.
* `sku` (string) — holds on a specific SKU.
* `warehouse_id` (integer) — restrict to one warehouse. Must be a warehouse the merchant can access.
* `reason_code` (string) — exact [hold reason](#inventory-holdreasons) code. Matches that reason only; it does **not** roll child reasons up to their parent.
* `lot_id` (integer) — holds on a specific lot by internal lot ID.
* `lot_number` (string) — holds on a specific lot by lot number.
* `status` (string) — `active` (not yet released) or `released`.
* `held_after` (string) — only holds placed on or after this ISO 8601 timestamp.
* `held_before` (string) — only holds placed on or before this ISO 8601 timestamp.
The ambiguous `lot` filter is not supported — use `lot_id` or `lot_number`.
Pagination and sorting:
* `sort_field` (string) — `held_at` (default), `released_at`, or `hold_id`.
* `sort_dir` (string) — `asc` or `desc` (default `desc`).
* `page` (integer) — 1-based page number (default `1`).
* `limit` (integer) — page size, capped at `100` (default `50`).
### Return Value
An object with `results` (an array of [Inventory Hold](#inventory-hold-properties) objects), `totalCount`, and `numPages`.
### Example Request
Active damage holds for one SKU, newest first:
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"inventory.holdSearch",
[
{
"sku": "BlueWidget-1",
"reason_code": "damaged",
"status": "active"
},
{
"sort_field": "held_at",
"sort_dir": "desc",
"limit": 50
}
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"result" : {
"results": [
{
"hold_id": 4821,
"sku": "BlueWidget-1",
"product_name": "Blue Widget (single)",
"lot": {
"lot_id": 42,
"lot_number": "2026-03-15",
"expiration_date": "2027-03-15",
"origination_date": "2026-03-15",
"group_value": null,
"is_active": 1,
"is_expired": 0,
"created_at": "2026-03-15T08:30:00+00:00"
},
"reason": {
"code": "damaged",
"label": "Damaged",
"display_group": "Hold"
},
"qty": "2.0000",
"held_at": "2026-04-12T16:09:44+00:00",
"released_at": null,
"notes": "Crushed corner found during QC",
"status": "active"
}
],
"totalCount": 1,
"numPages": 1
}
}
```
### Error Codes
| code | message |
| ---- | --------------------------------------------------------------------------------------------- |
| 101 | The Warehouse does not exist or the Merchant does not have access to the Warehouse specified. |
| 102 | Invalid or unsupported filter, sort field, status, or date range. |
## `inventory.holdReasons`
`inventory.holdReasons()`
Retrieve the list of active inventory hold reasons that are visible to the calling merchant.
### Parameters
This method takes no parameters.
### Return Value
An array of objects, each containing the [Hold Reason Properties](#hold-reason-properties).
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"inventory.holdReasons"
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"result" : [
{ "code": "qc_inspection", "label": "QC Inspection", "display_group": "Hold" },
{ "code": "cycle_count", "label": "Cycle Count", "display_group": "Hold" },
{ "code": "damaged", "label": "Damaged", "display_group": "Hold" },
{ "code": "recalled", "label": "Recalled", "display_group": "Hold" },
{ "code": "expired", "label": "Expired", "display_group": "Hold" },
{ "code": "near_expiry", "label": "Near Expiry", "display_group": "Hold" },
{ "code": "contaminated", "label": "Contaminated", "display_group": "Hold" },
{ "code": "bond_hold", "label": "Customs/Bond Hold", "display_group": "Hold" },
{ "code": "pending_disposal", "label": "Pending Disposal", "display_group": "Hold" },
{ "code": "pending_return", "label": "Pending Return to Vendor", "display_group": "Hold" }
]
}
```
## Entity Properties
### Inventory Item
A unique identifier for a product. The SKU does appear on the packing slip. It is recommended that this be human-readable and end with a per-pack quantity to facilitate proper receiving. For example, a single blue widget may be "BlueWidget-1" and a pack of 5 blue widgets may be "BlueWidget-5". Maximum character length is 64.
The "Expected" quantity.
The "Processed" quantity.
The "Put-Away" quantity.
The "Available" quantity.
The "Allocated" quantity.
The "Reserved" quantity.
The "Picked" quantity.
The "Held" quantity — inventory placed on hold (quarantined, damaged, expired, recalled, etc.). Held inventory stays counted in `qty_on_hand` but is excluded from `qty_available` and cannot be allocated, picked, or packed until the hold is released.
The "Backordered" quantity. This quantity will not be present for single-warehouse requests since backordered amounts are not apportioned to specific warehouses.
The "Advertised" quantity. This is the "Available" quantity plus the virtual BOM quantity. The virtual BOM quantity is controlled by a product's "Virtual Inventory" attribute.
The total physical quantity currently in the warehouse, including held inventory exactly once. `qty_held` is a diagnostic subset of this total and must not be added to `qty_on_hand`; held Put-Away and Reserved quantities are already included in their corresponding lifecycle quantities.
Present only when a request is made with `withHeldBreakdown` set to `true`. An object that breaks `qty_held` down by parent (system) [hold reason](#inventory-holdreasons) code, e.g. `{ "damaged": "2.0000", "qc_inspection": "1.0000" }`. Reasons with no held quantity are omitted; an empty object means nothing is held.
Present only on `inventory.detailed` / `inventory.detailed_packaging` requests made with `withHeldBreakdown` set to `true`, and only when user-defined sub-reasons are in use. A nested object keyed by parent reason code, each mapping to its user-defined child reason codes and their held quantities, e.g. `{ "qc_inspection": { "qc_lab_review": "1.0000" } }`.
### Lot Properties
The internal lot ID.
Flag whether lot is active.
The "SKU" property.
The "Name" property.
The "Lot Number" property.
The "Expiration Date" property.
The "Origination Date" property.
The "Group Value" property.
The "Created At" property in ISO 8601 format.
A list of locations.
The "Put-Away" quantity.
The "Available" quantity.
The "Reserved" quantity.
The quantity of the lot currently on hold across all of its locations.
`true` when the lot has at least one active (unreleased) hold, otherwise `false`.
### Inventory Hold Properties
Returned by [inventory.holdSearch](#inventory-holdsearch). For privacy, hold rows do not include any location identifier or label — including inside nested objects.
The internal hold ID.
The SKU of the held product, or `null` if it cannot be resolved.
The name of the held product, or `null` if it cannot be resolved.
*Deprecated — use `lot.lot_number` instead.* The lot number of the held inventory, or `null` when the hold is not lot-specific.
*Deprecated — use `reason.code` instead.* The [hold reason](#inventory-holdreasons) code for this hold.
*Deprecated — use `reason.label` instead.* The human-readable hold reason label as configured in the merchant's account.
A subset of [Lot Properties](#lot-properties) for the held lot, or `null` when the hold is not lot-specific or the lot entity no longer exists. Contains no location information, quantity rollups, or product fields. Fields:
* `lot_id` (integer) — the internal lot ID.
* `lot_number` (string | null) — the lot number.
* `expiration_date` (string | null) — the expiration date.
* `origination_date` (string | null) — the origination date.
* `group_value` (string | null) — the group value.
* `is_active` (integer) — flag whether the lot is active.
* `is_expired` (integer) — flag whether the lot is expired (snapshot value, as last computed).
* `created_at` (string | null) — when the lot was created.
A [Hold Reason](#hold-reason-properties) object for this hold, or `null` when no reason is associated. Fields: `code`, `label`, `display_group`.
For an active Location Hold, the Location's current held quantity. This value changes as inventory enters or leaves the held Location. Released Holds and Lot-level sentinel records without a Location return `0.0000`.
When the hold was placed, in ISO 8601 format.
When the hold was released, in ISO 8601 format, or `null` if the hold is still active.
Free-text notes recorded when the hold was placed, or `null`.
`active` when `released_at` is `null`, otherwise `released`.
### Hold Reason Properties
The stable machine-readable identifier for the reason. Use this value when calling other endpoints that accept a `reason_code`.
The human-readable label for the reason as configured in the merchant's account.
The bucket the reason is grouped under in the UI. Built-in groups are `Hold`, `Review`, `Expired`, and `Unsellable`; user-defined reasons may use any text up to 25 characters.
# Order
Source: https://docs.shipstream.io/merchant-api/order
An order is a request from the merchant for an outbound shipment of the merchant's inventory. Each order is closely tracked through picking and packing all of the way to the time it is placed on the carrier's truck, even including which pallet the packages were loaded onto. When an order has begun picking it is split (if needed) into "Shipments" based on the most efficient way to meet carrier size and weight limitations. Each "shipment" therefore typically results in only one package although under some circumstances may still require more than one package.
## Methods
* [order.create](#order-create)
* [order.bulk\_create](#order-bulk_create)
* [order.edit](#order-edit)
* [order.search](#order-search)
* [order.info](#order-info)
* [order.hold](#order-hold)
* [order.unhold](#order-unhold)
* [order.cancel](#order-cancel)
* [order.comment](#order-comment)
## Entity Properties
* [Order Properties](#order-properties)
* [Order Item Properties](#order-item-properties)
* [Address Properties](#address-properties)
* [Package Properties](#package-properties)
* [Tracking Number Properties](#tracking-number-properties)
* [Status History](#status-history)
* [Serial Number Properties](#serial-number-properties)
* [Packing instruction Confirmation Properties](#packing-instruction-confirmation-properties)
* [Order Custom Field](#order-custom-field)
## Order States and Statuses
Order received and inventory reserved.
Valid statuses: `new`, `partial_backorder`, `backordered`
Shipments created and assigned to a picking batch.
Valid statuses: `processing`, `partial_backorder`
Entire order has been packaged and labeled for shipping.
Valid statuses: `complete`
Order has been canceled.
Valid statuses: `canceled`
Order is on hold.
Valid statuses: `holded`, `delayed_shipment`, `unresolved`
## `order.create`
`order.create (string|null $storeCode, object|array $items, object $address, object $info, object $flags = [])`
Create a new order. This operation will only be successful if the inventory is available and the unique\_id is unique (if specified).
### Parameters
Store code. If not specified will default to the configured default store. Merchants with multiple stores may specify which store the order belongs to.
Order Items. Three possible formats:
```json theme={null}
{ "product1's_SKU": 1, "product2's_SKU": 3 }
```
```json theme={null}
[ { "sku": "product1", "qty": 1 }, { "sku": "product2", "qty": 3 } ]
```
```json theme={null}
[ { "sku": "product1", "qty": 1, "unit_declared_value": "20.40", "unit_customs_value": "21.15" }, {...} ]
```
Shipping Address (see [Shipping Address Properties](#address-properties))
Order Additional Data (see [Order Additional Data](#order-additional-data))
Order Flags (see [Order Flags](#order-flags))
### Order Items Data
Use to specify the SKU of the item being ordered.
Use to specify the Barcode of the item being ordered as an alternative to using a SKU. The fields `sku`, `barcode`, and `vendor_sku` will be evaluated in that order, and the first matching product found will be selected.
Use to specify the Vendor SKU of the item being ordered as an alternative to using a SKU or Barcode. The fields `sku`, `barcode`, and `vendor_sku` will be evaluated in that order, and the first matching product found will be selected. As Vendor SKUs are not unique, if the value matches multiple products then an error will be thrown.
Use to specify the quantity being ordered of a particular item.
If required by your integration you may specify a reference to an external order item id.
Specify a declared unit value. Specifying the unit declared value is preferred over specifying only the entire order declared value so that an accurate amount can be computed for partial fulfillments. If a value is specified for an order item, then `"declared_value_service": true` will need to be sent in with the \$info object section.
Specify the declared unit value currency. Must be a valid ISO 4217 alphabetic code.
Specify a customs unit value. Specifying the unit customs value is preferred over specifying only the entire order customs value so that an accurate amount can be computed for partial fulfillments.
Specify the customs unit value currency. Must be a valid ISO 4217 alphabetic code.
The number of eaches per inner container. Must be a positive whole number. If no BOM is found, individual units will be added.
The number of inner containers, or number of eaches if there are no inner containers, per outer container. Must be a positive whole number. If no BOM is found, individual units will be added.
### Order Additional Data
This field is optional and if not specified an auto-incrementing number will be assigned. Uniqueness based on this field is enforced so an error will be given if an order with the same unique\_id already exists. This 'unique\_id' is the id used for other API calls such as "order.info".
This field is optional and if not specified will be left blank. Uniqueness based on this field is not enforced (two orders may have the same order\_ref value). If specified, this number will appear on packing slips in place of the unique\_id.
See the [Shipping Methods](/merchant-api/shipping-methods) document for a reference. Is not optional.
If specified will override the configured Packing Slip default greeting. Allowing the addition of a Packing Slip Custom Greeting.
The "Note" adds a status history to the order that only you and the warehouse staff may see. Adding a note will not affect the way the order is picked and packed and is not required.
Values can be `none`, `any`, `adult`, `indirect`*, or `default`*.
\*Supported by FedEx.
* `none` — No signature requirement.
* `any` — The package(s) will be shipped with the "Direct" signature required (recipient of any age).
* `adult` — The package(s) will be shipped with the Adult Signature Required option (21 years or older).
* `indirect` — The package(s) will be shipped with the `indirect` signature required (If `indirect` is not supported by the carrier, this option will fall back to `any`).
* `default` — May be used to defer to the default based on the carrier service type (If `default` is not supported by the carrier, this option will fall back to `none`).
If the signature requirement is not specified it will fall back to `default` for HazMat orders or `none` for all others.
Saturday delivery option. If not specified will default to 'false'.
Reason for export. Values can be `sold`, `not_sold`, `gift`, `sample`, `repair_return`, `personal_effects`. If not specified will default to `sold`. Only applicable to international orders.
If 'true' then the order or the package(s) will be shipped with declared\_value\_service requested. Only the unit\_declared\_value must be specified for at least one SKU or declared\_value for the order, but not both. If not specified will default to 'false'.
Needs to be set if `"declared_value_service": true` and `"unit_declared_value"` is not set on any individual product SKU being ordered. e.g. `"declared_value": "40.50"`
The currency of `declared_value`. Must be a valid ISO 4217 alphabetic code.
Only the unit\_customs\_value must be specified for at least one SKU or customs\_value for the order, but not both. e.g. `"customs_value": "30.25"`
The currency of `customs_value`. Must be a valid ISO 4217 alphabetic code.
Request overbox option. If not specified will default to 'false'.
If specified, sets this order's backorder policy. Order will use specified policy instead of store's default policy. Values can be `default`, `all_or_nothing`, `as_available`, or `up_to_X`. If not specified will default to `"default"`.
* `all_or_nothing` - Accept order but do not ship anything until all items are in stock.
* `as_available` - No limit to number or frequency of additional shipments.
* `up_to_X` shipments - Same as "As Available", but changes to All or Nothing before shipping Xth shipment.
When using `up_to_X`, "X" represent a positive integer number. Example: ` { "backorder_policy": "up_to_3" }`
If specified, sets this order's priority. Setting the priority will boost or suppress this order's priority in relation to other orders for the same products. Valid input are values in the range `0 -100`. Lower numbers are higher in priority. If not specified will default to `50`.
If specified, the requested ship date will determine if the merchant wishes for the item to be shipped on the same day or not. Whether or not this date becomes the Target Ship Date depends on the merchant's target ship date cutoff time and the time the order is placed. Format: `YYYY-MM-DD`
Required for the Cheapest On-Time shipping method. Format: `YYYY-MM-DD`
If specified, the order will be placed in "hold" status until this date and time. May be specified as a date or a date and time. The timezone is assumed to be the global default timezone if not specified. If a time is not specified it is assumed to be 00:00:00 (12:00 am). Format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss` or `YYYY-MM-DDThh:mm:ssZ`
If specified, the order will be placed in "hold" status indefinitely (cannot be used with `delayed_ship_date`).
The ID number of a [Third Party Billing Account Group](/merchant-api/third-party-billing-group). If unset or `null`, and a default group is configured, the default group will be used. Set to `0` to disable third party billing.
Duties Payor. Values can be `default`, `shipper`, `recipient`, `third_party`. If not specified will default to `default`. Only applicable to international orders.
The ID number of a [Duties Payor Third Party Billing Account Group](/merchant-api/third-party-billing-group). Only applicable to `third_party` duties payor.
Array of packing instructions. See [Packing Instruction](#packing-instructions).
Generate Serial Shipping Container Codes option. Array with elements 'pack' and/or 'item'. If not specified will default to an empty array.
Object with Custom Fields. See [Order Custom Field](#order-custom-field).
Links the order to a [Retailer](/merchant-api/retailer) by its code. When set, the retailer's configured order defaults (duties payor, third-party-billing groups, shipping method) fill any of those fields left unset.
Identifies the retailer ship-to location this order is destined for by its `(qualifier, code)` pair. Requires `retailer_code`. On a match the existing location is linked. On a miss, a `drop_ship`/`mixed` retailer proceeds with no link, while a `wholesale` retailer either auto-creates the location (when the `retailer_ship_to_location_create` flag is set) or is rejected.
The ship-to location code.
The canonical qualifier scheme for the code (for example `gln` or `buyer_location`). See the [Retailer Ship-To Location](/merchant-api/retailer#retailer-ship-to-location-properties) allowed values.
Optional display label applied when a location is auto-created.
Optional location type applied when a location is auto-created. Allowed values: `dc`, `store`, `drop_ship`, `other`.
### Order Flags
Values can be `true`, `false`, a PHP strtotime string indicating the oldest date to consider. e.g. `-3 days`.
* `true` — Must be unique across all orders.
* `false` — Uniqueness is not required. (default - current behavior).
* `-3 days` — Must be unique across all orders created for the last three days.
If not specified it will fall back to `false`.
When `true`, a wholesale retailer's `retailer_ship_to_location` that does not match an existing location is created from the order's shipping address inside the order transaction and linked. When `false` (default), an unmatched wholesale ship-to is rejected. Only applies to `wholesale` retailers.
### Return Value
An object with the new order's [Order Properties](#order-properties).
### Example Request
Create new order:
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"order.create",
[
"mystorecode",
[
{
"sku": "product2",
"qty": 5,
"order_item_ref": "ref_12356-409821"
}
],
{
"firstname" : "Davi",
"lastname" : "Demir",
"company" : "Demir Enterprises",
"street1" : "11 Times Square",
"city" : "New York",
"region" : "NY",
"postcode" : "10036",
"country" : "US",
"telephone" : "212.245.2100"
},
{
"order_ref" : "12345",
"shipping_method" : "ups_03",
"custom_greeting" : "Greeting text here",
"note" : "Note text here",
"signature_required" : "none",
"saturday_delivery" : false,
"declared_value_service" : false,
"overbox" : false,
"delayed_ship_date" : "2022-07-28",
"duties_payor" : "third_party",
"duties_tpb_group_id" : "1",
"custom_fields" : {"colors": [{"id" : 6}]}
}
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : {
"order_id" : 117,
"unique_id" : "100000017",
...
}
}
```
### Error Codes
| code | message |
| ---- | ----------------------------------------------- |
| 102 | Invalid data given. Details in error message. |
| 104 | An order with the specified ID already exists. |
| 106 | Invalid script given. Details in error message. |
| 107 | Product does not exist. |
***
## `order.bulk_create`
`order.bulk_create (object $orders)`
Create multiple new orders in a single request. This method is significantly faster than submitting orders one at a time. If an error occurs while processing an order, processing will continue with the next order.
### Parameters
An object with keys providing a reference for each order, which will be used in the response, and values which are an array of arguments as accepted by the [order.create](#ordercreate) endpoint.
```javascript theme={null}
{
"mykey1": [ /* First order arguments */ ],
"mykey2": [ /* Second order arguments */ ],
"mykey3": [ /* Etc */ ]
}
```
### Return Value
An object with the new order's [Order Properties](#order-properties).
### Example Request
Create new orders:
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
null,
"order.bulk_create",
[
{
"mykey1" : [
"mystorecode",
[
{
"sku": "product2",
"qty": 5,
"order_item_ref": "ref_12356-409821"
}
],
{
"firstname" : "Davi",
"lastname" : "Demir",
"company" : "Demir Enterprises",
"street1" : "11 Times Square",
"city" : "New York",
"region" : "NY",
"postcode" : "10036",
"country" : "US",
"telephone" : "212.245.2100"
},
{
"order_ref" : "12345",
"shipping_method" : "ups_03",
"custom_greeting" : "Greeting text here",
"note" : "Note text here",
"signature_required" : "none",
"saturday_delivery" : false,
"declared_value_service" : false,
"overbox" : false,
"delayed_ship_date" : "2022-07-28",
"duties_payor" : "third_party",
"duties_tpb_group_id" : "1",
"custom_fields" : {"colors": [{"id" : 6}]}
}
],
"mykey2" : [
"myotherstorecode",
[
{
"sku": "product1",
"qty": 5
}
],
{
"firstname" : "John",
"lastname" : "Smith",
"street1" : "220 Pleasant Valley Way",
"city" : "West Orange",
"region" : "NJ",
"postcode" : "07052",
"country" : "US",
"telephone" : "212.290.3822"
},
{
"unique_id" : "12345",
"shipping_method" : "cheapest_ALL"
}
]
}
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : {
"mykey1" : {
"order_id" : 117,
"unique_id" : "100000017",
"order_ref" : null,
"status" : "new"
},
"mykey2" : {
"error" : {
"code" : -32104,
"message" : "An order with the specified ID already exists."
}
}
}
}
```
### Error Codes
The error codes returned for specific orders are the same as those return by the [order.create](#error-codes) endpoint.
| code | message |
| ---- | --------------------------------------------- |
| 102 | Invalid data given. Details in error message. |
***
## `order.edit`
`order.edit (string $orderUniqueId, object $address, object $info, object $customFields)`
Modify the Shipping Address and/or the Order Additional Data for the existing order.
### Parameters
Order unique ID.
Shipping Address (see [Address Properties](#address-properties))
Order Additional Data (see [Order Additional Data](#order-additional-data))
Order Custom Field Operations (see [Order Custom Field Operations](#order-custom-field-operations))
### Order Custom Field Operations
An object with an operation name as the key and an object containing the [Order Custom Field](#order-custom-field) data for all operations except the `remove` operation. The `remove` operation only requires a list of custom field codes.
Allowed operations: `set`, `add`, `remove`, `add_option`, `remove_option`.
* `set` - Replace all values.
* `add` - Add new fields to existing, replace old values.
* `remove` - Remove only fields specified.
* `add_option` - Multi-selects only. Add an option without unsetting existing options.
* `remove_option` - Multi-selects only. Remove an option without unsetting other options not listed.
### Return Value
An object with the updated order's [Order Properties](#order-properties).
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"order.edit",
[
"100000309",
{
"firstname" : "Davi",
"lastname" : "Demir"
},
{
"shipping_method" : "ups_03"
},
{
"add" : {
"cost_of_goods" : { "amount" : 100 },
"colors" : [ { "id" : 6 } ]
}
}
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : {
"order_id" : 118,
"unique_id" : "100000309",
...,
"custom_fields" : {
"cost_of_goods" : { "amount" : 100 },
"colors" : [
{
"id" : 12,
"label" : "Red"
}
]
}
}
}
```
### Error Codes
| code | message |
| ---- | --------------------------------------------- |
| 102 | Invalid data given. Details in error message. |
| 105 | The order cannot be edited. |
***
## `order.search`
`order.search (null|object $filters, array $options = [], null|string|object $fields = [])`
Retrieve list of orders by filters. Order data can be customized by specifying properties to retrieve.
### Parameters
Filters to apply for the search.
* `null` - Retrieve list of all orders.
* `object` - Retrieve list of orders using specified [Search Filters](/merchant-api/search-filters).
Options to apply for the search.
* `null` - No options will be applied.
* `object` - Apply specified [Search Options](/merchant-api/search-options).
Specify which fields should be included in the response.
* `null` - Retrieve only "order\_id", "unique\_id", and "order\_ref" properties.
* `string` - The string `'*'` denotes all properties **excluding** "shipping\_address", "items", "shipments", "tracking\_numbers", "packages", "status\_history", and "serial\_number\_data".
* `object` - List of properties to retrieve in addition to "order\_id", "unique\_id", and "order\_ref". List may include '\*'.
Example:
```json theme={null}
["*", "shipping_address"]
```
See [Order Properties](#order-properties).
### Return Value
An object containing:
* `results` - The matching records as an array of objects. Each object will contain the specified (or default if no fields parameter was given) [Order Properties](#order-properties).
* `totalCount` - The total number of records that match the query - this may be more than the number of records returned.
* `numPages` - The number of pages of records with the given page size.
### Example Request
Get order status and order items for two order ids:
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"order.search",
[
{
"order_id" : {
"in" : [
114,
115
]
}
},
null,
[
"status",
"items"
]
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result": {
"results" : [
{
"order_id" : 114,
"unique_id" : "100000114",
"order_ref" : null,
"status" : "processing",
"items" : [
{
"sku" : "product2",
"name" : "product2",
"qty_ordered": "1.0000",
"qty_backordered": "0.0000",
"qty_canceled": "0.0000",
"qty_processing": "0.0000",
"qty_shipped": "1.0000",
"unit_declared_value": null,
"unit_declared_value_currency": "USD",
"unit_customs_value": null,
"unit_customs_value_currency": "USD",
"weight": "5.800000",
"row_weight": "5.800000",
"package_data": [
{ "label": "Serial Number - 8 Characters", "value": "12345ABC" }
],
"allocation_data": [
{ "warehouse_id": "2", "qty_allocated": "0.0000" }
],
"order_item_id": "214",
"order_item_ref": null,
"weight_unit": "lb",
"row_weight_unit": "lb"
},
{
"sku" : "product1",
"name" : "product1",
"qty_ordered": "1.0000",
"qty_backordered": "0.0000",
"qty_canceled": "0.0000",
"qty_processing": "0.0000",
"qty_shipped": "0.0000",
"unit_declared_value": null,
"unit_declared_value_currency": "USD",
"unit_customs_value": null,
"unit_customs_value_currency": "USD",
"weight": "5.800000",
"row_weight": "5.800000",
"allocation_data": [
{ "warehouse_id": "2", "qty_allocated": "1.0000" }
],
"order_item_id": "215",
"order_item_ref": null,
"weight_unit": "lb",
"row_weight_unit": "lb"
}
]
},
{
"order_id" : 115,
"unique_id" : "100000116",
"order_ref" : null,
"status" : "backordered",
"items" : [
{
"sku" : "product1",
"name" : "product1",
"qty_ordered": "2.0000",
"qty_backordered": "0.0000",
"qty_canceled": "0.0000",
"qty_processing": "0.0000",
"qty_shipped": "0.0000",
"unit_declared_value": null,
"unit_declared_value_currency": "USD",
"unit_customs_value": null,
"unit_customs_value_currency": "USD",
"weight": "5.800000",
"row_weight": "11.600000",
"allocation_data": [
{ "warehouse_id": "2", "qty_allocated": "2.0000" }
],
"order_item_id": "230",
"order_item_ref": null,
"weight_unit": "lb",
"row_weight_unit": "lb"
},
{
"sku" : "product3",
"name" : "product3",
"qty_ordered": "7.0000",
"qty_backordered": "1.0000",
"qty_canceled": "0.0000",
"qty_processing": "0.0000",
"qty_shipped": "0.0000",
"unit_declared_value": null,
"unit_declared_value_currency": "USD",
"unit_customs_value": null,
"unit_customs_value_currency": "USD",
"weight": "0.200000",
"row_weight": "1.400000",
"allocation_data": [
{ "warehouse_id": "1", "qty_allocated": "2.0000" },
{ "warehouse_id": "2", "qty_allocated": "4.0000" }
],
"order_item_id": "232",
"order_item_ref": null,
"weight_unit": "lb",
"row_weight_unit": "lb"
}
]
}
],
"totalCount": 2,
"numPages": 1
},
"jsonrpc" : 2.0,
"id" : 1234
}
```
### Error Codes
| code | message |
| ---- | ------------------------------------------------ |
| 101 | Invalid filters given. Details in error message. |
***
## `order.info`
`order.info(string $orderUniqueId, null|string|object $fields = [])`
Retrieve full order information.
### Parameters
Order unique ID.
Specify which fields should be included in the response.
* `null` - Retrieve only "order\_id", "unique\_id", and "order\_ref" properties.
* `string` - The string `'*'` denotes all properties **excluding** "shipping\_address", "items", "shipments", "tracking\_numbers", and "status\_history".
* `object` - List of properties to retrieve in addition to "order\_id", "unique\_id", and "order\_ref". List may include '\*'.
Example:
```json theme={null}
["*", "shipping_address"]
```
See [Order Properties](#order-properties).
### Return Value
Object which contains the specified (or default if no fields parameter was given) [Order Properties](#order-properties).
### Example Request
Get order information for the specified order:
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"order.info",
[
"100000114",
[
"status",
"items"
]
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : {
"order_id" : 114,
"unique_id" : "100000114",
"order_ref" : null,
"status" : "picking",
"items" : [
{
"sku" : "product2",
"name" : "product2",
"weight" : 12.0000,
"weight_unit" : "lb",
"row_weight" : 12.0000,
"row_weight_unit" : "lb",
"qty_ordered" : 12.0000,
"qty_processing" : 1.0000,
"qty_shipped" : 0.0000,
"qty_canceled" : 0.0000,
"qty_backordered" : 11.0000,
"package_data" : [
{"label" : "Serial Number - 8 Characters", "value" : "55285368"},
{"label" : "Serial Number - 8 Characters", "value" : "55285368"}
]
},
{
"sku" : "product1",
"name" : "product1",
"weight" : 1.2300,
"weight_unit" : "lb",
"row_weight" : 1.2300,
"row_weight_unit" : "lb",
"qty_ordered" : 12.0000,
"qty_processing" : 1.0000,
"qty_shipped" : 0.0000,
"qty_canceled" : 0.0000,
"qty_backordered" : 11.0000,
"package_data" : [
{"label" : "Serial Number - 8 Characters", "value" : "55285368"},
{"label" : "Serial Number - 8 Characters", "value" : "55285368"}
]
}
]
}
}
```
### Error Codes
| code | message |
| ---- | ------------------------------- |
| 100 | Requested order does not exist. |
***
## `order.hold`
`order.hold(string $orderUniqueId)`
Hold an existing order. This operation will only be successful if the order exists and can be holded.
### Parameters
Order unique ID.
### Return Value
`true` if the order was holded.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"order.hold",
[
"100000112"
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : true
}
```
### Error Codes
| code | message |
| ---- | --------------------------------------------------- |
| 100 | Requested order does not exist. |
| 103 | Order status not changed. Details in error message. |
***
## `order.unhold`
`order.unhold(string $orderUniqueId)`
Unhold an existing order. This operation will only be successful if the order exists and can be unholded.
### Parameters
Order unique ID.
### Return Value
`true` if the order was unholded.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"order.unhold",
[
"100000112"
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : true
}
```
### Error Codes
| code | message |
| ---- | --------------------------------------------------- |
| 100 | Requested order does not exist. |
| 103 | Order status not changed. Details in error message. |
***
## `order.cancel`
`order.cancel (string $uniqueOrderId, array $options, null|string|object $fields = [])`
Cancel an existing order. This operation will only be successful if the order exists, and at least one of the cancellation options is permitted for the order's current status and the store configuration.
### Parameters
Order unique ID
A list of the following properties, at least one of which must be set to `true`.
* `backordered_items` - If the order has back ordered items, attempt to cancel them. If all items on the order are back ordered, then the entire order will be canceled.
* `unfulfilled_items` - If the order has unfulfilled items, attempt to cancel them. If all items on the order are unfulfilled, then the entire order will be canceled. An unfulfilled item is an item that has not yet been added to a shipment for picking, including backordered items.
* `all_items` - Attempt to cancel the entire order. If the order state is `processing` or `complete` then you will only be able to cancel the order if the store configuration allows it. If any items on the order have been fulfilled, then you must also set `cancellation_request` to `true`.
* `cancellation_request` - If the `all_items` option is not available, you can use this option send a cancellation request instead.
Example:
```json theme={null}
{
"backordered_items" : true,
"unfulfilled_items" : false,
"all_items" : false,
"cancellation_request" : false
}
```
Specify which fields should be included in the order object returned in the response.
* `null` - Retrieve only "order\_id", "unique\_id", and "order\_ref" properties.
* `string` - The string `'*'` denotes all properties excluding "shipping\_address", "items", "tracking\_numbers" and "status\_history".
* `object` - List of properties to retrieve in addition to "order\_id", "unique\_id", and "order\_ref". List may include '\*'.
Example:
```json theme={null}
["*", "shipping_address"]
```
See [Order Properties](#order-properties).
### Return Value
An object containing the following properties:
* `success` - If at least one of the cancellation options was successful, the value will be `true`
* `warnings` - An array of warning messages
* `order` - Contains the specified (or default if no fields parameter was given) [Order Properties](#order-properties).
### Example Request
Attempt to cancel all items on an order:
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"order.cancel",
[
"100000114",
{
"all_items": true
}
],
["status", "items"]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : {
"success": false,
"warnings": [
"Order contains fulfilled items, please set the \"cancellation_request\" option to \"true\" and try again"
],
"order": {
"order_id" : 114,
"unique_id" : "100000114",
"order_ref" : null,
"status" : "complete",
"items" : [
{
"sku" : "product2",
"name" : "product2",
"weight" : 12.0000,
"weight_unit" : "lb",
"row_weight" : 12.0000,
"row_weight_unit" : "lb",
"qty_ordered" : 12.0000,
"qty_processing" : 0.0000,
"qty_shipped" : 12.0000,
"qty_canceled" : 0.0000,
"qty_backordered" : 0.0000,
"package_data" : [
{"label" : "Serial Number - 8 Characters", "value" : "55285368"},
{"label" : "Serial Number - 8 Characters", "value" : "55285368"}
],
"lot_data": [
{"lot_number": "83CCC2", "expiration_date": "2021-10-25", "origination_date": "2019-01-23", "qty": "12.0000"}
]
}
]
}
}
}
```
### Error Codes
| code | message |
| ---- | --------------------------------------------------- |
| 100 | Requested order does not exist. |
| 102 | Invalid data given. Details in error message. |
| 103 | Order status not changed. Details in error message. |
***
## `order.comment`
`order.comment(string $orderUniqueId, string $comment)`
Add a comment to an order's history.
*This method was added in version 2021.6.*
### Parameters
Order unique ID.
Comment.
### Return Value
`true` if the comment was added.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"order.comment",
[
"100000112",
"Called customer and confirmed address."
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : true
}
```
### Error Codes
| code | message |
| ---- | -------------------------------------------------- |
| 100 | Requested order does not exist. |
| 102 | Invalid data given. Details in error message. |
| 103 | Order comment not added. Details in error message. |
***
## Entity Properties
### Order Properties
The internal order ID.
The unique id for the order. This will be auto-assigned if not specified by the merchant at order creation time. This "unique\_id" is the ID used for other API calls such as "order.info".
An optional merchant-supplied reference for the order. Not a unique identifier.
State
Valid Order Statuses:
| UI Label | Code |
| :------------------------- | :------------------ |
| Backordered | `backordered` |
| Canceled | `canceled` |
| Complete | `complete` |
| Scheduled Hold | `delayed_shipment` |
| On Hold | `holded` |
| Invalid Address | `invalid_address` |
| New | `new` |
| Partial Backorder | `partial_backorder` |
| Processing | `processing` |
| Unable To Process | `unable_to_process` |
| Unresolved Shipping Method | `unresolved` |
Store Code
Store Name
Carrier Code
Shipping Description
Shipping Description
Flag to identify whether carrier was changed.
Flag to identify whether address was modified.
Flag to identify whether address was modified automatically.
Weight
The unit of measure used for `weight`. See: [Weight Units](/merchant-api/units-of-measure#weight).
Amount of order items.
Remote IP address used to submit the order
User-friendly description of method order was submitted.
Type of source used to submit the order (admin, client or api).
The ID of the user that submitted the order.
Flag to identify whether signature is required.
Flag to identify saturday delivery.
Reason for export. Values can be `sold`, `not_sold`, `gift`, `sample`, `repair_return`, `personal_effects`. If not specified will default to `sold`. Only applicable to international orders.
Flag to identify overbox.
This order's backorder policy. Order will use specified policy instead of store's default policy. Values can be `default`, `all_or_nothing`, `as_available`, or `up_to_X`. Default value is `default`.
* `all_or_nothing` - Accept order but do not ship anything until all items are in stock.
* `as_available` - No limit to number or frequency of additional shipments.
* `up_to_X` shipments - Same as "As Available", but changes to All or Nothing before shipping Xth shipment.
When using `up_to_X`, "X" represent a positive integer number. Example: ` { "backorder_policy": "up_to_3" }`
This order's priority. Setting the priority will boost or suppress this order's priority in relation to other orders for the same products. Valid input are values in the range `0 -100`. The default value is `50`. Lower numbers are higher in priority.
Estimated number of packages.
Date when the order was requested to be shipped.
Custom greeting message if specified during order creation.
Order declared value. Only the order declared value or order item unit declared value may be specified, but not both.
Order declared value currency. Must be a valid ISO 4217 alphabetic code.
The ID number of a [Third Party Billing Account Group](/merchant-api/third-party-billing-group). If unset or `null`, and a default group is configured, then the default group will be used. Set to `0` to disable third party billing.
Duties Payor. Values can be `default`, `shipper`, `recipient`, `third_party`. If not specified will default to `default`. Only applicable to international orders.
The ID number of a [Duties Payor Third Party Billing Account Group](/merchant-api/third-party-billing-group). Only applicable to `third_party` duties payor.
The internal ID of the linked B2B [Retailer](/merchant-api/retailer), or `null`. Makes the link visible without loading the retailer.
The linked [Retailer](/merchant-api/retailer), or `null`. Excluded from `order.search` results by default; request it explicitly via the `fields` parameter.
The internal retailer ID.
The retailer code.
The retailer name.
The internal ID of the linked [Retailer Ship-To Location](/merchant-api/retailer#retailer-ship-to-location-properties), or `null`. Makes the link visible without loading the location.
The linked retailer ship-to location, or `null`. Excluded from `order.search` results by default; request it explicitly via the `fields` parameter.
The internal ship-to location ID.
The canonical qualifier scheme for the code. See the [Retailer Ship-To Location](/merchant-api/retailer#retailer-ship-to-location-properties) allowed values.
The ship-to location code.
Optional display label.
Location type. One of `dc`, `store`, `drop_ship`, `other`.
Date and time when the order was created in ISO 8601 format.
Date and time when the order was updated in ISO 8601 format.
Date and time when the order was completed in ISO 8601 format.
Date and time when the order was completely shipped from the warehouse in ISO 8601 format.
Date and time when the order was completely delivered in ISO 8601 format.
The shipping address. See [Shipping Address Properties](#address-properties).
Array of order items. See [Order Item Properties](#order-item-properties).
Array of shipments. Only the "shipment\_id" and the "status" fields are present in the Order API. Use the [Shipment](/merchant-api/shipment) API to retrieve full shipment details.
Array of tracking numbers. See [Tracking Number Properties](#tracking-number-properties). *This property is deprecated - please use "packages" instead).*
Array of packages. See [Package Properties](#package-properties).
Array of history statuses. See [Status History](#status-history).
Array of serial numbers. See [Serial Number Properties](#serial-number-properties).
### Packing Instructions
Packing Instructions are presented to the packer in a dialog that must be confirmed. If a file is attached, the file will be printed using the specified printer type the appropriate number of times depending on the "presentation". The file must be in PDF format, and for best results it is recommended for the paper size to match the printer target type. If the print target is a `LABEL` printer and the page size is not 4 inches in either dimension, the system will attempt to extract an image from the file or otherwise crop the page which may not always have good results.
The "Note" property. This is required.
The name to be given to the file attached using the "file\_content" or "file\_request" properties.
The base64-encoded contents of the file. If specified you must also provide a "file\_name".
Attach a file using a url instead of `file_content`. The file will be downloaded using the optional `auth` and `headers` if specified. The `file_name` will be used if specified, but is optional and will otherwise be set using the `Content-Disposition` header value or the last part of the url.
The "Presentation" property. Values can be `once_per_order`, `once_per_shipment`, or `once_per_package`.
The "Print Target" property. Values can be `LABEL`, `SMALL_LABEL`, or `LASER`.
The "copies\_printed" property.
The instruction confirmations. See [Packing instruction Confirmation Properties](#packing-instruction-confirmation-properties).
#### Single Instruction Example:
```json theme={null}
"instructions": [
{
"note" : "Place Amazon FBA Label in a pouch",
"file_name" : "amazon_fba_3425232.pdf",
"file_content" : "base64-encoded file contents",
"presentation" : "once_per_shipment",
"print_target" : "LABEL",
"copies_printed" : "1",
"confirmations" : [
{
"confirmed_id" : "1",
"confirmed_at": "2022-02-08T14:59:38+00:00"
}
]
}
]
```
#### Multiple Instructions example:
```json theme={null}
"instructions": [
{
"note" : "Place Amazon FBA Label in a pouch",
"file_name" : "amazon_fba_3425232.pdf",
"file_content" : "base64-encoded file contents",
"presentation" : "once_per_shipment",
"print_target" : "LABEL",
"copies_printed" : "1",
"confirmations" : [
{
"confirmed_id" : "1",
"confirmed_at": "2022-02-08T14:59:38+00:00"
}
]
},
{
"note" : "Place Flier in Package",
"file_name" : "flier_3425232.pdf",
"file_request" : {
"url": "https://....",
"auth": ["username...","password..."],
"headers": {
"X-Custom-Header": "header value..."
}
},
"presentation" : "once_per_package",
"print_target" : "LASER",
"copies_printed" : "1",
"confirmations" : []
}
]
```
#### Full `order.create` Example:
```json theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"order.create",
[
"rsf",
[
{
"sku": "product2",
"qty": 5,
"order_item_ref": "ref_12356-409821"
}
],
{
"firstname" : "Davi",
"lastname" : "Demir",
"company" : "Demir Enterprises",
"street1" : "11 Times Square",
"city" : "New York",
"region" : "NY",
"postcode" : "10036",
"country" : "US",
"telephone" : "212.245.2100"
},
{
"order_ref" : "12345",
"shipping_method" : "ups_03",
"custom_greeting" : "Greeting text here",
"note" : "Note text here",
"signature_required" : "none",
"saturday_delivery" : false,
"declared_value_service" : false,
"overbox" : false,
"requested_ship_date" : "2014-07-28",
"instructions" : [
{
"note" : "Place Amazon FBA Label in a pouch",
"file_name" : "amazon_fba_3425232.pdf",
"file_content" : "base64-encoded file contents",
"presentation" : "once_per_shipment",
"print_target" : "LABEL"
},
{
"note" : "Place extra padding between products and around edges.",
"presentation" : "once_per_package"
}
]
}
]
]
}
```
### Order Item Properties
The "Order Item ID" is a unique identifier for the order item.
The "Order Item Ref" is an optional user-supplied value for the order item.
The "SKU" property.
The "Name" property.
The "Weight" property.
The unit of measure used for `weight`. See: [Weight Units](/merchant-api/units-of-measure#weight).
Total order item weight.
The unit of measure used for `row_weight`. See: [Weight Units](/merchant-api/units-of-measure#weight).
Amount of ordered products.
Amount of processing products.
Amount of shipped products.
Amount of canceled products.
Amount of backordered products.
The allocation quantity for each warehouse.
The "Package Data" property.
The "Lot Data" property.
### Address Properties
The "First Name" property.
The "Last Name" property.
The "Company" property.
The street address. Multi-line street addresses will be separated by a newline ("\n") character. Only two address lines are supported.
The "City" property.
The "Region" property.
The "Postal Code" property. Pass as a string to prevent leading 0s from being dropped.
The "Country" property.
The "Classification" property. Allowed: "res" - residential, "com" - commercial, "po" - post office, "mil" - military, "unk" - unknown.
Flag whether address is valid. If order is created with "1" the address verification will be skipped.
The "Telephone" property.
The "Email" property.
### Package Properties
The ID of the warehouse associated with the package.
The "Status" property. Allowed values: packing, tracking\_required, packed, manifested, shipped, delivered.
The "Shipment ID" property. This number may appear on the packing slip as the "Packing Slip #" and is used for the Shipment API calls.
The "Shipment Status" property. Allowed values: new, picking, picked, packing, packed, shipped, canceled, voided.
Carrier code.
Manifest courier code.
Manifest courier name.
The date and time when the package was created in ISO 8601 format.
Date and time when the package was shipped from the warehouse in ISO 8601 format.
Date and time when the package was delivered in ISO 8601 format.
The weight of the package.
The unit of measure used for `weight`. See: [Weight Units](/merchant-api/units-of-measure#weight).
The billable weight of the package.
The unit of measure used for `billable_weight`. See: [Weight Units](/merchant-api/units-of-measure#weight).
The dimensional weight divisor of the package.
The dimensional weight divisor unit. See: [Dimensional Divisor Units](/merchant-api/units-of-measure#dimensional-divisor).
The dimensional weight of the package.
The unit of measure used for `dimensional_weight`. See: [Weight Units](/merchant-api/units-of-measure#weight).
The `length`, `width`, and `height` of the package.
The unit of measure used for `length`, `width`, and `height` in `dimensions`. See: [Length Units](/merchant-api/units-of-measure#length).
The Serial Shipping Container Code.
An array of tracking objects. The "number" property contains the tracking number. The "description" property contains the shipping method name. The "track\_url" property will contain a URL to the carrier's tracking page if applicable.
An array of order items contained in the package. These items may be different from those in "package\_items" if the order was fulfilled using a Bill of Materials. "order\_item\_id" is the unqiue identifier for the order item. "order\_item\_ref" is an optional user supplied reference for the order item. "sku" is the order item's SKU. "quantity" is the quantity of the order item in the package.
An array of items contained in the package. These items may be different from those in "order\_items" if the order was fulfilled using a Bill of Materials. "order\_item\_id" is the unqiue identifier of the related order item. "sku" is the package item's SKU. "quantity" is the quantity of the item in the package.
The "Package Data" property.
### Tracking Number Properties
*This entity is deprecated, please use [Package](#package-properties) instead.*
The "Shipment ID" property. This number may appear on the packing slip as the "Packing Slip #" and is used for the Shipment API calls.
Carrier code.
The carrier name.
The method description (without the carrier name).
Tracking number.
The date and time when the shipping label was created in ISO 8601 format.
SKUs and quantities of the related package items.
### Status History
The "Status" property.
The "Comment" property.
The "Created At" property in ISO 8601 format.
### Serial Number Properties
The "Serial ID" property.
The unique identifier of the serial number.
The SKU of the product associated with the serial number.
The ID of the product associated with the serial number.
The "Package ID" property. This will be `null` if this serial number was not packed yet.
### Packing instruction Confirmation Properties
The ID of the instruction confirmation.
Date and time when the instruction was confirmed in ISO 8601 format.
### Order Custom Field
An object with a Custom Field code as the key and the Custom Field data as the value. The value format depends on the Custom Field input type.
`"custom_fields": { ... }`
To find out what fields are available see [Order Custom Fields](/merchant-api/order-custom-field) — `order_custom_field.list`
Maximum number of characters is 1024.
```json theme={null}
{ "main_sku" : { "value" : "product2" } }
```
```json theme={null}
{ "order_details" : { "value" : "Long multiline \n order details \n here." } }
```
```json theme={null}
{ "number_of_skus" : { "value" : 5 } }
```
```json theme={null}
{ "length_and_girth" : { "value" : 54.25 } }
```
```json theme={null}
{ "cost_of_goods" : { "amount" : 105.95 } }
```
Select input type data must be an object with `label` or `id` key or both.
```json theme={null}
{ "claim_reason" : { "id" : 13 } }
```
Preferred. An option is set by `id`.
```json theme={null}
{ "claim_reason" : { "label" : "Damaged in shipping" } }
```
An option is set by `label`.
```json theme={null}
{ "claim_reason" : { "id" : 13, "label" : "Damaged in shipping" } }
```
An option is set by `id` and `label`. The `id` and the `label` must refer to the same option.
Multi-select input type data must be an array of objects with `label` or `id` key or both.
```json theme={null}
{ "claim_reasons" : [ { "id" : 13 }, { "id" : 14 } ] }
```
Preferred. An option is set by `id`.
```json theme={null}
{ "claim_reasons" : [ { "label" : "Damaged in shipping" }, { "label" : "Did not fit" } ] }
```
An option is set by `label`.
```json theme={null}
{ "claim_reasons" : [ { "id" : 13, "label" : "Damaged in shipping" }, { "id" : 14, "label" : "Did not fit" } ] }
```
An option is set by `id` and `label`. The `id` and the `label` must refer to the same option.
```json theme={null}
{ "allow_mailer" : { "value" : true } }
```
Must be in `Y-m-d` format.
```json theme={null}
{ "desired_delivery_date" : { "value" : "2023-01-23" } }
```
Must be a client user id.
```json theme={null}
{ "created_by" : { "value" : 5 } }
```
Must be an admin user id.
```json theme={null}
{ "created_by" : { "value" : 7 } }
```
Must be a valid email address. Maximum number of characters is 1024.
```json theme={null}
{ "custom_email" : { "value" : "john.doe@example.com" } }
```
Must be a valid URL. Maximum number of characters is 1024.
```json theme={null}
{ "documentation_url" : { "value" : "https://example.com" } }
```
# Order Custom Fields
Source: https://docs.shipstream.io/merchant-api/order-custom-field
## Methods
* [order\_custom\_field.list](#order-custom-field-list)
***
## Entity Properties
* [Order Custom Field](#field-properties)
* [Order Custom Field Option](#option-properties)
***
## Additional Resources
* [Order Custom Fields](/merchant-api/order#order-custom-field) — when submitting/receiving Order info.
* [UI Order Custom Fields article](https://help.shipstream.io/article/0hv4sjkn3d-custom-fields-for-orders)
***
## `order_custom_field.list`
`order_custom_field.list()`
Retrieve list of order custom fields available for the calling merchant.
### Return Value
An array of objects. Each object will contain [Order Custom Field](#field-properties) properties.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"34aa989befe360d67fe3f70b3517a1e5",
"order_custom_field.list"
]
}
```
### Example Response
```json title="Response" theme={null}
{
"result": [
{
"custom_field_id": "3",
"name": "Original Purchase Date",
"code": "purchase_date",
"is_active": "1",
"input_type": "date",
"is_required": "0",
"client_note": null,
"client_permissions": "restricted",
"is_display_client_grid": "1",
"is_display_client_form": "0",
"sort_order": "0",
"created_at": "2022-07-01T10:46:16+00:00",
"updated_at": "2022-07-01T10:46:16+00:00"
},
{
"custom_field_id": "4",
"name": "Main Item SKU",
"code": "main_sku",
"is_active": "1",
"input_type": "text",
"is_required": "0",
"client_note": null,
"client_permissions": "unrestricted",
"is_display_client_grid": "0",
"is_display_client_form": "1",
"sort_order": "99",
"created_at": "2022-07-01T11:43:28+00:00",
"updated_at": "2022-07-01T11:43:28+00:00"
}
],
"id": "1234",
"jsonrpc": "2.0"
}
```
## Entity Properties
### Order Custom Field Properties
An automatically generated unique identifier for an Order Custom Field.
The "name" property.
The "code" property.
Flag whether Order Custom Field is active.
The "input\_type" property. Allowed values: "text", "multiline-text", "number", "currency", "select", "multiselect", "boolean", "date", "client-user", "admin-user", "email", "url".
Flag whether Order Custom Field is required.
The "client\_note" property.
The "unrestricted" property. Allowed values: "unrestricted", "restricted", "read-only", "hidden".
Flag whether Order Custom Field is displayed in the client grid.
Flag whether Order Custom Field is displayed in the client form.
The "sort\_order" property.
The "Created At" property.
The "Updated At" property.
Array of options. See [Option Properties](#option-properties).
### Order Custom Field Option Properties
The internal option ID.
The "Label" property.
Flag whether option is default.
The "Sort Order" property.
# Packing Instructions
Source: https://docs.shipstream.io/merchant-api/order-instruction
## Methods
* [order\_instruction.create](#order-instruction-create)
* [order\_instruction.edit](#order-instruction-edit)
* [order\_instruction.list](#order-instruction-list)
* [order\_instruction.delete](#order-instruction-delete)
***
## Entity Properties
* [Packing instruction](#order-instruction-properties)
* [Packing instruction Confirmation](#order-instruction-confirmation-properties)
***
## `order_instruction.create`
`order_instruction.create (string $orderUniqueId, string $note, object|null $options)`
Create a new Packing Instruction.
### Parameters
Order unique ID
Note
Additional Options (see [Packing Instruction](#order-instruction-properties))
### Return Value
An object with the new [Packing Instruction](#order-instruction-properties). The "file\_content" property is not returned. Use the [order\_instruction.list](#order-instruction-list) method to retrieve it.
### Example Request
No file to print
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"order_instruction.create",
[
"100000309",
"Sign gift card with 'Happy Birthday, Susan!'",
{
"presentation" : "once_per_order"
}
]
]
}
```
Upload a file using Base64 encoding
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"order_instruction.create",
[
"100000309",
"Place Amazon FBA Label in a pouch",
{
"file_name" : "amazon_fba_3425232.pdf",
"file_content" : "base64-encoded file contents",
"presentation" : "once_per_shipment",
"print_target" : "LASER"
}
]
]
}
```
Upload a file using an HTTP request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"order_instruction.create",
[
"100000309",
"Place Amazon FBA Label in a pouch",
{
"file_name" : "amazon_fba_3425232.pdf",
"file_request" : {
"url": "https://....",
"auth": ["username...","password..."],
"headers": {
"X-Custom-Header": "header value..."
}
},
"presentation" : "once_per_shipment",
"print_target" : "LASER"
}
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : {
"instruction_id" : 1,
"order_id" : 118,
"unique_id" : "100000309",
"note" : "Place Amazon FBA Label in a pouch",
"file_name" : "amazon_fba_3425232.pdf",
"presentation" : "once_per_shipment",
"print_target" : "LASER",
"copies_printed" : "0",
"confirmations" : []
}
}
```
### Error Codes
| code | message |
| ---- | --------------------------------------------- |
| 100 | Invalid data given. Details in error message. |
| 102 | Requested order does not exist. |
***
## `order_instruction.edit`
`order_instruction.edit (string $instructionId, string|null $note, object|null $options)`
Modify the packing instruction.
### Parameters
Instruction ID
Note
Additional Options (see [Packing Instruction](#order-instruction-properties))
### Return Value
An object with the updated [Packing Instruction](#order-instruction-properties). The "file\_content" property is not returned.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"order_instruction.edit",
[
123,
null,
{
"presentation" : "once_per_order"
}
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : {
"instruction_id" : 1,
"order_id" : 118,
"unique_id" : "100000309",
"note" : "Place Amazon FBA Label in a pouch",
"file_name" : "amazon_fba_3425232.pdf",
"presentation" : "once_per_order",
"print_target" : "LASER",
"copies_printed" : "0",
"confirmations" : []
}
}
```
### Error Codes
| code | message |
| ---- | --------------------------------------------- |
| 100 | Invalid data given. Details in error message. |
| 101 | Requested packing instruction does not exist. |
***
## `order_instruction.list`
`order_instruction.list (string $orderUniqueId, array|null $fields = [])`
Retrieve list of packing instructions.
### Parameters
Order unique ID
Fields
### Return Value
An array of objects. Each object will contain [Packing Instruction](#order-instruction-properties) properties. Include "file\_content" to the list of the fields to return the "file\_content" property.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"order_instruction.list",
[
"100000309"
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : [
{
"instruction_id" : 1,
"order_id" : 118,
"unique_id" : "100000309",
"note" : "Place Amazon FBA Label in a pouch",
"file_name" : "amazon_fba_3425232.pdf",
"presentation" : "once_per_shipment",
"print_target" : "LASER",
"copies_printed" : "1",
"confirmations" : [
{
"confirmed_id" : "1",
"confirmed_at": "2022-02-08T14:59:38+00:00"
}
]
}
]
}
```
### Error Codes
| code | message |
| ---- | --------------------------------------------- |
| 100 | Invalid data given. Details in error message. |
| 102 | Requested order does not exist. |
***
## `order_instruction.delete`
`order_instruction.delete (string $instructionId)`
Delete packing instruction.
### Parameters
Instruction ID
### Return Value
`true` if the packing instruction was deleted.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"order_instruction.delete",
[
123
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : true
}
```
## Entity Properties
### Packing Instruction Properties
Instruction to the packer. The note is required.
The name to be given to the file attached using the "file\_content" or "file\_request" properties.
The base64-encoded contents of the file. If specified you must also provide a "file\_name".
Attach a file using a url instead of `file_content`. The file will be downloaded using the optional `auth` and `headers` if specified. The `file_name` will be used if specified, but is optional and will otherwise be set using the `Content-Disposition` header value or the last part of the url.
The "presentation" property. Allowed values: "once\_per\_order", "once\_per\_shipment", "once\_per\_package".
The "print\_target" property. Allowed values: "LABEL", "SMALL\_LABEL", "LASER".
The "copies\_printed" property.
The instruction confirmations. See [Packing instruction Confirmation Properties](#order-instruction-confirmation-properties).
### Packing instruction Confirmation Properties
The ID of the instruction confirmation.
Date and time when the instruction was confirmed in ISO 8601 format.
# Product
Source: https://docs.shipstream.io/merchant-api/product
Each merchant maintains a completely unique catalog of products managed at ShipStream whether in stock or not. It is preferable that a merchant creates all of their products with accurate names, goods type and barcodes before actually shipping physical inventory to aid in accurate processing of deliveries.
The canonical field names for the Harmonized System code fields are `hs_base_code` ("Harmonized System Code") and
`hs_country_extension` ("HS Code Extensions"). The legacy `hts_base_code` and `hts_country_code` field names remain
accepted as input aliases indefinitely, and responses include both the canonical and legacy keys for backwards
compatibility. If both a legacy alias and its canonical `hs_*` field are supplied in the same request, the canonical
`hs_*` value wins. See [Product Properties](#product-properties) for details.
## Methods
* [product.search](#product-search)
* [product.create](#product-create)
* [product.info](#product-info)
* [product.update](#product-update)
***
## Entity Properties
* [Product](#product-properties)
***
## `product.search`
`product.search(null|object $filters = null, null|array $options = null)`
Retrieve list of products with basic info (id, sku, type, set, name).
### Parameters
* `null` - Retrieve list of all products.
* `object` - Retrieve list of products using specified [Search Filters](/merchant-api/search-filters).
Allowed properties for filtering: "sku", "vendor\_sku", "manufacturer\_part\_number", "status", "availability", "visibility", "created\_at", "updated\_at", "external\_id".
* `null` - No options will be applied.
* `object` - Apply specified [Search Options](/merchant-api/search-options).
### Return Value
An array of objects. Each object will contain [Product Properties](#product-properties).
### Example Request
Get product information for one product SKU:
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"product.search",
[
{
"sku" : { "eq" : "product2" }
}
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : [
{
"sku" : "productsku",
"name" : "product name",
"barcode" : "productbarcode",
"goods_type" : "NORMAL",
"status" : 1,
"availability" : 1,
"visibility" : 2,
"weight" : 12.75,
"weight_unit" : "lb",
"length" : null,
"width" : null,
"height" : null,
"customs_value" : "24.5600",
"customs_value_currency" : "USD",
"country_of_manufacture" : "DK",
"hs_base_code" : "8471.30",
"hs_country_extension" : [
{
"country_id" : "US",
"extension" : "0010"
},
{
"country_id" : "CA",
"extension" : "0020"
}
],
"hts_base_code" : "8471.30",
"hts_country_code" : [
{
"country_id" : "US",
"extension" : "0010"
},
{
"country_id" : "CA",
"extension" : "0020"
}
],
"vendor_sku" : "vendorsku",
"manufacturer_part_number" : "manufacturerpartnumber",
"requires_packaging" : 1,
"can_contain_other_items" : 0,
"valid_containers" : ["containersku1", "containersku2"],
"special_supplies" : [ "supplysku1", "supplysku2" ],
"special_other" : [ "specialsku1", "specialsku2" ],
"unit_qty" : 5
}
]
}
```
### Error Codes
| code | message |
| ---- | ------------------------------------------------ |
| 108 | Invalid filters given. Details in error message. |
***
## `product.create`
`product.create (string $sku, object $productData)`
Create new product.
### Parameters
Product SKU.
Product data.
### Return Value
`true` if product was successfully created.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"product.create",
[
"product3",
{
"name" : "Product 3",
"barcode" : "product3",
"goods_type" : "NORMAL",
"weight" : 1.75,
"weight_unit": "lb",
"length" : 123,
"width" : 100,
"height" : 28,
"dimension_unit" : "in",
"customs_value" : "24.5600",
"customs_value_currency" : "USD",
"country_of_manufacture" : "DK",
"hs_base_code" : "8471.30",
"hs_country_extension" : "US:0010|CA:0020",
"vendor_sku" : "vendorsku",
"manufacturer_part_number" : "manufacturerpartnumber",
"requires_packaging" : 1,
"can_contain_other_items" : 1,
"valid_containers" : [ "containersku1", "containersku2" ],
"special_supplies" : [ "supplysku1", "supplysku2" ],
"special_other" : [ "specialsku1", "specialsku2" ],
"unit_qty" : 5
}
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : true
}
```
### Error Codes
| code | message |
| ---- | ------------------------------------------------------------- |
| 102 | Invalid data given. Details in error message. |
| 104 | Product type is not in allowed types. |
| 105 | Product's attribute set does not exist. |
| 106 | Product's attribute set is not a Catalog Product entity type. |
| 107 | Another product with this SKU already exists. |
***
## `product.info`
`product.info (string $sku)`
Retrieve product info.
### Parameters
Product SKU.
### Return Value
Object with [Product Properties](#product-properties).
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"product.info",
[
"product1"
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : {
"sku" : "productsku",
"name" : "product name",
"barcode" : "productbarcode",
"goods_type" : "NORMAL",
"status" : 1,
"availability" : 1,
"visibility" : 2,
"weight" : 12.75,
"weight_unit" : "lb",
"length" : null,
"width" : null,
"height" : null,
"dimension_unit" : "in",
"customs_value" : "24.5600",
"customs_value_currency" : "USD",
"country_of_manufacture" : "DK",
"hs_base_code" : "8471.30",
"hs_country_extension" : [
{
"country_id" : "US",
"extension" : "0010"
},
{
"country_id" : "CA",
"extension" : "0020"
}
],
"hts_base_code" : "8471.30",
"hts_country_code" : [
{
"country_id" : "US",
"extension" : "0010"
},
{
"country_id" : "CA",
"extension" : "0020"
}
],
"vendor_sku" : "vendorsku",
"manufacturer_part_number" : "manufacturerpartnumber",
"requires_packaging" : 1,
"can_contain_other_items" : 0,
"valid_containers" : [ "containersku1", "containersku2" ],
"special_supplies" : [ "supplysku1", "supplysku2" ],
"special_other" : [ "othersku1", "othersku2" ],
"unit_qty" : 5
}
}
```
### Error Codes
| code | message |
| ---- | ------------------- |
| 101 | Product not exists. |
***
## `product.update`
`product.update (string $sku, object $productData)`
Update product data.
### Parameters
Product SKU.
Product data.
### Return Value
`true` if product was successfully updated.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"product.update",
[
"product3",
{
"name" : "product name",
"barcode" : "productbarcode",
"goods_type" : "NORMAL",
"status" : 1,
"availability" : 1,
"visibility" : 2,
"weight" : 12.75,
"weight_unit" : "lb",
"length" : null,
"width" : null,
"height" : null,
"dimension_unit" : "in",
"customs_value" : "24.5600",
"customs_value_currency" : "USD",
"country_of_manufacture" : "DK",
"hs_base_code" : "8471.30",
"hs_country_extension" : [
{
"country_id" : "US",
"extension" : "0010"
},
{
"country_id" : "CA",
"extension" : "0020"
}
],
"vendor_sku" : "vendorsku",
"manufacturer_part_number" : "manufacturerpartnumber",
"requires_packaging" : 1,
"can_contain_other_items" : 0,
"valid_containers" : [ "containersku1", "containersku2" ],
"special_supplies" : [ "supplysku1", "supplysku2" ],
"special_other" : [ "specialsku1", "specialsku2" ],
"unit_qty" : 5
}
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : true
}
```
### Error Codes
| code | message |
| ---- | --------------------------------------------- |
| 101 | Product not exists. |
| 102 | Invalid data given. Details in error message. |
***
## Entity Properties
### Product Properties
A unique identifier for a product. The SKU does appear on the packing slip. It is recommended that this be human-readable and end with a per-pack quantity to facilitate proper receiving. For example, a single blue widget may be "BlueWidget-1" and a pack of 5 blue widgets may be "BlueWidget-5". Maximum character length is 64.
The "Name" property.
The "Export Description" property. A detailed description of the product used for international shipping and
customs declarations (e.g. on commercial invoices). Required for international shipping.
The "Barcode" property. Single or comma separated barcodes.
The "Goods Type" property. Allowed: "NORMAL", "ORM\_D", "LIMITED\_QUANTITIES\_COMMODITIES", "HAZMAT".
The "Status" property. Allowed: "0" - Disabled, "1" - Enabled.
The "Availability" property. Allowed: "1" - available. "2" - not available.
The "Visibility" property. Allowed: "1" - not visible, "2" - visible.
The "Weight" property.
The unit of measure used for `weight`. See: [Weight Units](/merchant-api/units-of-measure#weight).
The "Length" property.
The "Width" property.
The "Height" property.
The unit of measure used for `length`, `width`, and `height`. See: [Length Units](/merchant-api/units-of-measure#length). Note that this field is shared between `length`, `width`, and `height`; updating a single dimension will change the unit for all three.
The "Freight Class" property.
The "Freight Category" property.
The "Customs Value" property. The declared customs value per unit as a number with up to 4 decimal places.
Required for international shipping.
The currency of the "Customs Value" property. Must be a valid ISO 4217 alphabetic code (e.g. "USD").
Deprecated alias of `customs_value`, retained for backwards compatibility. Accepted as input only when
`customs_value` is not supplied, and included in responses alongside `customs_value`.
The "Country of Manufacture" property. The two-letter ISO 3166-1 alpha-2 code of the country where the product
was manufactured (e.g. "DK"). Required for international shipping.
The "Harmonized System Code" property. The 6-digit Harmonized System (HS) code that classifies the product for
international trade, formatted `####.##` (e.g. "8471.30"), not including any country-specific extensions. This
code can be found using a search tool such as [https://hts.usitc.gov/](https://hts.usitc.gov/). Required for
international shipping.
The "HS Code Extensions" property. Country-specific extensions to the 6-digit Harmonized System code — for
imports into the United States this is the last 4 digits of the 10-digit HTS (Harmonized Tariff Schedule) code.
As input, either a string in the format `"{COUNTRY}:{CODE}"` with multiple entries separated by the pipe
character (e.g. `"US:0010|CA:0020"`), or an array of objects each having `country_id` and `extension`
properties. `{COUNTRY}` (`country_id`) is the two-letter ISO 3166-1 alpha-2 code of the import country and
`{CODE}` (`extension`) is that country's extension digits.
In responses this property is returned as an array of objects with `country_id` and `extension` properties.
Deprecated alias of `hs_base_code`, retained for backwards compatibility. Accepted as input indefinitely
(ignored when `hs_base_code` is also supplied) and included in responses alongside `hs_base_code`.
Deprecated alias of `hs_country_extension`, retained for backwards compatibility. Accepted as input indefinitely
(ignored when `hs_country_extension` is also supplied) and included in responses alongside
`hs_country_extension`. The alias `hs_country_code` is also tolerated as input.
The "Requires Packaging" property. Allowed: "0" - not required. "1" - required.
The "Can Contain Other Items" property. Allowed: "0" - cannot contain other items. "1" - can contain other items.
The "Valid Containers" property. An array of SKUs for valid containers.
The "Special Supplies" property. An array of SKUs for special packaging supplies.
The "Other Special Features" property. An array of SKUs for other special packaging features.
The "Unit Quantity" property. Number of individually packaged items contained therein for purposes of special packaging features.
The "External ID" property. The external unique numeric identifier for the product.
The "Vendor SKU" property. Use if different from the "SKU" property.
The "Manufacturer Part Number" property. The manufacturer's part number for the item; may be required for
customs on shipments to EU countries.
# Product Media
Source: https://docs.shipstream.io/merchant-api/product-media
This API endpoint allows a merchant to manage product media such as images.
## Methods
* [product\_media.list](#product-media-list)
* [product\_media.types](#product-media-types)
* [product\_media.create](#product-media-create)
* [product\_media.update](#product-media-update)
* [product\_media.remove](#product-media-remove)
***
## Entity Properties
* [Image Type](#image-type-properties)
* [Image Mime Type](#image-mime-type)
* [Image Data](#image-data)
***
## `product_media.list`
`product_media.list (string $sku)`
Retrieve list of product images
### Parameters
Product SKU.
### Return Value
An array of objects. Each object will contain [Image Data](#image-data).
### Example Request
Get product images by product SKU:
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"product_media.list",
[
"product2"
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : [
{
"file" : "/b/l/blackberry8100_2.jpg",
"position" : 1,
"exclude" : 0,
"url" : "http://magentohost/media/catalog/product/b/l/blackberry8100_2.jpg",
"types" : [
"image",
"thumbnail"
]
}
]
}
```
### Error Codes
| code | message |
| ---- | ------------------------------- |
| 100 | Requested store view not found. |
| 101 | Product not exists. |
***
## `product_media.types`
`product_media.types (number $setId)`
Retrieve product image types
### Parameters
Attribute set id.
### Return Value
An array of objects. Each object will contain [Image Type Properties](#image-type-properties).
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"product_media.types",
[
4
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : [
{
"code" : "image",
"scope" : "store"
},
{
"code" : "thumbnail",
"scope" : "store"
}
]
}
```
***
## `product_media.create`
`product_media.create (string $sku, object $data)`
Upload new product image
### Parameters
Product SKU.
Image data.
### Return Value
Image file name (e.g., "/i/m/image.png")
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"product_media.create",
[
"product2",
{
"file" : {
"content" : "base64 encoded content",
"mime": "image/jpeg"
},
"position" : 100,
"types" : [
"thumbnail"
],
"exclude" : 0
}
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : [
"/i/m/image.png"
]
}
```
### Error Codes
| code | message |
| ---- | ------------------------------------------------ |
| 100 | Requested store view not found. |
| 101 | Product not exists. |
| 102 | Invalid data given. Details in error message. |
| 104 | Image creation failed. Details in error message. |
| 107 | Requested product doesn't support images |
***
## `product_media.update`
`product_media.update (string $sku, string $file, object $data)`
Update product image
### Parameters
Product SKU.
Image file name.
Image data.
### Return Value
`true`, if the image has been uploaded
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"product_media.update",
[
"product2",
"/i/m/image.png",
{
"file" : {
"content" : "base64 encoded content",
"mime": "image/jpeg"
},
"position" : 100,
"types" : [
"thumbnail"
],
"exclude" : 1
}
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : 1
}
```
### Error Codes
| code | message |
| ---- | ------------------------------------------------------ |
| 100 | Requested store view not found. |
| 101 | Product not exists. |
| 102 | Invalid data given. Details in error message. |
| 103 | Requested image not exists in product images' gallery. |
| 104 | Image creation failed. Details in error message. |
| 107 | Requested product doesn't support images |
***
## `product_media.remove`
`product_media.remove (string $sku, string $file)`
Remove product image
### Parameters
Product SKU.
Image file.
### Return Value
`true`, if the image has been removed
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"product_media.remove",
[
"product2",
"/b/l/blackberry8100_2.jpg"
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : 1
}
```
### Error Codes
| code | message |
| ---- | -------------------------------------------- |
| 100 | Requested store view not found. |
| 101 | Product not exists. |
| 106 | Image not removed. Details in error message. |
| 107 | Requested product doesn't support images |
## Entity Properties
### Image Type Properties
A unique identifier for an image type. Allowed: "image", "thumbnail".
The "Scope" property. Allowed: "global", "website", "store".
### Image Mime Type
```json theme={null}
{ "mime" : "image/jpeg" }
```
JPEG
```json theme={null}
{ "mime" : "image/gif" }
```
GIF
```json theme={null}
{ "mime" : "image/png" }
```
PNG
### Image Data
Creating a new file:
```json theme={null}
{ "file" : { "content" : "base64 encoded content", "mime" : "image/jpeg" }}
```
Retriving existing file:
```json theme={null}
{ "file" : "/b/l/blackberry8100_2.jpg" }
```
```json theme={null}
{ "position" : 3 }
```
```json theme={null}
{ "exclude" : 1 }
```
Allowed: "0" or "1".
```json theme={null}
{ "url" : "https://shipstream.io/media/catalog/product/b/l/blackberry8100_2.jpg" }
```
```json theme={null}
{ "types" : ["image", "thumbnail"] }
```
Allowed: "image", "thumbnail".
# Rate Limits
Source: https://docs.shipstream.io/merchant-api/rate-limits
Understand the rate and concurrency limits enforced on the Merchant API.
To ensure fair use and platform stability for all merchants, the Merchant API enforces rate and concurrency limits per API user. Exceeding these limits will result in specific HTTP-level error responses with headers to help you manage your request flow.
## Limits
| Limit | Value |
| ----------------------------- | ----------------------- |
| Rate limit | 10 requests/second |
| Burst capacity | 60 requests |
| Concurrency limit | 5 simultaneous requests |
| Maximum API keys per merchant | 6 |
The rate limiter uses a **token bucket** algorithm keyed by **API user ID**. This means limits are enforced per API credential, not per IP address. Each API user has an independent token bucket, so if you need to separate concerns (e.g., rating vs. order submission), consider using separate API keys to avoid one workflow's burst activity affecting another.
Each merchant is limited to **6 active API users**. Attempting to create or activate additional API keys beyond this limit will result in an error: *"You've reached your limit of 6 API keys. Please delete any unused API keys and try again."*
## Response Codes
| Code | Meaning |
| ----------------------- | -------------------------------------------------------------------------------------------------------------- |
| `409 Conflict` | The concurrency limit has been reached. Too many simultaneous requests are in flight for this API user. |
| `429 Too Many Requests` | The rate limit has been exceeded. Wait for the duration indicated in the `Retry-After` header before retrying. |
## Response Headers
These headers are included on **every response**, including rate-limited responses, to help you track your current usage.
### Rate Limit Headers
| Header | Description |
| --------------------- | ---------------------------------------------------------------------------------------------- |
| `RateLimit-Limit` | The maximum number of requests you can make per minute. |
| `RateLimit-Remaining` | The approximate number of requests remaining before being limited. |
| `Retry-After` | The number of seconds to wait before retrying. Only present when a `429` response is returned. |
### Concurrency Headers
| Header | Description |
| ----------------------- | -------------------------------------------------------------------- |
| `X-Concurrency-Limit` | The maximum number of concurrent requests allowed for this API user. |
| `X-Concurrency-Current` | The number of requests currently in flight for this API user. |
## Handling Rate Limit Errors
When you receive a `429 Too Many Requests` response, inspect the `Retry-After` header and wait at least that many seconds before retrying the request.
When you receive a `409 Conflict` response, reduce the number of in-flight requests. Use the `X-Concurrency-Current` and `X-Concurrency-Limit` headers to gauge how close you are to the limit.
If your integration processes high volumes of requests (e.g., bulk order imports or rating calls), consider using separate API keys for different workflows. Since limits are tracked per API user, this prevents spikes in one workflow from affecting another.
# Rating
Source: https://docs.shipstream.io/merchant-api/rating
This API endpoint allows a merchant to request shipping and handling quotes based on a set of order items and a destination zip code.
## Methods
* [rate.quote](#rate-quote)
* [rate.services](#rate-services)
***
## Entity Properties
* [Destination](#destination-properties)
* [Method Information Properties](#method-information-properties)
* [Rate Properties](#rate-properties)
***
## `rate.quote`
`rate.quote (object $destination, object $items, object $methodInfo)`
Request shipping and handling quotes based on a set of order items and a destination zip code.
### Parameters
Destination (see [Destination Properties](#destination-properties))
Order Items. Format:
```json theme={null}
[ { "sku": "product1", "qty": 1 }, { "sku": "product2", "qty": 3 } ]
```
Method Information (see [Method Information Properties](#method-information-properties))
### Return Value
An object with rates and handling cost.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"rate.quote",
[
{
"country" : "US",
"region" : "NY",
"city" : "New York",
"street" : "11 Times Square",
"postcode" : "10036",
"company" : "Microsoft",
"classification" : "com"
},
[
{
"sku" : "product1",
"qty": 1
},
{
"sku" : "product2",
"qty" : 3
}
],
{
"methods" : "ups_03",
"signature_required" : "adult",
"saturday_delivery" : false,
"overbox" : false
}
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : {
"rates" : [
{
"code" : "ups_03",
"description" : "UPS Ground",
"zone" : "002",
"days_in_transit" : "2",
"package_count" : 1,
"shipping_cost" : "17.23",
"shipping_cost_currency" : "USD",
"if_ordered_by" : "15:00:00",
"min_delivery_date" : "2017-02-05",
"max_delivery_date" : "2017-02-05",
"signature_fee" : "1.15",
"signature_fee_currency" : "USD",
"multiple_warehouses" : false,
"allocation" : [
{ "product1" : [{ "warehouse_id": 1, "qty": "1.000" }] },
{ "product2" : [{ "warehouse_id": 1, "qty": "3.000" }] }
]
}
],
"handling_cost" : "2.4",
"handling_cost_currency" : "USD"
}
}
```
***
## `rate.services`
`rate.services (int|null $warehouseId)`
Get a list of the enabled shipping methods.
### Parameters
Warehouse. If not specified, the first allowed warehouse will be used.
### Return Value
An array of enabled shipping methods.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"c4d62bb4c368d8158b1221cd5f27a659",
"rate.services",
1
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"result" : {
"external_ltl" : {
"title" : "LTL",
"carrier_code" : "external",
"service" : "ltl",
"rates_available" : false
},
"external_ltl_thirdparty" : {
"title" : "LTL - Third Party",
"carrier_code" : "external",
"service" : "ltl_thirdparty",
"rates_available" : false
},
"fedex_EUROPE_FIRST_INTERNATIONAL_PRIORITY" : {
"title" : "FedEx Europe First International Priority",
"carrier_code" : "fedex",
"service" : "EUROPE_FIRST_INTERNATIONAL_PRIORITY",
"rates_available" : true
},
"fedex_FEDEX_1_DAY_FREIGHT" : {
"title" : "FedEx 1 Day Freight",
"carrier_code" : "fedex",
"service" : "FEDEX_1_DAY_FREIGHT",
"rates_available" : true
},
"fedex_FEDEX_2_DAY" : {
"title" : "FedEx 2 Day",
"carrier_code" : "fedex",
"service" : "FEDEX_2_DAY",
"rates_available" : true
},
"ups_02" : {
"title" : "UPS 2nd Day Air",
"carrier_code" : "ups",
"service" : "02",
"rates_available" : true
},
"ups_03" : {
"title" : "UPS Ground",
"carrier_code" : "ups",
"service" : "03",
"rates_available" : true
},
"ups_07" : {
"title" : "UPS Worldwide Express",
"carrier_code" : "ups",
"service" : "07",
"rates_available" : true
}
}
}
```
***
## Entity Properties
### Destination Properties
The "Country" property. ISO-2 format.
The "Region" property. 2 characters.
The "City" property.
The street address. Multi-line street addresses will be separated by a newline ("\n") character.
The "Postal Code" property. Pass as a string to prevent leading 0s from being dropped.
The "Company" property.
The "Classification" property. Allowed: "res" - residential, "com" - commercial, "po" - post office, "mil" - military, "unk" - unknown.
### Method Information Properties
One or more shipping methods. See the [Shipping Methods](/merchant-api/shipping-methods) document for a reference.
If "adult" then the package(s) will be shipped with the Adult Signature Required option (21 years or older). If "any" then the package(s) will be shipped with the "Direct" signature required (recipient of any age). If "indirect" then the package(s) will be shipped with the "Indirect" signature required (if "Indirect" is not supported by the carrier, this option will fall back to 'any'). If not specified will default to "none".
Saturday delivery option. If not specified will default to 'false'.
Request overbox option. If not specified will default to 'false'.
### Rate Properties
Shipping methods. See the [Shipping Methods](/merchant-api/shipping-methods) document for a reference.
See the [Shipping Methods](/merchant-api/shipping-methods) document for a reference.
Carrier zone.
Days in transit.
The number of packages.
Shipping cost.
Shipping cost currency. An ISO 4217 alphabetic code.
Same day shipping if you place your order by this time. 24 hour clock time. Eastern Time.
Minimum delivery date.
Maximum delivery date.
Signature fee.
Signature fee currency. An ISO 4217 alphabetic code.
Multiple warehouses flag indicates if the items were split between multiple warehouses.
Inventory allocated to warehouses.
Base rate, before surcharges are applied.
Base rate currency. An ISO 4217 alphabetic code.
Residential surcharge.
Residential surcharge currency. An ISO 4217 alphabetic code.
Area surcharge.
Area surcharge currency. An ISO 4217 alphabetic code.
Fuel surcharge.
Fuel surcharge currency. An ISO 4217 alphabetic code.
Weight surcharge.
Weight surcharge currency. An ISO 4217 alphabetic code.
Packaging surcharge.
Packaging surcharge currency. An ISO 4217 alphabetic code.
Dimension surcharge.
Dimension surcharge currency. An ISO 4217 alphabetic code.
Oversize surcharge.
Oversize surcharge currency. An ISO 4217 alphabetic code.
Demand surcharge.
Demand surcharge currency. An ISO 4217 alphabetic code.
Additional surcharge.
Additional surcharge currency. An ISO 4217 alphabetic code.
# Retailers
Source: https://docs.shipstream.io/merchant-api/retailer
Retailers represent B2B retail partners for the calling merchant. Retailer records can include fulfillment defaults, retailer-specific custom fields, EDI identifiers, ship-to locations, and routing-guide metadata.
## Methods
* [retailer.list](#retailer-list)
* [retailer.info](#retailer-info)
***
## Entity Properties
* [Retailer](#retailer-properties)
* [Retailer Identifier](#retailer-identifier-properties)
* [Retailer Ship-To Location](#retailer-ship-to-location-properties)
* [Retailer Routing Guide](#retailer-routing-guide-properties)
***
## Additional Resources
* [Retailer Custom Fields](/merchant-api/retailer-custom-field) — definition metadata for Retailer `custom_fields` values.
***
## `retailer.list`
`retailer.list(filters, options, fields)`
Retrieve a paged list of Retailers for the calling merchant. Terminated Retailers are excluded unless a `status` filter is supplied or `options.include_terminated` is `true`.
### Parameters
Optional search filters. Supported fields: `retailer_id`, `code`, `name`, `status`, `fulfillment_model`, `parent_retailer_id`, `created_at`, and `updated_at`.
Optional [search options](/merchant-api/search-options). Supported options: `sort_field`, `sort_dir`, `page`, `limit`, and `include_terminated`.
Optional list of Retailer fields to return. Use nested fields such as `identifiers`, `ship_to_locations`, and `routing_guides` only when those child records are needed.
### Return Value
An object with `results`, `totalCount`, and `numPages`. Each item in `results` contains [Retailer](#retailer-properties) properties.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : "2.0",
"id" : 1234,
"method" : "call",
"params" : [
"34aa989befe360d67fe3f70b3517a1e5",
"retailer.list",
[
{ "status" : "active" },
{ "sort_field" : "code", "sort_dir" : "asc", "limit" : 50 },
["retailer_id", "code", "name", "status", "fulfillment_model"]
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc": "2.0",
"id": 1234,
"result": {
"results": [
{
"retailer_id": 123,
"code": "walmart",
"name": "Walmart",
"status": "active",
"fulfillment_model": "wholesale"
}
],
"totalCount": 1,
"numPages": 1
}
}
```
## `retailer.info`
`retailer.info(code, fields)`
Retrieve one Retailer by its merchant-facing `code`. The lookup is scoped to the calling merchant.
### Parameters
The Retailer code.
Optional list of fields to return.
### Return Value
An object containing [Retailer](#retailer-properties) properties.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : "2.0",
"id" : 1234,
"method" : "call",
"params" : [
"34aa989befe360d67fe3f70b3517a1e5",
"retailer.info",
[
"walmart",
["retailer_id", "code", "name", "identifiers", "ship_to_locations", "routing_guides"]
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc": "2.0",
"id": 1234,
"result": {
"retailer_id": 123,
"code": "walmart",
"name": "Walmart",
"identifiers": [
{
"identifier_id": 456,
"qualifier": "duns",
"value": "123456789",
"label": "Walmart DUNS",
"notes": null,
"created_at": "2026-05-28T12:00:00+00:00",
"updated_at": "2026-05-28T12:00:00+00:00"
}
],
"ship_to_locations": [
{
"ship_to_location_id": 789,
"code": "DC01",
"qualifier": "gln",
"location_type": "dc",
"city": "Bentonville",
"region": "AR",
"country_id": "US",
"is_default": true,
"status": "active"
}
],
"routing_guides": [
{
"guide_id": 987,
"title": "Walmart Routing Guide",
"file_name": "walmart-routing-guide.pdf",
"file_type": "pdf",
"file_size": 128000,
"uploaded_by": "Organization User: Jane Manager",
"uploaded_at": "2026-05-28T12:00:00+00:00"
}
]
}
}
```
## Entity Properties
### Retailer Properties
An automatically generated Retailer identifier.
The merchant-facing Retailer code. Codes are unique within a merchant.
The Retailer display name.
Retailer lifecycle status. Allowed values: `active`, `on_hold`, `terminated`.
Default fulfillment model. Allowed values: `wholesale`, `drop_ship`, `mixed`.
Optional parent Retailer ID.
Optional parent Retailer code. Returned only when requested.
Optional legal Retailer name.
Optional doing-business-as name.
Optional default duties payor for future order-integration defaults. Allowed values: `shipper`, `recipient`, `third_party`.
Optional default shipping method identifier for future order-integration defaults.
Optional list of shipping method identifiers allowed when this Retailer is selected.
Optional default shipping third-party billing group ID for future order-integration defaults.
Optional routing-guide notes.
Optional Retailer custom-field values keyed by custom-field code. Hidden custom fields are omitted. Currency custom fields include the merchant/global default currency. Use [Retailer Custom Fields](/merchant-api/retailer-custom-field) to retrieve field definitions.
Optional array of [Retailer Identifier](#retailer-identifier-properties) objects.
Optional array of [Retailer Ship-To Location](#retailer-ship-to-location-properties) objects.
Optional array of [Retailer Routing Guide](#retailer-routing-guide-properties) objects.
The creation timestamp in ISO 8601 format.
The last update timestamp in ISO 8601 format.
### Retailer Identifier Properties
An automatically generated identifier row ID.
Identifier qualifier. Common values include `duns`, `gln`, `mutually_defined`, and `custom`.
Identifier value.
Optional display label.
Optional notes.
The creation timestamp in ISO 8601 format.
The last update timestamp in ISO 8601 format.
### Retailer Ship-To Location Properties
An automatically generated ship-to location row ID.
Retailer-assigned ship-to location code.
The canonical scheme that identifies the location code. EDI qualifiers are normalized to this set. Allowed values: `duns`, `duns_plus_4`, `gln`, `buyer_location`, `seller_location`, `third_party_location`, `plant_code`, `dodaac`, `cage`, `dea`, `hin`, `san`, `approver_id`, `clli`, `census_schedule_d`, `census_schedule_k`.
Optional display label.
Location type. Allowed values: `dc`, `store`, `drop_ship`, `other`.
Optional company name.
Optional street address.
Optional city.
Optional ShipStream region ID.
Optional state or region value.
Optional postal code.
Optional ISO 3166-1 alpha-2 country code.
Optional telephone number.
Optional email address.
Flag indicating the default ship-to location for the Retailer.
Ship-to location status. Allowed values: `active`, `inactive`.
The creation timestamp in ISO 8601 format.
The last update timestamp in ISO 8601 format.
### Retailer Routing Guide Properties
An automatically generated routing guide row ID.
Routing guide title.
Optional routing guide description.
The uploaded file name.
The uploaded file extension or type.
File size in bytes.
Optional formatted Requester name for the uploader.
The upload timestamp in ISO 8601 format.
The creation timestamp in ISO 8601 format.
The last update timestamp in ISO 8601 format.
# Retailer Custom Fields
Source: https://docs.shipstream.io/merchant-api/retailer-custom-field
Retailer custom-field definitions describe the `custom_fields` object returned by Retailer API methods. Use this endpoint to discover field codes, input types, permissions, display flags, and options for the calling merchant.
## Methods
* [retailer\_custom\_field.list](#retailer-custom-field-list)
***
## Entity Properties
* [Retailer Custom Field](#field-properties)
* [Retailer Custom Field Option](#option-properties)
***
## Additional Resources
* [Retailers](/merchant-api/retailer#retailer-properties) — when submitting or receiving Retailer custom-field values.
***
## `retailer_custom_field.list`
`retailer_custom_field.list()`
Retrieve list of retailer custom fields available for the calling merchant. Global definitions are included, and merchant-specific definitions are returned for the calling merchant.
### Return Value
An array of objects. Each object will contain [Retailer Custom Field](#field-properties) properties.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : "2.0",
"id" : 1234,
"method" : "call",
"params" : [
"34aa989befe360d67fe3f70b3517a1e5",
"retailer_custom_field.list"
]
}
```
### Example Response
```json title="Response" theme={null}
{
"result": [
{
"custom_field_id": "12",
"name": "Retailer Department",
"code": "retailer_department",
"is_active": "1",
"input_type": "select",
"is_required": "0",
"client_note": "Department used for retailer reporting.",
"client_permissions": "unrestricted",
"is_display_client_grid": "1",
"is_display_client_form": "1",
"sort_order": "10",
"created_at": "2026-05-28T12:00:00+00:00",
"updated_at": "2026-05-28T12:00:00+00:00",
"options": [
{
"option_id": 31,
"label": "Grocery",
"is_default": true,
"sort_order": 10
},
{
"option_id": 32,
"label": "Apparel",
"is_default": false,
"sort_order": 20
}
]
},
{
"custom_field_id": "13",
"name": "Routing Region",
"code": "routing_region",
"is_active": "1",
"input_type": "text",
"is_required": "0",
"client_note": null,
"client_permissions": "restricted",
"is_display_client_grid": "0",
"is_display_client_form": "1",
"sort_order": "20",
"created_at": "2026-05-28T12:00:00+00:00",
"updated_at": "2026-05-28T12:00:00+00:00"
}
],
"id": "1234",
"jsonrpc": "2.0"
}
```
## Entity Properties
### Retailer Custom Field Properties
An automatically generated unique identifier for a Retailer Custom Field.
The display name of the Retailer Custom Field.
The custom-field code. This is the key used in Retailer `custom_fields` values.
Flag whether the Retailer Custom Field is active.
The input type. Allowed values: "text", "multiline-text", "number", "currency", "select", "multiselect", "boolean", "date", "client-user", "admin-user", "email", "url".
Flag whether the Retailer Custom Field is required.
Optional note shown to API clients.
Client-side permission mode. Allowed values: "unrestricted", "restricted", "read-only", "hidden".
Flag whether the Retailer Custom Field is displayed in the client grid.
Flag whether the Retailer Custom Field is displayed in the client form.
Display sort order.
The creation timestamp in ISO 8601 format.
The last update timestamp in ISO 8601 format.
Array of options for `select` and `multiselect` fields. See [Option Properties](#option-properties).
### Retailer Custom Field Option Properties
The internal option ID.
The option label.
Flag whether the option is default.
The option sort order.
# Search Filters
Source: https://docs.shipstream.io/merchant-api/search-filters
Filters are provided as a list of keys and filter specifications. The keys are names of fields that can be returned in the response. Not all fields support filtering.
Multiple filters are combined using "AND" logic. For example, to find orders that were created after 2023-01-01 and are not completed the filters could be specified like so:
```json title="Request" theme={null}
{
"created_at": {"from": "2023-01-01"},
"status": {"neq": "complete"}
}
```
### Filters
```json theme={null}
{ "status" : { "eq" : 1 } }
```
The value is equal to the given value.
```json theme={null}
{ "sku" : { "neq" : "product1" } }
```
The value is not equal to the given value.
```json theme={null}
{ "sku" : { "starts" : "abc-" } }
```
The value starts with the given value (prefix match).
```json theme={null}
{ "order_id" : { "gt" : 5 } }
```
The value is greater than the given value.
```json theme={null}
{ "order_id" : { "lt" : 5 } }
```
The value is less than the given value.
```json theme={null}
{ "order_id" : { "gteq" : 5 } }
```
The value is greater than or equal to the given value.
```json theme={null}
{ "order_id" : { "lteq" : 5 } }
```
The value is less than or equal to the given value.
```json theme={null}
{ "created_at" : { "from" : "2014-07-12 14:12:47", "datetime" : true } }
```
```json theme={null}
{ "created_at" : { "from" : "2014-07-12" } }
```
The value is greater than or equal to the given value. If the "datetime" flag is specified the value is compared with the exact timestamp given, otherwise the value is compared with the first second on the given date. The timezone is the merchant's configured timezone.
```json theme={null}
{ "created_at" : { "to" : "2014-07-12 14:12:47", "datetime" : true } }
```
```json theme={null}
{ "created_at" : { "to" : "2014-07-12" } }
```
The value is less than or equal to the given value. If the "datetime" flag is specified the value is compared with the exact timestamp given, otherwise the value is compared with the last second on the given date. The timezone is the merchant's configured timezone.
```json theme={null}
{ "order_id" : { "in" : [ "114", "115" ] } }
```
The value is equal to one of the given values. This can be used to locate multiple records with one query.
```json theme={null}
{ "status" : { "nin" : [ "new", "complete" ] } }
```
The value is not equal to any of the given values.
```json theme={null}
{ "target_ship_date" : { "null" : 1 } }
```
The field's value is null (has no value).
```json theme={null}
{ "target_ship_date" : { "notnull" : 1 } }
```
The field has a value that is not null.
# Search Options
Source: https://docs.shipstream.io/merchant-api/search-options
Search options are optional and can be used for safe paging.
### Options
```json theme={null}
{ "sort_field" : "status" }
```
The "Sort Field" option. Default: "order\_id".
```json theme={null}
{ "sort_dir" : "desc" }
```
The "Sort Direction" option. Allowed: "asc" or "desc". Default: "asc".
```json theme={null}
{ "page" : 5 }
```
The "Page" numeric option. Default: 1.
```json theme={null}
{ "limit" : 100 }
```
The "Limit" numeric option. Default: 50. Max value: 100.
```json theme={null}
{ "skip_totals" : 1 }
```
Set to `1` to omit `totalCount` and `numPages` from the response. Since computing totals requires an additional counting query, it is recommended to request totals only on the first page to build pagination and use `skip_totals` for subsequent page requests or when only the data is needed.
Currently supported only by [shipment.search](/merchant-api/shipment#shipment-search).
# Shipment
Source: https://docs.shipstream.io/merchant-api/shipment
Shipments are not created in the system until an order goes into picking. There may be multiple shipments for one order depending on the overall weight and number of items on the order. Although there may be more than one package for a single shipment, most shipments will have only one package. A packing slip will be printed for each shipment and if multiple packages are required for one shipment they will be linked to the same master tracking number if supported by the carrier.
## Methods
* [shipment.search](#shipment-search)
* [shipment.info](#shipment-info)
* [shipment.update](#shipment-update)
***
## Entity Properties
* [Shipment](#shipment-properties)
* [Shipment Item](#shipment-item-properties)
* [Package](#package-properties)
* [Shipment Track](#track-properties) (deprecated)
***
## `shipment.search`
`shipment.search(null|object $filters, array $options = [], null|string|object $fields = [])`
Retrieve list of shipments by filters. Shipment data can be customized by specifying properties to retrieve.
Some accounts may still receive deprecated shipment status names in `shipment.search` responses because of a compatibility flag from the 2023 package tracking migration. If your integration receives `loaded`, treat it as equivalent to `shipped` and support both the old and new status names. See the [Package Tracking Migration Guide](https://help.shipstream.io/release-notes/package-tracking-migration-guide#statuses) for the full status mapping.
### Parameters
* `null` - Retrieve list of all shipments.
* `object` - Retrieve list of shipments using specified [Search Filters](/merchant-api/search-filters).
Allowed properties for filtering: "shipment\_id", "warehouse\_id", "order\_unique\_id", "order\_ref", "order\_id", "store\_code", "created\_at", "updated\_at", "packed\_at", "status", "shipment\_type".
* `null` - No options will be applied.
* `object` - Apply specified [Search Options](/merchant-api/search-options).
* `null` - Retrieve only "shipment\_id", "order\_unique\_id", and "order\_ref" properties.
* `string '*'` - Retrieve all properties excluding "shipping\_address", "items", "packages", "tracking\_numbers", and "serial\_number\_data".
* `object` - List of properties to retrieve in addition to "shipment\_id", "order\_unique\_id", and "order\_ref". List may include '\*'.
Example:
```json theme={null}
["*", "shipping_address", "packages"]
```
See [Shipment Properties](#shipment-properties).
### Return Value
An object with the following properties:
An array of objects. Each object will contain the specified (or default if no fields parameter was given) [Shipment Properties](#shipment-properties).
The total number of shipments matching the given filters. Omitted if `skip_totals` is enabled.
The total number of pages. Omitted if `skip_totals` is enabled.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc": 2.0,
"id": 1234,
"method": "call",
"params": [
"97ca4f4a5cdca59e9dd0fe52e28bf7cf",
"shipment.search",
[
{ "status": "picked" },
{ "limit": 1 },
["status", "created_at", "updated_at"]
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc": 2.0,
"id": 1234,
"result": {
"results": [
{
"shipping_method": "fedex_FEDEX_GROUND",
"tpb_group_id": null,
"order_unique_id": "1100000005",
"order_ref": null,
"shipment_id": "1100000002",
"warehouse_id": "1",
"status": "picked",
"created_at": "2018-01-26T15:11:08+00:00",
"updated_at": "2020-03-20T17:01:15+00:00"
}
],
"totalCount": 28,
"numPages": 28
}
}
```
### Example Request (skip\_totals)
```json title="Request" theme={null}
{
"jsonrpc": 2.0,
"id": 1234,
"method": "call",
"params": [
"97ca4f4a5cdca59e9dd0fe52e28bf7cf",
"shipment.search",
[
{ "status": "picked" },
{ "limit": 1, "skip_totals": 1 },
["status", "created_at", "updated_at"]
]
]
}
```
### Example Response (skip\_totals)
```json title="Response" theme={null}
{
"jsonrpc": 2.0,
"id": 1234,
"result": {
"results": [
{
"shipping_method": "fedex_FEDEX_GROUND",
"tpb_group_id": null,
"order_unique_id": "1100000005",
"order_ref": null,
"shipment_id": "1100000002",
"warehouse_id": "1",
"status": "picked",
"created_at": "2018-01-26T15:11:08+00:00",
"updated_at": "2020-03-20T17:01:15+00:00"
}
]
}
}
```
### Error Codes
| code | message |
| ---- | ------------------------------------------------ |
| 101 | Invalid filters given. Details in error message. |
***
## `shipment.info`
`shipment.info(string $shipment)`
Retrieve all shipment information.
### Parameters
Shipment ID. Can be retrieved from the order "shipments" property.
### Return Value
Shipment information.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc": 2.0,
"id": 1234,
"method": "call",
"params": [
"97ca4f4a5cdca59e9dd0fe52e28bf7cf",
"shipment.info",
"100000020"
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc": 2.0,
"id": 1234,
"error": null,
"result":
{
"shipment_id": "100000020",
"warehouse_id": 1,
"order_unique_id": "10000015",
"order_ref": "ABC-54321",
"store_code": "acme",
"status": "packing",
"shipment_type": "parcel",
"total_weight": "13.2300",
"total_weight_unit": "lb",
"total_item_weight": "12.1100",
"total_item_weight_unit": "lb",
"total_qty": "2.0000",
"shipped_weight": "13.2300",
"shipped_weight_unit": "lb",
"source": "123",
"tpb_group_id": 1,
"manifest_courier_code": "fedex",
"manifest_courier_name": "FedEx",
"created_at": "2014-07-24T18:51:18+00:00",
"updated_at": "2014-07-24T18:51:18+00:00",
"items": [
{
"sku": "product2",
"name": "product2",
"weight": "12.0500",
"weight_unit": "lb",
"qty": "1.0000",
"qty_picked": "1.0000",
"qty_shipped": "0.0000",
"order_item_id": 121,
"package_data": [
{"order_item_id": 121, "label": "Serial Number - 8 Characters", "value": "55285368"}
],
"lot_data": [
{"lot_id": 456, "sku": "product2", "lot_number": "83CBC2", "expiration_date": "2021-10-05", "origination_date": "2019-01-23", "qty": "1.0000"}
]
},
{
"sku": "product1",
"name": "product1",
"weight": "1.2300",
"weight_unit": "lb",
"qty": "1.0000",
"qty_picked": "1.0000",
"qty_shipped": "1.0000",
"order_item_id": 122,
"package_data": [
{"order_item_id": 122, "label": "Serial Number - 8 Characters", "value": "55285442"}
],
"lot_data": [
{"lot_id": 789, "sku": "product1", "lot_number": "83CCC2", "expiration_date": "2021-10-25", "origination_date": "2019-01-23", "qty": "1.0000"}
],
"ssccs": [
{"sscc": "508101336500131005", "package_index": 0}
]
}
],
"packages": [
{
"warehouse_id": "1",
"shipment_id": "1100000061",
"shipment_status": "packed",
"status": "packed",
"carrier": "fedex",
"created_at": "2014-07-24T18:51:18+00:00",
"tracking_added_at": "2014-07-24T18:51:18+00:00",
"shipped_at": "2014-07-24T18:51:18+00:00",
"delivered_at": "2014-07-24T18:51:18+00:00",
"weight": "13.2300",
"weight_unit": "lb",
"billable_weight": "14",
"billable_weight_unit": "lb",
"dimensional_weight_divisor": "139",
"dimensional_weight_divisor_unit": "in^3/lb",
"dimensional_weight": "14",
"rating_weight_unit": "lb",
"dimensions": {
"length": "16.000",
"width": "12.000",
"height": "8.000"
},
"dimension_unit": "in",
"tracking": [
{
"number": "800027315160887",
"description": "FedEx International Economy",
"track_url": "https://www.fedex.com/apps/fedextrack/?action=track&tracknumbers=800027315160887"
}
],
"order_items": [
{
"order_item_id": "122",
"order_item_ref": null,
"sku": "product1",
"quantity": "1.0000"
}
],
"package_items": [
{
"order_item_id": "122",
"sku": "product1",
"quantity": "1.0000"
}
],
"package_data": [
{"order_item_id": 121, "label": "Serial Number - 8 Characters", "value": "55285368"},
{"order_item_id": 122, "label": "Serial Number - 8 Characters", "value": "55285442"}
],
"serial_number_data": [
{
"serial_id": "1",
"identifier": "123456123456",
"sku": "product1",
"product_id": "7"
}
]
}
],
"tracking_numbers": [
{
"carrier": "fedex",
"description": "FedEx International Economy",
"number": "800027315160887",
"date": "2014-07-24T18:51:18+00:00",
"items": [
{"sku": "product1", "quantity": "1.0000" },
{"sku": "product2", "quantity": "1.0000" }
],
"weight": "13.2300",
"weight_unit": "lb"
}
],
"custom_fields": {
"freight_broker": { "id": 15, "label": "FreightClub" },
"hazmat_inspected_by": { "value": 414 }
}
}
}
```
### Error Codes
| code | message |
| ---- | ---------------------------------- |
| 100 | Requested shipment does not exist. |
***
## `shipment.update`
`shipment.update (string $shipment, object $shipmentData, object $customFields)`
Update shipment information.
### Parameters
Shipment ID. Can be retrieved from the order "shipments" property.
Shipment data.
Allowed properties: source.
Shipment Custom Field Operations (see [Shipment Custom Field Operations](#shipment-custom-field-operations)).
### Shipment Custom Field Operations
An object with an operation name as the key and an object containing the [Shipment Custom Field](#shipment-custom-field)) data for all operations except the `remove` operation. The `remove` operation only requires a list of custom field codes.
Allowed operations: `set`, `add`, `remove`, `add_option`, `remove_option`.
* `set` - Replace all values.
* `add` - Add new fields to existing, replace old values.
* `remove` - Remove only fields specified.
* `add_option` - Multi-selects only. Add an option without unsetting existing options.
* `remove_option` - Multi-selects only. Remove an option without unsetting other options not listed.
### Return Value
`true` if shipment was successfully updated.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc": 2.0,
"id": 1234,
"method": "call",
"params": [
"97ca4f4a5cdca59e9dd0fe52e28bf7cf",
"shipment.update",
[
"100000020",
{
"source": "123456"
}
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"result" : true
}
```
### Error Codes
| code | message |
| ---- | --------------------------------------------- |
| 100 | Requested shipment does not exist. |
| 102 | Invalid data given. Details in error message. |
## Entity Properties
### Shipment Properties
The "Shipment ID" property. This number may appear on the packing slip as the "Packing Slip #".
The internal warehouse ID.
The "unique\_id" property for the order associated with this shipment.
The user-specified order "order\_ref" field.
The store code used to place the order.
The "Status" property. Allowed values: new, picking, picked, packing, packed, shipped, canceled, voided. Some accounts may receive the deprecated compatibility value `loaded`, which is equivalent to `shipped`.
The "Shipment Type" property. Allowed values: parcel, freight.
The "Source" property.
The estimated total weight of the shipment including packaging.
The unit of measure used for `total_weight`. See: [Weight Units](/merchant-api/units-of-measure#weight).
The "Total Item Weight" property.
The unit of measure used for `total_item_weight`. See: [Weight Units](/merchant-api/units-of-measure#weight).
The "Total Quantity" property.
The "Shipped Weight" property.
The unit of measure used for `shipped_weight`. See: [Weight Units](/merchant-api/units-of-measure#weight).
This field is used for storing association data for integrations.
The Third Party Billing Account Group ID.
The date the shipment is intended to be shipped. This is computed based on when the order was "Ready to Ship" and the configured cutoff times for same day shipping.
The Standard Carrier Alpha Code.
The manifest courier code.
The manifest courier name.
Date and time when the shipment was created in ISO 8601 format.
Date and time when the shipment was last updated in ISO 8601 format.
Date and time when all packages were packed in ISO 8601 format.
Date and time when all packages were shipped from the warehouse in ISO 8601 format.
Date and time when all packages were delivered in ISO 8601 format.
Date and time the tracking was added in ISO 8601 format.
Object of [Shipping Address](#address-properties) properties.
Array of [Shipment Item](#shipment-item-properties) objects.
Array of [Package](#package-properties) objects.
Array of [Shipment Track](#track-properties) objects. *This field is deprecated. Please use 'packages' instead.*
Object with Custom Fields. See [Shipment Custom Field](#shipment-custom-field).
The internal ID of the parent order's linked B2B [Retailer](/merchant-api/retailer), or `null`. Makes the link visible without loading the retailer.
The parent order's linked [Retailer](/merchant-api/retailer), or `null`. Excluded from `shipment.search` results by default; request it explicitly via the `fields` parameter.
The internal retailer ID.
The retailer code.
The retailer name.
The internal ID of the parent order's linked [Retailer Ship-To Location](/merchant-api/retailer#retailer-ship-to-location-properties), or `null`. Makes the link visible without loading the location.
The parent order's linked retailer ship-to location, or `null`. Excluded from `shipment.search` results by default; request it explicitly via the `fields` parameter.
The internal ship-to location ID.
The canonical qualifier scheme for the code. See the [Retailer Ship-To Location](/merchant-api/retailer#retailer-ship-to-location-properties) allowed values.
The ship-to location code.
Optional display label.
Location type. One of `dc`, `store`, `drop_ship`, `other`.
### Shipment Item Properties
The "SKU" property.
The "Name" property.
The "Weight" property.
The unit of measure used for `weight`. See: [Weight Units](/merchant-api/units-of-measure#weight).
The "Quantity" property.
The "Picked" quantity.
The "Shipped" quantity.
The "Cancel Requested" quantity. Denotes the quantity to be cancelled if cancellation request is confirmed.
The "Canceled" quantity.
The internal order item ID.
The "Package Data" property.
The Lot Data for the Shipment Item.
The internal Lot ID.
The SKU of the Product assigned to the Lot. This may differ from the Shipment Item `sku` for BOM and quantity-type workflows.
The Lot Number.
The Lot expiration date.
The Lot origination date.
The quantity assigned to the Lot.
The item SSCCs.
### Package Properties
The ID of the warehouse associated with the package.
The "Status" property. Allowed values: packing, tracking\_required, packed, manifested, shipped, delivered.
The "Shipment ID" property. This number may appear on the packing slip as the "Packing Slip #" and is used for the Shipment API calls.
The "Shipment Status" property. Allowed values: new, picking, picked, packing, packed, shipped, canceled, voided.
Carrier code.
Date and time when the package was shipped from the warehouse in ISO 8601 format.
Date and time when the package was delivered in ISO 8601 format.
The weight of the package.
The unit of measure used for `weight`. See: [Weight Units](/merchant-api/units-of-measure#weight).
The billable weight of the package.
The unit of measure used for `billable_weight`. See: [Weight Units](/merchant-api/units-of-measure#weight).
The dimensional weight divisor of the package.
The dimensional weight divisor unit. See: [Dimensional Divisor Units](/merchant-api/units-of-measure#dimensional-divisor).
The dimensional weight of the package.
The unit of measure used for `dimensional_weight`. See: [Weight Units](/merchant-api/units-of-measure#weight).
The `length`, `width`, and `height` of the package.
The unit of measure used for `length`, `width`, and `height` in `dimensions`. See: [Length Units](/merchant-api/units-of-measure#length).
The Serial Shipping Container Code.
An array of tracking objects. The "number" property contains the tracking number. The "description" property contains the shipping method name. The "track\_url" property will contain a URL to the carrier's tracking page if applicable.
An array of order items contained in the package. These items may be different from those in "package\_items" if the order was fulfilled using a Bill of Materials. "order\_item\_id" is the unqiue identifier for the order item. "order\_item\_ref" is an optional user supplied reference for the order item. "sku" is the order item's SKU. "quantity" is the quantity of the order item in the package.
An array of items contained in the package. These items may be different from those in "order\_items" if the order was fulfilled using a Bill of Materials. "order\_item\_id" is the unqiue identifier of the related order item. "sku" is the package item's SKU. "quantity" is the quantity of the item in the package.
The "Package Data" property.
The "Packaging" property.
Array of serial numbers. See [Serial Number properties](#serial-number-properties).
### Shipment Track Properties
The carrier code.
The method description (with the carrier name).
The carrier's tracking number.
The date and time the tracking number was created.
SKUs and quantities of the related package items.
The weight of the package.
The unit of measure used for `weight`. See: [Weight Units](/merchant-api/units-of-measure#weight).
### Serial Number Properties
The "Serial ID" property.
The unique identifier of the serial number.
The SKU of the product associated with the serial number.
The ID of the product associated with the serial number.
### Shipment Custom Field
An object with a Custom Field code as the key and the Custom Field data as the value. The value format depends on the Custom Field input type.
`"custom_fields": { ... }`
To find out what fields are available see [Shipment Custom Fields](/merchant-api/shipment-custom-field) — `shipment_custom_field.list`
Maximum number of characters is 1024.
```json theme={null}
{ "main_sku" : { "value" : "product2" } }
```
```json theme={null}
{ "shipment_details" : { "value" : "Long multiline
shipment details
here." } }
```
```json theme={null}
{ "number_of_skus" : { "value" : 5 } }
```
```json theme={null}
{ "length_and_girth" : { "value" : 54.25 } }
```
```json theme={null}
{ "cost_of_goods" : { "amount" : 105.95 } }
```
Select input type data must be an object with `label` or `id` key or both.
```json theme={null}
{ "claim_reason" : { "id" : 13 } }
```
Preferred. An option is set by `id`.
```json theme={null}
{ "claim_reason" : { "label" : "Damaged in shipping" } }
```
An option is set by `label`.
```json theme={null}
{ "claim_reason" : { "id" : 13, "label" : "Damaged in shipping" } }
```
An option is set by `id` and `label`. The `id` and the `label` must refer to the same option.
Multi-select input type data must be an array of objects with `label` or `id` key or both.
```json theme={null}
{ "claim_reasons" : [ { "id" : 13 }, { "id" : 14 } ] }
```
Preferred. An option is set by `id`.
```json theme={null}
{ "claim_reasons" : [ { "label" : "Damaged in shipping" }, { "label" : "Did not fit" } ] }
```
An option is set by `label`.
```json theme={null}
{ "claim_reasons" : [ { "id" : 13, "label" : "Damaged in shipping" }, { "id" : 14, "label" : "Did not fit" } ] }
```
An option is set by `id` and `label`. The `id` and the `label` must refer to the same option.
```json theme={null}
{ "allow_mailer" : { "value" : true } }
```
Must be in `Y-m-d` format.
```json theme={null}
{ "desired_delivery_date" : { "value" : "2023-01-23" } }
```
Must be a client user id.
```json theme={null}
{ "created_by" : { "value" : 5 } }
```
Must be an admin user id.
```json theme={null}
{ "created_by" : { "value" : 7 } }
```
Must be a valid email address. Maximum number of characters is 1024.
```json theme={null}
{ "custom_email" : { "value" : "john.doe@example.com" } }
```
Must be a valid URL. Maximum number of characters is 1024.
```json theme={null}
{ "documentation_url" : { "value" : "https://example.com" } }
```
# Shipment Custom Fields
Source: https://docs.shipstream.io/merchant-api/shipment-custom-field
## Methods
* [shipment\_custom\_field.list](#shipment-custom-field-list)
***
## Entity Properties
* [Shipment Custom Field](#field-properties)
* [Shipment Custom Field Option](#option-properties)
***
## Additional Resources
* [Shipment Custom Fields](/merchant-api/shipment#shipment-custom-field) — when updating Shipment info.
***
## `shipment_custom_field.list`
`shipment_custom_field.list()`
Retrieve list of shipment custom fields available for the calling merchant.
### Return Value
An array of objects. Each object will contain [Shipment Custom Field](#field-properties) properties.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"34aa989befe360d67fe3f70b3517a1e5",
"shipment_custom_field.list"
]
}
```
### Example Response
```json title="Response" theme={null}
{
"result": [
{
"custom_field_id": "3",
"name": "Original Purchase Date",
"code": "purchase_date",
"is_active": "1",
"input_type": "date",
"is_required": "0",
"client_note": null,
"client_permissions": "restricted",
"display_client_grid": "parcel,freight",
"display_client_form": "parcel,freight",
"export_client_grid": "parcel,freight",
"sort_order": "0",
"created_at": "2022-07-01T10:46:16+00:00",
"updated_at": "2022-07-01T10:46:16+00:00"
},
{
"custom_field_id": "4",
"name": "Main Item SKU",
"code": "main_sku",
"is_active": "1",
"input_type": "text",
"is_required": "0",
"client_note": null,
"client_permissions": "unrestricted",
"display_client_grid": "parcel",
"display_client_form": "parcel",
"export_client_grid": "parcel",
"sort_order": "99",
"created_at": "2022-07-01T11:43:28+00:00",
"updated_at": "2022-07-01T11:43:28+00:00"
}
],
"id": "1234",
"jsonrpc": "2.0"
}
```
## Entity Properties
### Shipment Custom Field Properties
An automatically generated unique identifier for an Shipment Custom Field.
The "name" property.
The "code" property.
Flag whether Shipment Custom Field is active.
The "input\_type" property. Allowed values: "text", "multiline-text", "number", "currency", "select", "multiselect", "boolean", "date", "client-user", "admin-user", "email", "url".
Flag whether Shipment Custom Field is required.
The "client\_note" property.
The "unrestricted" property. Allowed values: "unrestricted", "restricted", "read-only", "hidden".
Determine in which client grid the Shipment Custom Field is displayed. Possible values include: "parcel," "freight," "parcel,freight," or an empty string "".
Determine in which client form the Shipment Custom Field is displayed. Possible values include: "parcel," "freight," "parcel,freight," or an empty string "".
Determine in which exported document the Shipment Custom Field is included. Possible values include: "parcel," "freight," "parcel,freight," or an empty string "".
The "sort\_order" property.
The "Created At" property.
The "Updated At" property.
Array of options. See [Option Properties](#option-properties).
### Shipment Custom Field Option Properties
The internal option ID.
The "Label" property.
Flag whether option is default.
The "Sort Order" property.
# Package
Source: https://docs.shipstream.io/merchant-api/shipment-package
There may be multiple packages for one shipment. Each package may have multiple tracking numbers, most packages will have only one tracking number.
## Methods
* [package.search](#package-search)
***
## Entity Properties
* [Package](#package-properties)
***
## `package.search`
`package.search(null|object $filters, array $options = [], null|string|object $fields = [])`
Retrieve list of packages by filters. Package data can be customized by specifying properties to retrieve.
### Parameters
* `null` - Retrieve list of all packages.
* `object` - Retrieve list of packages using specified [Search Filters](/merchant-api/search-filters).
* `null` - No options will be applied.
* `object` - Apply specified [Search Options](/merchant-api/search-options).
* `null` - Retrieve "shipment\_id", "order\_unique\_id" and "order\_ref".
* `string '*'` - Retrieve all properties excluding "items" and "tracking\_numbers".
* `object` - List of properties to retrieve in addition to "shipment\_id", "order\_unique\_id" and "order\_ref". List may include '\*'.
Example:
```json theme={null}
['*', 'package_status']
```
See [Package Properties](#package-properties).
## Entity Properties
### Package Properties
The internal package ID.
The "Shipment ID" property. This number may appear on the packing slip as the "Packing Slip #".
The "unique\_id" property for the order associated with this shipment.
The user-specified order "order\_ref" field.
The "Status" property. Allowed values: packing, tracking\_required, packed, manifested, shipped, delivered.
The "Updated At" property.
Date and time when the package was shipped from the warehouse in ISO 8601 format.
Date and time when the package was delivered in ISO 8601 format.
Array of [Package Item](#package-item-properties) objects.
The Serial Shipping Container Code.
Array of [Shipment Track](#track-properties) objects.
### Package Item Properties
The "SKU" property.
The "Name" property.
The "Weight" property.
The unit of measure used for `weight`. See: [Weight Units](/merchant-api/units-of-measure#weight).
The "Quantity" property.
The internal order item ID.
The "Package Data" property.
### Shipment Track Properties
The internal track ID.
The carrier code.
The carrier name.
The method description (without the carrier name).
The carrier's tracking number.
The date and time the tracking number was created.
SKUs and quantities of the related package items.
The weight of the package.
The unit of measure used for `weight`. See: [Weight Units](/merchant-api/units-of-measure#weight).
# Shipping Methods
Source: https://docs.shipstream.io/merchant-api/shipping-methods
The following shipping methods are supported by the API where a "shipping\_method" parameter is used. Some services may not be available on your account or in your area but all services are listed for completeness.
## FedEx Services
| Code | Description |
| :----------------------------- | :---------------------------- |
| fedex\_FIRST\_OVERNIGHT | FedEx First Overnight® |
| fedex\_PRIORITY\_OVERNIGHT | FedEx Priority Overnight® |
| fedex\_STANDARD\_OVERNIGHT | FedEx Standard Overnight® |
| fedex\_FEDEX\_2\_DAY\_AM | FedEx 2Day® A.M. |
| fedex\_FEDEX\_2\_DAY | FedEx 2Day® |
| fedex\_FEDEX\_EXPRESS\_SAVER | FedEx Express Saver® |
| fedex\_FEDEX\_GROUND | FedEx Ground® |
| fedex\_GROUND\_HOME\_DELIVERY | FedEx Home Delivery® |
| fedex\_SMART\_POST | FedEx SmartPost® |
| fedex\_INTERNATIONAL\_FIRST | FedEx International First® |
| fedex\_INTERNATIONAL\_PRIORITY | FedEx International Priority® |
| fedex\_INTERNATIONAL\_ECONOMY | FedEx International Economy® |
| fedex\_INTERNATIONAL\_GROUND | FedEx International Ground® |
## UPS Services
| Code | Description |
| :------ | :------------------------------------------ |
| ups\_01 | UPS Next Day Air |
| ups\_14 | UPS Next Day Air Early |
| ups\_13 | UPS Next Day Air Saver |
| ups\_02 | UPS 2nd Day Air |
| ups\_59 | UPS 2nd Day Air A.M. |
| ups\_12 | UPS 3 Day Select |
| ups\_03 | UPS Ground |
| ups\_11 | UPS Standard |
| ups\_08 | UPS Worldwide Expedited |
| ups\_07 | UPS Worldwide Express |
| ups\_54 | UPS Worldwide Express Plus |
| ups\_65 | UPS Worldwide Saver |
| ups\_72 | UPS Worldwide Economy DDP |
| ups\_17 | UPS Worldwide Economy DDU |
| ups\_SP | UPS SurePost |
| ups\_M2 | UPS First Class Mail Innovations |
| ups\_M3 | UPS Priority Mail Innovations |
| ups\_M4 | UPS Parcel Select Mail Innovations |
| ups\_M5 | UPS Priority Mail Innovations International |
| ups\_M6 | UPS Economy Mail Innovations International |
| ups\_70 | UPS Access Point™ Economy |
## USPS Methods
| Code | Description |
| :----------- | :--------------------------------------- |
| usps\_US-FC | USPS First-Class |
| usps\_US-FCI | USPS First-Class International |
| usps\_US-LM | USPS Library Mail |
| usps\_US-MM | USPS Media Mail |
| usps\_US-PS | USPS Ground Advantage |
| usps\_US-PM | USPS Priority Mail |
| usps\_US-PMI | USPS Priority Mail International |
| usps\_US-XM | USPS Priority Mail Express |
| usps\_US-EMI | USPS Priority Mail Express International |
## Amazon Merchant Fulfillment
| Code | Description |
| :------------------ | :-------------------------- |
| amazon\_ANY | Amazon Merchant Fulfillment |
| amazon\_Standard | Amazon Standard Delivery |
| amazon\_FreeEconomy | Amazon Free Economy |
| amazon\_SecondDay | Amazon Two-Day Delivery |
| amazon\_NextDay | Amazon One-Day Delivery |
| amazon\_Expedited | Amazon Expedited Delivery |
## OnTrac Services
| Code | Description |
| :--------- | :-------------- |
| ontrac\_S | OnTrac Sunrise |
| ontrac\_C | OnTrac Ground |
| ontrac\_DC | OnTrac Same Day |
## LaserShip Services
| Code | Description |
| :----------------- | :---------------- |
| lasership\_NextDay | LaserShip NextDay |
## GLS Services
| Code | Description |
| :-------------------------- | :--------------------------- |
| gls\_Ground | GLS Ground |
| gls\_PriorityOvernight | GLS Priority Overnight |
| gls\_EarlyPriorityOvernight | GLS Early Priority Overnight |
| gls\_EarlySaturday | GLS Early Saturday |
| gls\_SaturdayDelivery | GLS Saturday Delivery |
## "Cheapest" Methods
| Code | Description |
| :------------------- | :------------------------------------------------------------------------------------------------- |
| cheapest\_ALL | Cheapest method overall |
| cheapest\_GROUND | Cheapest ground shipping method |
| cheapest\_POSTAL | Cheapest USPS or USPS last-mile shipping method |
| cheapest\_THREE\_DAY | Cheapest 3-day shipping method |
| cheapest\_TWO\_DAY | Cheapest 2-day shippng method |
| cheapest\_OVERNIGHT | Cheapest overnight shipping method |
| cheapest\_ON\_TIME | Cheapest shipping method to arrive on-time. This requires valid "desired\_delivery\_date" as well. |
## Other
The External Shipping Methods are user defined whithin ShipStream. This list is not exhaustive, but instead exemplifies how all External Shipping Method codes are prefixed with `external_` . *For External Shipping Method codes used by your 3PL please contact your represintative.*
| Code | Description |
| :------------------------ | :---------------- |
| external\_ltl | LTL |
| external\_ltl\_thirdparty | LTL - Third Party |
# Stock Movements
Source: https://docs.shipstream.io/merchant-api/stock-movement
Stock Movements record every change to inventory items such as when an order is received and allocated to a warehouse or a shipment is picked from the shelf.
## Methods
* [stock\_movement.list](#stock-movement-list)
***
## Entity Properties
* [Stock Movement](#stock-movement-properties)
***
## `stock_movement.list`
`stock_movement.list (null|object $filters, null|object $options)`
Retrieve list of stock movements.
### Parameters
[Filters](/merchant-api/search-filters) to apply to the request. Allowed properties for filtering: "id", "entity\_type", "entity\_action", "entity\_id", "sku", "created\_at", "warehouse\_id", "location", "adjustment\_reason\_code", "hold\_reason\_code".
`hold_reason_code` filters by the rolled-up parent reason code on movements attributed to a governing hold and accepts the standard filter operators. Movements without a governing hold have a null hold reason, so a `null` condition also matches those movements. This field is filter-only and cannot be used as a `sort_field`.
[Options](/merchant-api/search-options) to apply to the request.
### Return Value
An array of [Stock Movements](#stock-movement-properties) or an empty array.
### Example Request
Get all stock movements:
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"stock_movement.list"
]
}
```
Get all stock movements for warehouse "2":
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"stock_movement.list",
[
{
"warehouse_id": {
"eq": "2"
}
}
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"result": {
"results": [
{
"id": "12",
"entity_type": "order",
"entity_action": "create",
"product_id": "4",
"qty_expected": null,
"qty_processed": null,
"qty_putaway": null,
"qty_available": "-1.0000",
"qty_allocated": "1.0000",
"qty_reserved": null,
"qty_picked": null,
"qty_backordered": null,
"qty_held": null,
"created_at": "2022-09-12T19:47:50+00:00",
"sku": "12-345-6789",
"comment": null,
"warehouse_id": "2",
"entity_id": "100000001",
"location": "",
"adjustment_reason_code": null,
"hold_reason_code": null,
"hold": null
},
{
"id": "13",
"entity_type": "hold",
"entity_action": "hold",
"product_id": "4",
"qty_expected": null,
"qty_processed": null,
"qty_putaway": null,
"qty_available": "-2.0000",
"qty_allocated": null,
"qty_reserved": null,
"qty_picked": null,
"qty_backordered": null,
"qty_held": "2.0000",
"created_at": "2026-07-13T10:15:00+00:00",
"sku": "12-345-6789",
"comment": null,
"warehouse_id": "2",
"entity_id": "A-01-02",
"location": "A-01-02",
"adjustment_reason_code": null,
"hold_reason_code": "qc_inspection",
"hold": {
"scope_type": "location",
"lot_id": 42,
"parent_hold_id": 731,
"reason": {
"code": "merchant_review",
"label": "Merchant Review",
"display_group": "Review"
}
}
}
],
"totalCount": 2,
"numPages": 1
},
"id": "1",
"jsonrpc": "2.0"
}
```
### Error Codes
| code | message |
| ---- | ------------------------------------------------ |
| 101 | Invalid filters given. Details in error message. |
## Entity Properties
### Stock Movement Properties
The internal stock movement ID.
The "Type" property. Allowed values: "delivery", "order", "work\_order", "stock", "relocation", "hold".
The "Action" property. Allowed values: "create", "edit", "cancel", "void", "adjust", "process", "unprocess", "putaway", "commit", "transfer", "ship", "unship", "pick", "unpick", "relocate", "pull", "push", "convert", "allocate", "deallocate", "correction", "assemble", "hold", "release".
The "Entity ID" property.
The internal product ID.
The "Product SKU" property.
The internal warehouse ID.
The "Expected" qty.
The "Processed" qty.
The "Put-Away" qty.
The "Available" qty.
The "Allocated" qty.
The "Reserved" qty.
The "Picked" qty.
The "Backordered" qty.
The "Held" qty. Populated on movements that affect held quantity; otherwise null.
The "Timestamp" property.
The "Comment" property.
The "Location" property.
The code of the structured Adjustment Reason recorded when an inventory adjustment was made (for example, a cycle count or manual correction). Allowed values: "cycle\_count", "found", "shrinkage", "damaged", "defective", "expired", "destroyed", "receiving\_error", "shipping\_error", "customer\_return", "sample", "other".
The rolled-up parent reason code for the movement's governing hold. User-defined reasons roll up to their parent system code (for example, a custom "Merchant Review" reason reports its parent "qc\_inspection"). Null when the movement has no governing hold. Filterable through the `hold_reason_code` filter using the standard filter operators.
Hold detail for the movement's governing hold; null when the movement has no governing hold.
The scope recorded on the movement's hold. Movement-producing holds currently use `location`; lot-scope sentinel holds do not create movement rows.
The internal lot ID recorded on the hold, or null when the held location is not associated with a lot.
The internal parent hold ID, or null for a direct location hold. This can reference a lot-scope sentinel that has no stock movement row, so it provides partial relationship metadata and does not guarantee that the complete hold tree can be reconstructed from this endpoint.
The specific hold reason applied to the movement. Null if the reason could not be resolved.
The exact hold reason code applied. This is the child reason and can differ from the top-level `hold_reason_code`, which rolls up to the parent system code.
The human-readable name of the hold reason.
The hold group the reason belongs to — one of the canonical English tokens ("Hold", "Review", "Expired", "Unsellable") or a custom group.
# Third Party Billing
Source: https://docs.shipstream.io/merchant-api/third-party-billing-group
A Third Party Billing Account Group represents a group of third party billing accounts. Each group can have one account per carrier/warehouse combination. Groups can be be assigned to an order using `order.options.tpb_group_id`.
## Methods
* [tpb\_group.list](#tpb-group-list)
***
## Entity Properties
* [Third Party Billing Account Group](#tpb-group-properties)
***
## `tpb_group.list`
`tpb_group.list()`
Retrieve a list of Third Party Billing Groups. Use the `tpb_group_id` to instruct an order to be shipped on the appropriate third party billing account within the group.
### Parameters
The method is used without parameters.
### Return Value
An array of objects. Each object will contain [Third Party Billing Group Properties](#tpb-group-properties).
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"tpb_group.list",
[]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : [
{
"tpb_group_id" : 73,
"label" : "TPB Group A",
"status" : "active",
"payment_types" : ["shipping"],
"pva_id" : null,
"ioss_id" : null,
"voec_id" : null
},
{
"tpb_group_id" : 74,
"label" : "TPB Group B",
"status" : "pending_approval",
"payment_types" : ["shipping", "duties_and_taxes"],
"pva_id" : "GB370241527",
"ioss_id" : "IM3720000960",
"voec_id" : "VOEC2036495"
}
]
}
```
## Entity Properties
### Third Party Billing Account Group Properties
An automatically generated unique identifier for a Third Party Billing Account Group.
A descriptive name to identify a Third Party Billing Account Group.
The status of the group. Possible values: `active`, `inactive`, `pending_approval`
The payment types of the group. Allowed payment types: `shipping`, `duties_and_taxes`
The PVA ID of the group.
The IOSS ID of the group.
The VOEC ID of the group.
# Units of Measure
Source: https://docs.shipstream.io/merchant-api/units-of-measure
The following units of measure are supported by the API for any property with a "\_unit" suffix. If a unit is not specified for a create or update operation then the default unit will be used.
## Weight
| Code | Description |
| :--- | :---------- |
| lb | Pounds |
| oz | Ounces |
| kg | Kilograms |
| g | Grams |
## Length
| Code | Description |
| :--- | :---------- |
| in | Inches |
| cm | Centimeters |
| mm | Millimeters |
## Volume
| Code | Description |
| :--- | :---------------------- |
| in^3 | Cubic inches (in³) |
| cm^3 | Cubic centimeters (cm³) |
| mm^3 | Cubic millimeters (mm³) |
## Dimensional Divisor
| Code | Description |
| :------ | :-------------------------------------- |
| in^3/lb | Cubic inches per pound (in³/lb) |
| in^3/oz | Cubic inches per ounce (in³/oz) |
| cm^3/kg | Cubic centimeters per kilogram (cm³/kg) |
| cm^3/g | Cubic centimeters per gram (cm³/g) |
| mm^3/kg | Cubic millimeters per kilogram (mm³/kg) |
| mm^3/g | Cubic millimeters per gram (mm³/g) |
# Warehouse
Source: https://docs.shipstream.io/merchant-api/warehouse
ShipStream supports multiple warehouses. Use this API endpoint to retrieve your list of warehouses.
## Methods
* [warehouse.list](#warehouse-list)
***
## Entity Properties
* [Warehouse](#warehouse-properties)
***
## `warehouse.list`
`warehouse.list()`
Retrieve warehouses list.
### Parameters
The method is used without parameters.
### Return Value
An array of objects with warehouse information.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"warehouse.list",
[]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : [
{
"warehouse_id" : 1,
"name" : "Warehouse 1",
"is_active": 1,
"address": {
"street1": "4616 Crossroads Park Dr",
"street2": "",
"city": "Liverpool",
"country": "US",
"region": "NY",
"postcode": "13088"
}
},
{
"warehouse_id" : 2,
"name" : "Warehouse 2",
"is_active": 1,
"address": {
"street1": "3900 Produce Rd",
"street2": "",
"city": "Louisville",
"country": "US",
"region": "KY",
"postcode": "40218"
}
}
]
}
```
## Entity Properties
### Warehouse Properties
The internal warehouse ID.
The "Name" property.
Flag whether warehouse is active.
The address of the warehouse. [Details](#warehouse-address-properties).
### Warehouse Address Properties
The street address. First Line
The street address. Second Line
The city.
The country code ISO 3166-1.
The region code ISO 3166-2.
The "Postal Code" property. Pass as a string to prevent leading 0s from being dropped.
# Webhook
Source: https://docs.shipstream.io/merchant-api/webhook
Use this API endpoint to register "webhooks" for various events such as when an order has completed or an inventory adjustment is made. A "webhook" subscribes to one or more [topics](/merchant-api/webhook-topics) and specifies a URL which event data will be sent via HTTP POST as events occur. See the [Topics](/merchant-api/webhook-topics) page for details on the available topics and the event details included.
## Authentication
Webhook authenticity can be verified by the `X-Plugin-Hmac-Sha256` HTTP header which is included with every webhook request. You can compare this header value with the HMAC generated locally to ensure that the request was not spoofed or modified in transit. The HMAC "message" is the entire request body and the HMAC "secret" is the `secret_key` associated with the webhook.
```php title="PHP Example" theme={null}
$json = file_get_contents('php://input');
$headerValue = $_SERVER['HTTP_X_PLUGIN_HMAC_SHA256'];
$expectedValue = base64_encode(hash_hmac('sha256', $json, $webhookSecretKey, TRUE));
if ($headerValue !== $expectedValue) {
http_response_code(401);
exit;
}
```
## Webhook Retry Intervals
Webhook retries occur for any non-20X response. There is a 3-second connect timeout and a 5-second overall timeout. ShipStream will make up to 14 retires. Each failed retry will be delayed. Instead of making the 15th attempt, ShipStream will mark the queued webhook call with the status "failed".
**Retry Intervals:**
* +1 minute
* +2 minutes
* +4 minutes
* +8 minutes
* +15 minutes
* +30 minutes
* +1 hour
* +2 hours
* +4 hours
* +8 hours
* +16 hours
* +24 hours
* +24 hours
* +24 hours
## Methods
* [webhook.list](#webhook-list)
* [webhook.create](#webhook-create)
* [webhook.update\_status](#webhookupdate-status)
* [webhook.delete](#webhook-delete)
***
## Entity Properties
* [Webhook](#webhook-properties)
***
## `webhook.list`
`webhook.list()`
Retrieve webhooks list.
### Parameters
The method is used without parameters.
### Return Value
An array of objects with webhook information.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"webhook.list",
[]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"error" : null,
"result" : [
{
"webhook_id" : 1,
"is_active" : 1,
"include_pcd" : 0,
"topics" : "order:created",
"url" : "http://example.com",
"extra_headers" : "",
"secret_key" : "2RUJ8NXLnLRrAj3"
}
]
}
```
***
## `webhook.create`
`webhook.create(object $webhookData)`
Create new webhook for a single or multiple [topics](/merchant-api/webhook-topics).
### Parameters
Webhook data.
### Return Value
`true` if webhook was successfully created.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"webhook.create",
[
{
"is_active" : 1,
"include_pcd" : 0,
"topics" : ["order:created","order:canceled"],
"url" : "http://example.com",
"extra_headers" : "",
"secret_key" : "2RUJ8NXLnLRrAj3"
}
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"error" : null,
"result" : true
}
```
### Error Codes
| code | message |
| ---- | -------------------------------------------------------- |
| 101 | Invalid data given. Details in error message. |
| 102 | An unexpected error occurred while creating the webhook. |
| 106 | Webhook not created. Details in error message. |
***
## `webhook.update_status`
`webhook.update_status(string $topic, number $status)`
Update webhook status.
### Parameters
Topic
Status. Allowed values: "0" - inactive or "1" - active.
### Return Value
`true` if status was successfully updated.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"webhook.update_status",
[
{
"status" : 1
}
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"error" : null,
"result" : true
}
```
### Error Codes
| code | message |
| ---- | ---------------------------------------------------------------------- |
| 100 | Error changing status for specified webhook. Details in error message. |
***
## `webhook.delete`
`webhook.delete(int $webhookId)`
Delete webhook.
### Parameters
Webhook Id.
### Return Value
`true` if webhook was successfully deleted.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"webhook.delete",
[
123
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"jsonrpc" : 2.0,
"error" : null,
"result" : true
}
```
### Error Codes
| code | message |
| ---- | -------------------------------------------------------- |
| 103 | Webhook not exists. |
| 104 | An unexpected error occurred while deleting the webhook. |
| 105 | Webhook not deleted. Details in error message. |
## Entity Properties
### Webhook Properties
The internal webhook ID.
Sequential ID of each payload so missed events can be detected easily.
Flag to determine whether the webhook is active. Allowed values: "0" - inactive or "1" - active.
Flag to determine whether Protected Customer Data (PCD) — such as the shipping address and contact info — is populated in the webhook payload. Allowed values: "0" - excluded (default) or "1" - included.
Either a string with one or more topics separated by commas or an array of topics which the webhook is subscribed to.
Url for the webhook callback.
Extra headers.
Secret Key is used for the webhook signature.
# Webhook Topics
Source: https://docs.shipstream.io/merchant-api/webhook-topics
This page lists the available topics to specify when subscribing to [Webhooks](/merchant-api/webhook) and provides examples for the event data which is sent via an HTTP POST request to the webhook url. "unique\_id" is deprecated and should not be used.
Some payload fields contain **Protected Customer Data (PCD)** — personal information such as customer
names, addresses, phone numbers, and email addresses. These fields are only included when the webhook
subscription has **Include PCD** enabled; otherwise they are omitted.
## Event Payloads
### `delivery:created`
```json title="Payload" theme={null}
{
"topic" : "delivery:created",
"message" : {
"merchant_code" : "acme",
"delivery_id" : 15,
"delivery_type" : "rma",
"increment_id" : "1000029",
"sender_name" : "Microsoft",
"sender_ref" : "00123456",
"sender_ref_alt" : "abc123",
"merchant_ref" : "xyz456",
"merchant_status" : null,
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
`sender_name` contains Protected Customer Data (PCD) for RMA deliveries and is only included when the webhook subscription has **Include PCD** enabled.
### `delivery:canceled`
```json title="Payload" theme={null}
{
"topic" : "delivery:canceled",
"message" : {
"merchant_code" : "acme",
"delivery_id" : 16,
"delivery_type" : "rma",
"increment_id" : "1000030",
"sender_name" : "Microsoft",
"sender_ref" : "00123456",
"sender_ref_alt" : "abc123",
"merchant_ref" : "xyz456",
"merchant_status" : null,
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
`sender_name` contains Protected Customer Data (PCD) for RMA deliveries and is only included when the webhook subscription has **Include PCD** enabled.
### `delivery:accepted`
```json title="Payload" theme={null}
{
"topic" : "delivery:accepted",
"message" : {
"merchant_code" : "acme",
"delivery_id" : 17,
"delivery_type" : "rma",
"increment_id" : "1000031",
"sender_name" : "Microsoft",
"sender_ref" : "00123456",
"sender_ref_alt" : "abc123",
"merchant_ref" : "xyz456",
"merchant_status" : null,
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
`sender_name` contains Protected Customer Data (PCD) for RMA deliveries and is only included when the webhook subscription has **Include PCD** enabled.
### `delivery:processed`
```json title="Payload" theme={null}
{
"topic" : "delivery:processed",
"message" : {
"merchant_code" : "acme",
"delivery_id" : 18,
"delivery_type" : "rma",
"increment_id" : "1000032",
"sender_name" : "Microsoft",
"sender_ref" : "00123456",
"sender_ref_alt" : "abc123",
"merchant_ref" : "xyz456",
"merchant_status" : null,
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
`sender_name` contains Protected Customer Data (PCD) for RMA deliveries and is only included when the webhook subscription has **Include PCD** enabled.
### `delivery:exception`
```json title="Payload" theme={null}
{
"topic" : "delivery:exception",
"message" : {
"merchant_code" : "acme",
"delivery_id" : 19,
"delivery_type" : "rma",
"increment_id" : "1000033",
"sender_name" : "Microsoft",
"sender_ref" : "00123456",
"sender_ref_alt" : "abc123",
"merchant_ref" : "xyz456",
"merchant_status" : null,
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
`sender_name` contains Protected Customer Data (PCD) for RMA deliveries and is only included when the webhook subscription has **Include PCD** enabled.
### `delivery:putaway`
```json title="Payload" theme={null}
{
"topic" : "delivery:putaway",
"message" : {
"merchant_code" : "acme",
"delivery_id" : 20,
"delivery_type" : "rma",
"increment_id" : "1000034",
"sender_name" : "Microsoft",
"sender_ref" : "00123456",
"sender_ref_alt" : "abc123",
"merchant_ref" : "xyz456",
"merchant_status" : null,
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
`sender_name` contains Protected Customer Data (PCD) for RMA deliveries and is only included when the webhook subscription has **Include PCD** enabled.
### `delivery:committed`
```json title="Payload" theme={null}
{
"topic" : "delivery:committed",
"message" : {
"merchant_code" : "acme",
"delivery_id" : 21,
"delivery_type" : "rma",
"increment_id" : "1000035",
"sender_name" : "Microsoft",
"sender_ref" : "00123456",
"sender_ref_alt" : "abc123",
"merchant_ref" : "xyz456",
"merchant_status" : null,
"stock_adjustments" : {
"MINT-12" : {
"sku" : "MINT-12",
"external_id" : null,
"product_id" : 7,
"qty_adjust" : 12,
"qty_available" : 102,
"qty_advertised" : 102,
"details" : [
{
"lot_id" : 67,
"qty_adjust" : "12.0000"
}
]
}
},
"closed_at" : "2026-07-13T09:08:40+00:00",
"containers" : [
{
"container_id" : 31,
"delivery_id" : 21,
"container_type_id" : 1,
"damage_type" : "none",
"weight_discrepancy" : "none",
"tare_weight" : 5,
"weighed_at" : "2026-07-13T09:08:38+00:00",
"weighed_by" : 12,
"notes" : "Inbound pallet",
"weight" : 33,
"tare_weight_unit" : "lb",
"weight_unit" : "lb",
"contents" : [
{
"delivery_item_id" : 44,
"qty_counted" : "12.0000",
"qty_shortage" : "0.0000",
"lots" : [
{
"lot_id" : 67,
"qty_counted" : "12.0000",
"qty_shortage" : "0.0000",
"qty_processed" : "12.0000",
"qty_putaway" : "12.0000",
"qty_committed" : "12.0000"
}
]
}
]
}
],
"webhook_increment_id" : 1,
"event_timestamp" : "2026-07-13T09:08:40+00:00"
}
}
```
The `containers` property is included on every `delivery:committed` and `delivery:complete` event, although the array can be empty. Each entry follows the existing [Delivery Container Properties](/merchant-api/delivery#container-properties) structure.
The webhook payload is generated asynchronously shortly after the event occurs, so `containers` is a snapshot of the delivery's committed state at generation time — not the exact instant the event fired. Changes made in that brief window (for example, an overage exception approved right after commit) are reflected in the payload, so it may not byte-match a `delivery.search` response captured at a different moment.
Non-lot content returns `lots: []`. Container content and lot quantity values are formatted decimal strings, such as `"12.0000"`. For lot-tracked content, webhook lot entries add `qty_processed`, `qty_putaway`, and `qty_committed` to `lot_id`, `qty_counted`, and `qty_shortage`. These three commit quantities are webhook-only and are not added to the `delivery.search` container lot response. A pending overage-only lot is omitted while all of its reported quantities are zero; after the overage is approved, the lot can appear with its processed quantity.
`sender_name` contains Protected Customer Data (PCD) for RMA deliveries and is only included when the webhook subscription has **Include PCD** enabled.
### `delivery:complete`
`delivery:complete` uses the same enriched container snapshot as `delivery:committed`. Its existing header does not include `delivery_type`.
```json title="Payload" theme={null}
{
"topic" : "delivery:complete",
"message" : {
"merchant_code" : "acme",
"delivery_id" : 21,
"increment_id" : "1000035",
"sender_name" : "Microsoft",
"sender_ref" : "00123456",
"sender_ref_alt" : "abc123",
"merchant_ref" : "xyz456",
"merchant_status" : null,
"stock_adjustments" : [],
"closed_at" : "2026-07-13T09:08:40+00:00",
"containers" : [
{
"container_id" : 31,
"delivery_id" : 21,
"container_type_id" : 1,
"damage_type" : "none",
"weight_discrepancy" : "none",
"tare_weight" : 5,
"weighed_at" : "2026-07-13T09:08:38+00:00",
"weighed_by" : 12,
"notes" : "Inbound pallet",
"weight" : 33,
"tare_weight_unit" : "lb",
"weight_unit" : "lb",
"contents" : [
{
"delivery_item_id" : 44,
"qty_counted" : "12.0000",
"qty_shortage" : "0.0000",
"lots" : [
{
"lot_id" : 67,
"qty_counted" : "12.0000",
"qty_shortage" : "0.0000",
"qty_processed" : "12.0000",
"qty_putaway" : "12.0000",
"qty_committed" : "12.0000"
}
]
}
]
}
],
"webhook_increment_id" : 2,
"event_timestamp" : "2026-07-13T09:08:40+00:00"
}
}
```
`sender_name` contains Protected Customer Data (PCD) for RMA deliveries and is only included when the webhook subscription has **Include PCD** enabled.
### `delivery:status_changed`
```json title="Payload" theme={null}
{
"topic" : "delivery:status_changed",
"message" : {
"merchant_code" : "acme",
"delivery_id" : 22,
"delivery_type" : "rma",
"increment_id" : "1000036",
"sender_name" : "Microsoft",
"sender_ref" : "00123456",
"sender_ref_alt" : "abc123",
"merchant_ref" : "xyz456",
"merchant_status" : null,
"old_status" : "putting_away",
"new_status" : "put_away",
"old_state" : "putting_away",
"new_state" : "complete",
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
`sender_name` contains Protected Customer Data (PCD) for RMA deliveries and is only included when the webhook subscription has **Include PCD** enabled.
### `delivery_label:created`
```json title="Payload" theme={null}
{
"topic" : "delivery_label:created",
"message" : {
"merchant_code" : "acme",
"unique_id" : 5,
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
### `delivery_label:voided`
```json title="Payload" theme={null}
{
"topic" : "delivery_label:voided",
"message" : {
"merchant_code" : "acme",
"unique_id" : 7,
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
### `import:created`
```json title="Payload" theme={null}
{
"topic" : "import:created",
"message" : {
"merchant_code" : "acme",
"unique_id" : 4,
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
### `import:completed`
```json title="Payload" theme={null}
{
"topic" : "import:completed",
"message" : {
"merchant_code" : "acme",
"unique_id" : 5,
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
### `inventory:adjusted`
```json title="Payload" theme={null}
{
"topic" : "inventory:adjusted",
"message" : {
"merchant_code" : "acme",
"stock_adjustments" : {
"sku123" : {
"sku" : "sku123",
"external_id" : null,
"product_id" : 7,
"qty_adjust" : "5.0000",
"qty_available": 95,
"qty_advertised": 95,
"details" : [
{
"lot_id" : 123,
"qty_adjust" : "10.0000",
"adjustment_reason_code" : "found"
},
{
"lot_id" : 124,
"qty_adjust" : "-6.0000",
"hold_reason_code" : "quality_review",
"qty_held" : "6.0000"
},
{
"lot_id" : null,
"qty_adjust" : "1.0000"
}
]
}
},
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
Stock adjustments are also included when adjusting a Bill of Materials (BOM) component changes a related product's virtual inventory. Adjustments caused only by virtual inventory omit `qty_adjust` and include only absolute values.
#### Stock adjustment details
The optional `details` array breaks `qty_adjust` down by lot and adjustment or hold reason. The same structure can appear in `inventory:adjusted`, `delivery:committed`, and `delivery:complete` payloads, as well as other topics that include `stock_adjustments`.
| Field | Type | Description |
| ------------------------ | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `lot_id` | integer or null | The ShipStream lot ID. A null value represents quantity that is not attributed to a lot. Lot numbers, expiration dates, and other lot metadata are not included. |
| `qty_adjust` | string | The quantity attributed to this detail, formatted to four decimal places. |
| `adjustment_reason_code` | string | The inventory adjustment reason. This field and `hold_reason_code` are mutually exclusive. |
| `hold_reason_code` | string or null | The inventory hold reason. This field and `adjustment_reason_code` are mutually exclusive. |
| `qty_held` | string | The held-quantity change. This field appears only on hold or release details. |
Details use `(lot_id, reason namespace, reason code)` as their aggregation key. The reason namespace is either `adjustment_reason_code` or `hold_reason_code`. Entries with the same key are combined. Entries for different lots or reasons remain separate, even when they offset one another, and a keyed entry remains present when its combined `qty_adjust` is `0.0000`.
When `details` is present, the sum of every detail's `qty_adjust` equals the stock adjustment's top-level `qty_adjust`. ShipStream adds a null-lot, reasonless detail when it needs to represent a residual quantity. If an adjustment has no lot or reason breakdown, `details` is omitted.
### `inventory:advertised_changed`
Sent after a committed transaction changes the advertised quantity of one or more products. Use this topic to synchronize the quantity available for sale without inferring advertised inventory changes from order, delivery, hold, or adjustment events.
```json title="Payload" theme={null}
{
"topic" : "inventory:advertised_changed",
"message" : {
"merchant_code" : "acme",
"changes" : [
{
"product_id" : 7,
"sku" : "sku123",
"external_id" : null,
"qty_advertised_was" : 100,
"qty_advertised" : 94,
"warehouses" : [
{
"warehouse_id" : 1,
"qty_advertised_was" : 60,
"qty_advertised" : 54
}
],
"holds" : [
{
"hold_id" : 321,
"action" : "placed",
"reason_code" : "quality_review",
"lot_id" : 123,
"lot_number" : "LOT-2026-001",
"warehouse_id" : 1,
"qty_available" : "-6.0000",
"qty_held" : "6.0000"
}
]
}
],
"webhook_increment_id" : 1,
"event_timestamp" : "2026-08-06T10:15:30+00:00"
}
}
```
Each change reports the first captured quantity and the final quantity for one product in the transaction. Intermediate changes are combined. A transaction that finishes with no net advertised quantity change at either the merchant or warehouse level does not emit this topic.
The `changes` array contains up to 500 products. A transaction that changes more than 500 products produces multiple webhook events.
#### Advertised inventory change fields
| Field | Type | Description |
| -------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `product_id` | integer | The internal product ID. |
| `sku` | string | The product SKU. |
| `external_id` | string or null | The merchant-supplied external product ID, or `null` when one is not set. |
| `qty_advertised_was` | integer or null | The merchant-level advertised quantity before the transaction. This is `null` when the advertised inventory record was created by the transaction. |
| `qty_advertised` | integer | The merchant-level advertised quantity after the transaction. |
| `warehouses` | array | The warehouses whose advertised quantity changed. The array is empty when only the merchant-level quantity changed. |
| `holds` | array | Hold operations associated with the advertised quantity change. |
The merchant-level quantity can remain unchanged while warehouse quantities change, such as when inventory moves between warehouses. In that case, `qty_advertised_was` and `qty_advertised` are equal, and `warehouses` identifies each changed warehouse.
#### Warehouse change fields
| Field | Type | Description |
| -------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `warehouse_id` | integer | The internal warehouse ID. |
| `qty_advertised_was` | integer or null | The warehouse's advertised quantity before the transaction. This is `null` when the advertised inventory record was created by the transaction. |
| `qty_advertised` | integer | The warehouse's advertised quantity after the transaction. |
#### Hold context fields
The optional `holds` array describes hold placements and releases that occurred in the same transaction and affected the product's advertised quantity.
| Field | Type | Description |
| --------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hold_id` | integer | The internal inventory hold ID. |
| `action` | string | The hold operation: `placed` or `released`. |
| `reason_code` | string | The parent [hold reason](/merchant-api/inventory#hold-reason-properties) code. User-defined sub-reasons are reported as their parent reason code. |
| `lot_id` | integer or null | The internal ID of the lot attributed to the affected inventory, or `null` when the inventory is not attributed to a lot. |
| `lot_number` | string or null | The lot number, or `null` when the inventory is not attributed to a lot. |
| `warehouse_id` | integer | The internal warehouse ID where the hold was placed or released. |
| `qty_available` | string | The available-quantity change caused by the hold operation, formatted to four decimal places. A placement is negative, and a release is positive. |
| `qty_held` | string | The signed held-quantity change, formatted to four decimal places. A placement is positive, and a release is negative. |
#### Event boundaries and attribution
Each committed inventory transaction is reported independently. One API request or warehouse operation can therefore produce multiple events when it commits an inventory change and then recalculates virtual inventory in a follow-up transaction.
The `holds` array is contributing context rather than a complete inventory-change audit. It includes hold placements and releases when that context is available to the transaction. Advertised changes caused by allocation, reallocation, Work Orders, or virtual-inventory calculations do not include hold or Lot attribution. The `lot_id` and `lot_number` fields identify a contributing hold; they do not represent per-Lot advertised quantities.
### `order:created`
```json title="Payload" theme={null}
{
"topic" : "order:created",
"message" : {
"merchant_code" : "acme",
"brand_code" : "default",
"unique_id" : "100000015",
"order_ref" : "9099",
"source" : null,
"shipping_address" : {
"firstname" : "John",
"lastname" : "Doe",
"company" : "ACME",
"street" : "123 ACME BIG STREET",
"city" : "New York",
"region" : "NY",
"postcode" : "99999",
"country" : "US",
"classification" : "com",
"is_valid" : true,
"telephone" : "865999999",
"email" : "john.doe@example.com"
},
"stock_adjustments" : {
"sku123" : {
"sku" : "sku123",
"external_id" : null,
"product_id" : 7,
"qty_adjust" : -5,
"qty_available": 95,
"qty_advertised": 95
}
},
"items" : [
{
"sku" : "product1",
"name" : "product1",
"qty_ordered" : "2.0000",
"qty_backordered" : "0.0000",
"qty_canceled" : "0.0000",
"qty_processing" : "0.0000",
"qty_shipped" : "0.0000",
"unit_declared_value" : null,
"unit_declared_value_currency" : "USD",
"unit_customs_value" : null,
"unit_customs_value_currency" : "USD",
"gift_message" : null,
"weight" : "5.800000",
"row_weight" : "11.600000",
"allocation_data" : [
{
"warehouse_id" : "2",
"qty_allocated" : "2.0000"
}
],
"order_item_id" : "230",
"order_item_ref" : null,
"weight_unit" : "lb",
"row_weight_unit" : "lb"
},
{
"sku" : "product3",
"name" : "product3",
"qty_ordered" : "7.0000",
"qty_backordered" : "1.0000",
"qty_canceled" : "0.0000",
"qty_processing" : "0.0000",
"qty_shipped" : "0.0000",
"unit_declared_value" : null,
"unit_declared_value_currency" : "USD",
"gift_message" : null,
"unit_customs_value" : null,
"unit_customs_value_currency" : "USD",
"weight" : "0.200000",
"row_weight" : "1.400000",
"allocation_data" : [
{
"warehouse_id" : "1",
"qty_allocated" : "2.0000"
},
{
"warehouse_id" : "2",
"qty_allocated" : "4.0000"
}
],
"order_item_id" : "232",
"order_item_ref" : null,
"weight_unit" : "lb",
"row_weight_unit" : "lb"
}
],
"webhook_increment_id" : 2,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
`shipping_address` contains Protected Customer Data (PCD) and is only included when the webhook subscription has **Include PCD** enabled.
### `order:canceled`
```json title="Payload" theme={null}
{
"topic" : "order:canceled",
"message" : {
"merchant_code" : "acme",
"brand_code" : "default",
"unique_id" : "100000016",
"order_ref" : "9099",
"source" : null,
"shipping_address" : {
"firstname" : "John",
"lastname" : "Doe",
"company" : "ACME",
"street" : "123 ACME BIG STREET",
"city" : "New York",
"region" : "NY",
"postcode" : "99999",
"country" : "US",
"classification" : "com",
"is_valid" : true,
"telephone" : "865999999",
"email" : "john.doe@example.com"
},
"stock_adjustments" : {
"sku123" : {
"sku" : "sku123",
"external_id" : null,
"product_id" : 7,
"qty_adjust" : 5,
"qty_available": 95,
"qty_advertised": 95
}
},
"shipments": [ {"unique_id" : "100000026"} ],
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
`shipping_address` contains Protected Customer Data (PCD) and is only included when the webhook subscription has **Include PCD** enabled.
### `order:items_updated`
```json title="Payload" theme={null}
{
"topic": "order:items_updated",
"message": {
"merchant_code": "acme",
"brand_code": "default",
"unique_id": "100000022",
"order_ref": "9099",
"source": null,
"shipping_address": {
"firstname": "John",
"lastname": "Doe",
"company": "ACME",
"street": "123 ACME BIG STREET",
"city": "New York",
"region": "NY",
"postcode": "99999",
"country": "US",
"classification": "com",
"is_valid": true,
"telephone": "865999999",
"email": "john.doe@example.com"
},
"items_canceled": [
{
"sku": "product1",
"order_item_id": "215",
"qty_canceled": "1.0000"
}
],
"items_remaining": [
{
"sku": "product2",
"name": "product2",
"qty_ordered": "1.0000",
"qty_backordered": "0.0000",
"qty_canceled": "0.0000",
"qty_processing": "0.0000",
"qty_shipped": "1.0000",
"unit_declared_value": null,
"unit_declared_value_currency": "USD",
"unit_customs_value": null,
"unit_customs_value_currency": "USD",
"weight": "5.800000",
"row_weight": "5.800000",
"package_data": [
{
"label": "Serial Number - 8 Characters",
"value": "12345ABC"
}
],
"allocation_data": [
{
"warehouse_id": "2",
"qty_allocated": "0.0000"
}
],
"order_item_id": "214",
"order_item_ref": null,
"weight_unit": "lb",
"row_weight_unit": "lb"
}
],
"webhook_increment_id": 1,
"event_timestamp": "2021-12-07T16:08:15+00:00"
}
}
```
`shipping_address` contains Protected Customer Data (PCD) and is only included when the webhook subscription has **Include PCD** enabled.
### `order:holded`
```json title="Payload" theme={null}
{
"topic" : "order:holded",
"message" : {
"merchant_code" : "acme",
"brand_code" : "default",
"unique_id" : "100000017",
"order_ref" : "9099",
"source" : null,
"shipping_address" : {
"firstname" : "John",
"lastname" : "Doe",
"company" : "ACME",
"street" : "123 ACME BIG STREET",
"city" : "New York",
"region" : "NY",
"postcode" : "99999",
"country" : "US",
"classification" : "com",
"is_valid" : true,
"telephone" : "865999999",
"email" : "john.doe@example.com"
},
"webhook_increment_id" : 3,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
`shipping_address` contains Protected Customer Data (PCD) and is only included when the webhook subscription has **Include PCD** enabled.
### `order:completed`
```json title="Payload" theme={null}
{
"topic" : "order:completed",
"message" : {
"merchant_code" : "acme",
"brand_code" : "default",
"unique_id" : "100000020",
"order_ref" : "9099",
"source" : null,
"shipping_address" : {
"firstname" : "John",
"lastname" : "Doe",
"company" : "ACME",
"street" : "123 ACME BIG STREET",
"city" : "New York",
"region" : "NY",
"postcode" : "99999",
"country" : "US",
"classification" : "com",
"is_valid" : true,
"telephone" : "865999999",
"email" : "john.doe@example.com"
},
"webhook_increment_id" : 5,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
`shipping_address` contains Protected Customer Data (PCD) and is only included when the webhook subscription has **Include PCD** enabled.
### `order:shipped`
```json title="Payload" theme={null}
{
"topic" : "order:shipped",
"message" : {
"merchant_code" : "acme",
"brand_code" : "default",
"unique_id" : "100000022",
"order_ref" : "9099",
"source" : null,
"shipping_address" : {
"firstname" : "John",
"lastname" : "Doe",
"company" : "ACME",
"street" : "123 ACME BIG STREET",
"city" : "New York",
"region" : "NY",
"postcode" : "99999",
"country" : "US",
"classification" : "com",
"is_valid" : true,
"telephone" : "865999999",
"email" : "john.doe@example.com"
},
"shipments" : [
{
"unique_id" : "100000033",
"warehouse_id": 1,
"carrier": "fedex",
"status" : "shipped",
"service": "GROUND_HOME_DELIVERY",
"trackers" : [{
"tracker_id" : 4,
"status" : "in_transit",
"carrier" : "fedex",
"tracking_number" : "794657040105",
"carrier_tracking_url" : "https://www.fedex.com/apps/fedextrack/?action=track&tracknumbers=794657040105",
"est_delivery_at" : "2021-10-05T00:00:00-04:00",
"is_est_delivery_at_date" : true,
"original_est_delivery_at" : "2021-10-05T00:00:00-04:00",
"is_original_est_delivery_at_date" : true,
"delivered_at" : null,
"signed_by" : null
}]
}
],
"webhook_increment_id" : 1,
"event_timestamp": "2023-05-15T17:28:28+00:00"
}
}
```
`shipping_address` contains Protected Customer Data (PCD) and is only included when the webhook subscription has **Include PCD** enabled.
### `order:delivered`
```json title="Payload" theme={null}
{
"topic" : "order:delivered",
"message" : {
"merchant_code" : "acme",
"brand_code" : "default",
"unique_id" : "100000022",
"order_ref" : "9099",
"source" : null,
"shipping_address" : {
"firstname" : "John",
"lastname" : "Doe",
"company" : "ACME",
"street" : "123 ACME BIG STREET",
"city" : "New York",
"region" : "NY",
"postcode" : "99999",
"country" : "US",
"classification" : "com",
"is_valid" : true,
"telephone" : "865999999",
"email" : "john.doe@example.com"
},
"shipments" : [
{
"unique_id" : "100000033",
"warehouse_id": 1,
"carrier": "fedex",
"status" : "delivered",
"service": "GROUND_HOME_DELIVERY",
"trackers" : [{
"tracker_id" : 4,
"status" : "delivered",
"carrier" : "fedex",
"tracking_number" : "794657040105",
"carrier_tracking_url" : "https://www.fedex.com/apps/fedextrack/?action=track&tracknumbers=794657040105",
"est_delivery_at" : "2021-10-07T00:00:00-04:00",
"is_est_delivery_at_date" : true,
"original_est_delivery_at" : "2021-10-05T00:00:00-04:00",
"is_original_est_delivery_at_date" : true,
"delivered_at" : "2021-12-07T12:08:15-04:00",
"signed_by" : "J. Smith"
}]
}
],
"webhook_increment_id" : 1,
"event_timestamp": "2023-05-15T17:28:28+00:00"
}
}
```
`shipping_address` contains Protected Customer Data (PCD) and is only included when the webhook subscription has **Include PCD** enabled.
### `order:address_validation_failed`
```json title="Payload" theme={null}
{
"topic" : "order:address_validation_failed",
"message" : {
"merchant_code" : "acme",
"brand_code" : "default",
"unique_id" : "100000021",
"order_ref" : "9099",
"source" : null,
"shipping_address" : {
"firstname" : "John",
"lastname" : "Doe",
"company" : "ACME",
"street" : "123 ACME BIG STREET",
"city" : "New York",
"region" : "NY",
"postcode" : "99999",
"country" : "US",
"classification" : "com",
"is_valid" : false,
"telephone" : "865999999",
"email" : "john.doe@example.com"
},
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
`shipping_address` contains Protected Customer Data (PCD) and is only included when the webhook subscription has **Include PCD** enabled.
### `order:address_changed`
```json title="Payload" theme={null}
{
"topic" : "order:address_changed",
"message" : {
"merchant_code" : "acme",
"brand_code" : "default",
"unique_id" : "100000021",
"order_ref" : "9099",
"source" : null,
"old_status" : "new",
"status" : "new",
"old_state" : "new",
"state" : "new",
"old_address" : {
"firstname" : "John",
"lastname" : "Doe",
"company" : "ACME",
"street" : "123 ACME BIG STREET",
"city" : "New York",
"region" : "NY",
"postcode" : "99999",
"country" : "US",
"classification" : "com",
"is_valid" : true,
"telephone" : "865999999",
"email" : "john.doe@example.com"
},
"address" : {
"firstname" : "John",
"lastname" : "Doe",
"company" : "ACME",
"street" : "321 ACME BIG STREET",
"city" : "New York",
"region" : "NY",
"postcode" : "98765",
"country" : "US",
"classification" : "com",
"is_valid" : true,
"telephone" : "865999999",
"email" : "john.doe@gmail.com"
},
"update_method" : "manual",
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
`old_address` and `address` contain Protected Customer Data (PCD) and are only included when the webhook subscription has **Include PCD** enabled.
### `order:status_changed`
```json title="Payload" theme={null}
{
"topic" : "order:status_changed",
"message" : {
"merchant_code" : "acme",
"brand_code" : "default",
"unique_id" : "100000022",
"order_ref" : "9099",
"source" : null,
"shipping_address" : {
"firstname" : "John",
"lastname" : "Doe",
"company" : "ACME",
"street" : "123 ACME BIG STREET",
"city" : "New York",
"region" : "NY",
"postcode" : "99999",
"country" : "US",
"classification" : "com",
"is_valid" : true,
"telephone" : "865999999",
"email" : "john.doe@example.com"
},
"old_status" : null,
"status" : "new",
"old_state" : null,
"state" : "new",
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
`shipping_address` contains Protected Customer Data (PCD) and is only included when the webhook subscription has **Include PCD** enabled.
### `order:shipments_updated`
```json title="Payload" theme={null}
{
"topic" : "order:shipments_updated",
"message" : {
"merchant_code" : "acme",
"brand_code" : "default",
"unique_id" : "100000022",
"order_ref" : "9099",
"source" : null,
"shipping_address" : {
"firstname" : "John",
"lastname" : "Doe",
"company" : "ACME",
"street" : "123 ACME BIG STREET",
"city" : "New York",
"region" : "NY",
"postcode" : "99999",
"country" : "US",
"classification" : "com",
"is_valid" : true,
"telephone" : "865999999",
"email" : "john.doe@example.com"
},
"shipments" : [
{
"unique_id" : "100000033",
"warehouse_id": 1,
"carrier": "fedex",
"service": "GROUND_HOME_DELIVERY"
}
],
"webhook_increment_id" : 1,
"event_timestamp": "2023-05-15T17:28:28+00:00"
}
}
```
`shipping_address` contains Protected Customer Data (PCD) and is only included when the webhook subscription has **Include PCD** enabled.
### `order:shipping_options_changed`
```json title="Payload" theme={null}
{
"topic" : "order:shipping_options_changed",
"message" : {
"merchant_code" : "acme",
"brand_code" : "default",
"unique_id" : "100000022",
"order_ref" : "9099",
"source" : null,
"shipping_address" : {
"firstname" : "John",
"lastname" : "Doe",
"company" : "ACME",
"street" : "123 ACME BIG STREET",
"city" : "New York",
"region" : "NY",
"postcode" : "99999",
"country" : "US",
"classification" : "com",
"is_valid" : true,
"telephone" : "865999999",
"email" : "john.doe@example.com"
},
"status" : "partial_backorder",
"state" : "processing",
"shipping_options" : {
"saturday_delivery" : true
},
"old_shipping_options" : {
"saturday_delivery" : false
},
"webhook_increment_id" : 1,
"event_timestamp": "2023-05-15T17:28:28+00:00"
}
}
```
`shipping_address` contains Protected Customer Data (PCD) and is only included when the webhook subscription has **Include PCD** enabled.
### `product:created`
```json title="Payload" theme={null}
{
"topic" : "product:created",
"message" : {
"merchant_code" : "acme",
"sku" : "product1",
"external_id" : null,
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
### `product:updated`
```json title="Payload" theme={null}
{
"topic" : "product:updated",
"message" : {
"merchant_code" : "acme",
"sku" : "product1",
"external_id" : null,
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
### `product:sku_changed`
```json title="Payload" theme={null}
{
"topic" : "product:sku_changed",
"message" : {
"merchant_code" : "acme",
"sku" : "product1",
"external_id" : null,
"old_sku": "344828-22",
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
### `product:deleted`
```json title="Payload" theme={null}
{
"topic" : "product:deleted",
"message" : {
"merchant_code" : "acme",
"sku" : "product1",
"external_id" : null,
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
### `product_media:created`
```json title="Payload" theme={null}
{
"topic" : "product_media:created",
"message" : {
"merchant_code" : "acme",
"sku" : "product1",
"external_id" : null,
"webhook_increment_id" : 3,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
### `product_media:updated`
```json title="Payload" theme={null}
{
"topic" : "product_media:updated",
"message" : {
"merchant_code" : "acme",
"sku" : "product1",
"external_id" : null,
"webhook_increment_id" : 3,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
### `product_media:deleted`
```json title="Payload" theme={null}
{
"topic" : "product_media:deleted",
"message" : {
"merchant_code" : "acme",
"sku" : "product1",
"external_id" : null,
"webhook_increment_id" : 5,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
### `serial_number:created`
```json title="Payload" theme={null}
{
"topic" : "serial_number:created",
"message" : {
"merchant_code" : "acme",
"serial_id" : 234,
"identifier" : "123456123456",
"product_id" : 7,
"sku" : "sku123",
"created_at" : "2024-10-22T16:08:15+00:00",
"warehouse_id" : 1,
"old_status" : "unknown",
"new_status" : "received",
"old_availability" : "checked_out",
"new_availability" : "pending",
"old_location" : null,
"old_location_id" : null,
"new_location" : null,
"new_location_id" : null,
"target_type" : "asn",
"target_id" : 15,
"target_description" : "1000029",
"target_child_type" : "container",
"target_child_id" : 16,
"target_child_description" : "Pallet 1",
"package_id" : null,
"webhook_increment_id" : 1,
"event_timestamp" : "2024-10-22T16:08:15+00:00"
}
}
```
### `serial_number:updated`
```json title="Payload" theme={null}
{
"topic" : "serial_number:updated",
"message" : {
"merchant_code" : "acme",
"serial_id" : 234,
"identifier" : "123456123456",
"product_id" : 7,
"sku" : "sku123",
"created_at" : "2024-10-22T16:08:15+00:00",
"warehouse_id" : 1,
"old_status" : "received",
"new_status" : "located",
"old_availability" : "pending",
"new_availability" : "available",
"old_location" : null,
"old_location_id" : null,
"new_location" : "A-2",
"new_location_id" : 224,
"target_type" : "asn",
"target_id" : 15,
"target_description" : "1000029",
"target_child_type" : "container",
"target_child_id" : 16,
"target_child_description" : "Pallet 1",
"package_id" : null,
"webhook_increment_id" : 1,
"event_timestamp" : "2024-10-22T16:45:13+00:00"
}
}
```
### `serial_number:checkin`
```json title="Payload" theme={null}
{
"topic" : "serial_number:checkin",
"message" : {
"merchant_code" : "acme",
"serial_id" : 234,
"identifier" : "123456123456",
"product_id" : 7,
"sku" : "sku123",
"created_at" : "2024-10-22T16:08:15+00:00",
"warehouse_id" : 1,
"old_status" : "unknown",
"new_status" : "received",
"old_availability" : "checked_out",
"new_availability" : "pending",
"old_location" : null,
"old_location_id" : null,
"new_location" : null,
"new_location_id" : null,
"target_type" : "asn",
"target_id" : 15,
"target_description" : "1000029",
"target_child_type" : "container",
"target_child_id" : 16,
"target_child_description" : "Pallet 1",
"package_id" : null,
"webhook_increment_id" : 1,
"event_timestamp" : "2024-10-22T16:08:15+00:00"
}
}
```
### `serial_number:checkout`
```json title="Payload" theme={null}
{
"topic" : "serial_number:checkout",
"message" : {
"merchant_code" : "acme",
"serial_id" : 234,
"identifier" : "123456123456",
"product_id" : 7,
"sku" : "sku123",
"created_at" : "2024-10-22T16:08:15+00:00",
"warehouse_id" : 1,
"old_status" : "packed",
"new_status" : "shipped",
"old_availability" : "pending",
"new_availability" : "checked_out",
"old_location" : null,
"old_location_id" : null,
"new_location" : null,
"new_location_id" : null,
"target_type" : "order",
"target_id" : 15,
"target_description" : "1000029",
"target_child_type" : "shipment",
"target_child_id" : 16,
"target_child_description" : "1000042",
"package_id" : 48,
"webhook_increment_id" : 1,
"event_timestamp" : "2024-10-23T09:22:26+00:00"
}
}
```
The `packages[]` payload in the `shipment:*` and `tracker:*` events mirrors the package shape returned by [`shipment.info`](/merchant-api/shipment#shipment-info) — see [Package Properties](/merchant-api/shipment#package-properties) for the full reference. For `items[].lot_data[]`, see the Lot Data fields under [Shipment Item Properties](/merchant-api/shipment#shipment-item-properties). `manifest_courier_code` is included only when the shipment has a manifest code.
### `shipment:packed`
```json title="Payload" theme={null}
{
"topic": "shipment:packed",
"message": {
"merchant_code": "acme",
"brand_code": "default",
"unique_id": "100000595",
"warehouse_id": "1",
"status": "packed",
"external_id": null,
"order_ref": null,
"order_unique_id": "100000540",
"source": null,
"order_status": "complete",
"carrier": "ups",
"service": "03",
"service_description": "UPS Ground",
"shipping_address": {
"firstname": "John",
"lastname": "Doe",
"company": "ACME",
"street": "123 ACME BIG STREET",
"city": "New York",
"region": "NY",
"postcode": "99999",
"country": "US",
"classification": "com",
"is_valid": true,
"telephone": "865999999",
"email": "john.doe@example.com"
},
"items": [
{
"order_item_id": "2954",
"order_item_ref": null,
"order_item_sku": "556x45mm62FMJM855Fed-500",
"sku": "556x45mm62FMJM855Fed-500",
"quantity": "1.0000",
"lot_data": [
{
"lot_id": 456,
"sku": "556x45mm62FMJM855Fed-500",
"lot_number": "2021-01-01",
"expiration_date": "2021-01-01",
"origination_date": "2023-10-27",
"quantity": "1.0000"
}
]
},
{
"order_item_id": "2955",
"order_item_ref": null,
"order_item_sku": "10mm200TMJCCI-1000",
"sku": "10mm200TMJCCI-1000",
"quantity": "1.0000",
"lot_data": []
}
],
"packages": [
{
"package_id": "234",
"status": "packed",
"weight": "1.7500",
"weight_unit": "lb",
"tracker_id": "229",
"created_at": "2023-10-27T11:59:08+00:00",
"tracking_added_at": "2023-10-27T11:59:09+00:00",
"shipped_at": null,
"delivered_at": null,
"items": [
{
"order_item_id": "2954",
"order_item_ref": null,
"order_item_sku": "556x45mm62FMJM855Fed-500",
"sku": "556x45mm62FMJM855Fed-500",
"quantity": "1.0000",
"order_item_qty": 1
}
],
"package_data": [
{
"order_item_id": "2954",
"label": "Serial Number",
"value": "123456-3"
}
],
"tracking_numbers": [
"TT234"
],
"tracking_urls": [
"https://wwwapps.ups.com/tracking/tracking.cgi?tracknum=TT234"
],
"packaging": [],
"manifest_courier": "UPS",
"carrier": "ups",
"manifest_courier_code": "ups",
"billable_weight": "14",
"billable_weight_unit": "lb",
"dimensional_weight_divisor": "139",
"dimensional_weight_divisor_unit": "in^3/lb",
"dimensional_weight": "14",
"rating_weight_unit": "lb",
"dimensions": {
"length": "16.000",
"width": "12.000",
"height": "8.000"
},
"dimension_unit": "in",
"sscc": "00508101336500131005",
"serial_number_data": [
{
"serial_id": "1",
"identifier": "123456123456",
"sku": "556x45mm62FMJM855Fed-500",
"product_id": "7"
}
]
},
{
"package_id": "235",
"status": "packed",
"weight": "0.5000",
"weight_unit": "lb",
"tracker_id": "230",
"created_at": "2023-10-27T11:59:08+00:00",
"tracking_added_at": "2023-10-27T11:59:09+00:00",
"shipped_at": null,
"delivered_at": null,
"items": [
{
"order_item_id": "2955",
"order_item_ref": null,
"order_item_sku": "10mm200TMJCCI-1000",
"sku": "10mm200TMJCCI-1000",
"quantity": "1.0000",
"order_item_qty": 1
}
],
"package_data": [
{
"order_item_id": "2955",
"label": "Serial Number",
"value": "123456-5"
}
],
"tracking_numbers": [
"TT235"
],
"tracking_urls": [
"https://wwwapps.ups.com/tracking/tracking.cgi?tracknum=TT235"
],
"packaging": [],
"manifest_courier": "UPS",
"carrier": "ups",
"manifest_courier_code": "ups",
"billable_weight": "14",
"billable_weight_unit": "lb",
"dimensional_weight_divisor": "139",
"dimensional_weight_divisor_unit": "in^3/lb",
"dimensional_weight": "14",
"rating_weight_unit": "lb",
"dimensions": {
"length": "16.000",
"width": "12.000",
"height": "8.000"
},
"dimension_unit": "in",
"sscc": "00508101336500131005",
"serial_number_data": [
{
"serial_id": "1",
"identifier": "123456123456",
"sku": "10mm200TMJCCI-1000",
"product_id": "7"
}
]
}
],
"trackers": [
{
"tracker_id": "229",
"status": "unknown",
"carrier": "ups",
"tracking_number": "TT234",
"est_delivery_at": null,
"is_est_delivery_at_date": null,
"original_est_delivery_at": null,
"is_original_est_delivery_at_date": null,
"delivered_at": null,
"signed_by": null,
"carrier_tracking_url": "https://wwwapps.ups.com/tracking/tracking.cgi?tracknum=TT234"
},
{
"tracker_id": "230",
"status": "unknown",
"carrier": "ups",
"tracking_number": "TT235",
"est_delivery_at": null,
"is_est_delivery_at_date": null,
"original_est_delivery_at": null,
"is_original_est_delivery_at_date": null,
"delivered_at": null,
"signed_by": null,
"carrier_tracking_url": "https://wwwapps.ups.com/tracking/tracking.cgi?tracknum=TT235"
}
],
"updated_at": "2023-10-27T11:59:09+00:00",
"shipping_method": "ups_03",
"tpb_group_id": null,
"total_weight": 2.25,
"total_qty": "2.0000",
"order_id": "2542",
"shipped_weight": null,
"created_at": "2023-10-27T11:59:08+00:00",
"target_ship_date": "2023-10-27",
"packed_at": "2023-10-27T11:59:09+00:00",
"total_item_weight": "2.2500",
"scac": null,
"shipped_at": null,
"delivered_at": null,
"store_code": "default",
"total_weight_unit": "lb",
"shipped_weight_unit": null,
"webhook_increment_id": 3,
"event_timestamp": "2023-10-27T11:59:09+00:00"
}
}
```
`shipping_address` contains Protected Customer Data (PCD) and is only included when the webhook subscription has **Include PCD** enabled.
### `shipment:shipped`
```json title="Payload" theme={null}
{
"topic": "shipment:shipped",
"message": {
"merchant_code": "acme",
"brand_code": "default",
"unique_id": "300000008",
"warehouse_id": "1",
"status": "shipped",
"external_id": "123456",
"order_ref": "456789",
"order_unique_id": "400111867",
"source": null,
"order_status": "complete",
"carrier": "ups",
"service": "03",
"service_description": "UPS Ground",
"shipping_address": {
"firstname": "John",
"lastname": "Doe",
"company": "ACME",
"street": "123 ACME BIG STREET",
"city": "New York",
"region": "NY",
"postcode": "99999",
"country": "US",
"classification": "com",
"is_valid": true,
"telephone": "865999999",
"email": "john.doe@example.com"
},
"items": [
{
"order_item_id": "21",
"order_item_ref": null,
"order_item_sku": "12ga2-34buck00FederalPrem-250",
"sku": "12ga2-34buck00FederalPrem-250",
"quantity": "1.0000",
"lot_data": []
}
],
"packages": [
{
"package_id": "1",
"status": "shipped",
"weight": "28.5000",
"weight_unit": "lb",
"tracker_id": "2",
"created_at": "2013-02-28T20:18:04+00:00",
"tracking_added_at": "2023-05-10T15:36:44+00:00",
"shipped_at": "2023-05-10T15:36:44+00:00",
"delivered_at": null,
"items": [
{
"order_item_id": "21",
"order_item_ref": null,
"order_item_sku": "12ga2-34buck00FederalPrem-250",
"sku": "12ga2-34buck00FederalPrem-250",
"quantity": "1.0000",
"order_item_qty": 1
}
],
"package_data": [],
"tracking_numbers": [
"1Z999AA10123456784"
],
"tracking_urls": [
"https://wwwapps.ups.com/tracking/tracking.cgi?tracknum=1Z999AA10123456784"
],
"packaging": [],
"manifest_courier": "UPS",
"carrier": "ups",
"manifest_courier_code": "ups",
"billable_weight": "14",
"billable_weight_unit": "lb",
"dimensional_weight_divisor": "139",
"dimensional_weight_divisor_unit": "in^3/lb",
"dimensional_weight": "14",
"rating_weight_unit": "lb",
"dimensions": {
"length": "16.000",
"width": "12.000",
"height": "8.000"
},
"dimension_unit": "in",
"sscc": "00508101336500131005",
"serial_number_data": [
{
"serial_id": "1",
"identifier": "123456123456",
"sku": "12ga2-34buck00FederalPrem-250",
"product_id": "7"
}
]
}
],
"trackers": [
{
"tracker_id": "2",
"status": "unknown",
"carrier": "ups",
"tracking_number": "1Z999AA10123456784",
"est_delivery_at": null,
"is_est_delivery_at_date": null,
"original_est_delivery_at": null,
"is_original_est_delivery_at_date": null,
"delivered_at": null,
"signed_by": null,
"carrier_tracking_url": "https://wwwapps.ups.com/tracking/tracking.cgi?tracknum=1Z999AA10123456784"
}
],
"updated_at": "2023-10-27T12:06:10+00:00",
"shipping_method": "ups_03",
"tpb_group_id": null,
"total_weight": 26.7,
"total_qty": "1.0000",
"order_id": "17",
"shipped_weight": 26.7,
"created_at": "2013-02-28T20:18:04+00:00",
"target_ship_date": null,
"packed_at": null,
"total_item_weight": "26.7000",
"scac": null,
"shipped_at": "2023-05-10T15:36:44+00:00",
"delivered_at": null,
"store_code": "default",
"total_weight_unit": "lb",
"shipped_weight_unit": "lb",
"webhook_increment_id": 1,
"event_timestamp": "2023-10-27T12:06:10+00:00"
}
}
```
`shipping_address` contains Protected Customer Data (PCD) and is only included when the webhook subscription has **Include PCD** enabled.
### `shipment:delivered`
```json title="Payload" theme={null}
{
"topic": "shipment:delivered",
"message": {
"merchant_code": "acme",
"brand_code": "default",
"unique_id": "300000008",
"warehouse_id": "1",
"status": "shipped",
"external_id": "123456",
"order_ref": "456789",
"order_unique_id": "400111867",
"source": null,
"order_status": "complete",
"carrier": "ups",
"service": "03",
"service_description": "UPS Ground",
"shipping_address": {
"firstname": "John",
"lastname": "Doe",
"company": "ACME",
"street": "123 ACME BIG STREET",
"city": "New York",
"region": "NY",
"postcode": "99999",
"country": "US",
"classification": "com",
"is_valid": true,
"telephone": "865999999",
"email": "john.doe@example.com"
},
"items": [
{
"order_item_id": "21",
"order_item_ref": null,
"order_item_sku": "12ga2-34buck00FederalPrem-250",
"sku": "12ga2-34buck00FederalPrem-250",
"quantity": "1.0000",
"lot_data": []
}
],
"packages": [
{
"package_id": "1",
"status": "delivered",
"weight": "28.5000",
"weight_unit": "lb",
"tracker_id": "3",
"created_at": "2013-02-28T20:18:04+00:00",
"tracking_added_at": "2023-05-10T21:42:17+00:00",
"shipped_at": "2023-05-10T21:42:17+00:00",
"delivered_at": "2023-05-13T14:53:14+00:00",
"items": [
{
"order_item_id": "21",
"order_item_ref": null,
"order_item_sku": "12ga2-34buck00FederalPrem-250",
"sku": "12ga2-34buck00FederalPrem-250",
"quantity": "1.0000",
"order_item_qty": 1
}
],
"package_data": [],
"tracking_numbers": [
"1Z999AA10123456784"
],
"tracking_urls": [
"https://wwwapps.ups.com/tracking/tracking.cgi?tracknum=1Z999AA10123456784"
],
"packaging": [],
"manifest_courier": "UPS",
"carrier": "ups",
"manifest_courier_code": "ups",
"billable_weight": "14",
"billable_weight_unit": "lb",
"dimensional_weight_divisor": "139",
"dimensional_weight_divisor_unit": "in^3/lb",
"dimensional_weight": "14",
"rating_weight_unit": "lb",
"dimensions": {
"length": "16.000",
"width": "12.000",
"height": "8.000"
},
"dimension_unit": "in",
"sscc": "00508101336500131005",
"serial_number_data": [
{
"serial_id": "1",
"identifier": "123456123456",
"sku": "12ga2-34buck00FederalPrem-250",
"product_id": "7"
}
]
}
],
"trackers": [
{
"tracker_id": "3",
"status": "delivered",
"carrier": "ups",
"tracking_number": "1Z999AA10123456784",
"est_delivery_at": "2023-05-13T12:00:00-04:00",
"is_est_delivery_at_date": false,
"original_est_delivery_at": "2023-05-12T00:00:00-04:00",
"is_original_est_delivery_at_date": true,
"delivered_at": "2023-05-13T10:53:14-04:00",
"signed_by": "J. Smith",
"carrier_tracking_url": "https://wwwapps.ups.com/tracking/tracking.cgi?tracknum=1Z999AA10123456784"
}
],
"updated_at": "2023-10-27T12:09:45+00:00",
"shipping_method": "ups_03",
"tpb_group_id": null,
"total_weight": 26.7,
"total_qty": "1.0000",
"order_id": "17",
"shipped_weight": 26.7,
"created_at": "2013-02-28T20:18:04+00:00",
"target_ship_date": null,
"packed_at": null,
"total_item_weight": "26.7000",
"scac": null,
"shipped_at": "2023-05-10T21:42:17+00:00",
"delivered_at": "2023-05-13T14:53:14+00:00",
"store_code": "default",
"total_weight_unit": "lb",
"shipped_weight_unit": "lb",
"webhook_increment_id": 1,
"event_timestamp": "2023-10-27T12:09:45+00:00"
}
}
```
`shipping_address` contains Protected Customer Data (PCD) and is only included when the webhook subscription has **Include PCD** enabled.
### `shipment:reverted`
```json title="Payload" theme={null}
{
"topic": "shipment:reverted",
"message": {
"merchant_code": "acme",
"brand_code": "default",
"unique_id": "100000596",
"warehouse_id": "1",
"status": "voided",
"external_id": null,
"order_ref": null,
"order_unique_id": "100000541",
"source": null,
"order_status": "backordered",
"carrier": "ups",
"service": "03",
"service_description": "UPS Ground",
"shipping_address": {
"firstname": "John",
"lastname": "Doe",
"company": "ACME",
"street": "123 ACME BIG STREET",
"city": "New York",
"region": "NY",
"postcode": "99999",
"country": "US",
"classification": "com",
"is_valid": true,
"telephone": "865999999",
"email": "john.doe@example.com"
},
"items": [
{
"order_item_id": "2956",
"order_item_ref": null,
"order_item_sku": "556x45mm62FMJM855Fed-500",
"sku": "556x45mm62FMJM855Fed-500",
"quantity": "1.0000",
"lot_data": [
{
"lot_id": 456,
"sku": "556x45mm62FMJM855Fed-500",
"lot_number": "2021-01-01",
"expiration_date": "2021-01-01",
"origination_date": "2023-10-27",
"quantity": "1.0000"
}
]
},
{
"order_item_id": "2957",
"order_item_ref": null,
"order_item_sku": "10mm200TMJCCI-1000",
"sku": "10mm200TMJCCI-1000",
"quantity": "1.0000",
"lot_data": []
}
],
"packages": [
{
"package_id": "236",
"status": "packed",
"weight": "1.7500",
"weight_unit": "lb",
"tracker_id": "231",
"created_at": "2023-10-27T12:12:50+00:00",
"tracking_added_at": "2023-10-27T12:12:51+00:00",
"shipped_at": null,
"delivered_at": null,
"items": [
{
"order_item_id": "2956",
"order_item_ref": null,
"order_item_sku": "556x45mm62FMJM855Fed-500",
"sku": "556x45mm62FMJM855Fed-500",
"quantity": "1.0000",
"order_item_qty": 1
}
],
"package_data": [
{
"order_item_id": "2956",
"label": "Serial Number",
"value": "123456-3"
}
],
"tracking_numbers": [
"TT236"
],
"tracking_urls": [
"https://wwwapps.ups.com/tracking/tracking.cgi?tracknum=TT236"
],
"packaging": [],
"manifest_courier": "UPS",
"carrier": "ups",
"manifest_courier_code": "ups",
"billable_weight": "14",
"billable_weight_unit": "lb",
"dimensional_weight_divisor": "139",
"dimensional_weight_divisor_unit": "in^3/lb",
"dimensional_weight": "14",
"rating_weight_unit": "lb",
"dimensions": {
"length": "16.000",
"width": "12.000",
"height": "8.000"
},
"dimension_unit": "in",
"sscc": "00508101336500131005",
"serial_number_data": [
{
"serial_id": "1",
"identifier": "123456123456",
"sku": "556x45mm62FMJM855Fed-500",
"product_id": "7"
}
]
},
{
"package_id": "237",
"status": "packed",
"weight": "0.5000",
"weight_unit": "lb",
"tracker_id": "232",
"created_at": "2023-10-27T12:12:50+00:00",
"tracking_added_at": "2023-10-27T12:12:51+00:00",
"shipped_at": null,
"delivered_at": null,
"items": [
{
"order_item_id": "2957",
"order_item_ref": null,
"order_item_sku": "10mm200TMJCCI-1000",
"sku": "10mm200TMJCCI-1000",
"quantity": "1.0000",
"order_item_qty": 1
}
],
"package_data": [
{
"order_item_id": "2957",
"label": "Serial Number",
"value": "123456-5"
}
],
"tracking_numbers": [
"TT237"
],
"tracking_urls": [
"https://wwwapps.ups.com/tracking/tracking.cgi?tracknum=TT237"
],
"packaging": [],
"manifest_courier": "UPS",
"carrier": "ups",
"manifest_courier_code": "ups",
"billable_weight": "14",
"billable_weight_unit": "lb",
"dimensional_weight_divisor": "139",
"dimensional_weight_divisor_unit": "in^3/lb",
"dimensional_weight": "14",
"rating_weight_unit": "lb",
"dimensions": {
"length": "16.000",
"width": "12.000",
"height": "8.000"
},
"dimension_unit": "in",
"sscc": "00508101336500131005",
"serial_number_data": [
{
"serial_id": "1",
"identifier": "123456123456",
"sku": "10mm200TMJCCI-1000",
"product_id": "7"
}
]
}
],
"trackers": [
{
"tracker_id": "231",
"status": "unknown",
"carrier": "ups",
"tracking_number": "TT236",
"est_delivery_at": null,
"is_est_delivery_at_date": null,
"original_est_delivery_at": null,
"is_original_est_delivery_at_date": null,
"delivered_at": null,
"signed_by": null,
"carrier_tracking_url": "https://wwwapps.ups.com/tracking/tracking.cgi?tracknum=TT236"
},
{
"tracker_id": "232",
"status": "unknown",
"carrier": "ups",
"tracking_number": "TT237",
"est_delivery_at": null,
"is_est_delivery_at_date": null,
"original_est_delivery_at": null,
"is_original_est_delivery_at_date": null,
"delivered_at": null,
"signed_by": null,
"carrier_tracking_url": "https://wwwapps.ups.com/tracking/tracking.cgi?tracknum=TT237"
}
],
"updated_at": "2023-10-27T12:12:53+00:00",
"shipping_method": "ups_03",
"tpb_group_id": null,
"total_weight": 2.25,
"total_qty": "2.0000",
"order_id": "2543",
"shipped_weight": null,
"created_at": "2023-10-27T12:12:50+00:00",
"target_ship_date": "2023-10-27",
"packed_at": "2023-10-27T12:12:51+00:00",
"total_item_weight": "2.2500",
"scac": null,
"shipped_at": null,
"delivered_at": null,
"store_code": "default",
"total_weight_unit": "lb",
"shipped_weight_unit": null,
"webhook_increment_id": 4,
"event_timestamp": "2023-10-27T12:12:53+00:00"
}
}
```
`shipping_address` contains Protected Customer Data (PCD) and is only included when the webhook subscription has **Include PCD** enabled.
### `shipment:labels_voided`
```json title="Payload" theme={null}
{
"topic": "shipment:labels_voided",
"message": {
"merchant_code": "acme",
"brand_code": "default",
"unique_id": "100000597",
"warehouse_id": "1",
"status": "picked",
"external_id": null,
"order_ref": null,
"order_unique_id": "100000542",
"source": null,
"order_status": "processing",
"carrier": "ups",
"service": "03",
"service_description": "UPS Ground",
"shipping_address": {
"firstname": "John",
"lastname": "Doe",
"company": "ACME",
"street": "123 ACME BIG STREET",
"city": "New York",
"region": "NY",
"postcode": "99999",
"country": "US",
"classification": "com",
"is_valid": true,
"telephone": "865999999",
"email": "john.doe@example.com"
},
"packages": [
{
"package_id": "238",
"status": "packed",
"weight": "1.7500",
"weight_unit": "lb",
"tracker_id": "233",
"created_at": "2023-10-27T12:18:04+00:00",
"tracking_added_at": "2023-10-27T12:18:04+00:00",
"shipped_at": null,
"delivered_at": null,
"items": [
{
"order_item_id": "2958",
"order_item_ref": null,
"order_item_sku": "556x45mm62FMJM855Fed-500",
"sku": "556x45mm62FMJM855Fed-500",
"quantity": "1.0000",
"order_item_qty": 1
}
],
"package_data": [
{
"order_item_id": "2958",
"label": "Serial Number",
"value": "123456-3"
}
],
"tracking_numbers": [
"TT238"
],
"tracking_urls": [
"https://wwwapps.ups.com/tracking/tracking.cgi?tracknum=TT238"
],
"packaging": [],
"manifest_courier": "UPS",
"carrier": "ups",
"manifest_courier_code": "ups",
"billable_weight": "14",
"billable_weight_unit": "lb",
"dimensional_weight_divisor": "139",
"dimensional_weight_divisor_unit": "in^3/lb",
"dimensional_weight": "14",
"rating_weight_unit": "lb",
"dimensions": {
"length": "16.000",
"width": "12.000",
"height": "8.000"
},
"dimension_unit": "in",
"sscc": "00508101336500131005",
"serial_number_data": [
{
"serial_id": "1",
"identifier": "123456123456",
"sku": "556x45mm62FMJM855Fed-500",
"product_id": "7"
}
]
},
{
"package_id": "239",
"status": "packed",
"weight": "0.5000",
"weight_unit": "lb",
"tracker_id": "234",
"created_at": "2023-10-27T12:18:04+00:00",
"tracking_added_at": "2023-10-27T12:18:04+00:00",
"shipped_at": null,
"delivered_at": null,
"items": [
{
"order_item_id": "2959",
"order_item_ref": null,
"order_item_sku": "10mm200TMJCCI-1000",
"sku": "10mm200TMJCCI-1000",
"quantity": "1.0000",
"order_item_qty": 1
}
],
"package_data": [
{
"order_item_id": "2959",
"label": "Serial Number",
"value": "123456-5"
}
],
"tracking_numbers": [
"TT239"
],
"tracking_urls": [
"https://wwwapps.ups.com/tracking/tracking.cgi?tracknum=TT239"
],
"packaging": [],
"manifest_courier": "UPS",
"carrier": "ups",
"manifest_courier_code": "ups",
"billable_weight": "14",
"billable_weight_unit": "lb",
"dimensional_weight_divisor": "139",
"dimensional_weight_divisor_unit": "in^3/lb",
"dimensional_weight": "14",
"rating_weight_unit": "lb",
"dimensions": {
"length": "16.000",
"width": "12.000",
"height": "8.000"
},
"dimension_unit": "in",
"sscc": "00508101336500131005",
"serial_number_data": [
{
"serial_id": "1",
"identifier": "123456123456",
"sku": "10mm200TMJCCI-1000",
"product_id": "7"
}
]
}
],
"trackers": [
{
"tracker_id": "233",
"status": "unknown",
"carrier": "ups",
"tracking_number": "TT238",
"est_delivery_at": null,
"is_est_delivery_at_date": null,
"original_est_delivery_at": null,
"is_original_est_delivery_at_date": null,
"delivered_at": null,
"signed_by": null,
"carrier_tracking_url": "https://wwwapps.ups.com/tracking/tracking.cgi?tracknum=TT238"
},
{
"tracker_id": "234",
"status": "unknown",
"carrier": "ups",
"tracking_number": "TT239",
"est_delivery_at": null,
"is_est_delivery_at_date": null,
"original_est_delivery_at": null,
"is_original_est_delivery_at_date": null,
"delivered_at": null,
"signed_by": null,
"carrier_tracking_url": "https://wwwapps.ups.com/tracking/tracking.cgi?tracknum=TT239"
}
],
"updated_at": "2023-10-27T12:18:06+00:00",
"shipping_method": "ups_03",
"tpb_group_id": null,
"total_weight": 2.25,
"total_qty": "2.0000",
"order_id": "2544",
"shipped_weight": null,
"created_at": "2023-10-27T12:18:04+00:00",
"target_ship_date": "2023-10-27",
"packed_at": null,
"total_item_weight": "2.2500",
"scac": null,
"shipped_at": null,
"delivered_at": null,
"store_code": "default",
"total_weight_unit": "lb",
"shipped_weight_unit": null,
"webhook_increment_id": 2,
"event_timestamp": "2023-10-27T12:18:06+00:00"
}
}
```
`shipping_address` contains Protected Customer Data (PCD) and is only included when the webhook subscription has **Include PCD** enabled.
### `package:packed`
```json title="Payload" theme={null}
{
"topic" : "package:packed",
"message" : {
"merchant_code" : "acme",
"brand_code" : "default",
"package_id" : 22,
"status" : "packed",
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
### `package:manifested`
```json title="Payload" theme={null}
{
"topic" : "package:manifested",
"message" : {
"merchant_code" : "acme",
"brand_code" : "default",
"package_id" : 22,
"status" : "manifested",
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
### `package:shipped`
```json title="Payload" theme={null}
{
"topic" : "package:shipped",
"message" : {
"merchant_code" : "acme",
"brand_code" : "default",
"package_id" : 22,
"status" : "shipped",
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
### `package:delivered`
```json title="Payload" theme={null}
{
"topic" : "package:delivered",
"message" : {
"merchant_code" : "acme",
"brand_code" : "default",
"package_id" : 22,
"status" : "delivered",
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
### `track:created`
This topic is deprecated. Please use [shipment:packed](#shipment-packed) instead.
```json title="Payload" theme={null}
{
"topic" : "track:created",
"message" : {
"merchant_code" : "acme",
"brand_code" : "default",
"order_ref" : "9099",
"order_unique_id" : "100000018",
"shipment_unique_id" : "100000007",
"warehouse_id": 1,
"package_id" : 99,
"source" : "shopify",
"carrier" : "fedex",
"service" : "FEDEX_2_DAY",
"number" : "794657040105",
"url" : "https://www.fedex.com/apps/fedextrack/?action=track&tracknumbers=794657040105",
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
### `tracker:updated`
```json title="Payload" theme={null}
{
"topic" : "tracker:updated",
"message" : {
"merchant_code" : "acme",
"tracker_id" : 23,
"order_unique_id" : "100000018",
"order_ref" : "9099",
"order_source" : "shopify",
"shipment_unique_id" : "100000007",
"warehouse_id" : 1,
"carrier" : "fedex",
"tracking_number" : "794657040105",
"carrier_tracking_url" : "https://www.fedex.com/apps/fedextrack/?action=track&tracknumbers=794657040105",
"old_status" : "unknown",
"new_status" : "pre_transit",
"new_details" : [{
"status" : "pre_transit",
"timestamp" : "2021-12-03T12:08:15-04:00",
"is_timestamp_date" : false,
"message" : "Label created.",
"source" : "carrier_api",
"location" : {
"city" : "Amsterdam",
"country" : "US",
"postcode" : "12010-6269",
"region" : "NY",
"timezone" : "America/New_York",
"lat" : 42.9387,
"lng" : -74.1882
}
}],
"est_delivery_at" : "2021-10-05T00:00:00-04:00",
"is_est_delivery_at_date" : true,
"original_est_delivery_at" : "2021-10-05T00:00:00-04:00",
"is_original_est_delivery_at_date" : true,
"delivered_at" : null,
"signed_by" : null,
"packages" : [{
"package_id" : 99,
"weight" : 10.2,
"weight_unit" : "lb",
"tracker_id" : 3,
"created_at" : "2021-12-03T16:08:15+00:00",
"tracking_added_at" : "2021-12-03T16:08:15+00:00",
"shipped_at" : null,
"delivered_at" : null,
"items" : [
{"order_item_id" : "443313", "sku" : "sku123", "quantity" : 1}
],
"package_data" : [
{"order_item_id" : "443313", "label" : "Serial Number - 8 Characters", "value" : "55285442"}
],
"tracking_numbers" : [
"794657040105"
],
"tracking_urls" : [
"https://www.fedex.com/apps/fedextrack/?action=track&tracknumbers=794657040105"
],
"packaging" : [],
"manifest_courier" : "FedEx",
"carrier" : "fedex",
"manifest_courier_code" : "fedex",
"billable_weight" : "14",
"billable_weight_unit" : "lb",
"dimensional_weight_divisor" : "139",
"dimensional_weight_divisor_unit" : "in^3/lb",
"dimensional_weight" : "14",
"rating_weight_unit" : "lb",
"dimensions" : {
"length" : "16.000",
"width" : "12.000",
"height" : "8.000"
},
"dimension_unit" : "in",
"sscc" : "00508101336500131005",
"serial_number_data" : [
{
"serial_id" : "1",
"identifier" : "123456123456",
"sku" : "sku123",
"product_id" : "7"
}
]
}],
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-03T16:08:15+00:00"
}
}
```
### `tracker:delivered`
```json title="Payload" theme={null}
{
"topic" : "tracker:delivered",
"message" : {
"merchant_code" : "acme",
"tracker_id" : 23,
"order_unique_id" : "100000018",
"order_ref" : "9099",
"order_source" : "shopify",
"shipment_unique_id" : "100000007",
"warehouse_id" : 1,
"carrier" : "fedex",
"tracking_number" : "794657040105",
"carrier_tracking_url" : "https://www.fedex.com/apps/fedextrack/?action=track&tracknumbers=794657040105",
"old_status" : "out_for_delivery",
"new_status" : "delivered",
"new_details" : [{
"status" : "delivered",
"message" : "Delivered at front door.",
"timestamp" : "2021-12-07T12:08:15-04:00",
"is_timestamp_date" : false,
"source" : "carrier_api",
"location" : {
"city" : "Amsterdam",
"country" : "US",
"postcode" : "12010-6269",
"region" : "NY",
"timezone" : "America/New_York",
"lat" : 42.9387,
"lng" : -74.1882
}
}],
"est_delivery_at" : "2021-10-05T00:00:00-04:00",
"is_est_delivery_at_date" : true,
"original_est_delivery_at" : "2021-10-05T00:00:00-04:00",
"is_original_est_delivery_at_date" : true,
"delivered_at" : "2021-12-07T12:08:15-04:00",
"signed_by" : "J. Smith",
"packages" : [{
"package_id" : 99,
"weight" : 10.2,
"weight_unit" : "lb",
"tracker_id" : 3,
"created_at" : "2021-12-03T16:08:15+00:00",
"tracking_added_at" : "2021-12-03T16:08:15+00:00",
"shipped_at" : "2021-12-06T16:08:15+00:00",
"delivered_at" : "2021-12-07T12:08:15-04:00",
"items" : [
{"order_item_id" : "443313", "sku" : "sku123", "quantity" : 1}
],
"package_data" : [
{"order_item_id" : "443313", "label" : "Serial Number - 8 Characters", "value" : "55285442"}
],
"tracking_numbers" : [
"794657040105"
],
"tracking_urls" : [
"https://www.fedex.com/apps/fedextrack/?action=track&tracknumbers=794657040105"
],
"packaging" : [],
"manifest_courier" : "FedEx",
"carrier" : "fedex",
"manifest_courier_code" : "fedex",
"billable_weight" : "14",
"billable_weight_unit" : "lb",
"dimensional_weight_divisor" : "139",
"dimensional_weight_divisor_unit" : "in^3/lb",
"dimensional_weight" : "14",
"rating_weight_unit" : "lb",
"dimensions" : {
"length" : "16.000",
"width" : "12.000",
"height" : "8.000"
},
"dimension_unit" : "in",
"sscc" : "00508101336500131005",
"serial_number_data" : [
{
"serial_id" : "1",
"identifier" : "123456123456",
"sku" : "sku123",
"product_id" : "7"
}
]
}],
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
### `tracker:exception`
```json title="Payload" theme={null}
{
"topic" : "tracker:exception",
"message" : {
"merchant_code" : "acme",
"tracker_id" : 23,
"order_unique_id" : "100000018",
"order_ref" : "9099",
"order_source" : "shopify",
"shipment_unique_id" : "100000007",
"warehouse_id" : 1,
"carrier" : "fedex",
"tracking_number" : "794657040105",
"carrier_tracking_url" : "https://www.fedex.com/apps/fedextrack/?action=track&tracknumbers=794657040105",
"old_status" : "out_for_delivery",
"new_status" : "return_to_sender",
"new_details" : [{
"status" : "return_to_sender",
"message" : "Refused by customer.",
"timestamp" : "2021-12-07T12:08:15-04:00",
"is_timestamp_date" : false,
"source" : "carrier_api",
"location" : {
"city" : "Amsterdam",
"country" : "US",
"postcode" : "12010-6269",
"region" : "NY",
"timezone" : "America/New_York",
"lat" : 42.9387,
"lng" : -74.1882
}
}],
"packages" : [{
"package_id" : 99,
"weight" : 10.2,
"weight_unit" : "lb",
"tracker_id" : 3,
"created_at" : "2021-12-03T16:08:15+00:00",
"tracking_added_at" : "2021-12-03T16:08:15+00:00",
"shipped_at" : null,
"delivered_at" : null,
"items" : [
{"order_item_id" : "443313", "sku" : "sku123", "quantity" : 1}
],
"package_data" : [
{"order_item_id" : "443313", "label" : "Serial Number - 8 Characters", "value" : "55285442"}
],
"tracking_numbers" : [
"794657040105"
],
"tracking_urls" : [
"https://www.fedex.com/apps/fedextrack/?action=track&tracknumbers=794657040105"
],
"packaging" : [],
"manifest_courier" : "FedEx",
"carrier" : "fedex",
"manifest_courier_code" : "fedex",
"billable_weight" : "14",
"billable_weight_unit" : "lb",
"dimensional_weight_divisor" : "139",
"dimensional_weight_divisor_unit" : "in^3/lb",
"dimensional_weight" : "14",
"rating_weight_unit" : "lb",
"dimensions" : {
"length" : "16.000",
"width" : "12.000",
"height" : "8.000"
},
"dimension_unit" : "in",
"sscc" : "00508101336500131005",
"serial_number_data" : [
{
"serial_id" : "1",
"identifier" : "123456123456",
"sku" : "sku123",
"product_id" : "7"
}
]
}],
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
### `manifest:sealed`
```json title="Payload" theme={null}
{
"topic" : "manifest:sealed",
"message" : {
"manifest_id" : 3,
"warehouse_id" : 1,
"carrier" : "ups",
"weight" : 45,
"weight_unit" : "lb",
"orders" : [{
"unique_id" : "100000021",
"order_ref" : null,
"state" : "complete",
"source" : "sps:test:123:8ZC3:544",
"tracking_numbers" : [
"794657040105"
]
}],
"shipments" : [{
"unique_id" : "100000035",
"order_ref" : null,
"order_unique_id" : "100000021",
"source" : "123456",
"status" : "packed"
}],
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```
### `manifest:loaded`
```json title="Payload" theme={null}
{
"topic" : "manifest:loaded",
"message" : {
"manifest_id" : 3,
"warehouse_id" : 1,
"carrier" : "ups",
"weight" : 45,
"weight_unit" : "lb",
"orders" : [{
"unique_id" : "100000021",
"order_ref" : null,
"state" : "complete",
"source" : "sps:test:123:8ZC3:544",
"tracking_numbers" : [
"794657040105"
]
}],
"shipments" : [{
"unique_id" : "100000035",
"order_ref" : null,
"order_unique_id" : "100000021",
"source" : "123456",
"status" : "packed"
}],
"webhook_increment_id" : 1,
"event_timestamp" : "2021-12-07T16:08:15+00:00"
}
}
```