> ## Documentation Index > Fetch the complete documentation index at: https://docs.dekhq.com/llms.txt > Use this file to discover all available pages before exploring further. # Place an order > Place an order: priced by the same rules as our portal, for the client your credential acts for. Send `expectedTotal` from a preview; if the total has changed, the submission is refused with `total_changed` and `currentTotal`. The answer is always `202` with the submission: usually already `accepted` (with its order) or `refused` (with a problem naming each field); if it is `received`, poll it. Retry safely with the same `Idempotency-Key` and body: you get the first answer and never a second order. The same key with a different body is `409 idempotency_conflict`. ## OpenAPI ````yaml /api/partners/openapi.json post /api/partners/v1/order-submissions openapi: 3.1.0 info: title: DEKHQ Partner REST API version: 1.0.0 description: >- JSON versions of the PromoStandards Order Status and Order Shipment Notification services, and the partner order API. Same credentials, scopes and rate limit as the SOAP endpoints. Generated from the dekhq repo; do not edit by hand. servers: - url: https://partners.dekhq.com security: - basicAuth: [] paths: /api/partners/v1/order-submissions: post: summary: Place an order description: >- Place an order: priced by the same rules as our portal, for the client your credential acts for. Send `expectedTotal` from a preview; if the total has changed, the submission is refused with `total_changed` and `currentTotal`. The answer is always `202` with the submission: usually already `accepted` (with its order) or `refused` (with a problem naming each field); if it is `received`, poll it. Retry safely with the same `Idempotency-Key` and body: you get the first answer and never a second order. The same key with a different body is `409 idempotency_conflict`. operationId: createOrderSubmission parameters: - name: Idempotency-Key in: header required: true description: >- Your unique key for this order. Retrying with the same key and body returns the first answer; the same key with a different body is 409. schema: type: string pattern: ^[\x21-\x7E]{1,255}$ requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OrderSubmissionBody' example: orderName: Spring team order purchaseOrderNumber: PO-10042 shippingMethod: ship shipTo: company: Example Co firstName: Sam lastName: Sample address1: 200 Sample St city: Riverton region: WY postalCode: '82501' country: US requestedInHandsDate: '2026-03-02' inboundTracking: - 1Z999AA10123456784 lines: - ref: L1 garment: styleId: 0b4a2a9e-1c1d-4e6f-9a10-2b3c4d5e6f70 colorId: 7c1e5a3b-2d4f-4a6b-8c9d-0e1f2a3b4c5d suppliedBy: customer sizes: - size: M quantity: 24 - size: L quantity: 12 clientSku: TEE-BLK - ref: L2 garment: brand: Patagonia styleNumber: '25528' colorName: Stone Grey productName: Better Sweater Jacket suppliedBy: customer sizes: - size: L quantity: 6 decorations: - method: SP locationCode: FF size: width: 10 height: 12 inks: - name: White pms: WHITE artUploadId: upl_7Hq2Xk9Lm3Np8Rs4Tv6Wy1Za5Bc0De2F lineRefs: - L1 - L2 expectedTotal: '412.50' responses: '202': description: Success. headers: X-Request-Id: description: Id of this call. Quote it when you contact us. schema: type: string content: application/json: schema: $ref: '#/components/schemas/OrderSubmission' example: submissionId: sub_4f8c2a7e9b1d3f5a7c9e1b3d5f7a9c1e status: accepted order: orderId: ord_0123456789abcdef0123456789 orderNumber: '00058817' status: pending_approval '400': description: >- A query parameter or body field is missing or invalid. `errors[]` lists each field. headers: X-Request-Id: description: Id of this call. Quote it when you contact us. schema: type: string content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.dekhq.com/api/partners/errors#invalid_request title: Invalid request status: 400 detail: >- A query parameter or body field is missing or invalid. `errors[]` lists each field. code: invalid_request requestId: req_0123456789abcdef '401': description: Missing or invalid credentials. headers: X-Request-Id: description: Id of this call. Quote it when you contact us. schema: type: string WWW-Authenticate: description: Basic realm="DEKHQ Partner API" schema: type: string content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.dekhq.com/api/partners/errors#unauthenticated title: Unauthenticated status: 401 detail: Missing or invalid credentials. code: unauthenticated requestId: req_0123456789abcdef '403': description: Your credential is not enabled for the scope this endpoint needs. headers: X-Request-Id: description: Id of this call. Quote it when you contact us. schema: type: string content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.dekhq.com/api/partners/errors#forbidden title: Forbidden status: 403 detail: >- Your credential is not enabled for the scope this endpoint needs. code: forbidden requestId: req_0123456789abcdef '409': description: >- This `Idempotency-Key` was already used with a different body. Send the original body to get the original answer, or a new key for a new order. headers: X-Request-Id: description: Id of this call. Quote it when you contact us. schema: type: string content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: >- https://docs.dekhq.com/api/partners/errors#idempotency_conflict title: Idempotency conflict status: 409 detail: >- This `Idempotency-Key` was already used with a different body. Send the original body to get the original answer, or a new key for a new order. code: idempotency_conflict requestId: req_0123456789abcdef '413': description: The request body is larger than this endpoint accepts. headers: X-Request-Id: description: Id of this call. Quote it when you contact us. schema: type: string content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.dekhq.com/api/partners/errors#payload_too_large title: Payload too large status: 413 detail: The request body is larger than this endpoint accepts. code: payload_too_large requestId: req_0123456789abcdef '422': description: >- The request is well formed but the order cannot be placed as sent. `errors[]` names each field and why: `not_supported_yet` for something this API does not take yet, `total_changed` when `expectedTotal` is not the current total (`currentTotal` carries it). `detail` says what to change. headers: X-Request-Id: description: Id of this call. Quote it when you contact us. schema: type: string content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.dekhq.com/api/partners/errors#order_refused title: Order refused status: 422 detail: >- The request is well formed but the order cannot be placed as sent. `errors[]` names each field and why: `not_supported_yet` for something this API does not take yet, `total_changed` when `expectedTotal` is not the current total (`currentTotal` carries it). `detail` says what to change. code: order_refused requestId: req_0123456789abcdef '429': description: More than the allowed requests per minute. headers: X-Request-Id: description: Id of this call. Quote it when you contact us. schema: type: string Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.dekhq.com/api/partners/errors#rate_limited title: Rate limited status: 429 detail: More than the allowed requests per minute. code: rate_limited requestId: req_0123456789abcdef '500': description: An unexpected error on our side. It is logged; retry later. headers: X-Request-Id: description: Id of this call. Quote it when you contact us. schema: type: string content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.dekhq.com/api/partners/errors#internal title: Internal error status: 500 detail: An unexpected error on our side. It is logged; retry later. code: internal requestId: req_0123456789abcdef components: schemas: OrderSubmissionBody: type: object properties: orderName: type: string minLength: 1 maxLength: 200 description: Your name for the order, shown on it. shippingMethod: type: string enum: - ship - pickup description: >- `ship`: we ship the order to `shipTo` on our carrier account. `pickup`: you collect it from us; send no `shipTo`. shipTo: $ref: '#/components/schemas/SubmissionShipTo' description: >- Required when `shippingMethod` is `ship`; must be absent for `pickup`. requestedInHandsDate: type: string format: date description: The date you need the order in hand. lines: minItems: 1 maxItems: 50 type: array items: $ref: '#/components/schemas/SubmissionLine' decorations: minItems: 1 maxItems: 20 type: array items: $ref: '#/components/schemas/SubmissionDecoration' purchaseOrderNumber: type: string minLength: 1 maxLength: 64 pattern: ^[\x21-\x7E](?:[\x20-\x7E]*[\x21-\x7E])?$ description: >- Your PO number, stored exactly as you send it. Printable characters, no leading or trailing spaces, and no HTML tags or entities (`422 order_refused`). A PO you used before is accepted: retries are matched by `Idempotency-Key`, never by PO. inboundTracking: minItems: 1 maxItems: 20 type: array items: type: string pattern: ^[A-Za-z0-9 -]{6,60}$ description: >- Tracking numbers for the shipments bringing your garments to us. Each needs a digit and, without its spaces and dashes, 6 to 40 letters and digits; anything else is `422 order_refused` naming it. rush: description: >- Not supported yet: rush. Sending it gets 422 `order_refused` naming this field. proof: description: >- Not supported yet: a proof you supply. Sending it gets 422 `order_refused` naming this field. splitShip: description: >- Not supported yet: split shipping. Sending it gets 422 `order_refused` naming this field. individualShip: description: >- Not supported yet: individual shipping. Sending it gets 422 `order_refused` naming this field. finishing: description: >- Not supported yet: finishing services. Sending it gets 422 `order_refused` naming this field. packaging: description: >- Not supported yet: packaging services. Sending it gets 422 `order_refused` naming this field. notes: description: >- Not supported yet: order notes. Sending it gets 422 `order_refused` naming this field. expectedTotal: $ref: '#/components/schemas/Money' required: - orderName - shippingMethod - lines - decorations - expectedTotal additionalProperties: false description: >- An order to place. `expectedTotal` is the total from the preview; if it is no longer the total, the order is refused with `total_changed` and the current total. OrderSubmission: oneOf: - type: object properties: submissionId: type: string pattern: ^sub_[A-Za-z0-9]{1,64}$ description: The submission id. status: type: string const: accepted order: type: object properties: orderId: type: string pattern: ^ord_[A-Za-z0-9]{1,64}$ description: >- The order id, e.g. `ord_22699286ac3294327ea813dd8d`. Stable for the life of the order. orderNumber: description: Our order number, once assigned. type: - string - 'null' status: $ref: '#/components/schemas/OrderStatus' required: - orderId - orderNumber - status additionalProperties: false required: - submissionId - status - order additionalProperties: false - type: object properties: submissionId: type: string pattern: ^sub_[A-Za-z0-9]{1,64}$ description: The submission id. status: type: string const: refused problem: $ref: '#/components/schemas/Problem' required: - submissionId - status - problem additionalProperties: false - type: object properties: submissionId: type: string pattern: ^sub_[A-Za-z0-9]{1,64}$ description: The submission id. status: type: string const: received required: - submissionId - status additionalProperties: false description: >- A submitted order and what became of it. `received` means it is still being processed: poll it. Problem: type: object properties: type: type: string description: URI of the docs entry for this error code. title: type: string description: Short summary of the error code; the same for every occurrence. status: type: integer description: The HTTP status code. detail: type: string description: What went wrong in this request. code: type: string enum: - forbidden - idempotency_conflict - internal - invalid_request - not_found - order_refused - payload_too_large - rate_limited - unauthenticated - upload_refused description: Stable, machine-readable error code. errors: type: array items: $ref: '#/components/schemas/ProblemFieldError' description: The rejected fields, for `invalid_request` and `order_refused`. currentTotal: type: string pattern: ^\d{1,10}\.\d{2}$ description: >- With `order_refused` and a `total_changed` field error: the order's current total in US dollars, e.g. `1234.50`. Send it back as `expectedTotal` once you accept it. requestId: type: string description: >- The X-Request-Id of the call that produced this problem. Quote it when you contact us. A submission's stored refusal, replayed for its Idempotency-Key or a poll, keeps the id of the call that refused it. required: - type - title - status - detail - code - requestId additionalProperties: false description: An RFC 9457 problem (application/problem+json). SubmissionShipTo: type: object properties: firstName: type: string minLength: 1 maxLength: 100 description: The recipient's first name. lastName: type: string minLength: 1 maxLength: 100 description: The recipient's last name. company: type: string minLength: 1 maxLength: 200 description: The company at the address. address1: type: string minLength: 1 maxLength: 200 description: Street address. address2: type: string minLength: 1 maxLength: 200 description: Suite, unit or floor. city: type: string minLength: 1 maxLength: 100 description: City. region: type: string minLength: 1 maxLength: 100 description: State or province. postalCode: type: string minLength: 1 maxLength: 20 description: ZIP or postal code. country: type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2, e.g. `US`. phone: type: string minLength: 1 maxLength: 40 description: A phone number for the carrier. email: type: string minLength: 1 maxLength: 200 description: An email for delivery notices. required: - address1 - city - region - postalCode - country additionalProperties: false description: >- Where the order ships: any complete address. A first name or a company is required; an incomplete address is refused (422). SubmissionLine: type: object properties: ref: type: string pattern: ^[A-Za-z0-9_-]{1,32}$ description: Your id for this line, unique within `lines`. garment: anyOf: - $ref: '#/components/schemas/CatalogGarment' - $ref: '#/components/schemas/TextGarment' description: >- Exactly one of: our catalog ids (`styleId` + `colorId`), or all four text fields (`brand`, `styleNumber`, `colorName`, `productName`). Never both, never part of one. suppliedBy: type: string enum: - customer - decorator description: >- Who supplies the garments: `customer` (you send them to us) or `decorator` (we source them). Only `customer` is supported yet. sizes: minItems: 1 maxItems: 40 type: array items: type: object properties: size: type: string minLength: 1 maxLength: 20 description: A size the colour comes in, e.g. `M`. quantity: type: integer minimum: 1 maximum: 100000 description: How many of that size. required: - size - quantity additionalProperties: false clientSku: type: string minLength: 1 maxLength: 64 description: >- Your SKU for this line. Required when your account is set up to require it. required: - ref - garment - suppliedBy - sizes additionalProperties: false description: One garment line. SubmissionDecoration: type: object properties: method: type: string pattern: ^[A-Z_]{1,24}$ description: The decoration method. Only `SP` (screen print) is supported yet. locationCode: type: string pattern: ^[A-Za-z0-9_-]{1,32}$ description: The print location code, e.g. `FF` (full front). size: type: object properties: width: type: number exclusiveMinimum: 0 maximum: 100 description: Width in inches. height: type: number exclusiveMinimum: 0 maximum: 100 description: Height in inches. required: - width - height additionalProperties: false description: The print size in inches (the artwork, not the garment). inks: minItems: 1 maxItems: 9 type: array items: type: object properties: name: type: string minLength: 1 maxLength: 60 description: The ink colour's name, e.g. `White`. pms: type: string minLength: 1 maxLength: 40 description: Its Pantone (PMS) code, e.g. `295 C`, or `WHITE` / `BLACK`. required: - name - pms additionalProperties: false description: >- Each ink colour. A colour outside our stock inks is priced as a custom PMS colour. artUploadId: type: string pattern: ^upl_[A-Za-z0-9]{1,64}$ description: The id of an upload you finalized. lineRefs: minItems: 1 maxItems: 50 type: array items: type: string pattern: ^[A-Za-z0-9_-]{1,32}$ description: Your id for this line, unique within `lines`. description: The `ref` of each line this decoration goes on. stitchFileUploadId: description: >- Not supported yet: stitch files (embroidery). Sending it gets 422 `order_refused` naming this field. required: - method - locationCode - size - inks - artUploadId - lineRefs additionalProperties: false description: One decoration, on one or more lines. Money: type: string pattern: ^\d{1,10}\.\d{2}$ description: US dollars as a decimal string with exactly two places, e.g. `1234.50`. OrderStatus: type: string enum: - draft - pending_approval - approved - in_production - shipped - delivered - cancelled description: >- Where the order is. `shipped` and `delivered` are distinct; `cancelled` is final. ProblemFieldError: type: object properties: field: type: string description: >- Dotted path of the field, e.g. `lines.0.quantity`, or the query parameter name. code: type: string description: >- Why the field was rejected, e.g. `invalid_type`, `too_small`, `unrecognized_keys`, `not_supported_yet`, `total_changed`. required: - field - code additionalProperties: false description: One rejected field. CatalogGarment: type: object properties: styleId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: The catalog colour id; it must belong to the style. colorId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: The catalog colour id; it must belong to the style. required: - styleId - colorId additionalProperties: false description: A garment in our catalog, by id. TextGarment: type: object properties: brand: type: string minLength: 1 maxLength: 100 pattern: \S description: The brand, e.g. `Patagonia`. styleNumber: type: string minLength: 1 maxLength: 60 pattern: \S description: The brand's style number. colorName: type: string minLength: 1 maxLength: 100 pattern: \S description: The colour, as the brand names it. productName: type: string minLength: 1 maxLength: 200 pattern: \S description: The product name, e.g. `Better Sweater Jacket`. required: - brand - styleNumber - colorName - productName additionalProperties: false description: >- A garment you supply that is not in our catalog, described in your words. We never match it to our catalog: it is decorated exactly as described. No HTML tags or entities (`422 order_refused`). securitySchemes: basicAuth: type: http scheme: basic description: Your DEKHQ partner `id` and `password`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.