---
title: "Create order"
method: POST
path: "/api/sites/multiscreen/{site_name}/ecommerce/orders"
tags: ["Orders"]
---

# Create order

`POST /api/sites/multiscreen/{site_name}/ecommerce/orders`

## Request

- Base URL: `https://api.duda.co`
- URL: `https://api.duda.co/api/sites/multiscreen/{site_name}/ecommerce/orders`
- Auth: HTTP basic

Creates an order for the site from the given mode, currency, invoice number, customer email, billing address, and line items, plus optional shipping address, shipping method, payment reference, and inventory sync strategy. Returns the created order.

## Path parameters

- `site_name` string, required

## Request body

- CreateOrderInputDto
  - `mode` 'LIVE' | 'TEST', required
  - `currency` string, required: Currency ISO code of the order
  - `external_id` string, nullable: External reference to the order
  - `status` 'IN_PROGRESS' | 'PROCESSED' | 'SHIPPED' | 'DELIVERED' | 'PENDING' | 'CANCELLED' | 'DISPATCHED', required
  - `invoice_number` string, required: Unique bureaucratic reference to the order. The invoice number need to be a unique value for all orders on a site
  - `email` string, required: Email of the customer associated to the order
  - `items` CreateOrderLineItemInputDto[], required: Items bought with the order
    - `product_id` string, nullable: Product ID of the variation of the line item This property is required if value is set for variation_id
    - `variation_id` string, nullable: Variation ID of the line item. This property is required if value is set for product_id
    - `external_product_id` string, nullable: Product ID for an external catalog
    - `external_variation_id` string, nullable: Variation ID for an external catalog
    - `name` string, required: Display name of the line item
    - `image` string, nullable: Absolute URL of an image associated to the line item
    - `options` CreateOrderItemOptionValueInputDto[]: Options selected by the customer for the line item
      - `name` string, required: Name of the option
      - `value` string, required: Value of the option
    - `quantity` integer, required: Quantity bought for the line item
    - `shippable` boolean: If the line item require shipment
    - `unit_price` number, double, required: Price of a single unit of this line item
    - `unit_weight` number, double, nullable: Weight of a single unit of this line item
    - `unit_dimensions` CreateOrderLineItemDimensionsInputDto
      - `height` integer, required: Height of a single unit of this line item
      - `width` integer, required: Width of a single unit of this line item
      - `length` integer, required: Length of a single unit of this line item
    - `taxes` CreateOrderLineItemTaxInputDto[]: Taxes applied to the line item
      - `name` string, required: Name of the tax applied to the line item
      - `amount` number, double, required: Total amount of the tax for the line item
    - `discounts` CreateOrderLineItemDiscountInputDto[]: Discounts applied to the line item
      - `name` string, required: Name of the discount applied to the line item
      - `amount` number, double, required: Total amount of the discount for the line item
    - `metadata` string, nullable: Merchant defined JSON data for the line item
  - `billing_address` PersonalAddressInputDto, required
    - `first_name` string, nullable
    - `last_name` string, nullable
    - `full_name` string, nullable
    - `address_1` string, required
    - `address_2` string, nullable
    - `city` string, required
    - `region` string, nullable
    - `sub_locality` string, nullable
    - `street_number` string, nullable
    - `street_name` string, nullable
    - `country` string
    - `postal_code` string, required
    - `phone` string, nullable
  - `shipping_address` PersonalAddressInputDto
    - `first_name` string, nullable
    - `last_name` string, nullable
    - `full_name` string, nullable
    - `address_1` string, required
    - `address_2` string, nullable
    - `city` string, required
    - `region` string, nullable
    - `sub_locality` string, nullable
    - `street_number` string, nullable
    - `street_name` string, nullable
    - `country` string
    - `postal_code` string, required
    - `phone` string, nullable
  - `shipping_method` CreateOrderShippingMethodInputDto
    - `name` string, required: Name of the shipping method selected on the order.
    - `cost` number, double, required: The cost incurred for the order by the shipping method.
  - `shipping_instructions` string, nullable: Special instructions left by the customer for the delivery
  - `payment` CreateOrderPaymentInputDto
    - `transaction_id` string, required: External reference of a payment transaction associated to this order
  - `inventory_sync_strategy` 'IGNORE' | 'SYNC'
  - `user_agent` string, nullable: User agent of the customer when placed the order
  - `ip_address` string, nullable: The Ip address from which the order was placed
  - `created` string, date-time, nullable: The date and time when the order was placed
  - `metadata` string, nullable: Merchant defined JSON data for the whole order

