# Create Order

Creates a fulfilment order: an instruction to pick stock Quiqup already holds for you, pack it and ship it to your customer. The warehouse builds the parcels, so you send products, not parcels.
The order is created as `pending` and goes to the warehouse for picking straight away. There is no separate release call. Two kinds of order wait first: an export (origin and shipping countries differ) waits until its carrier is settled, and an order that needs a Saudi national address waits until the address is valid.
`service_kind` sets the picking and packing deadline from your account's cut-off times and selects the carrier:
- `partner_next_day`: next day, the standard service, in the UAE and Saudi Arabia.
- `partner_same_day`: same day, in the UAE only.
- `partner_4hr`: within four hours, in Dubai only.
- `partner_export`: international. The carrier is chosen by rules.
- `partner_store`: store replenishment, business to business.
- `partner_return`: a return. Use `is_return` instead, below.

Ask your account manager which services are enabled on your account.
To create a return, set `is_return` to `true` and point `initial_order_id` at the original order. The order is stored with `service_kind` `partner_return` and is not picked from your stock. Only a return can carry `mark_as_ready_for_collection`.
Send a `uuid` to make the create safe to retry: a repeat with the same `uuid` returns the original order. A reference with `is_unique` set to `true` cannot be reused by another order on your account.

Endpoint: POST /api/fulfilment/orders
Version: 1.0.0
Security: BearerAuth, OAuth2

## Security:

  - `BearerAuth` (unknown)
    http bearer

  - `OAuth2` (unknown)
    oauth2

