# Create a new order

Creates a new order for a specific sales channel within the merchant's organization.

Endpoint: POST /orders
Version: 2.0.0
Security: BearerAuth

## Request fields (application/json):

  - `carrier_preference` (string,null)
    The preferred carrier to use for delivering this order

  - `currency` (string)
    3-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code.
Examples: EUR, USD, GBP, JPY

  - `custom_metadata` (object,null)
    A JSON object with custom metadata

  - `customer_order_number` (string,null)
    The order number which your customer sees. In case this is not the same as merchant_order_id.

  - `external_created_at` (string,null)
    When the order was originally created/placed by the customer. This can be different from created_at when doing bulk imports or when there's a delay between order placement and API submission.

  - `financial_status` (string)
    Financial status of this order. Possible values:
- failed: Payment failed
- paid: Payment completed successfully
- pending: Payment is pending
- refunded: Payment has been refunded
    Enum: "failed", "paid", "pending", "refunded"

  - `items` (array, required)
    List of items in the order (see OrderItem)

  - `items.merchant_item_id` (string, required)
    Identifier for the line item. Needs to be unique among the line items of the order.

  - `items.price_per_unit_in_cents` (integer)
    The price per unit of this item

  - `items.price_per_unit_in_cents_with_discount` (integer)
    The discounted price per unit of this item

  - `items.quantity` (integer, required)
    The quantity of this item in the order

  - `items.sku_code` (string)
    The merchant's SKU identifier - required if sku_id is not provided

  - `items.sku_id` (integer)
    Hive's SKU identifier - required if sku_code is not provided

  - `merchant_order_id` (string, required)
    An ID that uniquely identifies this order within the sales channel. Must be unique per sales channel.

  - `payment_method` (string,null)
    The payment method used for this order

  - `sales_channel_id` (integer, required)
    The ID of the sales channel this order belongs to

  - `shipping_address` (object, required)

  - `shipping_address.city` (string, required)
    City name

  - `shipping_address.company` (string,null)
    Company name

  - `shipping_address.country_code` (string, required)
    2-letter [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code.
Examples: DE, US, FR, NL

  - `shipping_address.email` (string,null)
    Email address

  - `shipping_address.first_name` (string,null)
    Customer's first name - required if last_name and full_name are omitted

  - `shipping_address.full_name` (string,null)
    Customer's full name - required if first_name and last_name are omitted

  - `shipping_address.last_name` (string,null)
    Customer's last name - required if first_name and full_name are omitted

  - `shipping_address.line1` (string, required)
    Customer's address line 1

  - `shipping_address.line2` (string,null)
    Customer's address line 2

  - `shipping_address.parcel_point_id` (string,null)
    Parcel point ID - see [Sendcloud service points](https://api.sendcloud.dev/docs/sendcloud-public-api/branches/v2/service-points)

  - `shipping_address.phone` (string,null)
    Customer's phone number

  - `shipping_address.postal_code` (string, required)
    Customer's postal code

  - `shipping_address.province_or_state_code` (string,null)
    State or province code. For US addresses, this should be the 2-letter state code (e.g., CA, NY, TX).
For other countries, this should be the appropriate province/state/region code.
Examples: CA (California), NY (New York), ON (Ontario), BE (Berlin)

  - `tags` (array,null)
    String tags for this order

  - `total_net_refunds_in_cents` (integer)
    Net refunds in cents (total refunded minus taxes)

  - `total_net_revenue_in_cents` (integer)
    Net revenue in cents (amount paid minus taxes)

  - `total_price_in_cents` (integer)
    Total price paid in cents

  - `total_tax_in_cents` (integer)
    Total tax paid in cents

  - `total_tax_refunds_in_cents` (integer)
    Total tax in the refunded amount in cents

## Response 201 fields (application/json):

  - `carrier_preference` (string,null, required)
    The preferred carrier to use for delivering this order

  - `created_at` (string, required)
    When the order was created. Will default to current time if omitted.

  - `currency` (string, required)
    3-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code.
Examples: EUR, USD, GBP, JPY

  - `custom_metadata` (object,null)
    A JSON object with custom metadata

  - `customer_order_number` (string,null)
    The order number which your customer sees. In case this is not the same as merchant_order_id.

  - `external_created_at` (string,null)
    When the order was originally created/placed by the customer. This can be different from created_at when doing bulk imports or when there's a delay between order placement and API submission.

  - `financial_status` (string, required)
    Financial status of this order. Possible values:
- failed: Payment failed
- paid: Payment completed successfully
- pending: Payment is pending
- refunded: Payment has been refunded
    Enum: "failed", "paid", "pending", "refunded"

  - `id` (integer, required)
    Hive's unique identifier for this order

  - `items` (array, required)
    List of items in the order (see OrderItem)

  - `items.merchant_item_id` (string, required)
    Identifier for the line item. Needs to be unique among the line items of the order.

  - `items.price_per_unit_in_cents` (integer)
    The price per unit of this item

  - `items.price_per_unit_in_cents_with_discount` (integer)
    The discounted price per unit of this item

  - `items.quantity` (integer, required)
    The quantity of this item in the order

  - `items.sku_code` (string)
    The merchant's SKU identifier - required if sku_id is not provided

  - `items.sku_id` (integer)
    Hive's SKU identifier - required if sku_code is not provided

  - `merchant_order_id` (string, required)
    An ID that uniquely identifies this order within the sales channel. Must be unique per sales channel.

  - `payment_method` (string,null)
    The payment method used for this order

  - `sales_channel_id` (integer, required)
    The ID of the sales channel this order belongs to

  - `shipping_address` (object, required)

  - `shipping_address.city` (string, required)
    City name

  - `shipping_address.company` (string,null)
    Company name

  - `shipping_address.country_code` (string, required)
    2-letter [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code.
Examples: DE, US, FR, NL

  - `shipping_address.email` (string,null)
    Email address

  - `shipping_address.first_name` (string,null)
    Customer's first name - required if last_name and full_name are omitted

  - `shipping_address.full_name` (string,null)
    Customer's full name - required if first_name and last_name are omitted

  - `shipping_address.last_name` (string,null)
    Customer's last name - required if first_name and full_name are omitted

  - `shipping_address.line1` (string, required)
    Customer's address line 1

  - `shipping_address.line2` (string,null)
    Customer's address line 2

  - `shipping_address.parcel_point_id` (string,null)
    Parcel point ID - see [Sendcloud service points](https://api.sendcloud.dev/docs/sendcloud-public-api/branches/v2/service-points)

  - `shipping_address.phone` (string,null)
    Customer's phone number

  - `shipping_address.postal_code` (string, required)
    Customer's postal code

  - `shipping_address.province_or_state_code` (string,null)
    State or province code. For US addresses, this should be the 2-letter state code (e.g., CA, NY, TX).
For other countries, this should be the appropriate province/state/region code.
Examples: CA (California), NY (New York), ON (Ontario), BE (Berlin)

  - `fulfillment_status` (string, required)
    Current fulfillment status of the order within Hive's fulfillment process.
This tracks the order's progress from confirmation through delivery. Possible values:
- waiting_for_picking: Order is confirmed and waiting to be picked in the fulfillment center
- processing: Order is actively being processed (picked/packed) in the fulfillment center
- partially_shipped: Some items from the order have been shipped, but others are still pending
- shipped: All items from the order have been shipped
- on_hold: Order is temporarily paused (e.g., payment issues, merchant request)
- payment_pending: Order is waiting for payment confirmation
- cancelled: Order has been cancelled
- ignored: Order will not be fulfilled (automatically set based on external conditions)

Note: This field is read-only and managed entirely by Hive based on the fulfillment process.
    Enum: "waiting_for_picking", "processing", "partially_shipped", "shipped", "on_hold", "payment_pending", "cancelled", "ignored"

  - `tags` (array,null)
    String tags for this order

  - `total_net_refunds_in_cents` (integer, required)
    Net refunds in cents (total refunded minus taxes)

  - `total_net_revenue_in_cents` (integer, required)
    Net revenue in cents (amount paid minus taxes)

  - `total_price_in_cents` (integer, required)
    Total price paid in cents

  - `total_tax_in_cents` (integer, required)
    Total tax paid in cents

  - `total_tax_refunds_in_cents` (integer, required)
    Total tax in the refunded amount in cents

  - `updated_at` (string, required)
    When the order was last updated

## Response 400 fields (application/json):

  - `errors` (any, required)
    Error information. Can be:
- Object with field names as keys and error arrays as values (for validation errors)
- Array of error objects with message, code, and optional metadata
- Array of strings (for simple error messages)

  - `success` (boolean)
    Indicates if the request was successful

  - `title` (string)
    A brief, human-readable message about the error

  - `status` (integer)
    HTTP status code

## Response 401 fields (application/json):

  - `errors` (any, required)
    Error information. Can be:
- Object with field names as keys and error arrays as values (for validation errors)
- Array of error objects with message, code, and optional metadata
- Array of strings (for simple error messages)

  - `success` (boolean)
    Indicates if the request was successful

  - `title` (string)
    A brief, human-readable message about the error

  - `status` (integer)
    HTTP status code

## Response 403 fields (application/json):

  - `errors` (any, required)
    Error information. Can be:
- Object with field names as keys and error arrays as values (for validation errors)
- Array of error objects with message, code, and optional metadata
- Array of strings (for simple error messages)

  - `success` (boolean)
    Indicates if the request was successful

  - `title` (string)
    A brief, human-readable message about the error

  - `status` (integer)
    HTTP status code

## Response 409 fields (application/json):

  - `errors` (any, required)
    Error information. Can be:
- Object with field names as keys and error arrays as values (for validation errors)
- Array of error objects with message, code, and optional metadata
- Array of strings (for simple error messages)

  - `success` (boolean)
    Indicates if the request was successful

  - `title` (string)
    A brief, human-readable message about the error

  - `status` (integer)
    HTTP status code

## Response 422 fields (application/json):

  - `errors` (any, required)
    Error information. Can be:
- Object with field names as keys and error arrays as values (for validation errors)
- Array of error objects with message, code, and optional metadata
- Array of strings (for simple error messages)

  - `success` (boolean)
    Indicates if the request was successful

  - `title` (string)
    A brief, human-readable message about the error

  - `status` (integer)
    HTTP status code

## Response 429 fields (application/json):

  - `errors` (any, required)
    Error information. Can be:
- Object with field names as keys and error arrays as values (for validation errors)
- Array of error objects with message, code, and optional metadata
- Array of strings (for simple error messages)

  - `success` (boolean)
    Indicates if the request was successful

  - `title` (string)
    A brief, human-readable message about the error

  - `status` (integer)
    HTTP status code