Terminology
When making an API call you can either use camel case or snake case when referencing fields. Either syntax is allowed when making a POST or GET call. As an example, Order Status can be called as orderStatus or order_status. Additional information regarding boolean value, field type and requirements can be found in the API Endpoint References.
Definitions
| Field Name | API Reference | Description |
|---|---|---|
| Account Number | account_number | ShipMonk-issued account identifier included in GET order API calls. |
| Address | address | Physical location information for shipping or receiving purposes. |
| Arrived at | arrived_at | ISO 8601 timestamp indicating arrival time at ShipMonk. |
| ASN | asn | Advanced Shipping Notice number. |
| At Risk | at_risk | Boolean value indicating items or orders requiring special attention. |
| Authorization Number | authorization_number | Carrier-authorized unique identifier for a shipment. |
| Automation Rule | automation_rule | Boolean value indicating whether an automation rule execution encountered an error. |
| Backordered Quantity | backordered_quantity | Number of units from the ordered quantity that cannot be fulfilled due to insufficient inventory. |
| Bill of Lading Number (BOL) | bolNumber, bill_of_lading_number | Unique identifier for a bill of lading, a legal document issued by a carrier to a shipper that serves as a contract of carriage and receipt for goods. |
| Box Number | box_number | Sequential number identifying a specific box within a shipment. |
| Bundle SKU | bundle_sku | SKU/identifier of a virtual bundle, also referred to as the "virtual" or "marketplace" SKU. |
| Cancel Date | cancelDate, cancel_date | Date at which an order will be cancelled if not yet fulfilled, typically used for B2B/EDI orders. |
| Carrier | carrier | Shipping provider responsible for transporting a shipment. |
| Carrier Alpha Code | carrier_alpha_code | Carrier's two-to-four character SCAC (Standard Carrier Alpha Code) as assigned by the National Motor Freight Traffic Association, uniquely identifying the freight carrier. |
| Carrier Tracking URL | carrier_tracking_url | ShipMonk-branded tracking URL for tracking shipments on a customizable webpage. |
| Carrier Trans Method Code | carrier_trans_method_code | Specific method used by the carrier for transportation, identifying the shipping service level. |
| Category | category | Type of receiving: 'purchase_order_asn', 'inventory_transfer', 'wholesale_order_return', etc. |
| City | city | City where the address is located. Required for valid addresses. |
| Code | code | Recipient's tax identification code used for tax reporting and compliance purposes. |
| Color | color | Enumerated value specifying embroidery thread color. |
| Company | company | Company or organization associated with an entity. |
| Completion Mode | completionMode | Completion method for completing a receiving in Sandbox: 'fully_received', 'short_received', 'excess_received', or 'partially_received'. |
| Count | count | Number of units contained in a handling unit. |
| Country/Country Code | countryCode | Two-letter ISO country code. |
| Country of Origin | countryOfOrigin, country_of_origin | Two-letter ISO country code indicating the product's country of origin for customs documentation on international shipments. |
| Created at | created_at | ISO 8601 timestamp indicating when the entity was created. |
| Currency Code | currencyCode, currency_code | Three-letter currency code for pricing (e.g., 'USD'). |
| Email/Customer Email | email, customerEmail, customer_email | Customer's email address used by the carrier for delivery communications. |
| Customer Notes | customerNotes, customer_notes | Notes provided by the customer or end buyer for reference, capturing additional details relevant to the request. |
| Customs | customs | Boolean value indicating whether an order requires customs documentation. |
| Customs Declaration Value | customsDeclarationValue | Declared value of goods for customs purposes, used to calculate duties and taxes upon import. Required for international shipments. |
| Delivery Date | delivery_date | Expected or actual date of delivery. |
| Description | description | Description of the receiving (maximum 65,535 characters). |
| Desired Action | desiredAction, desired_action | Processing method for returned items as determined by the returns team. Value must be from the enumerated list of acceptable options. |
| Dimensions | dimensions | Physical measurements of a product. |
| Earliest (Order) | earliest | ISO 8601 date indicating the earliest acceptable delivery date for an order. |
| Enabled (Warehouse) | enabled | Boolean indicating whether the account has access to utilize the specified warehouse. |
| Estimated Delivery | estimatedDelivery, estimated_delivery | Anticipated delivery date in YYYY-MM-DD format. |
| Estimated Shipping Cost | estimated_shipping_cost | Anticipated shipping cost. This value is an estimate and may differ from final charges. |
| Expected Quantity | expectedQuantity, expected_quantity | Number of SKU units expected for a receiving, indicating the anticipated quantity of items. |
| Expiration Date | expirationDate, expiration_date | Date indicating when a lot of an item expires. |
| External Return Id | externalReturnId | External system's identifier for this return. |
| File Identifier | fileIdentifier | File identification reference. |
| Final Disposition | final_disposition | Conclusion status of items returned to ShipMonk. Available values: 'reworked', 'returned_to_inventory', 'return_to_merchant', 'dispose', 'donate', 'other'. |
| Font | font | String value specifying embroidery font instructions to be included in special instructions for order items. |
| Fragile (Order) | fragile | Boolean indicating product requires fragile handling. |
| Freight Info | freight_info | Boolean indicating order requires freight information action. |
| Freight Quote | freight_quote | Boolean indicating order requires a freight quote action. |
| Fulfilled Quantity | fulfilled_quantity | Number of units fulfilled for that line item. |
| Fulfillment Strategy | fulfillmentStrategy | String communicating the fulfillment strategy in an order's special instructions. Values: 'standard', 'drop-ship', or 'cross-dock'. |
| Gift From | gift_from | Name to be printed on a gift note, indicating who the gift is from. |
| Gift Message | giftMessage, gift_message | Message to be printed on a gift note included with the shipment. |
| Global-e Label | global_e_label | Boolean indicating the order requires a Global-e shipping label action. |
| Handling Unit Quantity | handlingUnitQuantity, handling_unit_quantity | Number of eaches contained in a handling unit. |
| Handling Unit Type | handlingUnitType, handling_unit_type | Type of the handling unit. |
| Height | height | Height measurement in inches. |
| HS Code | hsCode, hs_code | Harmonized System code for customs (maximum 255 characters). |
| Id | id | Internal identification number |
| Image Url | imageUrl, image_url | Product image URL. |
| Issuing Country Id | issuingCountryId, issuing_country | Two-letter ISO country code for the country that issued the recipient's tax ID, identifying the originating jurisdiction for tax purposes. |
| Item Mapping | item_mapping | Boolean indicating the order requires item/product mapping action. |
| Key | key | General key identifier. |
| Label | label | Label designation or description. |
| Latest | latest | Latest date within an acceptable date range. |
| Length | length | Length measurement in inches. |
| Line1 | line1 | Primary address line containing the street number and street name. |
| Line2 | line2 | Secondary address line for apartment numbers, suites, or other additional address information. Optional. |
| Line3 | line3 | Tertiary address line for apartment, suite, or unit numbers, accommodating additional address details. |
| Line Key | lineKey, line_key | Identifier provided by an integration to associate the line item with an external system. |
| Load Number | load_number | Number used to track and manage the logistics of transported goods. |
| Location | location | Specification of where content is engraved or embroidered. |
| LogoUrl | logoUrl | File to be embroidered or engraved on the product. |
| Lot | lot, lot | Lot number of the product. |
| Lot Number | lotNumber, lot_number | Lot number of the product. |
| Master Bill of Lading Number | master_bill_of_lading_number | Primary bill of lading number for consolidated freight shipments. |
| Master Tracking Number | master_tracking_number | Primary tracking number for the shipment. |
| Message | message | Response message (deprecated; use data.message). |
| Name | name | User-facing identifier or name. |
| Note | note | Optional notes regarding the return. |
| Number | number | General numeric identifier. |
| Order Detail Url | order_detail_url | URL to view complete order details in the ShipMonk interface. |
| Order Key | orderKey, order_key | Unique identifier from an external system used to associate an order. Must be unique per order. |
| Order Number | orderNumber, order_number | Customer-facing identifier for an order. Uniqueness is recommended but not strictly enforced. |
| Order Parts | order_parts | Information about related orders when an order has been split into multiple parts. |
| Order Size | orderSize, order_size | Classification of order dimensions: 'unknown', 'regular', 'oversized_item', 'large', or 'extra_large'. |
| Order Status | orderStatus, order_status | Current order status: 'unfulfilled', 'fulfilled', 'cancelled', or 'onHold'. |
| Ordered At | orderedAt, ordered_at | ISO 8601 timestamp indicating when the order was originally placed (e.g., "2022-05-01T11:43:16-04:00"). |
| Order Type | orderType | Classification or category of the order. |
| Override Warehouse To Related Order Ship From Warehouse | overrideWarehouseToRelatedOrderShipFromWarehouse | Boolean to use the original order's ship-from warehouse. |
| Pack List Required | packListRequired, pack_list_required | Boolean indicating whether a packing list must be included with the shipment. |
| Pack Type | packType | Type of packaging: 'singlepack' or 'multipack'. |
| Page | page | Current page number for pagination. |
| Pages | pages | Total number of pages available. |
| Pallet Number | pallet_number | Sequential identifier for a specific pallet within a shipment. |
| Pallet Weight lb | pallet_weight_lb | Numeric weight of pallets in pounds. |
| Pending B2B Routing | pending_b2b_routing | Boolean indicating the B2B order requires routing information action. |
| Phone | phone | Phone number for contact purposes. |
| Postal Code | postalCode, postal_code | Postal or ZIP code in an address. |
| Price | price | Unit price of a product or shipment service. |
| Processing Status | processing_status | Detailed processing status (e.g., 'submitted', 'pick_in_progress', 'packed', etc.). |
| Product Type | product_type | Category or classification of the product. |
| Product Key | productKey | Unique identifier for the product in your system. |
| Quantity | quantity | Numeric count of items. |
| Quantity Available | quantity_available | Number of units available for fulfillment at a specific location. |
| Quantity Final | quantity_final | Final quantity count at a specific location, including all statuses. |
| Quantity on Hand | quantity_on_hand | Physical count of units present at a specific location. |
| Quantity Total Available | quantity_total_available | Total units available for fulfillment across all locations. |
| Quantity Total Final | quantity_total_final | Total final quantity count across all locations. |
| Quantity Total Quarantined | quantity_total_quarantined | Total units in quarantine status across all locations. |
| Quantity Total Unavailable | quantity_total_unavailable | Total units unavailable for fulfillment across all locations. |
| Quantity Unavailable | quantity_unavailable | Number of units unavailable for fulfillment at a specific location. |
| Quarantined Quantity | quarantined_quantity | Number of units held in quarantine status at a specific location. |
| Received At | received_at | ISO 8601 timestamp indicating when the receiving or return was completed. |
| Received Quantity | received_quantity | Number of units actually received into inventory. |
| Receiving Key | receivingKey, receiving_key | Optional unique identifier for the receiving or purchase order (maximum 255 characters). |
| Recipient Tax Id | recipient_tax_id | Tax identification number for the shipment recipient, required for certain international destinations. |
| Region | region | HS code region: 'us', 'uk', or 'eu'. |
| Replacement Cost | replacementCost, replacement_cost | Cost to replace the product, used for insurance and claims purposes. |
| Replacement Cost Currency | replacement_cost_currency | Three-letter ISO 4217 currency code for replacement cost. |
| Requested | requestedShippingService, requested_shipping_service | Requested date within a date range. |
| Requested Shipping Service | requestedShippingService, requested_shipping_service | Requested shipping method or service for the order. |
| Required Packaging | requiredPackaging, required_packaging | Minimum packaging type needed: 'poly_mailer', 'bubble_mailer', 'box', 'slap_a_label', or 'custom'. |
| Residential | residential | Boolean indicating whether the address is residential (versus commercial). |
| Return Reason | returnReason, return_reason | Reason code for the return (e.g., 'reason_exchange', 'reason_changed_mind', 'reason_undeliverable'). For reference and reporting purposes only. |
| RMA | rma | Return Merchandise Authorization number—a unique identifier for the return. |
| Routing | routing_key | Boolean indicating the order requires routing action. |
| Routing Key | routing_key | Identifier for the routing configuration or plan. |
| Search In All Stores | searchInAllStores | Boolean to search across all stores when looking up related orders. |
| Serial Number | serial_number | Unique serial number assigned to an individual product unit. |
| Service | service | Carrier service level or mapping name. |
| Ship_from | ship_from, ship_from | Origin address from which the order will ship. |
| Ship Monk Hazmat Carrier Service Not Available | ship_monk_hazmat_carrier_service_not_available | Boolean indicating hazardous materials require alternative carrier service. |
| Ship Short | ship_short | Boolean indicating the order requires short shipment handling action. |
| Ship To | ship_to | Shipping destination address. |
| Shipment Data | shipment_data | Carrier and service information for the shipment. |
| Shipped At | shipped_at | ISO 8601 timestamp indicating when the order was shipped. |
| Shipping Date | shipping_date | ISO 8601 date indicating when a shipment should occur. |
| Shipping Label | shipping_label | URL of the shipping label associated with an order. |
| Shipping Mapping | shipping_mapping | Boolean indicating the order requires shipping method mapping action. |
| Shipping Method | shipping_method | Resolved carrier and service method to be used for shipping. |
| Shipping Paid | shippingPaid, shipping_paid | Amount the customer paid for shipping. |
| Shipping Payment Terms | shipping_payment_terms | Payment responsibility: 'sender', 'collect', or 'third_party', with optional account details. |
| Shipping Data Required | shippingDataRequired | Boolean indicating whether shipping data must be populated for carton labels or packing slips. |
| SKU | sku | Stock Keeping Unit—unique product identifier. |
| Source | source | Source system: 'shipmonk', 'loop', 'returnly', 'deposco', etc. |
| Special Instruction | specialInstruction, special_instruction | Additional handling instructions or requirements for an order. |
| Special Requirements | special_requirements | Object containing special handling needs such as packing lists, shipping labels, date constraints, etc. |
| State | state | State, province, or region in an address. |
| Status | status | Current status of the entity (e.g., receiving status: 'awaiting', 'arrived', 'in_progress', 'received'; return status: 'status_created', 'in_progress', 'en_route', 'returned', 'arrived'; or product status: 'blacklisted', 'active', 'disabled'). |
| Stock Out Days | stock_out_days | Number of days the product has been out of stock. |
| Store Id | storeId, store_id | Unique identifier of the ShipMonk store. |
| Street1 | street1 | First line of a street address. |
| Street2 | street2 | Second line of a street address (apartment, suite, unit). |
| Street3 | street3 | Third line of a street address (additional information). |
| Submit At | submitAt, submit_at | ISO 8601 timestamp for when to submit the order (can be future or past). |
| Supplier Name | supplierName, supplier_name | Name of the supplier sending the goods (maximum 255 characters). |
| Symbol | symbol | Symbol identifier for embroidery designs. |
| Symbol Color | symbolColor | Color specification for embroidered symbols. |
| Tax Id | tax_id | Tax identification number for the sender or merchant. |
| Tax Id Type | tax_id_type | Type of tax ID: 'VAT', 'IOSS', 'TIN', 'EIN', 'EORI', 'ARN', 'RFC', 'CPF', 'CNPJ', or 'PCCC'. |
| Tax Paid | tax_paid | Amount of tax the customer paid. |
| Timezone | timezone | Time zone identifier for the warehouse location. |
| Total | total | Total number of products matching the specified filters. |
| Tracking Number | trackingNumber, tracking_number | The tracking number associated with an order, often used in Returns. |
| Tracking Url | tracking_url | URL to track the shipment. |
| Trading Partner | tradingPartner, trading_partner | Business partner or trading entity associated with B2B orders. |
| Type | type | Classification or category of the entity (e.g., embroidery type, label type, tax ID type). |
| Type Scope Id | type_scope_id | Unique identifier within a specific type scope. |
| Unit | unit | Unit of measurement. |
| Updated At | updated_at | ISO 8601 timestamp of the last update. |
| Value | value | Numeric or string value. |
| Value Added Service Problem | value_added_service_problem | Issue or flag related to value-added services. |
| Verified | verified | Boolean indicating verification status. |
| Warehouse | warehouse, warehouse | Warehouse identifier where goods are processed, received, or shipped from (e.g., 'FL1', 'CA1'). |
| Warehouse WMS Type | warehouse_wms_type | Type of warehouse management system: 'shipmonk' or 'deposco'. |
| Weight | weight | Physical weight measurement of a product or package. |
| Weight lb | weightLb, weight_lb | Product weight in pounds (decimal value). |
| Width | width | Width dimension of a product or package. |
| Zip | zip | Postal or ZIP code in an address. |
Query Parameters
Query parameters can be used for filtering and pagination when pulling a list of items, orders, returns or receivings. Example below:
curl --request GET \
--url 'https://app.shipmonk.com/v1/integrations/returns-list?page=1&page_size=100' \
--header 'Api-Key: YOUR_API_KEY_HERE' \
--header 'accept: application/json'- asn - Filter by Advanced Shipping Notice number
- created_at - Filter by creation timestamp
- createdAt - Filter by creation timestamp
- dateCreatedEnd - Filter by creation date end range
- dateCreatedStart - Filter by creation date start range
- dateUpdatedEnd - Filter by update date end range
- dateUpdatedStart - Filter by update date start range
- desired_action - Filter by desired action
- orderKey - Filter by order key
- orderNumber - Filter by order number
- orderStatus - Filter by order status
- page - Page number for pagination (default: 1)
- page_size - Number of results per page
- pageSize - Number of results per page
- receivingKey - Filter by receiving key
- return_reason - Filter by return reason
- return_status - Filter by return status
- rma - Filter by RMA number
- search - General search term
- sortBy - Field to sort results by
- sortOrder - Sort direction (ascending or descending)
- status - Filter by status
- storeId - Filter by store ID
- updated_at - Filter by update timestamp
- updatedAt - Filter by update timestamp
- warehouse_id - Filter by warehouse ID
- warehouseId - Filter by warehouse ID
Updated 1 day ago