## Request fields (application/json):

  - `billing_address` (object)
    An address on an order request.

  - `billing_address.address1` (string, required)
    Street address. Required, at most 255 characters.

  - `billing_address.address2` (string)
    Building, floor, apartment or other detail, at most 100 characters.

  - `billing_address.city` (string, required)
    City. Required, at most 50 characters.

  - `billing_address.coordinate` (object)
    Latitude and longitude of the address. Optional.

  - `billing_address.coordinate.latitude` (number, required)
    Geographic latitude.

  - `billing_address.coordinate.longitude` (number, required)
    Geographic longitude.

  - `billing_address.country` (string)
    Country name, at most 50 characters.

  - `billing_address.country_code` (string, required)
    ISO 3166-1 alpha-2 country code, for example AE. Required.

  - `billing_address.email` (string)
    Contact email, at most 100 characters. Required on the shipping address of a partner_export order and optional everywhere else.

  - `billing_address.first_name` (string, required)
    First name of the contact. Required, at most 50 characters.

  - `billing_address.ksa_national_address` (string)
    Saudi national address short code, for example RNMA7272, at most 50 characters. Used for deliveries in Saudi Arabia.

  - `billing_address.last_name` (string)
    Last name of the contact, at most 50 characters.

  - `billing_address.name` (string)
    Business or recipient name, at most 100 characters. When empty, first_name and last_name are used as the contact name.

  - `billing_address.notes` (string)
    Delivery instructions for this address, at most 500 characters.

  - `billing_address.phone` (string, required)
    Contact phone number in E.164 format, for example +971501234567. Spaces are removed before it is checked. Required.

  - `billing_address.postcode` (string)
    Postal code, at most 20 characters.

  - `billing_address.state` (string)
    State, province or emirate, at most 50 characters.

  - `billing_identifier` (string)
    A free-text label carried on the order for billing, for example to tell apart several brands that share one account. Optional.

  - `carrier` (string)
    The carrier to ship with. Optional: normally the carrier is chosen for you.

  - `currency` (string, required)
    Three-letter ISO 4217 code for payment_amount, for example AED or SAR. Required.

  - `delivery_options` (array)
    Special delivery requirements. The only accepted value is customer_identification_photo. Optional.

  - `incoterm` (string)
    For an export, the Incoterm the order ships under, for example DAP. Optional.

  - `initial_order_id` (string)
    For a return, the id of the original order. When you send it, the original order must exist on your account or the create fails. Optional.

  - `is_return` (boolean)
    Set to true to create a return order. The order is then created with service_kind partner_return, and it is not picked from your stock. Optional.

  - `mark_as_ready_for_collection` (boolean)
    Return orders only. Send true together with is_return true to create the return as ready_for_collection instead of pending, so it is collected without a further step. Sending true on any other order is rejected. A normal order needs no such flag: it goes to the warehouse for picking as soon as it is created.

  - `notes` (string)
    Delivery instructions for the courier, at most 255 characters. Optional.

  - `partner_order_id` (string, required)
    Your own reference for the order. Required.

  - `payment_amount` (number)
    What the courier collects from the customer. Required, and must not be 0, when payment_mode is paid_on_delivery. For pre_paid, send 0 or omit it.

  - `payment_mode` (string, required)
    pre_paid when you have already taken payment, paid_on_delivery when the courier collects it.
    Enum: "pre_paid", "paid_on_delivery"

  - `products` (array, required)
    The SKUs to pick and the quantity of each. Required. Every SKU must be a product on your account.

  - `products.barcode` (string)
    Barcode to use for this line instead of the catalogue value, at most 50 characters. Optional.

  - `products.dangerous_goods` (boolean)
    Set to true to treat this line as dangerous goods. Omit it to use the product's own classification.

  - `products.quantity` (integer, required)
    Number of units to pick. Required, at least 1.

  - `products.sku` (string, required)
    A SKU from your product catalogue. Required, at most 100 characters.

  - `references` (array)
    Your own identifiers for the order as label and value pairs, for example a marketplace order number. They are stored on the order and returned when you read it. Optional.

  - `references.is_unique` (boolean)
    When true, no other order on your account may carry the same label and value: a later create that repeats them is rejected. Defaults to false.

  - `references.label` (string, required)
    The reference name, for example marketplace_order_id. Required, at most 255 characters.

  - `references.value` (string, required)
    The reference value. Required, at most 255 characters.

  - `registration_numbers` (array)
    Customs and VAT registration numbers for an export, such as a Mirsal 2 code. Optional.

  - `registration_numbers.issuer_country_code` (string, required)
    ISO 3166-1 alpha-2 code of the country that issued the number, for example AE.

  - `registration_numbers.type_code` (string, required)
    The registration type, for example MIRSAL2.

  - `registration_numbers.value` (string, required)
    The registration number.

  - `service_kind` (string, required)
    The delivery service of an order.
    Enum: "partner_next_day", "partner_same_day", "partner_4hr", "partner_export", "partner_store", "partner_return"

  - `uuid` (string)
    Optional idempotency key, a UUID. Retry a create with the same uuid and you get the original order back instead of a second one, which makes a timed-out request safe to resend. Any UUID spelling is accepted (upper or lower case, with or without dashes) and anything else is rejected. A uuid is scoped to your account, and one already used by another account is rejected. Omit it and every request creates a new order.

## Response 200:

  - `200` (unknown)
    Success response

