Orders API

The Orders API allows you to create orders and retrieve order history for your account.

Get All Orders

GET/api/orders

Retrieves a list of all orders for your account.

Response

Response

[
  {
    "orderNumber": 1001,
    "orderDate": "2023-05-01T10:00:00Z",
    "status": "completed",
    "items": [
      {
        "product": {
          "displayName": "Microsoft Office 2021 Home & Business",
          "_id": "507f1f77bcf86cd799439011"
        },
        "quantity": 2,
        "price": 89.99,
        "subtotal": 179.98,
        "isReplacement": false,
        "licenses": [
          {
            "licenseKey": "ABCD-EFGH-IJKL-MNOP"
          },
          {
            "licenseKey": "QRST-UVWX-YZAB-CDEF"
          }
        ],
        "bundleLicenses": null
      }
    ],
    "subTotal": 179.98,
    "discountPercentage": null,
    "discountAmount": 20.00,
    "discountType": 0,
    "discountTotal": 20.00,
    "grandTotal": 179.98,
    "paymentMethod": "N/A",
    "orderFrom": 2
  }
]

Request

curl -X GET https://api.attivita.de/api/orders \
  -H "Authorization: Bearer YOUR_API_ACCESS_TOKEN"

Get Order by Number

GET/api/orders/:orderNumber

Retrieves details of a specific order.

Parameters

Parameter	Type	Required	Description
orderNumber	number	Yes	The order number

Response

The response format is identical to a single order object from the "Get All Orders" endpoint.

Create Order

POST/api/orders

Creates a new order with automatic discount application.

Request Body

Request Body

{
  "products": [
    {
      "productId": "507f1f77bcf86cd799439011",
      "amount": 2
    },
    {
      "productId": "507f191e810c19729de860ea",
      "amount": 1
    }
  ]
}

cURL

curl -X POST https://api.attivita.de/api/orders \
  -H "Authorization: Bearer YOUR_API_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "productId": "507f1f77bcf86cd799439011",
        "amount": 2
      }
    ]
  }'

JavaScript

const order = {
  products: [
    {
      productId: "507f1f77bcf86cd799439011",
      amount: 2
    }
  ]
};

const response = await fetch('https://api.attivita.de/api/orders', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(order)
});

const result = await response.json();

Response

Success Response

{
  "customer": 7,
  "orderNumber": 1002,
  "orderDate": "2023-05-02T11:00:00Z",
  "status": "completed",
  "items": [
    {
      "product": "Microsoft Office 2021 Home & Business",
      "quantity": 2,
      "price": 89.99,
      "isReplacement": false,
      "licenses": [
        {
          "licenseKey": "ABCD-EFGH-IJKL-MNOP"
        },
        {
          "licenseKey": "QRST-UVWX-YZAB-CDEF"
        }
      ],
      "bundleLicenses": null,
      "productId": "507f1f77bcf86cd799439011"
    }
  ],
  "subTotal": 179.98,
  "discountTotal": 20.00,
  "grandTotal": 179.98,
  "paymentMethod": "N/A",
  "orderFrom": 2
}

Error - Out of Stock

{
  "error": "Some products are not available",
  "unavailableItems": [
    {
      "productId": "507f1f77bcf86cd799439011",
      "productName": "Microsoft Office 2021",
      "requestedQuantity": 10,
      "availableQuantity": 5
    }
  ]
}

Error - Credit Limit

{
  "error": "You have reached your credit limit. For assistance, please reach out to our support team."
}

Important Notes

Automatic Discounts

Customer-specific discounts are automatically applied during order creation. The price field shows the final discounted price.

German VAT

For German customers, 19% VAT is automatically added to the order total.

Credit Limits

Orders that exceed your credit limit will be rejected. Contact support to increase your limit.

Order Response Fields

Field	Type	Description
orderNumber	number	Unique order identifier
orderDate	string	ISO 8601 timestamp
status	string	Order status (completed/pending/failed)
items	array	Order line items
items[].product	string/object	Product name or details
items[].quantity	number	Quantity ordered
items[].price	number	Final price per unit (after discounts)
items[].licenses	array	License keys (for digital products)
items[].bundleLicenses	array|null	Bundle license details grouped by pool (only for bundle products, see below)
items[].productId	string	Product identifier
subTotal	number	Total before discounts
discountTotal	number	Total discount amount
grandTotal	number	Final total (including VAT if applicable)

Bundle Products

When ordering a bundle product (isBundle: true), the response includes a bundleLicenses array that groups licenses by their respective license pool. This allows you to see which license belongs to which component of the bundle.

Bundle Order Response Example

{
  "items": [
    {
      "product": "Office + Antivirus Bundle",
      "quantity": 1,
      "price": 129.99,
      "licenses": [
        { "licenseKey": "ABCD-EFGH-IJKL-MNOP" },
        { "licenseKey": "QRST-UVWX-YZAB-CDEF" }
      ],
      "bundleLicenses": [
        {
          "licensePoolId": "507f1f77bcf86cd799439011",
          "poolName": "Office 2021 Pool",
          "productName": "Microsoft Office 2021",
          "licenses": [
            { "licenseKey": "ABCD-EFGH-IJKL-MNOP" }
          ]
        },
        {
          "licensePoolId": "507f191e810c19729de860ea",
          "poolName": "Antivirus Pool",
          "productName": "Norton Antivirus",
          "licenses": [
            { "licenseKey": "QRST-UVWX-YZAB-CDEF" }
          ]
        }
      ],
      "productId": "60d5ec49f1b2c72d9c8b4567"
    }
  ]
}

Bundle License Fields

Field	Type	Description
bundleLicenses[].licensePoolId	string	License pool identifier
bundleLicenses[].poolName	string	Name of the license pool
bundleLicenses[].productName	string	Display name of the pool's product
bundleLicenses[].licenses	array	License keys allocated from this pool

Bundle Stock

For bundle products, stock availability is determined by the minimum available licenses across all linked pools. If any pool runs out, the bundle is unavailable.

Testing with Sandbox Mode

You can test order creation without affecting production by using Sandbox Mode:

curl -X POST https://api.attivita.de/api/orders \
  -H "Authorization: Bearer YOUR_API_ACCESS_TOKEN" \
  -H "X-Sandbox-Mode: true" \
  -H "Content-Type: application/json" \
  -d '{"products": [{"productId": "...", "amount": 1}]}'

Next Steps

• Learn about Sandbox Mode for safe testing
• Set up Webhooks for order notifications
• Read about Error Handling