## Response `201`

Created

- ExternalOrderResponseDto
  - `source` 'CHECKOUT' | 'EXTERNAL' | 'SUBSCRIPTION_BILLING_ENGINE' | 'ECWID'
  - `mode` 'LIVE' | 'TEST'
  - `tax_mode` 'TAXES_EXCLUDED_FROM_PRICE' | 'TAX_INCLUDED_WITH_NET_PRICE' | 'TAX_INCLUDED_WITH_GROSS_PRICE'
  - `id` string: Unique identifier of the order.
  - `external_id` string, nullable
  - `status` 'IN_PROGRESS' | 'PROCESSED' | 'SHIPPED' | 'DELIVERED' | 'PENDING' | 'CANCELLED' | 'DISPATCHED'
  - `email` string: Email associated with the order.
  - `invoice_number` string: Invoice number of the order.
  - `items` OrderLineItemResponseDto[]: The items in the order.
    - `id` string: System identifier of the line item.
    - `product_id` string, nullable: The unique identifier for the product backing this order item.
    - `variation_id` string, nullable: The unique identifier for the product variation backing this order item.
    - `external_product_id` string, nullable: The external id of the product backing this order item.
    - `external_variation_id` string, nullable: The external id of the product variation backing this order item.
    - `name` string: Display name of the line item.
    - `image` string, nullable: Display image of the line item.
    - `sku` string, nullable
    - `options` OrderItemOptionValue[]: Options selected by the customer associated with the line item.
      - `name` string: Name of the option.
      - `value` string: Value of the option.
    - `product_customizations` union[]: Array of product customizations selected for the line item.
      - union
        - ExternalLineItemProductCustomizationBaseResponseDto
          - `type` string, required
          - `id` string
          - `name` string
          - `label` string, nullable
          - `price_modifier` number, double, nullable
        - ExternalLineItemTextProductCustomizationResponseDto
          - `type` string, required
          - `id` string
          - `name` string
          - `label` string, nullable
          - `price_modifier` number, double, nullable
        - ExternalLineItemBooleanProductCustomizationResponseDto
          - `type` string, required
          - `id` string
          - `name` string
          - `label` string, nullable
          - `price_modifier` number, double, nullable
        - ExternalLineItemOptionsProductCustomizationResponseDto
          - `type` string, required
          - `id` string
          - `name` string
          - `label` string, nullable
          - `price_modifier` number, double, nullable
        - ExternalLineItemFileProductCustomizationResponseDto
          - `type` string, required
          - `id` string
          - `name` string
          - `label` string, nullable
          - `price_modifier` number, double, nullable
    - `quantity` integer: Quantity bought for this item.
    - `shippable` boolean: Indicates if this item requires shipping.
    - `unit_price` number, double: Price of a single unit of this line item.
    - `unit_weight` number, double, nullable: Weight of a single unit of this line item.
    - `unit_dimensions` OrderLineItemDimensionsResponseDto
      - `height` integer, nullable: Height of a single unit of this line item.
      - `width` integer, nullable: Width of a single unit of this line item.
      - `length` integer, nullable: Length of a single unit of this line item.
    - `total` number, double: Total price of this line item (quantity × unit price).
    - `combined_weight` number, double, nullable: Total weight of this line item (quantity × unit weight).
    - `metadata` string
  - `billing_address` AddressOutputDto
    - `name` string, nullable
    - `first_name` string, nullable: First Name attached to the address.
    - `last_name` string, nullable: Last Name attached to the address.
    - `full_name` string, nullable: Full Name attached to the address.
    - `address_1` string, nullable: The first line of the address.
    - `address_2` string, nullable: The second line of the address.
    - `street_number` string, nullable: The street number Note: this may be part of the address1 or address_2 values, but is available here as a separate value._
    - `street_name` string, nullable: The street name Note: this may be part of the address1 or address_2 values, but is available here as a separate value._
    - `city` string, nullable: Name of city attached to the address.
    - `sub_locality` string, nullable: Sub-locality attached to the address (ex: county or district name).
    - `region` string, nullable: Region attached to the address (ex. the state or province name).
    - `country` string, nullable: Country attached to the address.
    - `postal_code` string, nullable: Postal code attached to the address.
    - `phone` string, nullable: Phone number of contact located at this address.
  - `shipping_address` AddressOutputDto
    - `name` string, nullable
    - `first_name` string, nullable: First Name attached to the address.
    - `last_name` string, nullable: Last Name attached to the address.
    - `full_name` string, nullable: Full Name attached to the address.
    - `address_1` string, nullable: The first line of the address.
    - `address_2` string, nullable: The second line of the address.
    - `street_number` string, nullable: The street number Note: this may be part of the address1 or address_2 values, but is available here as a separate value._
    - `street_name` string, nullable: The street name Note: this may be part of the address1 or address_2 values, but is available here as a separate value._
    - `city` string, nullable: Name of city attached to the address.
    - `sub_locality` string, nullable: Sub-locality attached to the address (ex: county or district name).
    - `region` string, nullable: Region attached to the address (ex. the state or province name).
    - `country` string, nullable: Country attached to the address.
    - `postal_code` string, nullable: Postal code attached to the address.
    - `phone` string, nullable: Phone number of contact located at this address.
  - `shipping_method` OrderShippingMethodResponseDto
    - `courier_id` string, nullable
    - `name` string: Name of the shipping method selected on the order.
    - `cost` number, double: The cost incurred for the order by the shipping method.
  - `shipping_instructions` string, nullable
  - `pickup` ExternalOrderPickupResponseDto
    - `name` string
    - `instructions` string, nullable
    - `pickup_date_time` string, date-time, nullable
  - `discounts` OrderDiscountResponseDto[]: The discounts applied to the order.
    - `id` string: System identifier of the discount resource that was added to this order.
    - `savings` number, double: The amount of money that was saved on the total of the order using the discount.
    - `name` string: The name of the discount.
    - `type` string: The type of discount that was applied to the order.
  - `taxes` OrderTaxResponseDto[]: The taxes applied to the order.
    - `name` string: Name of the tax.
    - `amount` number, double: Amount of the tax when applied to the given order.
    - `rate` number, double: Percentage rate of the amount that was added for this tax.
  - `subtotal` number, double: Cost of the order before any additions (i.e.: Taxes, Shipping, etc.)
  - `total` number, double: The total cost of the order.
  - `payment` OrderPaymentResponseDto
    - `transaction_id` string: Unique identifier given by the payment provider used to identify the payment made for the order.
    - `status` 'PAID' | 'DEFERRED' | 'PAID_DEFERRED' | 'CHARGED_BACK' | 'REFUNDED' | 'PAIDOUT' | 'PENDING' | 'FAILED' | 'EXPIRED' | 'CANCELLED' | 'OPEN' | 'AUTHORIZED'
    - `currency` string: Currency of the order.
    - `method` string
    - `card_brand` 'NULL' | 'VISA' | 'MASTERCARD' | 'AMEX' | 'DINERS_CLUB' | 'DISCOVER' | 'JCB' | 'CARD_BLEUE' | 'DANKORT' | 'CARTA_SI' | 'POSTEPAY' | 'MAESTRO' | 'LASER' | 'UNIONPAY' | 'OTHER'
    - `card_last_4` string, nullable
    - `confirmed_method` ConfirmedPaymentMethodResponseDto
      - `gateway` 'NONE' | 'STRIPE' | 'SQUARE' | 'CUSTOM' | 'PAYPAL_COMMERCE_EXPRESS_CHECKOUT_ONLY' | 'PAYPAL_COMMERCE' | 'MANUAL_PAYMENTS' | 'MOLLIE' | 'AUTHORIZE_NET'
      - `name` 'UNKNOWN' | 'CREDIT_CARD' | 'PAYPAL' | 'MANUAL' | 'CUSTOM' | 'NO_PAYMENT' | 'APPLE_PAY' | 'GOOGLE_PAY' | 'MASTERPASS' | 'AMEX_EXPRESS_CHECKOUT' | 'SAMSUNG_PAY' | 'VISA_CHECKOUT' | 'LINK' | 'ACH_CREDIT_TRANSFER' | 'ACH_DIRECT_DEBIT' | 'ACSS_DEBIT' | 'ALIPAY' | 'BECS_DIRECT_DEBIT' | 'BANCONTACT' | 'POINT_OF_SALE' | 'EPS' | 'IDEAL' | 'KLARNA' | 'MULTIBANCO' | 'PRZELEWY24' | 'SEPA_DIRECT_DEBIT' | 'SOFORT' | 'WE_CHAT_PAY' | 'AFFIRM' | 'AFTERPAY_CLEARPAY' | 'BACS_DIRECT_DEBIT' | 'BLIK' | 'BOLETO' | 'CASH' | 'FPX' | 'GRAB_PAY' | 'INTERAC_DEBIT' | 'KONBINI' | 'OXXO' | 'PAY_NOW' | 'PIX' | 'PROMPT_PAY' | 'TWINT' | 'CHECK' | 'BANK_TRANSFER' | 'GIFT_CARD' | 'CRYPTO' | 'SQUARE_CASH_APP' | 'VOUCHER' | 'CASH_APP' | 'PAY_PAY' | 'RAKUTEN_PAY' | 'AU_PAY' | 'D_BARAI' | 'MERPAY' | 'AMAZON_PAY' | 'MOBILE_PAY' | 'REVOLUT_PAY' | 'SWISH' | 'ZIP' | 'ALMA' | 'BELFIUS' | 'DIRECT_DEBIT' | 'KBC' | 'MYBANK' | 'PAY_SAFE_CARD' | 'SATISPAY' | 'TRUSTLY' | 'IN3'
      - `display_name` string, nullable: The name of the payment method.
      - `icon` string, nullable: The icon associated with the payment method.
      - `details` string, nullable: The details of the payment method.
      - `instructions` string, nullable: The instructions for the payment method.
  - `refunds` OrderRefundResponseDto[]: The refunds applied to the order.
    - `id` string: System identifier of the refund.
    - `order_id` string
    - `transaction_id` string, nullable
    - `reason` string, nullable: Reason written by the merchant for the refund.
    - `items` OrderRefundItemResponseDto[]
      - `id` string
      - `quantity` number, double
      - `amount` number, double
      - `taxes` OrderRefundTaxResponseDto[]
        - `id` string
        - `name` string
        - `rate` number, double
        - `amount` number, double
        - `provider` 'BUILT_IN' | 'AVALARA' | 'UNKNOWN'
    - `currency` string
    - `tax_provider` OrderRefundTaxProviderResponseDto
      - `provider` 'BUILT_IN' | 'AVALARA' | 'UNKNOWN'
      - `avalara_reference_id` string, nullable
    - `subtotal` number, double
    - `taxes` OrderRefundTaxResponseDto[]
      - `id` string
      - `name` string
      - `rate` number, double
      - `amount` number, double
      - `provider` 'BUILT_IN' | 'AVALARA' | 'UNKNOWN'
    - `total` number, double
    - `created` string, date-time: Date of the refund.
  - `fulfillments` OrderFulfillmentResponseDto[]: The fulfillments applied to the order.
    - `id` string: System identifier of a fulfillment, it will always start with the prefix `fulfil_`.
    - `order_id` string, nullable: The associated order id.
    - `status` 'UNKNOWN' | 'READY_FOR_PICKUP' | 'FULFILLED' | 'PROCESSING' | 'LEGACY_FULFILLED'
    - `method` 'NONE' | 'EMAIL_MESSAGE' | 'SHIPMENT' | 'PICKUP'
    - `items` OrderFulfillmentItemResponseDto[]: Record of the order’s line item IDs and the quantity fulfilled by the specific fulfillment. Note that it can only contain fulfillable items (e.g. paid memberships, bookings (in the future), are not fulfillable). All items in a same fulfillment must be fulfillable by the same method. e.g. A fulfillment with digital goods, and physical items, can’t be in the same fulfillment.
      - `id` string: The unique identifier of the line item.
      - `quantity` integer: Quantity fulfilled of the line item.
    - `tracking` OrderFulfillmentTrackingResponseDto
      - `number` string: Reference number given by the shipping carrier. This will be customer facing in the emails, customer dashboard, etc.
      - `url` string: Absolute URL pointing to the carrier’s interface so customers and merchant can follow up on a shipment. This will be customer facing in the emails, customer dashboard, etc.
      - `carrier` string, nullable: Display name of the carrier used for the shipment. This will be customer facing in the emails, customer dashboard, etc.
    - `created` string, date-time: Timestamp of the creation of the fulfillment.
    - `updated` string, date-time: Timestamp of the last update of the fulfillment. (`status` update OR `tracking` update).
  - `unfulfilled_items` OrderUnfulfilledItemResponseDto[]: Line items, or quantities of them, that still need to be fulfilled.
    - `id` string: The unique identifier of the line item that needs to be fulfilled by the merchant.
    - `method` 'NONE' | 'EMAIL_MESSAGE' | 'SHIPMENT' | 'PICKUP'
    - `quantity` integer: Quantity of the line item that still needs to be fulfilled.
  - `created` string, date-time: Date that indicates when the order was completed.
  - `user_agent` string: User agent of the customer who made the order.
  - `customer_accepts_email_marketing` boolean, nullable
  - `customer_accepts_sms_marketing` boolean, nullable
  - `customer_accepts_marketing` boolean: Indicates if the customer accepts marketing outreach.
  - `ip_address` string: IP address of the customer who made the order.
  - `cancellation_reason` string, nullable: Reason why the order was cancelled.
  - `cancelled` string, date-time, nullable: Date when the order was cancelled.
  - `custom_fields` ExternalOrderCustomFieldResponseDto[]: Custom fields that were configured when the order was placed.
    - `id` string: Id of the custom field.
    - `label` string: Label displayed alongside the input in the checkout inputs, emails, and in the merchant dashboard.
    - `type` 'TEXT' | 'TEXTAREA' | 'SELECT' | 'RADIO_LIST' | 'CHECKBOX' | 'DATE'
    - `zone` 'CONTACT_INFO' | 'SHIPPING_ADDRESS' | 'SHIPPING_METHODS' | 'BILLING_ADDRESS' | 'PAYMENT_METHODS'
    - `value` string, nullable: String value entered by the customer. This value can be null when the type is CHECKBOX and the customer did not check the input at checkout. When a custom field has type DATE, its value is an ISO datetime string in UTC time. If includes_time is true, then the time is midnight UTC
    - `includes_time` boolean, nullable: For a `DATE` custom field, whether the value includes a time (`true`) or only a date (`false`).
    - `date_range_policy` 'ANY' | 'PAST_ONLY' | 'FUTURE_ONLY'
  - `metadata` string: Metadata associated with the order.
  - `fees` ExternalOrderFeeResponseDto[]
    - `id` string
    - `external_id` string, nullable
    - `name` string
    - `amount` number, double
    - `description` string, nullable
    - `tax_code` string, nullable
    - `tax_group` string, nullable
    - `taxes` ExternalOrderFeeTaxResponseDto[]
      - `name` string
      - `amount` number, double
      - `rate` number, double
    - `metadata` string

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Content
- `429`: Too many requests. The rate limit was exceeded.

---

[API](https://skmtc.dev/duda/apis/duda-partner-api.md) - [All operations](https://skmtc.dev/duda/apis/duda-partner-api/llms.txt) - [OpenAPI document](https://skmtc.dev/duda/apis/duda-partner-api/revisions/52be4d41cb12?raw)