## Response 200 fields (application/json):

  - `billing_address` (object)
    An address on an order.

  - `billing_address.address1` (string)
    Street address.

  - `billing_address.address2` (string)
    Building, floor, apartment or other detail.

  - `billing_address.city` (string)
    City.

  - `billing_address.coordinate` (object)
    Latitude and longitude of the address.

  - `billing_address.coordinate.latitude` (number, required)
    Latitude of the location (between -90 and 90 degrees).

  - `billing_address.coordinate.longitude` (number, required)
    Longitude of the location (between -180 and 180 degrees).

  - `billing_address.country` (string)
    Country name.

  - `billing_address.country_code` (string)
    ISO 3166-1 alpha-2 country code.

  - `billing_address.created_at` (string)
    When the address was recorded.

  - `billing_address.email` (string)
    Contact email.

  - `billing_address.first_name` (string)
    First name of the contact.

  - `billing_address.ksa_national_address` (string)
    Saudi national address short code.

  - `billing_address.last_name` (string)
    Last name of the contact.

  - `billing_address.name` (string)
    Business or recipient name.

  - `billing_address.notes` (string)
    Delivery instructions for this address.

  - `billing_address.phone` (string)
    Contact phone number.

  - `billing_address.postcode` (string)
    Postal code.

  - `billing_address.state` (string)
    State, province or emirate.

  - `billing_address.updated_at` (string)
    When the address was last changed.

  - `carrier` (string)
    The carrier the order ships with.

  - `created_at` (string)
    When the order was created.

  - `currency` (string)
    Three-letter ISO 4217 code for payment_amount.

  - `delivery_options` (array)
    Special delivery requirements, for example customer_identification_photo.

  - `errors` (array)
    Problems recorded against the order, each as a set of key and value strings.

  - `id` (string)
    The order id, a number sent as a string. It is the id you pass to GET and PATCH, and order.* webhooks carry the same number as payload.id.

  - `incoterm` (string)
    The Incoterm of an export.

  - `initial_order_id` (string)
    For a return, the original order's id.

  - `is_return` (boolean)
    Whether this is a return order.

  - `notes` (string)
    Delivery instructions for the courier.

  - `parcels` (array)
    The parcels the warehouse packed the order into.

  - `parcels.dimensions` (object)
    Physical dimensions of the parcel (length, width, height).

  - `parcels.dimensions.height` (number, required)
    Height, in unit.

  - `parcels.dimensions.length` (number, required)
    Length, in unit.

  - `parcels.dimensions.unit` (string, required)
    Unit of the three measurements, for example cm.

  - `parcels.dimensions.width` (number, required)
    Width, in unit.

  - `parcels.id` (string)
    Unique identifier for the parcel.

  - `parcels.name` (string)
    Name or description of the parcel.

  - `parcels.notes` (string)
    Additional notes or handling instructions for the parcel.

  - `parcels.parcel_barcode` (string)
    Unique barcode assigned to the parcel for tracking.

  - `parcels.quantity` (integer)
    Number of items in the parcel.

  - `parcels.weight` (number)
    Weight of the parcel in kilograms.

  - `partner_order_id` (string)
    Your own reference for the order.

  - `payment_amount` (number)
    What the courier collects from the customer.

  - `payment_mode` (string)
    pre_paid when you have already taken payment, paid_on_delivery when the courier collects it.
    Enum: "pre_paid", "paid_on_delivery"

  - `picking_order_created` (boolean)
    True once the order has been sent to the warehouse for picking.

  - `products` (array)
    List of products included in the order.

  - `products.barcode` (string)
    Product barcode (EAN, UPC, ISBN, etc.).

  - `products.country_of_origin` (string)
    ISO 3166-1 alpha-2 code of the country of manufacture.

  - `products.dangerous_goods` (boolean)
    Whether the line is treated as dangerous goods.

  - `products.description` (string)
    Detailed description of the product.

  - `products.dimensions` (object)
    Physical dimensions of the product.

  - `products.hs_code` (string)
    Harmonized System Code for customs classification.

  - `products.name` (string)
    Name of the product.

  - `products.quantity` (integer)
    Number of units ordered.

  - `products.selling_price` (number)
    Price at which the product is sold to customers.

  - `products.sku` (string)
    The product SKU.

  - `products.weight` (number)
    Weight of a single unit.

  - `products.weight_unit` (string)
    Unit of weight measurement (e.g., kg, g).

  - `references` (array)
    The references attached to the order when it was created.

  - `references.is_unique` (boolean)
    When true, no other order on your account may carry the same label and value: a later create that repeats them is rejected. Defaults to false.

  - `references.label` (string, required)
    The reference name, for example marketplace_order_id. Required, at most 255 characters.

  - `references.value` (string, required)
    The reference value. Required, at most 255 characters.

  - `service_kind` (string)
    The delivery service: partner_next_day, partner_same_day, partner_4hr, partner_export, partner_store or partner_return. A return order reports partner_return.

  - `status` (string)
    Status of an order. pending (created, and waiting for or in the warehouse), problematic (a stock or warehouse problem that needs attention), wms_on_hold (held in the warehouse system) and picking_started occur only on fulfilment orders. From ready_for_collection the order follows the shared order lifecycle.
    Enum: "pending", "ready_for_collection", "picking_started", "out_for_collection", "out_for_return", "at_depot", "received_at_depot", "in_transit", "out_for_delivery", "collection_failed", "on_hold", "scheduled", "wms_on_hold", "return_to_origin", "returned_to_origin", "cancelled", "collected", "delivery_complete", "delivery_failed", "problematic"

  - `status_reason` (string)
    Why the order is in its current status, for example the warehouse error behind problematic.

  - `tracking_url` (string)
    Tracking page for the order.

  - `tracking_url_advance` (string)
    Tracking page with more detail.

  - `updated_at` (string)
    When the order was last changed.

  - `uuid` (string)
    The order UUID. order.* webhooks carry it as payload.uuid.

