orderCreate

Creates a new order. By default orders are created in DRAFT state. Pass state: OPENED to skip the draft step and immediately submit for fulfillment.

Required scope: create_orders

Mutation

graphql

mutation OrderCreate($input: OrderInput!) {
  orderCreate(input: $input) {
    id
    externalReference
    invoiceNumber
    state
    lines {
      id
      sku
      quantity
    }
  }
}

Input: `OrderInput`

Field	Type	Required	Description
`organizationId`	String	✅	Organization UUID the order belongs to
`externalReference`	String	❌	Your system's order ID — must be unique per `tpAppId`
`invoiceNumber`	String	❌	Invoice number for accounting
`type`	OrderTypeEnum	❌	`B2C` or `B2B`
`dispatchingType`	OrderDispatchingTypeEnum	❌	`AUTOMATIC` (default) or `MANUAL`
`priority`	PriorityEnum	❌	`LOW`, `NORMAL` (default), or `HIGH`
`state`	OrderStateEnum	❌	`DRAFT` (default) or `OPENED`
`inventoryPolicy`	InventoryPolicyEnum	❌	`DENY` (default), `ALLOW`, `SKIP`, or `ADJUST`
`total`	Float	❌	Order total excluding tax
`totalTaxInclusive`	Float	❌	Order total including tax
`totalShipping`	Float	❌	Shipping cost
`currency`	String	❌	ISO 4217 currency code (e.g. `EUR`, `USD`)
`issuedAt`	DateTime	❌	Date the order was issued in your system
`delivery`	DeliveryInput	❌	Delivery address and contact details
`lines`	[OrderLineInput!]	✅	Order lines — at least one required
`comment`	String	❌	Free-text comment visible to warehouse operators

DeliveryInput

Field	Type	Required	Description
`type`	DeliveryTypeEnum	❌	`PERSON` (home delivery) or `RELAY_POINT`
`fullname`	String	❌	Recipient full name
`email`	String	❌	Recipient email address
`address`	String	❌	Street address line 1
`addressComplement`	String	❌	Street address line 2 (apartment, suite, etc.)
`zipcode`	String	❌	Postal / ZIP code
`city`	String	❌	City
`country`	String	❌	ISO 3166-1 alpha-2 country code (e.g. `FR`, `US`)
`phone`	String	❌	Recipient phone number

OrderLineInput

Field	Type	Required	Description
`label`	String	❌	Human-readable product name
`sku`	String	✅	Stock-Keeping Unit identifier
`quantity`	Int	✅	Quantity ordered (must be > 0)
`price`	Float	❌	Unit price excluding tax
`vatRate`	Float	❌	VAT rate as a decimal (e.g. `0.2` for 20%)
`total`	Float	❌	Line total excluding tax
`totalTaxInclusive`	Float	❌	Line total including tax

Example Variables

json

{
  "input": {
    "organizationId": "org_123",
    "externalReference": "EXT-2024-001",
    "invoiceNumber": "INV-2024-001",
    "type": "B2C",
    "dispatchingType": "AUTOMATIC",
    "priority": "NORMAL",
    "state": "DRAFT",
    "inventoryPolicy": "DENY",
    "total": 59.98,
    "totalTaxInclusive": 71.98,
    "totalShipping": 5.99,
    "currency": "EUR",
    "issuedAt": "2024-01-15T10:30:00Z",
    "delivery": {
      "type": "PERSON",
      "fullname": "John Doe",
      "email": "john.doe@example.com",
      "address": "123 Main Street",
      "addressComplement": "Apt 4B",
      "zipcode": "75001",
      "city": "Paris",
      "country": "FR",
      "phone": "+33612345678"
    },
    "lines": [
      {
        "label": "Classic T-Shirt - Small Blue",
        "sku": "TSHIRT-S-BLUE",
        "quantity": 2,
        "price": 29.99,
        "vatRate": 0.2,
        "total": 59.98,
        "totalTaxInclusive": 71.98
      }
    ],
    "comment": "Please leave at door if not home"
  }
}

Example Response

json

{
  "data": {
    "orderCreate": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "externalReference": "EXT-2024-001",
      "invoiceNumber": "INV-2024-001",
      "state": "DRAFT",
      "lines": [
        {
          "id": "line-uuid-001",
          "sku": "TSHIRT-S-BLUE",
          "quantity": 2
        }
      ]
    }
  }
}

Code Examples

