> ## Documentation Index > Fetch the complete documentation index at: https://developer.jtl-software.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Orders > Create new Orders ## OpenAPI ````yaml /openapi/scx/channel.json post /v1/channel/order openapi: 3.0.2 info: title: JTL-Channel API version: 1.0.0 x-logo: url: https://scx-sandbox.ui.jtl-software.com/docs/scx.png description: > JTL-Channel API is a REST-based API that helps a Channel Integrator to connect Marketplace with the JTL-Wawi ERP System. # Key Features With the JTL-Channel API, you can: * Describe connected Marketplace Data Structure by providing Category and Attribute Data * Manage Product and Offer Listings * Manage Orders * Handle the Post Order Process # Development Guide There is a detailed development guide available at [developer.jtl-software.com](https://developer.jtl-software.com/products/marketplaces/scx-channel-api/change_log). servers: - url: https://scx-sbx.api.jtl-software.com description: Sandbox - url: https://scx.api.jtl-software.com description: Production security: [] tags: - name: Seller description: | Seller Management - name: Channel description: Meta channel routes - name: Notification description: Channel notifications - name: Supported Prices description: Price type management - name: Meta description: meta - name: Attributes description: Channel attributes - name: Categories description: Channel categories - name: Order description: Orders - name: Return description: Order returns - name: Events description: SCX events - name: Offer description: Channel offers - name: Report description: SCX reports - name: Ticket description: Channel tickets - name: Stock Updates description: Stock update operations paths: /v1/channel/order: post: tags: - Order summary: Create Orders description: | Create new Orders operationId: CreateOrders requestBody: $ref: '#/components/requestBodies/CreateOrder' responses: '200': $ref: '#/components/responses/OptionalErrorResponse' '201': description: Orders Created '401': $ref: '#/components/responses/AccessForbidden' '404': $ref: '#/components/responses/SellerNotFound' '500': $ref: '#/components/responses/ServerError' security: - ChannelAuth: [] components: requestBodies: CreateOrder: description: >- List of new orders received from the marketplace that should be forwarded to the sellers. content: application/json: schema: $ref: '#/components/schemas/OrderList' responses: OptionalErrorResponse: description: Call was overall successful but some items can be faulty content: application/json: schema: $ref: '#/components/schemas/ErrorResponseList' example: errorList: - code: CHN401 message: >- Not all orders could be processed. 9 out of 10 orders were stored successfully severity: warning hint: null AccessForbidden: description: Access forbidden, invalid or unknown Token was used. SellerNotFound: description: The requested seller could not be found or is not active. ServerError: description: Unexpected Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponseList' example: errorList: - code: GEN500 message: Internal Server Error severity: error hint: null schemas: OrderList: type: object required: - orderList properties: orderList: type: array minItems: 1 maxItems: 1000 items: $ref: '#/components/schemas/Order' ErrorResponseList: type: object properties: errorList: nullable: true type: array example: - code: GEN700 message: Seller SELLER_4711 does not exist on channel kaufland. severity: error hint: i9n-order22 items: title: Error type: object properties: code: type: string example: GEN700 message: type: string example: Seller SELLER_4711 does not exist on channel kaufland. severity: type: string enum: - error - warning - info default: error hint: type: string nullable: true example: i9n-order22 Order: title: Order type: object properties: sellerId: $ref: '#/components/schemas/SellerId' orderStatus: $ref: '#/components/schemas/ChannelOrderStatus' orderAcceptUntil: description: > When `orderStatus` is type `UNACKED` a Seller integration must confirn a Order bevor it can be proccessed. This field provides a time until when an order can be accepted. To accept an Order a Seller integration must invoke API call `PUT /v1/seller/order/accept`. type: string format: date-time paymentMethod: type: string example: CHANNEL minLength: 1 maxLength: 150 paymentReference: description: >- Payment reference can be used to reference or identify a payment transaction type: string orderId: $ref: '#/components/schemas/ChannelOrderId' purchasedAt: type: string format: date-time example: '2019-02-11T14:54:32+00:00' lastChangedAt: type: string format: date-time example: '2019-02-11T16:54:32+00:00' currency: type: string example: EUR orderItem: description: > List of Order Positions such as Order Items, Shipping or Payment. There must be at least on Item of Type ITEM and at least on Item of Type SHIPPING. type: array minItems: 1 items: $ref: '#/components/schemas/OrderItem' billingAddress: $ref: '#/components/schemas/Address' shippingAddress: $ref: '#/components/schemas/Address' note: description: A optional note type: string example: This note can be everything, but a least a additional message. buyer: $ref: '#/components/schemas/OrderBuyer' weeePickup: description: > This Order require a electrical and electronic equipment disposal service (WEEE) type: boolean example: true nullable: true language: description: The language of the order as a ISO 639-1 language code type: string nullable: true example: de invoiceDocumentTransfer: description: > This field indicates whether the channel provides the invoice document or the seller has to upload it. This overwrites the default setting of the channel. Possible values are: - `from-seller`: Seller has to upload the invoice document - `from-channel`: Channel provides the invoice document - `not-set` (Default): Use the default setting of the channel or indicates that invoice transfer is not supported type: string enum: - not-set - from-seller - from-channel nullable: true default: not-set example: from-seller additionalOrderData: description: > Additional order data is a list of key value pairs. The key is a string and the value is a string or a number. The key must be unique in the list. type: array minItems: 0 maxItems: 10 items: $ref: '#/components/schemas/AdditionalOrderDataGroup' fbc: description: > Fulfillment by Channel - indicates if the order is fulfilled by the channel type: boolean nullable: true default: null example: true b2b: description: | Business to Business - indicates if this is a B2B order type: boolean nullable: true default: null example: false salesChannelName: description: > Sales channel name (Verkaufskanalname) - identifies the specific sales channel type: string maxLength: 100 nullable: true example: MyMarketplace.de required: - sellerId - orderStatus - orderId - purchasedAt - lastChangedAt - currency - orderItem SellerId: description: > A unique Id identify a Seller on a specific SalesChannel. The SellerId is generated from the Channel itself during the Seller SignUp Process. type: string example: '4711' pattern: ^\w{1,50}$ ChannelOrderStatus: description: > The current order status. * **UNACKED**: Order is created in Marketplace but a Seller acknowledge is required. * **CREATED**: Order is created but not yet completed. * **ACCEPTED**: Order is placed and checkout process is complete but not yet shipped. * (DEPRECATED) ~~SHIPPED~~: All items in the order have been shipped * (DEPRECATED) ~~PARTIALLY_SHIPPED~~: Some items (but not all) have been shipped. * (DEPRECATED) ~~CANCELED_BY_SELLER~~: Order is canceled by seller. * (DEPRECATED) ~~CANCELED_BY_BUYER~~: Order is canceled by buyer. type: string enum: - UNACKED - CREATED - ACCEPTED - SHIPPED - PARTIALLY_SHIPPED - CANCELED_BY_SELLER - CANCELED_BY_BUYER ChannelOrderId: type: string minLength: 1 maxLength: 150 example: 43523-43432-43532 OrderItem: type: object anyOf: - $ref: '#/components/schemas/OrderItemTypeItem' - $ref: '#/components/schemas/OrderItemTypeShipping' - $ref: '#/components/schemas/OrderItemTypePayment' Address: type: object required: - lastName - street - city - country properties: firstName: type: string example: Arno lastName: type: string example: Nym gender: type: string enum: - male - female - diverse companyName: type: string street: type: string example: Leyboldstrasse houseNumber: type: string example: 14a addition: type: string example: 1. UG postcode: type: string example: '50354' city: type: string example: Hürth phone: type: string example: +49 0221 123456 country: type: string example: DE state: type: string example: NRW nullable: true OrderBuyer: type: object properties: email: type: string format: email vatId: type: string AdditionalOrderDataGroup: title: AdditionalOrderDataGroup description: > Additional order data is a list of key value pairs and should be used to add additional information to an order. The data is used by a connected client implementation (such as JTL-Wawi) to display and print this information. type: object properties: group: type: string description: > The group name is used to group the additional order data. The group name must be unique in the list. minLength: 1 maxLength: 150 example: Marketplace Fees values: type: array minItems: 1 maxItems: 50 items: $ref: '#/components/schemas/AdditionalOrderDataGroupValues' OrderItemTypeItem: type: object title: OrderItemTypeItem properties: orderItemId: $ref: '#/components/schemas/OrderItemId' type: type: string default: ITEM itemStatus: $ref: '#/components/schemas/OrderItemStatus' itemPaymentStatus: $ref: '#/components/schemas/OrderItemPaymentStatus' grossPrice: type: string example: '2.00' description: | The order item gross price The gross price is not allowed to have more than 2 decimal places. total: type: string example: '2.00' description: | Overall gross price (quantity * grossPrice) The total is not allowed to have more than 2 decimal places. taxPercent: type: string nullable: true example: '16.00' grossFee: description: > The accrued sales charge (gross), which is levied by the marketplace. This property is optional and if a marketplace does not support sales fees then this property must be null or not present. The gross fee is not allowed to have more than 2 decimal places. type: string example: '0.29' nullable: true offerId: $ref: '#/components/schemas/OfferId' channelOfferId: $ref: '#/components/schemas/ChannelOfferId' sku: $ref: '#/components/schemas/SKU' quantity: type: string default: '1.0' example: '1.0' title: type: string example: Dark Beer estimatedShippingDate: type: string format: date-time example: '2010-03-11T00:00:00+00:00' estimatedDeliveryDate: type: string format: date-time example: '2010-03-12T00:00:00+00:00' remainingQuantity: type: string description: > Includes the rest of the inventory available on the connected Marketplace. The remaining quanity can be used by a connected client implementation (such as JTL-Wawi) to manage quanity updates. nullable: true example: '54.0' additionalOrderItemData: description: > Additional order data is a list of key value pairs. The key is a string and the value is a string or a number. The key must be unique in the list. type: array minItems: 0 maxItems: 10 items: $ref: '#/components/schemas/AdditionalOrderDataGroup' shipFromCountry: description: > Ship from country (Versandland) - ISO 3 letter country code indicating the country from which the item is shipped type: string pattern: ^[A-Z]{3}$ nullable: true example: DEU required: - orderItemId - type - grossPrice - total OrderItemTypeShipping: type: object title: OrderItemTypeShipping properties: orderItemId: $ref: '#/components/schemas/OrderItemId' type: type: string default: SHIPPING grossPrice: type: string example: '3.99' taxPercent: type: string example: '19.00' nullable: true shippingGroup: $ref: '#/components/schemas/shippingGroup' required: - orderItemId - type - grossPrice - shippingGroup OrderItemTypePayment: type: object title: OrderItemTypePayment properties: orderItemId: $ref: '#/components/schemas/OrderItemId' type: type: string default: PAYMENT grossPrice: type: string example: '3.99' taxPercent: type: string example: '19.00' nullable: true note: type: string example: Cash on delivery required: - orderItemId - type - grossPrice - note AdditionalOrderDataGroupValues: title: AdditionalOrderDataGroupValues type: object properties: key: type: string description: > The key is used to identify the additional order data. The key can be used multiple times in the list and we recommend to use a human readable key. minLength: 1 maxLength: 255 example: Advertising fee value: type: string description: > The value is used to store the additional order data and must be always a string. minLength: 1 maxLength: 5000 example: 0.50 USD OrderItemId: description: >- A unique identifier to identify a order item. This ID is provided by the Channel itself an should be used to identify a order item id. type: string example: '5437233' format: string minLength: 1 maxLength: 50 OrderItemStatus: description: | The current for order item. * **UNSHIPPED**: Item is ready for shipping * **SHIPPED**: Item is sent to buyer * **CANCELED_BY_SELLER**: Order is canceled by seller. * **CANCELED_BY_BUYER**: Order is canceled by buyer. * **RETURNED**: Item is returned to Seller. * **REFUNDED**: Item was returned and refunded. type: string enum: - UNSHIPPED - SHIPPED - CANCELED_BY_SELLER - CANCELED_BY_BUYER - RETURNED - REFUNDED OrderItemPaymentStatus: description: | The current payment status * **PENDING**: Order Item is not yet paid. * **PAID**: Order Item is complete paid. type: string enum: - PENDING - PAID OfferId: description: | Unique Offer Id to identify an Offer on a Sales Channel. type: integer example: 5437233 format: int64 minimum: 1 maxLength: 50 ChannelOfferId: description: | Channel defined unique Offer Id to identify an Offer on a Sales Channel. type: string example: XCD233554 minLength: 1 maxLength: 100 SKU: description: | Stock keeping unit is a unique Id used to identify one product. type: string example: BEER-001 minLength: 1 maxLength: 150 shippingGroup: description: >- The shipping group is a unique identifier about what kind of shipping method and carrier is used to fulfill a order. A shipping group can be given by the connected salesChannel or defined by the seller itself. type: string example: DHL_DOMESTIC securitySchemes: ChannelAuth: description: > As a Channel Integrator you will receive a API Refresh Token. With such a Refresh Token you need to request an Access Token with a limited Lifetime (see POST /v1/auth). This Access Token must be provided as a Bearer Token in the Authorization Header with every request. type: http scheme: bearer bearerFormat: JWT ````