> ## Documentation Index > Fetch the complete documentation index at: https://docs.parceltracer.app/llms.txt > Use this file to discover all available pages before exploring further. # Create order > Create a new order with customer and location details. - If `customer.id` is provided, an existing customer is updated. - If only `phone_number` is provided, a customer is looked up or created. - `customer_location.id` works similarly, but must belong to the customer. - `cod` is a list of currency/amount pairs. Example: [['USD', '10'], ['LBP', '1000000']] ## OpenAPI ````yaml api-reference/schema.yaml post /orders/ openapi: 3.0.3 info: title: '' version: 0.0.0 servers: - url: https://api.parceltracer.com/v1/external/ description: Parcel Tracer api endpoint security: [] paths: /orders/: post: tags: - Orders summary: Create order description: >- Create a new order with customer and location details. - If `customer.id` is provided, an existing customer is updated. - If only `phone_number` is provided, a customer is looked up or created. - `customer_location.id` works similarly, but must belong to the customer. - `cod` is a list of currency/amount pairs. Example: [['USD', '10'], ['LBP', '1000000']] operationId: create_order requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateOrderSerializerDocs' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CreateOrderSerializerDocs' multipart/form-data: schema: $ref: '#/components/schemas/CreateOrderSerializerDocs' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/ExternalOrder' examples: SuccessfulOrderCreation: value: order_id: '179' reference_id: '123' is_exchange: 'false' workflow: STANDARD tracking_link: https://prod.parceltracer.app/tracking/xxxxxxx-yyyyyy is_critical: 'true' merchant_location: 1 cod: - - LBP - '2000.00' - - USD - '50.50' number_of_packages: 1 description: '' notes: '' return_reason: '' delivery_state: CREATED payment_state: UNPAID merchant_invoice: null customer: id: 9707 name: Joelle phone_number: '+96131234567' secondary_phone_number: null email: '' customer_location: id: 9689 area: id: 55 name_en: Balde name_ar: بلدي lat: 34.56076 long: 36.14491 district: Akkar maps_link: http://maps.google.com/maps?q=34.56076,36.14491 directions: '' summary: Successful order creation description: Successful creation '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: ValidationError: value: error: 'true' message: Validation failed. details: 'workflow: "STANDARDS" is not a valid choice.' summary: Example of validation error response description: Validation error '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: ServerError: value: error: 'true' message: Unexpected error. details: Internal server error summary: Example of internal server error response description: Server error security: - MerchantAPIKey: [] components: schemas: CreateOrderSerializerDocs: type: object properties: reference_id: type: string default: '' description: Reference ID of the order, for internal tracking by the shop. is_critical: type: boolean default: false description: >- Mark the order as critical for prioritized handling (subject to the delivery company load and availability) is_exchange: type: boolean default: false description: >- ('Require pickup of a return package upon delivery.\n', 'This option is only applicable when workflow is STANDARD') workflow: allOf: - $ref: '#/components/schemas/Workflow969Enum' default: STANDARD description: |- Order workflow: STANDARD or RETURN. * `STANDARD` - STANDARD * `RETURN` - RETURN merchant_location: type: integer description: >- ("Unique identifier of the merchant's location.\n", 'This identifier should correspond to one of the pickup locations visible on the pickup locations page on Parcel Tracer.') customer: allOf: - $ref: '#/components/schemas/CustomerDocs' description: >- Customer object for the order. - Provide 'id' to identify an existing customer (other fields update the record). - Otherwise provide 'phone_number' plus required customer fields to create a new customer. customer_location: allOf: - $ref: '#/components/schemas/CustomerLocationDocs' description: >- Customer location for delivery or pickup. - Provide 'id' to identify an existing location (other fields update it). - Otherwise, provide full location details to create a new location. cod: type: array items: type: array items: type: string maxItems: 2 minItems: 2 description: >- Total amount to be collected upon delivery (or upon return). Example: [['USD', '123.5']] number_of_packages: type: integer default: 1 description: >- ('Number of packages in the order.\n', 'Should be greater than or equal to 1.') description: type: string description: Optional description of the order contents. notes: type: string description: >- Extra notes about the order, visible to delivery company, carriers and customers. return_reason: type: string description: Applicable if the order is a return. Reason for the return. required: - customer - customer_location - merchant_location ExternalOrder: type: object properties: order_id: type: string readOnly: true nullable: true reference_id: type: string pattern: ^([A-Za-z0-9]|\.|-)*$ maxLength: 40 is_exchange: type: boolean workflow: $ref: '#/components/schemas/ExternalOrderWorkflowEnum' tracking_link: type: string format: uri readOnly: true is_critical: type: boolean title: Critical customer: type: object additionalProperties: {} writeOnly: true description: >- Customer object identifying the customer for the order. - To identify an existing customer, provide the unique 'id' field. Other fields will update the existing record. - Alternatively, if 'id' is not provided, provide the unique 'phone_number' to identify the customer. - If neither 'id' nor existing 'phone_number' is found, a new customer will be created, and all required customer fields must be provided. customer_location: type: object additionalProperties: {} writeOnly: true description: >- Customer location object for order delivery or pickup. - To identify an existing location, provide the unique 'id'. Other fields will update that location. - If 'id' is not provided, a new location will be created and all required fields must be present. - The location must belong to the specified customer, else the request will be rejected. resolved_customer: allOf: - $ref: '#/components/schemas/Customer' readOnly: true resolved_customer_location: allOf: - $ref: '#/components/schemas/ExternalLocation' readOnly: true merchant_location: type: integer cod: type: array items: type: array items: type: string maxItems: 2 minItems: 2 description: >- Total amount to be collected upon delivery. Example: [['USD', '123.5']] delivery_fee: type: array items: type: array items: type: string maxItems: 2 minItems: 2 readOnly: true description: >- Delivery fees charged on the delivery operation. Irrelevant in case of `RETURN` orders. number_of_packages: type: integer maximum: 99 minimum: 1 description: type: string maxLength: 300 notes: type: string return_reason: type: string maxLength: 300 delivery_state: allOf: - $ref: '#/components/schemas/DeliveryStateEnum' readOnly: true payment_state: type: string readOnly: true merchant_invoice: type: integer readOnly: true nullable: true required: - customer - customer_location - delivery_fee - delivery_state - merchant_invoice - merchant_location - order_id - payment_state - resolved_customer - resolved_customer_location - tracking_link ErrorResponse: type: object properties: error: type: boolean message: type: string details: {} required: - details - error - message Workflow969Enum: enum: - STANDARD - RETURN type: string description: |- * `STANDARD` - STANDARD * `RETURN` - RETURN CustomerDocs: type: object properties: id: type: integer minimum: 1 description: >- Unique ID of the customer. If provided, other fields are optional and update the customer. phone_number: type: string description: Customer phone number. Required if 'id' is not provided. secondary_phone_number: type: string description: Secondary customer phone number. name: type: string description: Customer full name. Required if creating a new customer. email: type: string format: email description: Customer email. CustomerLocationDocs: type: object properties: id: type: integer minimum: 1 description: >- Unique ID of the location. If provided, other fields update this location. area: allOf: - $ref: '#/components/schemas/Area' description: City of the location. directions: type: string description: Additional indications to help the carrier reach the customer. ExternalOrderWorkflowEnum: enum: - STANDARD - RETURN type: string description: |- * `STANDARD` - Standard * `RETURN` - Return Customer: type: object properties: id: type: integer readOnly: true name: type: string maxLength: 255 phone_number: type: string secondary_phone_number: type: string email: type: string format: email required: - id - name - phone_number ExternalLocation: type: object properties: id: type: integer readOnly: true area: $ref: '#/components/schemas/Area' directions: type: string required: - area - id DeliveryStateEnum: enum: - CREATED - PICKUP_REQUESTED - PICKUP_ASSIGNED - SCANNED_FOR_PICKUP - PICKED_UP - AT_WAREHOUSE - DELIVERY_ASSIGNED - SCANNED_FOR_DELIVERY - PICKED_UP_FOR_DELIVERY - IN_TRANSIT - DELIVERED - AWAITING_RETURN - CANCELLED - DELIVERED_AT_WAREHOUSE type: string description: |- * `CREATED` - Created * `PICKUP_REQUESTED` - Pickup Requested * `PICKUP_ASSIGNED` - Pickup Assigned * `SCANNED_FOR_PICKUP` - Scanned for Pickup * `PICKED_UP` - Picked Up * `AT_WAREHOUSE` - At Warehouse * `DELIVERY_ASSIGNED` - Delivery Assigned * `SCANNED_FOR_DELIVERY` - Scanned For Delivery * `PICKED_UP_FOR_DELIVERY` - Picked Up For Delivery * `IN_TRANSIT` - In Transit * `DELIVERED` - Delivered * `AWAITING_RETURN` - Awaiting Return * `CANCELLED` - Cancelled * `DELIVERED_AT_WAREHOUSE` - Delivered At Warehouse Area: type: object description: |- A ModelSerializer that takes an additional `fields` argument that controls which fields should be displayed. properties: id: type: integer readOnly: true name_ar: type: string default: '' maxLength: 200 name_en: type: string default: '' maxLength: 200 district: $ref: '#/components/schemas/DistrictEnum' lat: type: string format: decimal pattern: ^-?\d{0,3}(?:\.\d{0,15})?$ nullable: true long: type: string format: decimal pattern: ^-?\d{0,3}(?:\.\d{0,15})?$ nullable: true maps_link: type: string nullable: true maxLength: 200 code: type: string readOnly: true required: - code - id DistrictEnum: enum: - Zahleh - Hasbaya - Baalbek - Jezzine - Baabda - Jbeil - Zgharta - Bint Jbeil - Hermel - Marjeyoun - Bsharri - Aley - Rashaya - Miniyeh-Danniyeh - Tripoli - Tyre - Nabatieh - Chouf - Maatn - Western Beqaa - Akkar - Sidon - Batroun - Keserwan - Koura - Beirut type: string description: |- * `Zahleh` - Zahleh * `Hasbaya` - Hasbaya * `Baalbek` - Baalbek * `Jezzine` - Jezzine * `Baabda` - Baabda * `Jbeil` - Jbeil * `Zgharta` - Zgharta * `Bint Jbeil` - Bint Jbeil * `Hermel` - Hermel * `Marjeyoun` - Marjeyoun * `Bsharri` - Bsharri * `Aley` - Aley * `Rashaya` - Rashaya * `Miniyeh-Danniyeh` - Miniyeh-Danniyeh * `Tripoli` - Tripoli * `Tyre` - Tyre * `Nabatieh` - Nabatieh * `Chouf` - Chouf * `Maatn` - Maatn * `Western Beqaa` - Western Beqaa * `Akkar` - Akkar * `Sidon` - Sidon * `Batroun` - Batroun * `Keserwan` - Keserwan * `Koura` - Koura * `Beirut` - Beirut securitySchemes: MerchantAPIKey: type: apiKey in: header name: X-Api-Key ````