bash

curl -X POST https://api-v3.happycolis.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "query": "mutation OrderCreate($input: OrderInput!) { orderCreate(input: $input) { id externalReference state lines { id sku quantity } } }",
    "variables": {
      "input": {
        "organizationId": "org_123",
        "externalReference": "EXT-2024-001",
        "invoiceNumber": "INV-2024-001",
        "type": "B2C",
        "dispatchingType": "AUTOMATIC",
        "priority": "NORMAL",
        "state": "DRAFT",
        "inventoryPolicy": "DENY",
        "total": 59.98,
        "totalTaxInclusive": 71.98,
        "totalShipping": 5.99,
        "currency": "EUR",
        "issuedAt": "2024-01-15T10:30:00Z",
        "delivery": {
          "type": "PERSON",
          "fullname": "John Doe",
          "email": "john.doe@example.com",
          "address": "123 Main Street",
          "addressComplement": "Apt 4B",
          "zipcode": "75001",
          "city": "Paris",
          "country": "FR",
          "phone": "+33612345678"
        },
        "lines": [
          {
            "label": "Classic T-Shirt - Small Blue",
            "sku": "TSHIRT-S-BLUE",
            "quantity": 2,
            "price": 29.99,
            "vatRate": 0.2,
            "total": 59.98,
            "totalTaxInclusive": 71.98
          }
        ],
        "comment": "Please leave at door if not home"
      }
    }
  }'

const mutation = `
  mutation OrderCreate($input: OrderInput!) {
    orderCreate(input: $input) {
      id
      externalReference
      state
      lines {
        id
        sku
        quantity
      }
    }
  }
`;

const variables = {
  input: {
    organizationId: 'org_123',
    externalReference: 'EXT-2024-001',
    invoiceNumber: 'INV-2024-001',
    type: 'B2C',
    dispatchingType: 'AUTOMATIC',
    priority: 'NORMAL',
    state: 'DRAFT',
    inventoryPolicy: 'DENY',
    total: 59.98,
    totalTaxInclusive: 71.98,
    totalShipping: 5.99,
    currency: 'EUR',
    issuedAt: '2024-01-15T10:30:00Z',
    delivery: {
      type: 'PERSON',
      fullname: 'John Doe',
      email: 'john.doe@example.com',
      address: '123 Main Street',
      addressComplement: 'Apt 4B',
      zipcode: '75001',
      city: 'Paris',
      country: 'FR',
      phone: '+33612345678',
    },
    lines: [
      {
        label: 'Classic T-Shirt - Small Blue',
        sku: 'TSHIRT-S-BLUE',
        quantity: 2,
        price: 29.99,
        vatRate: 0.2,
        total: 59.98,
        totalTaxInclusive: 71.98,
      },
    ],
    comment: 'Please leave at door if not home',
  },
};

const response = await fetch('https://api-v3.happycolis.com/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.ACCESS_TOKEN}`,
  },
  body: JSON.stringify({ query: mutation, variables }),
});

const { data } = await response.json();
console.log(data.orderCreate);

python

import os
import requests

mutation = """
mutation OrderCreate($input: OrderInput!) {
  orderCreate(input: $input) {
    id
    externalReference
    state
    lines {
      id
      sku
      quantity
    }
  }
}
"""

variables = {
    "input": {
        "organizationId": "org_123",
        "externalReference": "EXT-2024-001",
        "invoiceNumber": "INV-2024-001",
        "type": "B2C",
        "dispatchingType": "AUTOMATIC",
        "priority": "NORMAL",
        "state": "DRAFT",
        "inventoryPolicy": "DENY",
        "total": 59.98,
        "totalTaxInclusive": 71.98,
        "totalShipping": 5.99,
        "currency": "EUR",
        "issuedAt": "2024-01-15T10:30:00Z",
        "delivery": {
            "type": "PERSON",
            "fullname": "John Doe",
            "email": "john.doe@example.com",
            "address": "123 Main Street",
            "addressComplement": "Apt 4B",
            "zipcode": "75001",
            "city": "Paris",
            "country": "FR",
            "phone": "+33612345678",
        },
        "lines": [
            {
                "label": "Classic T-Shirt - Small Blue",
                "sku": "TSHIRT-S-BLUE",
                "quantity": 2,
                "price": 29.99,
                "vatRate": 0.2,
                "total": 59.98,
                "totalTaxInclusive": 71.98,
            }
        ],
        "comment": "Please leave at door if not home",
    }
}

