Understanding orders and how to create them using Propeller REST API

What is an Order in Propeller Commerce?

An order in Propeller Commerce is a comprehensive record that details a customer's purchase, including product details, pricing, shipping, and payment information. The order API in Propeller Commerce exposes endpoints for creating, updating, searching, and managing orders.

Key Components of an Order

1. Basic Details:

   • Order ID: Unique identifier for the order.
   • Status: Current status of the order (e.g., pending, shipped).
   • User Details: Information about the customer placing the order, such as user ID, name, and email.

2. Order Items:

   • Product Details: Each order can have multiple items, each with details like product ID, name, quantity, price, and SKU.

3. Shipping Information:

   • Shipping Address: Address to which the order should be shipped.
   • Shipping Method: Method of shipment (e.g., standard, express).

4. Payment Information:

   • Payment Method: Method used for payment (e.g., credit card, PayPal).
   • Payment Status: Status of the payment (e.g., paid, pending).

5. Additional Information:

   • Remarks: Any additional notes or remarks related to the order.
   • Reference: External reference ID for the order.

How to Import Orders

To import orders into the Propeller Commerce system, you typically use the Create Order endpoint via a POST request. Here's a step-by-step guide:

1. Authentication:
   The REST API uses the oAuth 2.0 client credentials grant type for authentication, every API requests needs a valid access token. Request an access token by executing a POST request to the token endpoint. This POST request should include the Client Id and Client Secret. Parse the access_token value and use it as a bearer token to interact with the Propeller API.

2. Endpoint:
   Use the POST https://api.helice.cloud/api/g/v2/orders/ endpoint to create a new order.

3. Example Payload:

{
  "accountingId": "",
  "channelId": 1,
  "clientData": {
    "contact": {
      "source": "MsBusinessCentral",
      "sourceId": "contact-1234"
    }
  },
  "date": "2023-03-03T13:10:45",
  "invoiceData": {
    "address": {
      "city": "Arnhem",
      "code": "11234",
      "company": "Propel",
      "country": "NL",
      "email": "miles@propel.us",
      "firstName": "Miles",
      "gender": "U",
      "icp": "N",
      "lastName": "McCoy",
      "middleName": "",
      "mobile": "0038975648",
      "notes": "Address notes",
      "number": "34",
      "numberExtension": "A",
      "phone": "0032445888",
      "postalCode": "6822 DE",
      "region": "",
      "street": "Noordpad",
      "url": "www.propel.us"
    }
  },
  "items": [
    {
      "quantity": 2,
      "sku": "411544",
      "type": "product"
    }
  ],
  "language": "EN",
  "merchantCost": 4.9,
  "reference": "reference text",
  "remarks": "remarks text",
  "shippingData": {
    "address": {
      "city": "Arnhem",
      "code": "11234",
      "company": "Propel",
      "country": "NL",
      "email": "miles@propel.us",
      "firstName": "Miles",
      "gender": "U",
      "icp": "N",
      "lastName": "McCoy",
      "middleName": "",
      "mobile": "0038975648",
      "notes": "Address notes",
      "number": "34",
      "numberExtension": "A",
      "phone": "0032445888",
      "postalCode": "6822 DE",
      "region": "",
      "street": "Noordpad",
      "url": "www.propel.us"
    }
  },
  "source": "MsBusinessCentral",
  "sourceId": "order-123478",
  "status": "NEW",
  "total": {
    "discountAmount": 5
  },
  "trackTraceCode": ""
}

4. Send the Create Order Request:
   Send the POST request using an HTTP client (e.g., cURL, Postman).

Example cURL command for creating an order:

curl -X POST 'https://api.helice.cloud/api/g/v2/orders/' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
  "accountingId": "",
  "channelId": 1,
  "clientData": {
    "contact": {
      "source": "MsBusinessCentral",
      "sourceId": "contact-1234"
    }
  },
  "date": "2023-03-03T13:10:45",
  "invoiceData": {
    "address": {
      "city": "Arnhem",
      "code": "11234",
      "company": "Propel",
      "country": "NL",
      "email": "miles@propel.us",
      "firstName": "Miles",
      "gender": "U",
      "icp": "N",
      "lastName": "McCoy",
      "middleName": "",
      "mobile": "0038975648",
      "notes": "Address notes",
      "number": "34",
      "numberExtension": "A",
      "phone": "0032445888",
      "postalCode": "6822 DE",
      "region": "",
      "street": "Noordpad",
      "url": "www.propel.us"
    }
  },
  "items": [
    {
      "quantity": 2,
      "sku": "411544",
      "type": "product"
    }
  ],
  "language": "EN",
  "merchantCost": 4.9,
  "reference": "reference text",
  "remarks": "remarks text",
  "shippingData": {
    "address": {
      "city": "Arnhem",
      "code": "11234",
      "company": "Propel",
      "country": "NL",
      "email": "miles@propel.us",
      "firstName": "Miles",
      "gender": "U",
      "icp": "N",
      "lastName": "McCoy",
      "middleName": "",
      "mobile": "0038975648",
      "notes": "Address notes",
      "number": "34",
      "numberExtension": "A",
      "phone": "0032445888",
      "postalCode": "6822 DE",
      "region": "",
      "street": "Noordpad",
      "url": "www.propel.us"
    }
  },
  "source": "MsBusinessCentral",
  "sourceId": "order-123478",
  "status": "NEW",
  "total": {
    "discountAmount": 5
  },
  "trackTraceCode": ""
}'

5. Handle the Response
   Upon a successful request, the API will return the created order’s details, including a unique order ID. Handle the response to confirm that the order was created successfully.

Additional Resources

For detailed information, refer to the Propeller Commerce Order API Documentation. This includes complete descriptions of all fields, error codes, and additional endpoints for managing orders.

By following this guide, you can efficiently create and manage orders using the Propeller Commerce API.