openapi: 3.1.0 info: title: ShipMonk Orders API version: v1.024 description: The Orders surface of the ShipMonk public fulfillment API. servers: - url: https://api.shipmonk.com description: Once you finish testing on Sandbox, our support team generates you Production API keys and store_id for production. Just write us at api@shipmonk.com and we will handle it. - url: https://sandbox.shipmonk.dev description: 'Sandbox environment is used for preproduction testing. It allows you to play around without worries of corrupting the data. We highly recommend using the Sandbox environment and run tests before going to Production. To get access to the Sandbox, please contact the ShipMonk support team. Note: Sandbox access can only be requested by customers with signed contracts.' tags: - name: Orders paths: /v1/integrations/order: post: operationId: post-v1-integrations-order parameters: [] responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_Crate_OrderSyncOutput' tags: - Orders security: - api_key_header_Api-Key: [] description: 'This endpoint can be used to create an order. The orders are typically pushed to ShipMonk from the 3rd party software. The Create Order endpoint does not create duplicate entries when both the `store_id` and `order_key` are the same. Instead, it updates the existing order. *NOTE: Resending an Order with a different `order_key` will result in Order duplication.** The order can be in following 4 statuses: - `unfulfilled` will create order for ShipMonk to process - `cancelled` will create cancelled order or cancel existing order - `fulfilled` will create order in status "Fulfilled by 3rd party" or change existing order status to that status or not perform any action if order was fulfilled by ShipMonk - `onHold` will create order in status onHold or put an existing order on hold. Can be useful: - if the field `warehouse` is not given, ShipMonk resolves it based on inventory & shipping costs - the field `custom_data` can be used for any data that you need to store and then receive back in shipment notification - the field `attributes` is only used for a custom development and in most of the cases it won''t be needed - if the field submit_at is not given, order is submit according to store settings. ## Recipient Tax ID The **recipient_tax_id** field is an optional parameter when submitting an order through the API. However, it is **mandatory** for international shipments to certain countries, such as Mexico, Brazil, and South Korea. This field plays a role in customs clearance, ensuring accurate calculation of duties and taxes at the destination. ### How it''s used For orders shipping to destinations where a recipient tax ID is mandatory, failure to include this field on the shipping label will result in the order being placed in the **"Recipient Tax ID Required" Action Required status**. Without a valid tax ID, carriers may reject the shipment, returning it to the sender. ### Best Practices To prevent delays, collect the `recipient_tax_id` from the recipient at checkout. This information is unique to the individual or entity receiving the shipment. ### Resolving Missing Recipient Tax ID Issues To address a missing recipient tax ID, you can update the `recipient_tax_id` in one of two ways: - **Via API**: Submit the missing tax ID programmatically using the appropriate endpoint. - **Manually**: Edit the order details directly in the ShipMonk App. Additional Resources For more information, including a current list of countries requiring a recipient tax ID, consult the [Action Required Orders](https://support.shipmonk.com/s/article/Action-Required-Orders) documentation. Refer specifically to the **"Recipient Tax ID Required"** section for detailed guidance and troubleshooting steps. ## Lot requirements Settings for lot requirements (lot, minimum shelf life, etc.) depend on your account settings. Contact your happiness manager to enable lot management. It is possible to set minimum shelf life for the whole order, per order item, or specific lot requirements per order item. - If you set the minimum shelf life for the whole order, you can''t use settings at the item level. - If you set the minimum shelf life for an order item, you can''t set specific lot controls for the same order item. If the lot requirement is not applicable to the mapped bundle, the order is accepted, but the item mapping ends with action required and you have to update the bundles or set different lot requirements. You can override the requirements from public API manually in the application. New request from API will override the manual settings, also empty lot settings will remove existing lot restrictions.' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderInput' summary: Create or Update Order /v1/integrations/orders: get: operationId: get-v1-integrations-orders parameters: - in: query name: orderKey schema: type: - string - 'null' minLength: 1 maxLength: 255 default: null required: false description: Filter by the external system's unique order identifier (order_key). Returns only orders matching this value; omit to skip this filter. example: 327b5abd-017a-4504-a50d-54f1cea80269 - in: query name: orderNumber schema: type: - string - 'null' minLength: 1 maxLength: 255 default: null required: false description: Filter by the customer-facing order identifier (order_number). Returns only orders matching this value; omit to skip this filter. example: Order-123 - in: query name: storeId schema: type: - integer - 'null' minimum: 1 default: null required: false description: Filter by the internal numeric identifier of the store that owns the order. Omit to return orders across all stores. example: 123456 responses: '200': description: Success content: application/json: schema: type: object properties: status: type: integer data: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderDetailOutput' required: - status - data tags: - Orders security: - api_key_header_Api-Key: [] description: 'This endpoint can be used to retrieve data from the order you are calling.The order can be in following 4 statuses (field order_status): - `unfulfilled` indicates an order is ready for ShipMonk to process - `cancelled` indicates an order was cancelled - `fulfilled` indicates an order has been marked as "Fulfilled by 3rd party", unless already fulfilled by ShipMonk - `onHold` indicates an order is placed on hold You can retrieve orders from all of your stores. In case you have not unique orderKeys across stores you can specify the storeId.' summary: Get Order /v1/integrations/orders-list: get: operationId: get-v1-integrations-orders-list parameters: - in: query name: page schema: type: integer minimum: 1 default: 1 required: false description: 1-based page number to return. Defaults to 1. example: 1 - in: query name: pageSize schema: type: integer minimum: 1 maximum: 100 default: 100 required: false description: Number of results per page. Defaults to a server-configured value; check the response metadata for the effective size. example: 10 - in: query name: sortOrder schema: $ref: '#/components/schemas/Fulfillment_PublicApiBundle_Enum_PublicApiOrdering' default: ASC required: false description: 'Sort direction by internal order id: DESC (newest first) or ASC (oldest first).' - in: query name: orderKeys schema: type: - array - 'null' items: type: string minLength: 1 maxLength: 255 default: null required: false description: Filter to orders whose order_key matches any value in this list. - in: query name: orderNumbers schema: type: - array - 'null' items: type: string minLength: 1 maxLength: 255 default: null required: false description: Filter to orders whose order_number matches any value in this list. - in: query name: orderStatus schema: anyOf: - $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_Enum_PublicApiOrderStatus' - type: 'null' default: null required: false description: Filter by current order status (see PublicApiOrderStatus enum); omit to return all statuses. - in: query name: orderType schema: anyOf: - $ref: '#/components/schemas/ShipMonk_OMS_Order_Enum_OrderType' - type: 'null' default: null required: false description: Filter by order type (see OrderType enum); omit to return all types. - in: query name: updatedAtStart schema: type: string format: date-time default: null required: false description: Lower bound (inclusive) on updated_at as an ISO 8601 timestamp; returns orders updated at or after this time. example: '2025-07-24 14:53:00' - in: query name: updatedAtEnd schema: type: string format: date-time default: null required: false description: Upper bound (inclusive) on updated_at as an ISO 8601 timestamp; returns orders updated at or before this time. example: '2025-07-24 14:53:00' - in: query name: shippedAtStart schema: type: string format: date-time default: null required: false description: Lower bound (inclusive) on shipped_at as an ISO 8601 timestamp; returns orders shipped at or after this time. example: '2025-07-24 14:53:00' - in: query name: shippedAtEnd schema: type: string format: date-time default: null required: false description: Upper bound (inclusive) on shipped_at as an ISO 8601 timestamp; returns orders shipped at or before this time. example: '2025-07-24 14:53:00' responses: '200': description: Success content: application/json: schema: type: object properties: status: type: integer data: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderList_PublicApiOrderListOutput' required: - status - data tags: - Orders security: - api_key_header_Api-Key: [] description: When no filters are specified, the endpoint will return up to the first 1,000,000 orders, based on selected ordering. If filters are used, this endpoint will return a maximum of 10,000 orders. summary: Retrieve List of Orders /v1/integrations/sandbox/complete-order: post: operationId: post-v1-integrations-sandbox-complete-order parameters: [] responses: '200': description: Success content: application/json: schema: type: object properties: status: type: integer required: - status tags: - Orders security: - api_key_header_Api-Key: [] description: 'Simulates warehouse shipment of an order in your Sandbox environment. Cannot be used in production. The order must be in a submitted status with available inventory, a valid address, and a valid shipping method. A shipment notification is sent after the delay configured for the store under Account Settings > Stores, defaulting to 20 minutes. For D2C orders, there is approximately a 1-minute delay (up to 5 minutes) between the order transitioning from awaiting pick up to en route. During this window, an awaiting shipment webhook is delivered to simulate the real fulfillment process. You can also simulate order completion directly in the ShipMonk UI. See our Sandbox guide for instructions.' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_Input_CompleteOrderInput' summary: Complete Order /v1/integrations/submit-order: post: operationId: post-v1-integrations-submit-order parameters: [] responses: '200': description: Success content: application/json: schema: type: object properties: status: type: integer required: - status tags: - Orders security: - api_key_header_Api-Key: [] description: 'Submits an order for fulfillment or reschedules its submit date. Submitting an order makes it eligible for the operations team to begin fulfillment. Once submitted, the order enters the fulfillment pipeline and edit restrictions apply: - During picking, order items cannot be changed. - Once packed, no fields on the order can be changed. This endpoint serves two purposes: - Submit immediately — pass a submit_at timestamp in the past (or now) to release the order into the fulfillment queue right away. - Reschedule the submit date — even though submit_at can be set when creating an order, this is the simplest way to change it after the fact. When submit_at is in the future, inventory is reserved immediately and the order is released into the fulfillment queue at the scheduled time.' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_Input_SubmitOrderIntoQueueForFulfillmentAtDateInput' summary: Submit Order components: schemas: Fulfillment_AccountApiBundle_Input_Order_CreateUpdateFulfillmentRequirements_SpecialRequirementsDatesInput: type: object properties: earliest: type: - string - 'null' format: date default: null requested: type: - string - 'null' format: date default: null latest: type: - string - 'null' format: date default: null required: [] title: Special Requirements Dates Input Fulfillment_AccountApiBundle_Input_Order_OrderReferenceInput: type: object properties: type: $ref: '#/components/schemas/Fulfillment_OrderBundle_Enum_OrderReferenceType' value: type: string pattern: \S required: - type - value title: Order Reference Input Fulfillment_IntegrationsBundle_ApiResource_Output_Order_Enum_PublicApiOrderStatus: type: - string enum: - unfulfilled - fulfilled - onHold - cancelled title: Order Status Fulfillment_IntegrationsBundle_ApiResource_Output_Order_OrderPackedItemOutput: type: object properties: sku: description: Stock-keeping unit (SKU) of the order item that was packed. type: string line_key: description: Identifier of the order line this packed item refers to; null when the packed item is not tied to a specific line. type: - string - 'null' quantity: description: Number of units of this SKU packed in this package. type: integer required: - sku - line_key - quantity title: Order Packed Item Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PackingGroupOutput: type: object properties: key: description: Stable identifier of the packing group, unique within the order. type: string name: description: Human-readable name of the packing group; null if unnamed. type: - string - 'null' required: - key - name title: Packing Group Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiAccountForTradingPartnerOutput: type: object properties: id: description: Internal numeric identifier of the merchant account. type: integer name: description: Display name of the merchant account. type: string required: - id - name title: Account For Trading Partner Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiAccountTradingPartnerOutput: type: object properties: id: description: Internal numeric identifier of the trading partner. type: integer identifier: description: Short human-readable code identifying the trading partner. type: string name: description: Display name of the trading partner. type: string account: description: Merchant account that owns this trading partner relationship. $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiAccountForTradingPartnerOutput' required: - id - identifier - name - account title: Account Trading Partner Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiCountryDetailOutput: type: object properties: code: description: ISO 3166-1 alpha-2 country code; null if unknown. type: - string - 'null' name: description: Country name in English; null if unknown. type: - string - 'null' required: - code - name title: Country Detail Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiExtraDataOutput: type: object properties: label: description: 'Identifier of the extra data type. Currently supported: carrierShippingMethod.' $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_Enum_ShipmentNotificationExtraDataType' value: description: Value corresponding to the label of the extra data entry. type: string required: - label - value title: Extra Data Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderActionsRequiredOutput: type: object properties: item_mapping: description: True if one or more order items could not be mapped to a known product and require manual mapping. type: boolean address: description: True if the shipping address could not be validated and requires correction. type: boolean shipping_mapping: description: True if the requested shipping service could not be mapped to an available carrier service and requires manual mapping. type: boolean customs: description: True if customs information (e.g. declared value, HS codes) is missing or incomplete for an international shipment. type: boolean at_risk: description: True if the order is at risk of missing its required ship-by date. type: boolean routing: description: True if a B2B routing instruction is missing and must be supplied before shipping. type: boolean freight_quote: description: True if a freight quote must be selected before the order can ship. type: boolean freight_info: description: True if additional freight details (e.g. dimensions, pallet count) are required to obtain a freight quote. type: boolean ship_short: description: True if the order is flagged as a short ship, meaning one or more items could not be fulfilled in the requested quantity. type: boolean hs_code: description: True if Harmonized System (HS) tariff codes are missing for one or more items on a customs-bound shipment. type: boolean global_e_label: description: True if a Global-e label (cross-border shipping label provided by the Global-e service) is still required for the order. type: boolean ship_monk_hazmat_carrier_service_not_available: description: 'Deprecated: Will always be false, kept for backwards compatibility True if the order contains hazardous materials but no carrier service is available to ship them from the assigned warehouse.' deprecated: true type: boolean automation_rule: description: True if an automation rule has flagged the order for manual review or action. type: boolean pending_b2b_routing: description: True if the order is awaiting B2B retailer routing instructions before fulfillment can proceed. type: boolean value_added_service_problem: description: True if one of the order's value-added services (e.g. kitting, custom packaging) cannot be performed and needs attention. type: boolean required: - item_mapping - address - shipping_mapping - customs - at_risk - routing - freight_quote - freight_info - ship_short - hs_code - global_e_label - ship_monk_hazmat_carrier_service_not_available - automation_rule - pending_b2b_routing - value_added_service_problem title: Order Actions Required Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderAttributeOutput: type: object properties: name: description: Key of the custom attribute. type: string value: description: Value of the custom attribute. type: string required: - name - value title: Order Attribute Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderCostsOutput: type: object properties: estimated_shipping_related_charges: description: Estimated shipping-related charges for the order. Null when no estimate is available. anyOf: - $ref: '#/components/schemas/ShipMonk_Money_Output_MoneyOutput' - type: 'null' estimated_packaging_material_charges: description: Estimated charges for packaging materials used in the order. Null when no estimate is available. anyOf: - $ref: '#/components/schemas/ShipMonk_Money_Output_MoneyOutput' - type: 'null' estimated_pick_and_pack_charges: description: Estimated charges for picking and packing labor for the order. Null when no estimate is available. anyOf: - $ref: '#/components/schemas/ShipMonk_Money_Output_MoneyOutput' - type: 'null' required: - estimated_shipping_related_charges - estimated_packaging_material_charges - estimated_pick_and_pack_charges title: Order Costs Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderDetailCustomDataOutput: type: object properties: name: description: Key name of the custom data entry. type: string value: description: Value of the custom data entry. type: string required: - name - value title: Order Detail Custom Data Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderDetailOutput: type: object properties: order_key: description: Unique identifier from an external system used to associate an order. Must be unique per order and store. type: string order_number: description: Customer-facing identifier for an order. Uniqueness is recommended but not strictly enforced. type: string order_type: description: Order classification (e.g. standard, wholesale, return). Null when not categorized. anyOf: - $ref: '#/components/schemas/ShipMonk_OMS_Order_Enum_OrderType' - type: 'null' store: description: Sales channel or storefront the order originated from. $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiStoreNameOutput' warehouse: description: Warehouse where the order is processed. Null if a warehouse has not yet been assigned. anyOf: - $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiWarehouseDetailOutput' - type: 'null' trading_partner: description: B2B trading partner (e.g. retailer or distributor) the order is destined for. Null for direct-to-consumer orders. anyOf: - $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiAccountTradingPartnerOutput' - type: 'null' ordered_at: description: ISO 8601 timestamp indicating when the order was originally placed. type: string format: date-time customer_email: description: Customer's email address. Null when not provided by the source system. anyOf: - type: string - type: 'null' shipping_method: description: Carrier and service selected to ship the order. Null if no method has been resolved yet. anyOf: - $ref: '#/components/schemas/Fulfillment_PublicApiBundle_ApiResource_ShippingMethod_PublicApiShippingMethodDetailOutput' - type: 'null' requested_shipping_service: description: Free-text shipping service originally requested by the customer or source system; null if none was specified. type: - string - 'null' shipping_paid: description: Amount the customer paid for shipping, expressed in the order's currency_code. type: number format: double tax_paid: description: Amount the customer paid in taxes, expressed in the order's currency_code. type: number format: double order_costs: description: Estimated fulfillment-service charges (shipping, packaging, pick & pack) for the order. These are estimates and may differ from final billed amounts. $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderCostsOutput' ship_from: description: Origin address from which the order will ship. Null when not yet determined. anyOf: - $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiShippingOrderDetailAddressOutput' - type: 'null' ship_to: description: Destination address the order will be shipped to. Null when not yet specified. anyOf: - $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiShippingOrderDetailAddressOutput' - type: 'null' order_status: description: 'High-level order state: unfulfilled (not yet shipped), fulfilled (shipped), onHold (paused), cancelled.' $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_Enum_PublicApiOrderStatus' processing_status: description: 'Fine-grained processing stage of the order. Values: backorder, unable_to_submit, queued_to_submit, subscription, package_forwarding, awaiting_label_request_from_merchant_facility, on_hold, submitted, pick_in_progress, pack_in_progress, packed, awaiting_pick_up, awaiting_carrier_processing, en_route, delivered, undeliverable, shipped_untrackable, fulfilled_by_3rd, cancellation_requested, cancelled, updating.' $ref: '#/components/schemas/Fulfillment_OrderBundle_Enum_OrderListStatus' items: description: Line items (SKUs and quantities) included in the order. type: array items: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderItemOutput' attributes: description: Custom key/value attributes attached to the order by the merchant or source system. type: array items: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderAttributeOutput' currency_code: description: ISO 4217 currency code used for all monetary values on the order. type: string references: description: Additional external reference identifiers attached to the order (e.g. PO number, marketplace reference). type: array items: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderReferenceOutput' custom_data: description: Custom key-value data associated with the order. type: array items: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderDetailCustomDataOutput' special_requirements: description: Special handling requirements for the order, such as required documents, label dates, and pack list rules. Null when none apply. anyOf: - $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiSpecialRequirementsOutput' - type: 'null' actions_required: description: Boolean flags indicating issues that must be resolved before the order can be fulfilled. $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderActionsRequiredOutput' master_tracking_number: description: Master tracking number that groups all packages of a multi-piece shipment; null when not applicable. type: - string - 'null' tracking_url: description: Carrier URL where the customer can track the shipment; null if not yet available. type: - string - 'null' returns: description: Return Merchandise Authorizations (RMAs) created for this order. type: array items: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderReturnDataOutput' packages: description: Per-package fulfillment data, including tracking numbers, weights, and packed contents. type: array items: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderPackageDataOutput' tax_id: description: 'Deprecated: Use recipientTaxId Deprecated; use recipient_tax_id instead. Tax identifier associated with the recipient.' deprecated: true anyOf: - $ref: '#/components/schemas/Fulfillment_PublicApiBundle_ApiResource_Order_PublicApiOrderTaxIdOutput' - type: 'null' recipient_tax_id: description: Recipient tax identification (e.g. VAT or EIN); null when not provided. Used for customs clearance on international shipments. anyOf: - $ref: '#/components/schemas/Fulfillment_PublicApiBundle_ApiResource_Order_PublicApiOrderTaxIdOutput' - type: 'null' shipment_data: description: Carrier and tracking details once the order has shipped; null until shipment data is available. anyOf: - $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiShipmentDataOutput' - type: 'null' order_parts: description: Information about related orders when an order has been split into multiple parts; null if the order was not split. anyOf: - $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderPartOutput' - type: 'null' shipped_at: description: ISO 8601 timestamp of when the order was shipped; null if not yet shipped. type: - string - 'null' format: date-time updated_at: description: ISO 8601 timestamp of when the order was last updated; null if never updated since creation. type: - string - 'null' format: date-time order_size: description: 'Size classification of the order based on item dimensions: unknown, regular, oversized_item, large, or extra_large.' $ref: '#/components/schemas/Fulfillment_OrderBundle_Enum_OrderSize' extra_data: description: Additional key/value attributes attached to the shipment notification (e.g. carrier shipping method). type: array items: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiExtraDataOutput' serial_numbers: description: Serial numbers of items fulfilled in the order, grouped by order line. type: array items: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiSerialNumberOutput' gift_message: description: Gift message to include with the order; null if the order is not a gift. type: - string - 'null' gift_from: description: Name of the gift sender; null if the order is not a gift. type: - string - 'null' customer_notes: description: Customer-provided notes about the order; null if no notes were submitted. type: - string - 'null' order_detail_url: description: URL to view the order in the ShipMonk web application (requires sign-in). type: string required: - order_key - order_number - order_type - store - warehouse - trading_partner - ordered_at - customer_email - shipping_method - requested_shipping_service - shipping_paid - tax_paid - order_costs - ship_from - ship_to - order_status - processing_status - items - attributes - currency_code - references - custom_data - special_requirements - actions_required - master_tracking_number - tracking_url - returns - packages - tax_id - recipient_tax_id - shipment_data - order_parts - shipped_at - updated_at - order_size - extra_data - serial_numbers - gift_message - gift_from - customer_notes - order_detail_url title: Order Detail Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderItemOutput: type: object properties: line_key: description: External system identifier for this order line, unique within the order. Null when not provided. type: - string - 'null' sku: description: Stock Keeping Unit (SKU) identifying the marketplace item being ordered. type: string name: description: Display name of the marketplace item as captured on the order line. type: - string - 'null' quantity: description: Number of units of this SKU ordered. type: integer price: description: Per-unit price charged to the customer, in the order's currency_code. Null when not provided. type: - number - 'null' format: double image_url: description: Absolute URL of the marketplace item image, if available. type: - string - 'null' fulfilled_quantity: description: Number of units already shipped (fulfilled) for this line. Null if fulfillment has not started. type: - integer - 'null' source: description: 'How this line was added to the order: imported (from the source channel), manual (added by a user), inserted (system-inserted, e.g. promo), packaging (added as packaging material), claim_reship (added as part of a claim reship).' $ref: '#/components/schemas/Fulfillment_OrderBundle_Enum_OrderItemSource' products: description: Physical products allocated to fulfill this order line. A line with a bundle SKU may resolve to multiple component products. type: array items: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderItemProductOutput' required: - line_key - sku - name - quantity - price - image_url - fulfilled_quantity - source - products title: Order Item Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderItemProductLotOutput: type: object properties: number: description: Lot (batch) number assigned to the product. Null when the lot has no number recorded. type: - string - 'null' expiration_date: description: Lot expiration date in ISO 8601 format (YYYY-MM-DD), or null if not applicable. type: - string - 'null' format: date required: - number - expiration_date title: Order Item Product Lot Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderItemProductOutput: type: object properties: sku: description: Stock Keeping Unit (SKU) identifying the product being ordered. type: string quantity: description: Number of units of this physical product allocated to the order line. type: integer backordered_quantity: description: Number of units of this product that could not be allocated because of insufficient stock. type: integer lot: description: Inventory lot (batch) selected for this product. Null when the product is not lot-tracked or no lot has been assigned yet. anyOf: - $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderItemProductLotOutput' - type: 'null' other_potential_lots: description: Other inventory lots that could alternatively be used to fulfill this product. type: array items: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderItemProductLotOutput' required: - sku - quantity - backordered_quantity - lot - other_potential_lots title: Order Item Product Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderList_PublicApiOrderListOutput: type: object properties: orders: description: Orders matching the request criteria for the current page. type: array items: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderDetailOutput' required: - orders title: Order List Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderPackageDataOutput: type: object properties: number: description: Sequential index (1-based) of this package within the order; null if not assigned. type: - integer - 'null' tracking_number: description: Carrier tracking number for this package; null if not yet generated or untrackable. type: - string - 'null' tracking_url: description: Carrier URL for tracking this package; null if not yet available. type: - string - 'null' weight_lb: description: Total weight of the package (the unit, despite the field name, is provided in the value object); null if not measured. anyOf: - $ref: '#/components/schemas/ShipMonk_Measurement_Output_WeightOutput' - type: 'null' pallet_weight_lb: description: Weight of the pallet on which this package is shipped (unit given inside the value object); null if not palletized or not measured. anyOf: - $ref: '#/components/schemas/ShipMonk_Measurement_Output_WeightOutput' - type: 'null' pallet_number: description: Index (1-based) of the pallet that contains this package; null if not palletized. type: - integer - 'null' box_number: description: Index (1-based) of the box within its pallet; null if not palletized. type: - integer - 'null' carton_labels: description: Carton-level labels (e.g. packing slip, pallet label) applied to this package. type: array items: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiPackageCartonLabelOutput' packed_products: description: Products contained in this package, aggregated by SKU with packed quantities and lot details. type: array items: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiPackedProductOutput' packing_group: description: Packing group this package belongs to, used to split an order across multiple shipments; null if not grouped. anyOf: - $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PackingGroupOutput' - type: 'null' packed_items: description: Order line items packed in this package, with per-line quantities. type: array items: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_OrderPackedItemOutput' required: - number - tracking_number - tracking_url - weight_lb - pallet_weight_lb - pallet_number - box_number - carton_labels - packed_products - packing_group - packed_items title: Order Package Data Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderPartItemOutput: type: object properties: order_number: description: Order number of this part order. type: string required: - order_number title: Order Part Item Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderPartMainOrderOutput: type: object properties: order_number: description: Order number of the main order this part was split from. type: string parts: description: List of all part orders created from splitting the main order. type: array items: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderPartItemOutput' required: - order_number - parts title: Order Part Main Order Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderPartOutput: type: object properties: main_order: description: Reference to the original (main) order from which this order was split. $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderPartMainOrderOutput' required: - main_order title: Order Part Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderReferenceOutput: type: object properties: type: description: 'Type of order reference. One of: order_number, original_imported_order_number, customer_order_number, po_number, reference_number, b2b_routing_reference, release_number, job_number, depositor_order_number.' $ref: '#/components/schemas/Fulfillment_OrderBundle_Enum_OrderReferenceType' value: description: The reference identifier value, interpreted according to type. type: string required: - type - value title: Order Reference Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderReturnDataOutput: type: object properties: rma: description: Return Merchandise Authorization (RMA) number identifying this return. type: string required: - rma title: Order Return Data Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiPackageCartonLabelOutput: type: object properties: type: description: Kind of label printed on the carton. Values include order- and carton-level pack lists, retailer packing slips, carton/pallet labels, GS1 labels, and customized or special-instruction labels. $ref: '#/components/schemas/ShipMonk_OMS_RequiredLabels_Enum_PackingLabelType' identifier: description: Identifier printed on the label (e.g. SSCC); null if the label type has no identifier. type: - string - 'null' required: - type - identifier title: Package Carton Label Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiPackedProductOutput: type: object properties: sku: description: Stock-keeping unit (SKU) of the product packed in this package. type: string quantity: description: Number of units of this SKU packed in this package. type: integer lots: description: Lot/batch identifiers and quantities for the packed units, when lot tracking applies. type: array items: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderItemProductLotOutput' required: - sku - quantity - lots title: Packed Product Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiRoutingDataOutput: type: object properties: routing_key: description: Identifier of the routing instructions assigned to this shipment (used to match retailer routing guides). type: string required: - routing_key title: Routing Data Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiSerialNumberItemOutput: type: object properties: sku: description: Stock Keeping Unit (SKU) identifying the product. type: string serial_number: description: Serial number recorded for the fulfilled unit. type: string required: - sku - serial_number title: Serial Number Item Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiSerialNumberOutput: type: object properties: line_key: description: Key of the order line item these serial numbers belong to; null when serial numbers cannot be matched to a specific line. type: - string - 'null' serial_numbers: description: Serial numbers recorded for units fulfilled on this order line. type: array items: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiSerialNumberItemOutput' required: - line_key - serial_numbers title: Serial Number Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiShipmentDataOutput: type: object properties: carrier: description: Name of the carrier handling the shipment. For standard shipments it is one value from the list. In cases involving custom labels or freight shipments, the field may contain values outside of this list. anyOf: - $ref: '#/components/schemas/ShipMonk_ShippingConnector_ValueObject_PublicApiCarrierIdentifier' - type: string service: description: Carrier service level used (e.g. Ground, Express); null if the carrier does not report a service level. type: - string - 'null' carrier_tracking_url: description: Public URL provided by the carrier to track the shipment; null if not available. type: - string - 'null' carrier_alpha_code: description: Carrier's Standard Carrier Alpha Code (SCAC), a 2-4 letter identifier; null if not assigned. type: - string - 'null' carrier_trans_method_code: description: Carrier transportation method code (e.g. air, ground, ocean); null if not provided by the carrier. type: - string - 'null' bill_of_lading_number: description: Bill of lading (BOL) number, the transport document identifier issued by the carrier; null if not yet assigned. type: - string - 'null' master_bill_of_lading_number: description: Master bill of lading number grouping multiple BOLs under a consolidated shipment; null if not consolidated. type: - string - 'null' load_number: description: Carrier-assigned load number identifying the freight load this shipment belongs to; null if not provided. type: - string - 'null' authorization_number: description: Carrier authorization number (e.g. PRO or pickup authorization) issued for the shipment; null if not provided. type: - string - 'null' estimated_shipping_cost: description: Estimated shipping cost in the order's currency; null if not yet calculated. type: - number - 'null' format: double routing: description: Routing information assigned to the shipment (e.g. for retailer-routed freight); null when routing is not applicable. anyOf: - $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiRoutingDataOutput' - type: 'null' required: - carrier - service - carrier_tracking_url - carrier_alpha_code - carrier_trans_method_code - bill_of_lading_number - master_bill_of_lading_number - load_number - authorization_number - estimated_shipping_cost - routing title: Shipment Data Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiShippingLabelOutput: type: object properties: url: description: URL from which the customer-provided shipping label can be downloaded. type: string required: - url title: Shipping Label Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiShippingOrderDetailAddressOutput: type: object properties: name: description: Full name of the recipient or contact at this address. type: - string - 'null' company: description: Company name at this address, if any. type: - string - 'null' street1: description: Primary street address line (e.g. number and street). type: - string - 'null' street2: description: Secondary street address line (e.g. apartment, suite, or unit). type: - string - 'null' state: description: State, province, or region of the address. type: - string - 'null' city: description: City or locality of the address. type: - string - 'null' zip: description: Postal or ZIP code of the address. type: - string - 'null' country_code: description: ISO 3166-1 alpha-2 country code (e.g. US, DE). type: - string - 'null' phone: description: Contact phone number for the address. type: - string - 'null' email: description: Contact email for the address. type: - string - 'null' residential: description: true if the address is residential, false if commercial, null if unknown. type: - boolean - 'null' required: - name - company - street1 - street2 - state - city - zip - country_code - phone - email - residential title: Shipping Order Detail Address Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiSpecialInstructionDateOutput: type: object properties: earliest: description: Earliest acceptable date for the event (ISO-8601 date); null if no lower bound. type: - string - 'null' format: date-time requested: description: Preferred target date for the event (ISO-8601 date); null if not specified. type: - string - 'null' format: date-time latest: description: Latest acceptable date for the event (ISO-8601 date); null if no upper bound. type: - string - 'null' format: date-time required: - earliest - requested - latest title: Special Instruction Date Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiSpecialInstructionNameUrlOutput: type: object properties: name: description: Human-readable name or description of the document; null if unnamed. type: - string - 'null' url: description: URL from which the document file can be downloaded. type: string required: - name - url title: Special Instruction Name Url Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiSpecialRequirementsOutput: type: object properties: special_instruction: description: Free-text special handling instructions for the order, or null if none. type: - string - 'null' carton_labels: description: Carton labels (name and download URL) that must be applied to the order's cartons. type: array items: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiSpecialInstructionNameUrlOutput' additional_documents: description: Additional documents (name and download URL) that must accompany the order. type: array items: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiSpecialInstructionNameUrlOutput' shipping_label: description: Customer-provided shipping label to be used for the order; null if not supplied. anyOf: - $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiShippingLabelOutput' - type: 'null' shipping_date: description: Requested shipping date with earliest, requested, and latest dates (ISO-8601); null if none requested. anyOf: - $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiSpecialInstructionDateOutput' - type: 'null' delivery_date: description: Requested delivery date with earliest, requested, and latest dates (ISO-8601); null if none requested. anyOf: - $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiSpecialInstructionDateOutput' - type: 'null' cancel_date: description: Date (ISO-8601) after which the order should be cancelled if not yet shipped; null if no cutoff. type: - string - 'null' format: date-time pack_list_required: description: True if a packing list document must be included with the shipment. type: boolean required: - special_instruction - carton_labels - additional_documents - shipping_label - shipping_date - delivery_date - cancel_date - pack_list_required title: Special Requirements Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiStoreNameOutput: type: object properties: id: description: Internal numeric identifier of the store. type: integer name: description: Display name of the store. type: string required: - id - name title: Store Name Output Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiWarehouseDetailOutput: type: object properties: identifier: description: Short human-readable code identifying the warehouse. type: string id: description: Internal numeric identifier of the warehouse. type: integer name: description: Display name of the warehouse. type: string warehouse_wms_type: description: 'Warehouse management system (WMS) backing the warehouse. One of: shipmonk (ShipMonk-operated), merchant_facility (merchant''s own facility).' $ref: '#/components/schemas/ShipMonk_WmsConnector_Order_ValueObject_WmsType' required: - identifier - id - name - warehouse_wms_type title: Warehouse Detail Output Fulfillment_IntegrationsBundle_Crate_OrderSyncOutput: type: object properties: message: description: Human-readable message indicating whether the order was created or updated. type: string required: - message title: Order Sync Output Fulfillment_IntegrationsBundle_Enum_CartonLabelType: type: - string enum: - gs1 - shipmonk_gs1 - customized_carton_labels - custom title: Carton Label Type Fulfillment_IntegrationsBundle_Enum_OrderLevelPackingSlipType: type: - string enum: - retailer title: Order Level Packing Slip Type Fulfillment_IntegrationsBundle_Enum_SandboxPackType: type: - string enum: - singlepack - multipack title: Sandbox Pack Type Fulfillment_IntegrationsBundle_Enum_ShipmentNotificationExtraDataType: type: - string enum: - carrierShippingMethod title: Shipment Notification Extra Data Type Fulfillment_IntegrationsBundle_Input_CompleteOrderInput: type: object properties: order_key: description: Unique identifier of the order in the external (caller's) system, as originally supplied when the order was created. type: string example: 327b5abd-017a-4504-a50d-54f1cea80269 store_id: description: Identifier of the store this return belongs to. type: integer example: 123456 pack_type: description: 'Optional packaging type for the simulated fulfillment: ''singlepack'' (all items in one box) or ''multipack'' (items split across multiple boxes).' $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_Enum_SandboxPackType' default: singlepack required: - order_key - store_id title: Complete Order Input Fulfillment_IntegrationsBundle_Input_SubmitOrderIntoQueueForFulfillmentAtDateInput: type: object properties: order_key: description: Unique identifier of the order in the external (caller's) system, as originally supplied when the order was created. type: string example: 327b5abd-017a-4504-a50d-54f1cea80269 store_id: description: Identifier of the store this return belongs to. type: integer example: 123456 submit_at: description: ISO 8601 timestamp at which the order should be released into the fulfillment queue; submitting in the past releases it immediately. type: string format: date-time example: '2025-07-24 14:53:00' required: - order_key - store_id - submit_at title: Submit Order Into Queue For Fulfillment At Date Input Fulfillment_IntegrationsBundle_Type_OrderSyncOrderStatus: type: - string enum: - unfulfilled - fulfilled - cancelled - onHold x-enumDescriptions: unfulfilled: Order will be fulfilled by ShipMonk fulfilled: Order has been already fulfilled, ShipMonk won't fulfill this order cancelled: Order won't be fulfilled by ShipMonk onHold: Order is temporarily on hold and can be restored or cancelled any time title: Order Sync Order Status Fulfillment_OrderBundle_Enum_FulfillmentStrategy: type: - string enum: - standard - drop-ship - cross-dock title: Fulfillment Strategy Fulfillment_OrderBundle_Enum_OrderItemSource: type: - string enum: - imported - manual - inserted - packaging - claim_reship title: Order Item Source Fulfillment_OrderBundle_Enum_OrderListStatus: type: - string enum: - backorder - unable_to_submit - queued_to_submit - subscription - package_forwarding - awaiting_label_request_from_merchant_facility - on_hold - submitted - pick_in_progress - pack_in_progress - packed - awaiting_pick_up - awaiting_carrier_processing - en_route - delivered - undeliverable - shipped_untrackable - fulfilled_by_3rd - cancellation_requested - cancelled - updating title: Order List Status Fulfillment_OrderBundle_Enum_OrderReferenceType: type: - string enum: - order_number - original_imported_order_number - customer_order_number - po_number - reference_number - b2b_routing_reference - release_number - job_number - depositor_order_number title: Order Reference Type Fulfillment_OrderBundle_Enum_OrderSize: type: - string enum: - unknown - regular - oversized_item - large - extra_large title: Order Size Fulfillment_OrderBundle_Input_Enum_OrderItemSpecialInstructionType: type: - string enum: - embroidery title: Order Item Special Instruction Type Fulfillment_PublicApiBundle_ApiResource_Carrier_PublicApiCarrierDetailOutput: type: object properties: id: type: integer name: type: string required: - id - name title: Carrier Detail Output Fulfillment_PublicApiBundle_ApiResource_Order_PublicApiOrderTaxIdOutput: type: object properties: tax_id_type: description: 'Type of tax identifier. One of: VAT, IOSS, TIN, EIN, EORI, ARN, RFC, CPF, CNPJ, PCCC.' $ref: '#/components/schemas/Fulfillment_UserBundle_Enum_TaxIdType' value: description: Tax identification number, formatted according to its type and issuing country. type: string issuing_country: description: Country that issued the tax identification number. $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiCountryDetailOutput' required: - tax_id_type - value - issuing_country title: Order Tax Id Output Fulfillment_PublicApiBundle_ApiResource_ShippingMethod_PublicApiShippingMethodDetailOutput: type: object properties: id: type: integer name: type: string carrier: $ref: '#/components/schemas/Fulfillment_PublicApiBundle_ApiResource_Carrier_PublicApiCarrierDetailOutput' required: - id - name - carrier title: Shipping Method Detail Output Fulfillment_PublicApiBundle_Enum_PublicApiOrdering: type: - string enum: - DESC - ASC title: Ordering Fulfillment_UserBundle_Enum_TaxIdType: type: - string enum: - VAT - IOSS - TIN - EIN - EORI - ARN - RFC - CPF - CNPJ - PCCC title: Tax Id Type ShipMonk_Measurement_Output_WeightOutput: type: object properties: value: description: Numeric weight value, expressed in the unit given by the unit field. type: number format: double unit: description: 'Unit of measure for the weight value. One of: kg, g, lb, oz.' $ref: '#/components/schemas/ShipMonk_Measurement_ValueObject_WeightUnit' required: - value - unit title: Weight Output ShipMonk_Measurement_ValueObject_WeightUnit: type: - string enum: - kg - g - lb - oz title: Weight Unit ShipMonk_Money_Output_MoneyOutput: type: object properties: amount: description: Decimal monetary amount in the currency given by the sibling currency field. type: number format: double currency: description: ISO 4217 currency code (e.g. USD, EUR) for the accompanying amount. type: string required: - amount - currency title: Money Output ShipMonk_OMS_Order_Enum_Embroidery_EmbroideryType: type: - string enum: - logo - text - text_with_logo - logo_identifier - text_with_symbol title: Embroidery Type ShipMonk_OMS_Order_Enum_OrderType: type: - string enum: - direct_to_consumer - retail - amazon - transfer - internal_warehouse_transfer - removal_liquidation - disposal - bonded_inventory_clearance - work_order title: Order Type ShipMonk_OMS_RequiredLabels_Enum_PackingLabelType: type: - string enum: - shipmonk_pack_list_order_level - shipmonk_pack_list_carton_level - retailer_packing_slip_order_level - shipmonk_carton_label - shipmonk_pallet_label - gs1_label - shipmonk_gs1 - customized_carton_labels - liquid_iv_packing_list - custom_pack_list_order_level - special_instructions title: Packing Label Type ShipMonk_OMS_RequiredLabels_Enum_RequiredLabelDataSource: type: - string enum: - internal - third-party-after-shipment-notification title: Required Label Data Source ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderAdditionalDocumentInput: type: object properties: name: description: Human-readable name of the document, shown in reports and to warehouse staff. type: string maxLength: 255 url: description: Publicly accessible URL of the PDF document to print and enclose with the shipment. type: string maxLength: 2048 required: - name - url title: Create Or Update Order Additional Document Input ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderAttributeInput: type: object properties: name: description: Key identifying the custom attribute; must be unique within the order's attributes array. type: string maxLength: 255 value: description: Value paired with the attribute `name` on the order. type: string maxLength: 255 required: - name - value title: Create Or Update Order Attribute Input ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderB2BAttributeInput: type: object properties: name: description: Name (key) of the B2B attribute; should be unique within the item's b2b_attributes list. type: string maxLength: 255 value: anyOf: - type: integer - type: number - type: boolean - type: string - type: array required: - name - value title: Create Or Update Order B2 B Attribute Input ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderCartonLabelInput: type: object properties: type: description: Type of label requested to be applied to the carton (e.g., gs1, shipmonk_gs1, customized_carton_labels). Values include order- and carton-level pack lists, retailer packing slips, carton/pallet labels, GS1 labels, and customized or special-instruction labels. Incorrect configuration may result in retailer chargebacks. The ShipMonk B2B team will provide label configuration guidance during the retailer setup process (https://support.shipmonk.com/s/article/New-Retailer-Setup). $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_Enum_CartonLabelType' default: custom name: description: Human-readable name of the carton label template; used to identify the label in reports. type: - string - 'null' maxLength: 255 default: null url: description: Publicly accessible URL of the carton label PDF; required when `type` is `custom`. type: - string - 'null' maxLength: 2048 default: null shipping_data_required: description: If true, carrier tracking and address data must be merged onto the carton label before printing. type: boolean default: false approved_shipment_id_number_required: description: If true, the retailer's approved shipment ID (e.g., an ASN number returned after the shipment notice) must be printed on the label. The order will not ship until the ID is supplied. type: boolean default: false data_source: description: 'Where the label data comes from. Allowed values: `internal` (data already supplied with the order), `third-party-after-shipment-notification` (label is rendered after a third party returns data following the shipment notification).' $ref: '#/components/schemas/ShipMonk_OMS_RequiredLabels_Enum_RequiredLabelDataSource' default: internal required: [] title: Create Or Update Order Carton Label Input ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderCustomDataInput: type: object properties: name: description: Key (name) of the custom data entry; should be unique within the item's custom_data list. type: string minLength: 2 maxLength: 255 value: description: Value stored under the corresponding custom_data name. type: string required: - name - value title: Create Or Update Order Custom Data Input ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderInput: type: object properties: store_id: description: Identifier of the store the order belongs to. type: integer minimum: 1 example: 123456 order_number: description: Customer-facing order identifier (e.g. shown on the packing slip). Uniqueness is recommended but not enforced. Immutable after creation. type: string maxLength: 255 example: Order-123 order_key: description: Stable external identifier used to associate this order on subsequent updates; must be unique per order and acts as the upsert key. type: string maxLength: 255 example: 327b5abd-017a-4504-a50d-54f1cea80269 items: description: Line items to be fulfilled in the order. type: array items: $ref: '#/components/schemas/ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderItemInput' ship_to: description: Recipient's shipping destination address; used to generate the shipping label and select the carrier service. $ref: '#/components/schemas/ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderShipToInput' requested_shipping_service: description: The shipping option passed from your integration (e.g., Free Shipping, 2-Day Shipping); must match a Shipping Mapping configured in ShipMonk — if no match is found, the order will be placed in Action Required and cannot be fulfilled until resolved. type: string maxLength: 255 ordered_at: description: ISO 8601 timestamp when the order was originally placed in the source system. type: string format: date-time example: '2025-07-24 14:53:00' order_status: description: 'Current status of the order. Allowed values: `unfulfilled` (ready to be picked/shipped), `fulfilled` (already shipped externally), `cancelled` (will not be shipped), `onHold` (paused, will not be picked until released).' $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_Type_OrderSyncOrderStatus' attributes: description: Free-form key/value pairs stored on the order, used for custom development. type: array items: $ref: '#/components/schemas/ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderAttributeInput' default: [] trading_partner: description: Name of the retailer or trading partner for B2B/EDI orders; required to apply the partner's routing and labeling rules. type: - string - 'null' maxLength: 255 default: null order_type: description: Classifies how the order should be fulfilled. If not specified, defaults to direct_to_consumer. Orders intended for retail or B2B distribution must use retail to meet compliance requirements. anyOf: - $ref: '#/components/schemas/ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderOrderType' - type: 'null' default: null customer_email: description: Recipient email address forwarded to the carrier for delivery notifications. type: - string - 'null' maxLength: 255 default: null shipping_paid: description: Amount the customer paid for shipping, expressed in the order's `currency_code`. Informational only; does not affect rated postage. type: - number - 'null' format: double minimum: 0 default: null taxes_paid: description: Tax amount the customer paid, in the order's `currency_code`. Informational only; used for customs paperwork on international shipments. type: - number - 'null' format: double minimum: 0 default: null currency_code: description: ISO 4217 three-letter currency code for `shipping_paid`, `taxes_paid`, and item prices (e.g., 'USD', 'EUR'). type: - string - 'null' maxLength: 3 default: USD references: description: External identifiers (e.g., PO number, marketplace order ID) linking this order back to upstream systems; informational only. type: array items: $ref: '#/components/schemas/Fulfillment_AccountApiBundle_Input_Order_OrderReferenceInput' default: [] customer_notes: description: Notes provided by the buyer (e.g., delivery preferences). Stored on creation only; subsequent updates are ignored once a value is set. type: - string - 'null' maxLength: 65535 default: null internal_notes: description: Notes for internal warehouse staff, not shown to the buyer. Stored on creation only; ignored on subsequent updates. type: - string - 'null' maxLength: 65535 default: null warehouse: description: Identifier of the warehouse that must fulfill this order (e.g., 'FL1', 'CA1'). Use the codes provided by your account manager; omit to let the system pick the best warehouse. type: - string - 'null' maxLength: 255 default: null example: PA1 gift_message: description: Message printed on a gift note included with the shipment. Stored on creation only; ignored on subsequent updates. type: - string - 'null' maxLength: 65535 default: null gift_from: description: Sender name printed on the gift note alongside `gift_message`. type: - string - 'null' maxLength: 255 default: null custom_data: description: Free-form key/value metadata stored on the order; not interpreted by fulfillment logic and returned as-is in order reads. type: array items: $ref: '#/components/schemas/ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderCustomDataInput' default: [] b2b_attributes: description: B2B-specific attributes (e.g., ASN, routing instructions) used when fulfilling retailer orders. Contact api@shipmonk.com to enable B2B order processing on your account before sending these. type: array items: $ref: '#/components/schemas/ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderB2BAttributeInput' default: [] submit_at: description: ISO 8601 timestamp at which the order should be released to the warehouse for picking. Until this time the order is held; omit to release immediately. type: - string - 'null' format: date-time default: null example: '2025-07-24 14:53:00' special_requirements: description: Optional bundle of special handling requirements (packing slip, carton labels, custom dates, pre-generated shipping label, etc.) to apply to this order. anyOf: - $ref: '#/components/schemas/ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderSpecialRequirementsInput' - type: 'null' default: null recipient_tax_id: description: Recipient's tax identifier (e.g., VAT, EORI) required for customs clearance on international shipments. anyOf: - $ref: '#/components/schemas/ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderTaxIdInput' - type: 'null' default: null minimum_shelf_life_days: description: Minimum remaining shelf life (in days from the ship date) required for every lot-controlled item in the order; omit to accept any shelf life. type: - integer - 'null' minimum: 1 default: null required: - store_id - order_number - order_key - items - ship_to - requested_shipping_service - ordered_at - order_status title: Create Or Update Order Input ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderItemB2BAttributeInput: type: object properties: name: description: Name (key) of the B2B attribute; should be unique within the item's b2b_attributes list. type: string maxLength: 255 value: description: Value of the B2B attribute identified by the sibling `name` (free-form string). type: string maxLength: 255 required: - name - value title: Create Or Update Order Item B2 B Attribute Input ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderItemEmbroiderySpecialInstructionInput: type: object properties: type: $ref: '#/components/schemas/Fulfillment_OrderBundle_Input_Enum_OrderItemSpecialInstructionType' values: description: List of embroidery instruction values type: array items: $ref: '#/components/schemas/ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderItemEmbroiderySpecialInstructionValueInput' required: - type - values title: Create Or Update Order Item Embroidery Special Instruction Input ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderItemEmbroiderySpecialInstructionValueInput: type: object properties: type: description: Type of embroidery $ref: '#/components/schemas/ShipMonk_OMS_Order_Enum_Embroidery_EmbroideryType' location: description: Location on the product where the embroidery should be placed type: string maxLength: 255 color: description: Thread color for the embroidery type: - string - 'null' maxLength: 255 default: null font: description: Font for embroidered text type: - string - 'null' maxLength: 255 default: null line1: description: First line of embroidery text type: - string - 'null' maxLength: 25 default: null line2: description: Second line of embroidery text type: - string - 'null' maxLength: 25 default: null line3: description: Third line of embroidery text type: - string - 'null' maxLength: 25 default: null logo_url: description: URL of the logo file to be embroidered on the product type: - string - 'null' maxLength: 2048 default: null file_identifier: description: File identifier for the embroidery design type: - string - 'null' maxLength: 255 default: null symbol: description: Symbol identifier for embroidery designs type: - string - 'null' maxLength: 255 default: null symbol_color: description: Color of the embroidered symbol type: - string - 'null' maxLength: 255 default: null required: - type - location title: Create Or Update Order Item Embroidery Special Instruction Value Input ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderItemInput: type: object properties: sku: description: Marketplace Stock Keeping Unit (SKU) of the product; must match an existing product. type: string maxLength: 255 quantity: description: Number of units of this SKU on the order line; must be a positive integer. type: integer minimum: 0 maximum: 999999 line_key: description: Optional external key identifying this line item, useful for matching updates against the source system's line. type: - string - 'null' maxLength: 255 default: null name: description: Display name for the product on this line. Optional; immutable after the item is created. type: - string - 'null' maxLength: 65536 default: null price: description: Per-unit price of the product in the order currency. Optional; immutable after the item is created. type: - number - 'null' format: double default: null packing_group: description: Optional group identifier; items sharing the same packing_group.key should be packed together in the same parcel. anyOf: - $ref: '#/components/schemas/ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderItemPackingGroupInput' - type: 'null' default: null custom_data: description: Optional custom name/value pairs attached to the line item for integration metadata. Immutable after the item is created. type: array items: $ref: '#/components/schemas/ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderCustomDataInput' default: [] b2b_attributes: description: Optional B2B-specific attributes (e.g. retailer compliance fields) attached to the line. Immutable after the item is created. type: array items: $ref: '#/components/schemas/ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderItemB2BAttributeInput' default: [] special_instructions: description: Special handling instructions to apply to this line item; omit when none are needed. type: array items: $ref: '#/components/schemas/ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderItemSpecialInstructionInput' default: [] image_url: description: Publicly accessible image URL of the product. Set on creation only; updates are ignored once the item exists. type: - string - 'null' maxLength: 2048 default: null lot_requirements: description: Lot/expiration constraints that pickers must honor for this item. Can only be set before the order is submitted to the warehouse; later updates are ignored. anyOf: - $ref: '#/components/schemas/ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderItemLotRequirementsInput' - type: 'null' default: null required: - sku - quantity title: Create Or Update Order Item Input ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderItemLotControlInput: type: object properties: lot_number: description: Specific lot number that must be picked for this item; omit to allow any lot. type: - string - 'null' maxLength: 255 default: null expiration_date: description: Required expiration date of the picked lot in ISO 8601 (YYYY-MM-DD) format; omit to allow any expiration. type: - string - 'null' format: date default: null required: [] title: Create Or Update Order Item Lot Control Input ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderItemLotRequirementsInput: type: object properties: minimum_shelf_life_days: description: Minimum remaining shelf life (in days from the ship date) that any allocated lot must have. Omit to accept any shelf life. type: - integer - 'null' minimum: 1 default: null lot_controls: description: Specific lots (by lot number and/or expiration date) that must be used to fulfill this item. Leave empty to allow any qualifying lot. type: array items: $ref: '#/components/schemas/ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderItemLotControlInput' default: [] required: [] title: Create Or Update Order Item Lot Requirements Input ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderItemPackingGroupInput: type: object properties: key: description: Stable key identifying the packing group; items with the same key are packed together. type: string maxLength: 255 name: description: Optional human-readable name for the packing group, shown to warehouse staff. type: - string - 'null' maxLength: 255 default: null required: - key title: Create Or Update Order Item Packing Group Input ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderItemSpecialInstructionInput: oneOf: - $ref: '#/components/schemas/ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderItemEmbroiderySpecialInstructionInput' discriminator: propertyName: type mapping: embroidery: '#/components/schemas/ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderItemEmbroiderySpecialInstructionInput' title: Create Or Update Order Item Special Instruction Input ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderOrderType: type: - string enum: - direct_to_consumer - retail - amazon - transfer - removal_liquidation - disposal - bonded_inventory_clearance - work_order title: Create Or Update Order Order Type ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderPackingSlipInput: type: object properties: type: description: 'Packing slip template to use. Allowed values: `retailer` (retailer-supplied template stored with ShipMonk).' $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_Enum_OrderLevelPackingSlipType' default: retailer name: description: Human-readable name of the packing slip template; used to identify it in reports. type: - string - 'null' maxLength: 255 default: null shipping_data_required: description: If true, carrier tracking and address data must be merged onto the packing slip before printing. type: boolean default: false approved_shipment_id_number_required: description: If true, the retailer's approved shipment ID (e.g., an ASN number returned after the shipment notice) must be printed on the label. The order will not ship until the ID is supplied. type: boolean default: false required: [] title: Create Or Update Order Packing Slip Input ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderShipToInput: type: object properties: name: description: Full name of the recipient as it should appear on the shipping label. type: - string - 'null' maxLength: 255 default: null company: description: Recipient's company name as it should appear on the shipping label; omit for residential deliveries. type: - string - 'null' maxLength: 255 default: null street1: description: First line of the recipient's street address (e.g., house number and street). type: - string - 'null' maxLength: 255 default: null street2: description: Second line of the recipient's street address (apartment, suite, or unit); omit if not applicable. type: - string - 'null' maxLength: 255 default: null state: description: State, province, or region; use the ISO 3166-2 subdivision code where one exists (e.g., 'CA' for California). type: - string - 'null' maxLength: 255 default: null city: description: City of the recipient's address. type: - string - 'null' maxLength: 255 default: null zip: description: Postal or ZIP code of the recipient's address. type: - string - 'null' maxLength: 255 default: null country_code: description: ISO 3166-1 alpha-2 country code of the recipient (e.g., 'US', 'GB'). type: - string - 'null' maxLength: 255 default: null phone: description: Recipient phone number in E.164 format; used by carriers for delivery contact. type: - string - 'null' maxLength: 255 default: null required: [] title: Create Or Update Order Ship To Input ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderShippingLabelInput: type: object properties: url: description: Publicly accessible URL pointing to the pre-generated shipping label PDF or PNG. type: string maxLength: 2048 required: - url title: Create Or Update Order Shipping Label Input ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderSpecialRequirementsInput: type: object properties: special_instruction: description: Free-form instructions shown to warehouse staff while processing the order (e.g., 'fragile, do not stack'). type: - string - 'null' pattern: \S default: null pack_list_required: description: If true, a packing list document is enclosed in the shipment. Stored on creation only; ignored on subsequent updates. type: boolean default: false carton_labels: description: Carton labels (e.g., GS1, retailer-customized) that must be printed and affixed to each carton during packing. type: array items: $ref: '#/components/schemas/ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderCartonLabelInput' default: [] order_level_packing_slip: description: Configuration of the packing slip generated for the whole order (as opposed to per-carton); omit to use the account default. anyOf: - $ref: '#/components/schemas/ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderPackingSlipInput' - type: 'null' default: null shipping_label: description: Pre-generated shipping label supplied by the merchant; when present, the warehouse uses this label instead of buying postage. anyOf: - $ref: '#/components/schemas/ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderShippingLabelInput' - type: 'null' default: null additional_documents: description: Extra documents (e.g., commercial invoices, MSDS, certificates) that must be printed and enclosed with the shipment. type: array items: $ref: '#/components/schemas/ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderAdditionalDocumentInput' default: [] shipping_date: description: Requested ship-by date (single date or range, in ISO 8601). Warehouse will attempt to ship within this window. anyOf: - $ref: '#/components/schemas/Fulfillment_AccountApiBundle_Input_Order_CreateUpdateFulfillmentRequirements_SpecialRequirementsDatesInput' - type: 'null' default: null delivery_date: description: Required delivery date (single date or range, in ISO 8601). Warehouse picks a service expected to arrive within this window. anyOf: - $ref: '#/components/schemas/Fulfillment_AccountApiBundle_Input_Order_CreateUpdateFulfillmentRequirements_SpecialRequirementsDatesInput' - type: 'null' default: null cancel_date: description: ISO 8601 date after which the order should be auto-cancelled if it has not yet shipped; omit to disable auto-cancellation. type: - string - 'null' format: date default: null fulfillment_strategy: description: 'Fulfillment strategy for this order: standard (default D2C pick-and-pack), drop_ship (retailer D2C via EDI, requires Retailer Setup), cross_dock (pre-packed manufacturer orders received in bulk and routed outbound without pick-and-pack).' anyOf: - $ref: '#/components/schemas/Fulfillment_OrderBundle_Enum_FulfillmentStrategy' - type: 'null' default: null required: [] title: Create Or Update Order Special Requirements Input ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderTaxIdInput: type: object properties: type: description: 'Type of tax identifier supplied in `value`. Allowed: `VAT`, `IOSS`, `TIN`, `EIN`, `EORI`, `ARN`, `RFC`, `CPF`, `CNPJ`, `PCCC`.' $ref: '#/components/schemas/Fulfillment_UserBundle_Enum_TaxIdType' value: description: The tax identifier string itself, formatted according to the rules of the chosen `type` and `issuing_country_id`. type: string maxLength: 255 issuing_country_id: description: ISO 3166-1 alpha-2 country code of the authority that issued the tax ID (e.g., 'DE' for a German VAT number). type: string minLength: 2 maxLength: 2 required: - type - value - issuing_country_id title: Create Or Update Order Tax Id Input ShipMonk_ShippingConnector_ValueObject_PublicApiCarrierIdentifier: type: - string enum: - CanadaPost - Cirro - DHL eCommerce - DHL Express - DPD - FedEx - Global-E - International Bridge - OnTrac - Passport - Royal Mail - ShipMonk - SpeedX - UPS - USPS title: Carrier Identifier ShipMonk_WmsConnector_Order_ValueObject_WmsType: type: - string enum: - shipmonk - deposco - merchant_facility title: Wms Type securitySchemes: api_key_header_Api-Key: type: apiKey in: header name: Api-Key security: - api_key_header_Api-Key: []