> ## Documentation Index
> Fetch the complete documentation index at: https://developers.openborder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit a new order

> ## What this endpoint does
This endpoint **creates a final order in OpenBorder’s Order Management System (OMS)** once your customer has **selected their shipping option and agreed to the calculated landed cost**.
This call ensures the order is registered in OpenBorder’s OMS so we can:
- Record the exact **duties & taxes** to be remitted to authorities
- Guarantee the correct shipping rate is linked to the shipment
- Generate accurate billing and settlement for your international shipments




## OpenAPI

````yaml /api-reference/landed-cost.json post /v1/orders
openapi: 3.0.0
info:
  title: OpenBorder Direct API Service
  description: Direct API Service description for OPEN API documentation
  version: '0.1'
  contact: {}
servers:
  - url: https://api.openborder.com/api/direct/
    description: Production
  - url: https://api.staging.openborder.com/api/direct/
    description: Sandbox
security: []
tags: []
paths:
  /v1/orders:
    post:
      tags:
        - Orders
      summary: Submit a new order
      description: >
        ## What this endpoint does

        This endpoint **creates a final order in OpenBorder’s Order Management
        System (OMS)** once your customer has **selected their shipping option
        and agreed to the calculated landed cost**.

        This call ensures the order is registered in OpenBorder’s OMS so we can:

        - Record the exact **duties & taxes** to be remitted to authorities

        - Guarantee the correct shipping rate is linked to the shipment

        - Generate accurate billing and settlement for your international
        shipments
      operationId: OrdersController_createOrder
      parameters:
        - name: x-openborder-direct-api-key
          in: header
          description: OpenBorder merchant API token
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreatePayload'
      responses:
        '204':
          description: Order successfully created. No content returned.
        '400':
          description: Invalid order payload received.
        '401':
          description: Invalid authorization token received.
        '422':
          description: Order data failed validation rules.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityException'
components:
  schemas:
    OrderCreatePayload:
      type: object
      properties:
        source:
          type: string
          description: Source system from which the order originated.
        source_reference:
          type: number
          description: >-
            Reference ID from the source system. This is the unique identifier
            to reference the order on subsequent calls and cannot be updated.
        landedcost_request_id:
          type: string
          description: >-
            Unique ID for this tax calculation request provided when calculating
            landed cost.
        source_created_at:
          type: string
          description: >-
            Timestamp in ISO format when the order was created in the source
            system.
        source_updated_at:
          type: string
          description: >-
            Timestamp in ISO format when the order was last updated in the
            source system.
        billing_address:
          description: Billing address for the order.
          allOf:
            - $ref: '#/components/schemas/BillingAddress'
        total:
          type: number
          description: >-
            Total amount of the order including all charges, taxes, duties,
            discounts and refund in major currency units (e.g., dollars). Up to
            two decimal places are allowed.
        shipments:
          description: >-
            Shipments on the order. Each must include a tax_request_id from the
            tax calculation step.
          type: array
          items:
            $ref: '#/components/schemas/OrderCreateShipmentPayload'
        custom_properties:
          type: object
          description: >-
            Optional custom metadata or structured properties. Object max. size
            is 4 KB.
          nullable: true
      required:
        - source
        - source_reference
        - landedcost_request_id
        - source_created_at
        - source_updated_at
        - total
        - shipments
    UnprocessableEntityException:
      type: object
      properties:
        error:
          description: Validation errors
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetails'
    BillingAddress:
      type: object
      properties:
        country_code:
          type: string
          description: >-
            The two-letter country code (ISO 3166-1 alpha-2) for the billing
            address (e.g. "CA" for Canada).
        province:
          type: string
          description: >-
            The state, province, or region within the billing country. Include
            this if your billing country has one (e.g."ON" for Ontario).
          nullable: true
        postal_code:
          type: string
          description: The ZIP code or postal code for the billing address.
          nullable: true
        address1:
          type: string
          description: >-
            The primary street address line for billing, such as the house
            number and street name. Example: "123 Main Street".
          nullable: true
        address2:
          type: string
          description: >-
            A secondary billing address line, such as an apartment, suite, or
            unit number. Example: "Apt 4B".
          nullable: true
        city:
          type: string
          description: The city or locality for the billing address.
          nullable: true
        name:
          type: string
          description: >-
            The full name of the person or entity responsible for billing at
            this address.
          nullable: true
      required:
        - country_code
    OrderCreateShipmentPayload:
      type: object
      properties:
        tax_transaction_id:
          type: string
          description: >-
            Unique tax transaction identifier received on the cart tax
            calculation request for the shipment.
        shipment_id:
          type: string
          description: The unique ID for the shipment.
      required:
        - tax_transaction_id
        - shipment_id
    ErrorDetails:
      type: object
      properties:
        field:
          type: string
          description: Field name
          example: ship_from
        error:
          type: string
          description: Error message
          example: Name is required
      required:
        - field
        - error

````