response = requests.post(
    'https://api-v3.happycolis.com/graphql',
    headers={'Authorization': f'Bearer {os.environ["ACCESS_TOKEN"]}'},
    json={'query': mutation, 'variables': variables},
)

data = response.json()['data']
print(data['orderCreate'])

php

<?php
$mutation = <<<'GQL'
mutation OrderCreate($input: OrderInput!) {
  orderCreate(input: $input) {
    id
    externalReference
    state
    lines {
      id
      sku
      quantity
    }
  }
}
GQL;

$variables = [
    'input' => [
        'organizationId'    => 'org_123',
        'externalReference' => 'EXT-2024-001',
        'invoiceNumber'     => 'INV-2024-001',
        'type'              => 'B2C',
        'dispatchingType'   => 'AUTOMATIC',
        'priority'          => 'NORMAL',
        'state'             => 'DRAFT',
        'inventoryPolicy'   => 'DENY',
        'total'             => 59.98,
        'totalTaxInclusive' => 71.98,
        'totalShipping'     => 5.99,
        'currency'          => 'EUR',
        'issuedAt'          => '2024-01-15T10:30:00Z',
        'delivery' => [
            'type'              => 'PERSON',
            'fullname'          => 'John Doe',
            'email'             => 'john.doe@example.com',
            'address'           => '123 Main Street',
            'addressComplement' => 'Apt 4B',
            'zipcode'           => '75001',
            'city'              => 'Paris',
            'country'           => 'FR',
            'phone'             => '+33612345678',
        ],
        'lines' => [
            [
                'label'             => 'Classic T-Shirt - Small Blue',
                'sku'               => 'TSHIRT-S-BLUE',
                'quantity'          => 2,
                'price'             => 29.99,
                'vatRate'           => 0.2,
                'total'             => 59.98,
                'totalTaxInclusive' => 71.98,
            ],
        ],
        'comment' => 'Please leave at door if not home',
    ],
];

$ch = curl_init('https://api-v3.happycolis.com/graphql');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode(['query' => $mutation, 'variables' => $variables]),
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'Authorization: Bearer ' . getenv('ACCESS_TOKEN'),
    ],
]);

$result = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($result['data']['orderCreate']);

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	mutation := `
		mutation OrderCreate($input: OrderInput!) {
			orderCreate(input: $input) {
				id
				externalReference
				state
				lines {
					id
					sku
					quantity
				}
			}
		}`

	variables := map[string]any{
		"input": map[string]any{
			"organizationId":    "org_123",
			"externalReference": "EXT-2024-001",
			"invoiceNumber":     "INV-2024-001",
			"type":              "B2C",
			"dispatchingType":   "AUTOMATIC",
			"priority":          "NORMAL",
			"state":             "DRAFT",
			"inventoryPolicy":   "DENY",
			"total":             59.98,
			"totalTaxInclusive": 71.98,
			"totalShipping":     5.99,
			"currency":          "EUR",
			"issuedAt":          "2024-01-15T10:30:00Z",
			"delivery": map[string]any{
				"type":              "PERSON",
				"fullname":          "John Doe",
				"email":             "john.doe@example.com",
				"address":           "123 Main Street",
				"addressComplement": "Apt 4B",
				"zipcode":           "75001",
				"city":              "Paris",
				"country":           "FR",
				"phone":             "+33612345678",
			},
			"lines": []map[string]any{
				{
					"label":             "Classic T-Shirt - Small Blue",
					"sku":               "TSHIRT-S-BLUE",
					"quantity":          2,
					"price":             29.99,
					"vatRate":           0.2,
					"total":             59.98,
					"totalTaxInclusive": 71.98,
				},
			},
			"comment": "Please leave at door if not home",
		},
	}

	body, _ := json.Marshal(map[string]any{
		"query":     mutation,
		"variables": variables,
	})

	req, _ := http.NewRequest("POST", "https://api-v3.happycolis.com/graphql", bytes.NewBuffer(body))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer "+os.Getenv("ACCESS_TOKEN"))

	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()

	var result map[string]any
	json.NewDecoder(resp.Body).Decode(&result)
	fmt.Println(result["data"])
}

orderCreate ​

Mutation ​

Input: OrderInput ​

DeliveryInput ​

OrderLineInput ​

Example Variables ​

Example Response ​

Code Examples ​