--- title: "Create or Update Order" method: POST path: "/v1/integrations/order" tags: ["Orders"] --- # Create or Update Order `POST /v1/integrations/order` 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. ## Request body - ShipMonkPublicApiOrderOrderCreateOrUpdateCreateOrUpdateOrderInput - `store_id` integer, required — Identifier of the store the order belongs to. - `order_number` string, required — Customer-facing order identifier (e.g. shown on the packing slip). Uniqueness is recommended but not enforced. Immutable after creation. - `order_key` string, required — Stable external identifier used to associate this order on subsequent updates; must be unique per order and acts as the upsert key. - `items` ShipMonkPublicApiOrderOrderCreateOrUpdateCreateOrUpdateOrderItemInput[], required — Line items to be fulfilled in the order. - `sku` string, required — Marketplace Stock Keeping Unit (SKU) of the product; must match an existing product. - `quantity` integer, required — Number of units of this SKU on the order line; must be a positive integer. - `line_key` string, nullable — Optional external key identifying this line item, useful for matching updates against the source system's line. - `name` string, nullable — Display name for the product on this line. Optional; immutable after the item is created. - `price` number, double, nullable — Per-unit price of the product in the order currency. Optional; immutable after the item is created. - `packing_group` ShipMonkPublicApiOrderOrderCreateOrUpdateCreateOrUpdateOrderItemPackingGroupInput - `key` string, required — Stable key identifying the packing group; items with the same key are packed together. - `name` string, nullable — Optional human-readable name for the packing group, shown to warehouse staff. - `custom_data` ShipMonkPublicApiOrderOrderCreateOrUpdateCreateOrUpdateOrderCustomDataInput[] — Optional custom name/value pairs attached to the line item for integration metadata. Immutable after the item is created. - `name` string, required — Key (name) of the custom data entry; should be unique within the item's custom_data list. - `value` string, required — Value stored under the corresponding custom_data name. - `b2b_attributes` ShipMonkPublicApiOrderOrderCreateOrUpdateCreateOrUpdateOrderItemB2BAttributeInput[] — Optional B2B-specific attributes (e.g. retailer compliance fields) attached to the line. Immutable after the item is created. - `name` string, required — Name (key) of the B2B attribute; should be unique within the item's b2b_attributes list. - `value` string, required — Value of the B2B attribute identified by the sibling `name` (free-form string). - `special_instructions` ShipMonkPublicApiOrderOrderCreateOrUpdateCreateOrUpdateOrderItemSpecialInstructionInput[] — Special handling instructions to apply to this line item; omit when none are needed. - `type` 'embroidery', required - `values` ShipMonkPublicApiOrderOrderCreateOrUpdateCreateOrUpdateOrderItemEmbroiderySpecialInstructionValueInput[], required — List of embroidery instruction values - `type` 'logo' | 'text' | 'text_with_logo' | 'logo_identifier' | 'text_with_symbol', required - `location` string, required — Location on the product where the embroidery should be placed - `color` string, nullable — Thread color for the embroidery - `font` string, nullable — Font for embroidered text - `line1` string, nullable — First line of embroidery text - `line2` string, nullable — Second line of embroidery text - `line3` string, nullable — Third line of embroidery text - `logo_url` string, nullable — URL of the logo file to be embroidered on the product - `file_identifier` string, nullable — File identifier for the embroidery design - `symbol` string, nullable — Symbol identifier for embroidery designs - `symbol_color` string, nullable — Color of the embroidered symbol - `image_url` string, nullable — Publicly accessible image URL of the product. Set on creation only; updates are ignored once the item exists. - `lot_requirements` ShipMonkPublicApiOrderOrderCreateOrUpdateCreateOrUpdateOrderItemLotRequirementsInput - `minimum_shelf_life_days` integer, nullable — Minimum remaining shelf life (in days from the ship date) that any allocated lot must have. Omit to accept any shelf life. - `lot_controls` ShipMonkPublicApiOrderOrderCreateOrUpdateCreateOrUpdateOrderItemLotControlInput[] — Specific lots (by lot number and/or expiration date) that must be used to fulfill this item. Leave empty to allow any qualifying lot. - `lot_number` string, nullable — Specific lot number that must be picked for this item; omit to allow any lot. - `expiration_date` string, date, nullable — Required expiration date of the picked lot in ISO 8601 (YYYY-MM-DD) format; omit to allow any expiration. - `ship_to` ShipMonkPublicApiOrderOrderCreateOrUpdateCreateOrUpdateOrderShipToInput, required - `name` string, nullable — Full name of the recipient as it should appear on the shipping label. - `company` string, nullable — Recipient's company name as it should appear on the shipping label; omit for residential deliveries. - `street1` string, nullable — First line of the recipient's street address (e.g., house number and street). - `street2` string, nullable — Second line of the recipient's street address (apartment, suite, or unit); omit if not applicable. - `state` string, nullable — State, province, or region; use the ISO 3166-2 subdivision code where one exists (e.g., 'CA' for California). - `city` string, nullable — City of the recipient's address. - `zip` string, nullable — Postal or ZIP code of the recipient's address. - `country_code` string, nullable — ISO 3166-1 alpha-2 country code of the recipient (e.g., 'US', 'GB'). - `phone` string, nullable — Recipient phone number in E.164 format; used by carriers for delivery contact. - `requested_shipping_service` string, required — 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. - `ordered_at` string, date-time, required — ISO 8601 timestamp when the order was originally placed in the source system. - `order_status` 'unfulfilled' | 'fulfilled' | 'cancelled' | 'onHold', required - `attributes` ShipMonkPublicApiOrderOrderCreateOrUpdateCreateOrUpdateOrderAttributeInput[] — Free-form key/value pairs stored on the order, used for custom development. - `name` string, required — Key identifying the custom attribute; must be unique within the order's attributes array. - `value` string, required — Value paired with the attribute `name` on the order. - `trading_partner` string, nullable — Name of the retailer or trading partner for B2B/EDI orders; required to apply the partner's routing and labeling rules. - `order_type` 'direct_to_consumer' | 'retail' | 'amazon' | 'transfer' | 'removal_liquidation' | 'disposal' | 'bonded_inventory_clearance' | 'work_order' - `customer_email` string, nullable — Recipient email address forwarded to the carrier for delivery notifications. - `shipping_paid` number, double, nullable — Amount the customer paid for shipping, expressed in the order's `currency_code`. Informational only; does not affect rated postage. - `taxes_paid` number, double, nullable — Tax amount the customer paid, in the order's `currency_code`. Informational only; used for customs paperwork on international shipments. - `currency_code` string, nullable — ISO 4217 three-letter currency code for `shipping_paid`, `taxes_paid`, and item prices (e.g., 'USD', 'EUR'). - `references` FulfillmentAccountApiBundleInputOrderOrderReferenceInput[] — External identifiers (e.g., PO number, marketplace order ID) linking this order back to upstream systems; informational only. - `type` 'order_number' | 'original_imported_order_number' | 'customer_order_number' | 'po_number' | 'reference_number' | 'b2b_routing_reference' | 'release_number' | 'job_number' | 'depositor_order_number', required - `value` string, required - `customer_notes` string, nullable — Notes provided by the buyer (e.g., delivery preferences). Stored on creation only; subsequent updates are ignored once a value is set. - `internal_notes` string, nullable — Notes for internal warehouse staff, not shown to the buyer. Stored on creation only; ignored on subsequent updates. - `warehouse` string, nullable — 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. - `gift_message` string, nullable — Message printed on a gift note included with the shipment. Stored on creation only; ignored on subsequent updates. - `gift_from` string, nullable — Sender name printed on the gift note alongside `gift_message`. - `custom_data` ShipMonkPublicApiOrderOrderCreateOrUpdateCreateOrUpdateOrderCustomDataInput[] — Free-form key/value metadata stored on the order; not interpreted by fulfillment logic and returned as-is in order reads. - `name` string, required — Key (name) of the custom data entry; should be unique within the item's custom_data list. - `value` string, required — Value stored under the corresponding custom_data name. - `b2b_attributes` ShipMonkPublicApiOrderOrderCreateOrUpdateCreateOrUpdateOrderB2BAttributeInput[] — 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. - `name` string, required — Name (key) of the B2B attribute; should be unique within the item's b2b_attributes list. - `value` union, required - integer - number - boolean - string - `submit_at` string, date-time, nullable — 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. - `special_requirements` ShipMonkPublicApiOrderOrderCreateOrUpdateCreateOrUpdateOrderSpecialRequirementsInput - `special_instruction` string, nullable — Free-form instructions shown to warehouse staff while processing the order (e.g., 'fragile, do not stack'). - `pack_list_required` boolean — If true, a packing list document is enclosed in the shipment. Stored on creation only; ignored on subsequent updates. - `carton_labels` ShipMonkPublicApiOrderOrderCreateOrUpdateCreateOrUpdateOrderCartonLabelInput[] — Carton labels (e.g., GS1, retailer-customized) that must be printed and affixed to each carton during packing. - `type` 'gs1' | 'shipmonk_gs1' | 'customized_carton_labels' | 'custom' - `name` string, nullable — Human-readable name of the carton label template; used to identify the label in reports. - `url` string, nullable — Publicly accessible URL of the carton label PDF; required when `type` is `custom`. - `shipping_data_required` boolean — If true, carrier tracking and address data must be merged onto the carton label before printing. - `approved_shipment_id_number_required` boolean — 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. - `data_source` 'internal' | 'third-party-after-shipment-notification' - `order_level_packing_slip` ShipMonkPublicApiOrderOrderCreateOrUpdateCreateOrUpdateOrderPackingSlipInput - `type` 'retailer' - `name` string, nullable — Human-readable name of the packing slip template; used to identify it in reports. - `shipping_data_required` boolean — If true, carrier tracking and address data must be merged onto the packing slip before printing. - `approved_shipment_id_number_required` boolean — 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. - `shipping_label` ShipMonkPublicApiOrderOrderCreateOrUpdateCreateOrUpdateOrderShippingLabelInput - `url` string, required — Publicly accessible URL pointing to the pre-generated shipping label PDF or PNG. - `additional_documents` ShipMonkPublicApiOrderOrderCreateOrUpdateCreateOrUpdateOrderAdditionalDocumentInput[] — Extra documents (e.g., commercial invoices, MSDS, certificates) that must be printed and enclosed with the shipment. - `name` string, required — Human-readable name of the document, shown in reports and to warehouse staff. - `url` string, required — Publicly accessible URL of the PDF document to print and enclose with the shipment. - `shipping_date` FulfillmentAccountApiBundleInputOrderCreateUpdateFulfillmentRequirementsSpecialRequirementsDatesInput - `earliest` string, date, nullable - `requested` string, date, nullable - `latest` string, date, nullable - `delivery_date` FulfillmentAccountApiBundleInputOrderCreateUpdateFulfillmentRequirementsSpecialRequirementsDatesInput - `earliest` string, date, nullable - `requested` string, date, nullable - `latest` string, date, nullable - `cancel_date` string, date, nullable — ISO 8601 date after which the order should be auto-cancelled if it has not yet shipped; omit to disable auto-cancellation. - `fulfillment_strategy` 'standard' | 'drop-ship' | 'cross-dock' - `recipient_tax_id` ShipMonkPublicApiOrderOrderCreateOrUpdateCreateOrUpdateOrderTaxIdInput - `type` 'VAT' | 'IOSS' | 'TIN' | 'EIN' | 'EORI' | 'ARN' | 'RFC' | 'CPF' | 'CNPJ' | 'PCCC' | 'VOEC', required - `value` string, required — The tax identifier string itself, formatted according to the rules of the chosen `type` and `issuing_country_id`. - `issuing_country_id` string, required — ISO 3166-1 alpha-2 country code of the authority that issued the tax ID (e.g., 'DE' for a German VAT number). - `minimum_shelf_life_days` integer, nullable — 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. ## Response `200` Success - FulfillmentIntegrationsBundleCrateOrderSyncOutput - `message` string, required — Human-readable message indicating whether the order was created or updated. --- [API](https://skmtc.net/shipmonk/apis/shipmonk-api.md) · [All operations](https://skmtc.net/shipmonk/apis/shipmonk-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shipmonk/shipmonk-api/revisions/5dc3234a38a5/schema)