## Response 4XX:

  - `4XX` (unknown)
    Error response. See [Error responses](/docs/errors).

## Response 4XX fields (application/json):

  - `code` (string, required)
    The error code. It matches the HTTP status: invalid_argument and failed_precondition are 400, unauthenticated 401, permission_denied 403, not_found 404, already_exists 409, internal 500 and unavailable 503.
    Enum: "canceled", "unknown", "invalid_argument", "deadline_exceeded", "not_found", "already_exists", "permission_denied", "resource_exhausted", "failed_precondition", "aborted", "out_of_range", "unimplemented", "internal", "unavailable", "data_loss", "unauthenticated"

  - `details` (object)
    More about the error. Can be null.

  - `details.field_diffs` (array)
    When an inbound is refused because your product data and the warehouse's disagree, one entry per disagreement.

  - `details.field_diffs.field` (string)
    What disagrees, for example barcode_mismatch.

  - `details.field_diffs.ours` (string)
    The value Quiqup holds for the product.

  - `details.field_diffs.sku` (string)
    The SKU.

  - `details.field_diffs.warehouse` (string)
    The value the warehouse holds.

  - `details.fields` (array)
    For input errors, one entry per field that failed.

  - `details.fields.field` (string)
    The field that failed. Request validation names it by its path in the request, for example ShippingAddress.Phone or Items[0].UnitPrice, which is not always the JSON name.

  - `details.fields.message` (string)
    What was wrong. Request validation gives the rule that failed, for example required.

  - `details.reason` (string)
    A stable identifier for some failures, safe to branch on.

  - `details.request_id` (string)
    Identifies the request. Quote it when you contact support.

  - `details.type` (string)
    The kind of failure.
    Enum: "input", "not_found", "unauthorized", "forbidden", "integration", "internal"

  - `message` (string, required)
    A sentence describing the error.

## Response default:

  - `default` (unknown)
    Error response. See [Error responses](/docs/errors).

## Response default fields (application/json):

  - `code` (string, required)
    The error code. It matches the HTTP status: invalid_argument and failed_precondition are 400, unauthenticated 401, permission_denied 403, not_found 404, already_exists 409, internal 500 and unavailable 503.
    Enum: "canceled", "unknown", "invalid_argument", "deadline_exceeded", "not_found", "already_exists", "permission_denied", "resource_exhausted", "failed_precondition", "aborted", "out_of_range", "unimplemented", "internal", "unavailable", "data_loss", "unauthenticated"

  - `details` (object)
    More about the error. Can be null.

  - `details.field_diffs` (array)
    When an inbound is refused because your product data and the warehouse's disagree, one entry per disagreement.

  - `details.field_diffs.field` (string)
    What disagrees, for example barcode_mismatch.

  - `details.field_diffs.ours` (string)
    The value Quiqup holds for the product.

  - `details.field_diffs.sku` (string)
    The SKU.

  - `details.field_diffs.warehouse` (string)
    The value the warehouse holds.

  - `details.fields` (array)
    For input errors, one entry per field that failed.

  - `details.fields.field` (string)
    The field that failed. Request validation names it by its path in the request, for example ShippingAddress.Phone or Items[0].UnitPrice, which is not always the JSON name.

  - `details.fields.message` (string)
    What was wrong. Request validation gives the rule that failed, for example required.

  - `details.reason` (string)
    A stable identifier for some failures, safe to branch on.

  - `details.request_id` (string)
    Identifies the request. Quote it when you contact support.

  - `details.type` (string)
    The kind of failure.
    Enum: "input", "not_found", "unauthorized", "forbidden", "integration", "internal"

  - `message` (string, required)
    A sentence describing the error.