generated: '2026-08-02'
method: searched
source: >-
  https://apidocs.shipmonk.com/reference/common, https://apidocs.shipmonk.com/docs/intro,
  https://apidocs.shipmonk.com/docs/concepts, https://apidocs.shipmonk.com/reference/webhooks,
  and openapi/_original/shipmonk-openapi.json
description: >-
  Cross-cutting request/response semantics of the ShipMonk public fulfillment API: how you
  authenticate, how repeat writes are made safe, how lists are paged, how errors and rate
  limits are signalled, and how the contract is versioned. These are the runtime rules the
  OpenAPI does not fully express.
base_url: https://api.shipmonk.com
sandbox_url: https://sandbox.shipmonk.dev
api_style: REST over HTTPS, JSON request and response bodies

authentication:
  scheme: API key in a request header
  header: Api-Key
  scheme_name: api_key_header_Api-Key
  scopes: none - the key is account-wide; one key can CRUD an order in any store on the account
  key_management: >-
    Keys are created per store under Account Settings > Integration API Keys in the ShipMonk
    app; they can be regenerated and revoked from the same screen. A store must first be
    authorized by the ShipMonk integrations team.
  docs: https://apidocs.shipmonk.com/docs/api-key
  detail: authentication/shipmonk-authentication.yml

idempotency:
  supported: true
  mechanism: natural-key upsert (no Idempotency-Key header)
  header: null
  description: >-
    ShipMonk does not implement an idempotency-key protocol. Instead the write endpoints are
    upserts keyed on caller-supplied natural identifiers, so replaying the same request with
    the same key updates rather than duplicates.
  keys:
  - entity: Order
    operationId: post-v1-integrations-order
    key: store_id + order_key
    behaviour: >-
      Re-POSTing with the same store_id and order_key updates the existing order instead of
      creating a duplicate. Resending the same order with a DIFFERENT order_key WILL
      duplicate it - the order_key is the client's idempotency token and must be stable.
  - entity: Receiving
    operationId: post-v1-integrations-receiving
    key: receiving_key, then asn (resolved in that order)
    behaviour: >-
      Lookup is by receiving_key first, then by asn; a match updates, a miss creates. asn is
      required. Supplying only receiving_key is rejected.
  - entity: Receiving line
    operationId: post-v1-integrations-receiving
    key: line_key (unique per receiving)
    behaviour: >-
      A line_key uniquely identifies a line for later update. Keyless lines are matched by
      product + lot; multiple keyless lines sharing a product and lot cannot be told apart
      and are replaced as a group with the request treated as source of truth.
  - entity: Product
    operationId: post-v1-integrations-product
    key: sku
    behaviour: >-
      SKUs must be unique within the account; a non-unique SKU is rejected with 400. Product
      data is immutable via API after creation - updates are made in the web app.
  cautions:
  - The order_key is the only duplicate-suppression mechanism for orders; generate it once and persist it.
  - There is no replay window or stored-response semantics; a replay re-executes the upsert.
  docs: https://apidocs.shipmonk.com/reference/post-v1-integrations-order

pagination:
  styles: [offset, cursor]
  offset:
    used_by: [get-v1-integrations-orders-list, get-v1-integrations-receivings-list,
      get-v1-integrations-receipts-list, get-v1-integrations-returns-list,
      get-v1-integrations-warehouses, get-v1-products]
    request_params:
      page: page number
      pageSize: page size (page_size on the returns list - the returns surface is snake_case)
      sortBy: sort field (where supported)
      sortOrder: sort direction
    response_fields:
      paginator: pagination envelope returned alongside the data array
    caveats:
    - >-
      GET /v1/products is NOT consistent across paginated calls - inventory changes reorder
      products during fulfillment, so items can shift pages and reappear. Use the products
      search + paginate cursor pair for reliable full-catalog iteration.
    - >-
      GET /v1/integrations/orders-list returns up to 1,000,000 orders unfiltered but a
      maximum of 10,000 when any filter is applied.
  cursor:
    used_by: [post-v1-integrations-products-search, get-v1-integrations-products-search-paginate]
    request_params:
      cursor: opaque cursor returned by the search call (required on paginate)
      pageSize: page size
    response_fields:
      nextCursor: cursor for the following page
    semantics: >-
      Search results are frozen at request time, so the whole set can be iterated without
      missing products. The cursor is valid for 1 hour. This is the endpoint pair to use for
      inventory synchronisation.
  docs: https://apidocs.shipmonk.com/reference/post-v1-integrations-products-search

field_expansion:
  supported: false
  note: No expand[] / include / fields parameters; responses return fixed object graphs.

sparse_fieldsets:
  supported: false

metadata:
  supported: true
  fields:
  - field: custom_data
    entity: Order
    description: >-
      Free-form data stored on the order and echoed back in the shipment notification
      webhook. This is the round-trip correlation channel for external systems.
  - field: attributes
    entity: Order
    description: Reserved for custom development; not needed in most integrations.

request_tracing:
  request_id_header: null
  note: No documented request-id / correlation header is returned. Correlate via custom_data and order_key.

versioning:
  scheme: uri-path (/v1) plus a numbered documentation release train (v1.024)
  request_header: null
  detail: lifecycle/shipmonk-lifecycle.yml

error_envelope:
  format: bespoke JSON (not RFC 9457 problem+json)
  success_shape: '{ "status": <int>, "data": { ... } } on most endpoints; list endpoints return { "paginator": {...}, ... }'
  note: >-
    The published OpenAPI declares only 200 responses - no 4xx/5xx response objects are
    described for any operation, so error payload shapes are not machine-readable. What is
    documented in prose is captured in errors/shipmonk-problem-types.yml.
  detail: errors/shipmonk-problem-types.yml

rate_limit_signaling:
  status: 429
  headers: [Retry-After]
  retry_after_format: RFC 1123 date (e.g. 'Mon, 01 Jan 2024 12:00:00 GMT')
  quota_headers: none published
  detail: rate-limits/shipmonk-rate-limits.yml

datetimes:
  format: ISO 8601
  example: '2022-05-01T11:43:16-04:00'
  docs: https://apidocs.shipmonk.com/docs/intro

naming:
  note: >-
    Field naming is mixed. Request/response bodies are snake_case (order_key, store_id,
    recipient_tax_id) while most query parameters are camelCase (orderKey, pageSize,
    warehouseId) - except the returns list, whose query parameters are snake_case
    (return_status, warehouse_id, page_size). Read the parameter names per operation.

events:
  transport: HTTP POST webhooks
  subscriber_auth: HTTP Basic only
  integrity_header: X-Sm-Signature (HMAC-SHA512)
  expected_response: 2xx (200 named explicitly)
  retries: exponential backoff, up to 8 attempts, 30s doubling to a 60m cap (~2h total)
  detail: asyncapi/shipmonk-webhooks-asyncapi.yml