Add/Update Order

Implement an HTTP server endpoint that allows Talk2sync to create or update a sales order in an external data store, database, or application.

The endpoint receives the complete order object, performs the corresponding INSERT/UPDATE operation, and returns either the resulting order or a structured error response.

Request

The endpoint must accept a POST request using the following format:

POST https://www.example.com/your/endpoint/url?jobid=123&id=75554554546
T2SKey: {{API KEY}}

The request body contains the complete sales order to be created or updated:

{
  "_id": "75554554546",
  "orderid": "75554554546",
  "last_updated": 1517360038797,
  "status": "paid",
  "dateCreated": "",
  "dateClosed": "",
  "total": {
    "amount": 350,
    "currency": "USD"
  },
  "orderItems": [
    {
      "id": "7778545",
      "variation_id": "0",
      "quantity": 1,
      "unitPrice": 350,
      "currencyId": "USD"
    }
  ],
  "buyer": {
    "id": "4578889",
    "email": "testbuyer@example.com",
    "phone": "88888888",
    "firstName": "John",
    "lastName": "Doe",
    "billingaddress": {
      "addressline": "",
      "zipcode": "",
      "city": "",
      "state": "",
      "country": ""
    },
    "shipmentaddress": {
      "addressline": "",
      "zipcode": "",
      "city": "",
      "state": "",
      "country": ""
    }
  },
  "shipments": [
    {
      "id": "123",
      "shiptracknum": "TRK-1203912",
      "shipitems": ["4578889"],
      "shiptype": "Fedex",
      "shipstatus": "shipping"
    }
  ],
  "rating": 2.5,
  "feedback": "",
  "messages": [
    {
      "message_id": "",
      "date_created": 0,
      "from": "",
      "message": ""
    }
  ]
}

Request Parameters

  • jobid: Identifies the synchronization job associated with the operation.
  • id: Identifies the sales order being created or updated.
  • T2SKey: API key used to authenticate the request.
  • Request body: Contains the complete sales order data.

Successful Response

If the INSERT/UPDATE operation succeeds, the endpoint must return the resulting order using the following structure:

{
  "success": true,
  "code": 200,
  "warnings": [],
  "order": {
    "_id": "75554554546",
    "orderid": "75554554546",
    "last_updated": 1517360038797,
    "status": "paid",
    "dateCreated": "",
    "dateClosed": "",
    "total": {
      "amount": 350,
      "currency": "USD"
    },
    "orderItems": [
      {
        "id": "7778545",
        "variation_id": "0",
        "quantity": 1,
        "unitPrice": 350,
        "currencyId": "USD"
      }
    ],
    "buyer": {
      "id": "4578889",
      "email": "testbuyer@example.com",
      "phone": "88888888",
      "firstName": "John",
      "lastName": "Doe",
      "billingaddress": {
        "addressline": "",
        "zipcode": "",
        "city": "",
        "state": "",
        "country": ""
      },
      "shipmentaddress": {
        "addressline": "",
        "zipcode": "",
        "city": "",
        "state": "",
        "country": ""
      }
    },
    "shipments": [
      {
        "id": "123",
        "shiptracknum": "TRK-1203912",
        "shipitems": ["4578889"],
        "shiptype": "Fedex",
        "shipstatus": "shipping"
      }
    ],
    "rating": 2.5,
    "feedback": "",
    "messages": [
      {
        "message_id": "",
        "date_created": 0,
        "from": "",
        "message": ""
      }
    ]
  }
}

A successful response contains:

  • success: Indicates whether the operation succeeded.
  • code: HTTP-style result code. A successful operation returns 200.
  • warnings: Contains any non-blocking warnings generated during the operation.
  • order: Contains the resulting sales order after the INSERT/UPDATE operation.

Error Response

If the operation cannot be completed, the endpoint must return a structured error response:

{
  "success": false,
  "code": 400,
  "error": "Could not upsert sales order",
  "reasons": [
    {
      "msg": "Invalid blank SKU"
    },
    {
      "msg": "Invalid SKU"
    },
    {
      "msg": "Invalid 0 quantity"
    },
    {
      "msg": "Invalid business partner"
    },
    {
      "msg": "Invalid status"
    }
  ],
  "warnings": []
}

The error response contains:

  • success: Indicates that the operation failed.
  • code: Result code. A failed operation returns 400.
  • error: General description of the operation failure.
  • reasons: List of specific validation or processing errors.
  • warnings: Contains any warnings generated during the operation.

Possible Error Reasons

The provided examples include the following validation errors:

  • Invalid blank SKU
  • Invalid SKU
  • Invalid 0 quantity
  • Invalid business partner
  • Invalid status

Next Steps

Last Updated: