Creating an Order in the Courier Service

This method is used to create a delivery order in the courier service's information system. When an order is ready for shipment in the Gold Apple IS, the IS sends a request containing information about the sender, recipient, delivery parameters, and shipment contents. The order number is used as the tracking number. The tracking number makes it possible to track the order and retrieve its related statuses. The status model is presented in the corresponding directory, see Appendix: Order Status Directory. The endpoint must be published over the secure HTTPS protocol.

Basic Information

Request method type	POST
Path / URL	/api/v1/orders
Description	Method for sending an order from the Gold Apple IS to the courier service's IS
Direction	The request is executed by the Gold Apple IS. The response is provided by the courier service.

Request

Header Parameters

Parameter	Data type	Required	Description	Comment
Authorization	string	1	Access token obtained during authorization. Passed in the format Bearer <access_token>	The format is defined by the courier service (see Authorization in the ECS Service)
content-type	string	1	Request content type	Filled in as "application/json"

Request Parameters

№	Parameter			Type	Required	Description	Comment
1	orderNumber			string	1	Gold Apple order number	Internal order number in the Gold Apple IS. Tracking number.
2	deliveryServiceCode			string	1	Courier service code	Agreed upon during system integration.
3	courierTariffCode			string	1	ECS tariff code	Agreed upon during system integration.
4	isOrderFirstSend			boolean	1	Initial submission flag	Fill-in rule: if the order is being created for the first time, set "true" if the order was corrected or re-uploaded (even without corrections), set "false"
5	isOrderModified			boolean	1	Flag indicating whether the order contents have changed	Fill-in rule: if isOrderFirstSend = false AND the order composition was changed, set "true" if isOrderFirstSend = false AND the order composition was NOT changed, set "false" if isOrderFirstSend = true, do not send this field
6	needCustomerNotification			boolean	1	Flag for sending notifications from the ECS side.	Fill-in rule: if the flag is set to true, send customer notifications by any method available to the ECS's IS if the flag is set to false, no notifications from the ECS are sent at all
7	senderName			string	1	Sender name	Example: "Gold Apple Yekaterinburg LLC"
8	shippingWarehouse			object	1	Object with information about the sending warehouse
9		code		string	1	Internal Gold Apple warehouse code	Gold Apple warehouse code. Example: "225"
10		manager		string	0	Warehouse manager	Full name in free-form string form.
11		phone		string	0	Warehouse manager's phone	No special characters, digits only (country code and area code)
12	locationFrom			object	1	Sender's parcel address object
13		Address object type		object	1	Object containing address information.	Address object (see Appendix: Address Data Types)
14	recipient			object	1	Object with information about the recipient
15		name		string	1	Recipient's full name, free-form string	Example: Ivanov Ivan Ivanovich
16		phone		string	1	Recipient's phone	No special characters, digits only (country code and area code)
17		email		string	0	Recipient's email	In email format per the generalized "ISO 27000"
18	pickpointId			string	1 – if delivery to a PP 0 – if door delivery	Courier service PP code	Passed if delivery is made to a pickup point (PP)
19	locationTo			object	1 – if door delivery 0 – if delivery to a PP	Recipient's parcel address	Passed if delivery is made by courier to the customer's address
20		Address object type		object	1	Object containing address information.	Address object (see Appendix: Address Data Types)
21	package			array of objects	1	Array of shipment objects
22		barcode		string	1	Parcel barcode	Example: "M-095359727A"
23		weight		integer	1	Total package weight (in grams)	Example: "1000"
24		length		decimal	1	Package dimensions. Length (in cm)	Example: "20"
25		width		decimal	1	Package dimensions. Width (in cm)	Example: "15"
26		height		decimal	1	Package dimensions. Height (in cm)	Example: "18"
27		isPartialBuy		boolean	1	Flag indicating whether partial purchase is allowed for the package	Set to true if the parcel may not be purchased in full (partially)
28		isTryOnAllowed		boolean	1	Flag indicating whether the package may be tried on	Set to true if the parcel may be given for try-on
29		totalAmount		decimal	1	Price of the parcel's items (delivery not included)	Example: "222.43"
30		declaredAmount		decimal	1	Declared value of the parcel (delivery not included)	Example: "252.43"
31		paymentAmount		decimal	1	Amount payable for the parcel's items
32		courierComment		string	0	Additional instructions for handling the package	Partial delivery prohibited! Unboxing prohibited!
33		items		array of objects	1	Array of item objects in the parcel
34			name	string	1	Item name	Example: "DARLING Hydrating Restoring Sheet Mask"
35			warekey	string	1	Item SKU	Example: "19000181104"
36			quantity	integer	1	Quantity of identical items (pcs)	Example: 3
37			weight	number	1	Item weight (in grams)	Example: 200
38			isPartialBuy	boolean	1	Flag indicating whether partial purchase is allowed for the item	Set to true if only part of the item batch may be purchased
39			isTryOnAllowed	boolean	1	Flag indicating whether the item may be tried on	Set to true if the item may be given for try-on
40			priceAmount	decimal	1	Total price of a single item unit	Price of one item unit. Example: 562.1
41			declaredAmount	decimal	1	Declared value of a single item unit	Declared value of one item unit. Example: 564.5
42			paymentAmount	decimal	1	Amount payable per item unit If the order is prepaid, value = 0 If the order has not been paid for, value > 0	2449.67
43			vatRate	integer	1	VAT rate included in the item price	The rate is specified per 1 item unit. Example: 20
44			vatSum	decimal	1	VAT amount on post-payment of the order (per unit)	112.4
45	shipmentDate			date	1	Shipment date	Per the "ISO 8601" standard. Format: YYYY-MM-DDTHH:mm:ssZ
46	shipmentTimeIntervalFrom			date	0	Start of shipment interval	Per the "ISO 8601" standard. Format: HH:mm
47	shipmentTimeIntervalTo			date	0	End of shipment interval	Per the "ISO 8601" standard. Format: HH:mm
48	deliveryDate			date	1	Delivery date	Per the "ISO 8601" standard. Format: YYYY-MM-DDTHH:mm:ssZ
49	deliveryTimeIntervalFrom			date	1	Start of delivery interval	Per the "ISO 8601" standard. Format: HH:mm
50	deliveryTimeIntervalTo			date	1	End of delivery interval	Per the "ISO 8601" standard. Format: HH:mm
51	deliveryPaymentAmount			object	1	Delivery service cost object
52		declaredAmount		decimal	1	Declared value of the delivery	Declared value of delivery, passed by the Gold Apple IS
53		paymentAmount		decimal	1	Amount payable for delivery services
54		vatRate		integer	0	VAT rate for the delivery service
55		vatSum		decimal	1	VAT amount for the delivery service
56		displayedAmount		decimal	1	Delivery charge displayed to the customer	Delivery cost for the end user, displayed at checkout
57	orderPaymentAmount			object	1	Order cost object
58		declaredAmount		decimal	1	Declared value of the order	The declared value for the entire order. Example: 1200
59		totalAmount		decimal	1	Total order cost	Total order amount. Example: 1000
60		amountToCollect		decimal	1	Amount to collect from the customer	Example: 500; if no payment is collected, then 0. To determine the exact cash-on-delivery amount, this field's value must be used
61		currency		string	1	Currency	Per the "ISO 4217" standard
62	returnWarehouse			object	0	Return warehouse address object
63		code		string	0	Internal Gold Apple warehouse code	Gold Apple warehouse code. Example: "225"
64		Address object type		object	0	Object containing address information.	Address object (see Appendix: Address Data Types)

Request example

{
  "orderNumber": "IAQ-126543",
  "deliveryServiceCode": "EXAMPLE_CS",
  "courierTariffCode": "123",
  "isOrderFirstSend": true,
  "isOrderModified": false,
  "needCustomerNotification": false,
  "senderName": "Gold Apple Yekaterinburg LLC",
  "shippingWarehouse": {
    "code": "225",
    "manager": "Sidorov S.S.",
    "phone": "79123456780"
  },
  "locationFrom": {
    "addressType": "gar",
    "fullAddress": "214014, Smolensk Region, Smolensk, Example St., 7",
    "regionFias": "ed36085a-b2f5-454f-b9a9-1c9a678ee618",
    "cityFias": "2763c110-cb8b-416a-9dac-ad28a55b4402",
    "houseFias": "395bc31a-9fda-4804-a01b-13d79c15e3cb",
    "flat": "54",
    "latitude": 58.0167,
    "longitude": 56.235,
    "addressComment": "entrance from the courtyard"
  },
  "recipient": {
    "name": "Ivanov Ivan Ivanovich",
    "phone": "79999999999",
    "email": "ivan.ivanov@gmail.com"
  },
  "pickpointId": null,
  "locationTo": {
    "addressType": "coord",
    "fullAddress": "614054, Perm, 1st Example St., 5",
    "cityFias": "2763c110-cb8b-416a-9dac-ad28a55b4402",
    "latitude": 58.0167,
    "longitude": 56.235,
    "flat": "5",
    "addressComment": "call on arrival"
  },
  "package": [
    {
      "barcode": "M-095359727A",
      "weight": 1000,
      "length": 20,
      "width": 15,
      "height": 18,
      "isPartialBuy": true,
      "isTryOnAllowed": false,
      "totalAmount": 540.00,
      "declaredAmount": 600.00,
      "courierComment": "Partial delivery prohibited! Unboxing prohibited!",
      "items": [
        {
          "name": "DARLING Hydrating Restoring Sheet Mask",
          "warekey": "123434623",
          "quantity": 3,
          "weight": 200,
          "isPartialBuy": false,
          "isTryOnAllowed": true,
          "priceAmount": 180.0,
          "declaredAmount": 200.0,
          "vatRate": 20,
          "vatSum": 10.0
        }
      ]
    }
  ],
  "shipmentDate": "2025-04-06T00:00:00Z",
  "shipmentTimeIntervalFrom": "08:00",
  "shipmentTimeIntervalTo": "10:00",
  "deliveryDate": "2025-04-07T00:00:00Z",
  "deliveryTimeIntervalFrom": "10:00",
  "deliveryTimeIntervalTo": "18:00",
  "deliveryPaymentAmount": {
    "declaredAmount": 45.00,
    "displayedAmount": 39.90
  },
  "orderPaymentAmount": {
    "declaredAmount": 645.00,
    "totalAmount": 579.90,
    "amountToCollect": 0.00,
    "vatSum": 100.00,
    "currency": "RUB"
  },
  "returnWarehouse": {
    "code": "333",
    "addressType": "coord",
    "fullAddress": "191014, Saint Petersburg, Example St., 7",
    "cityFias": "2763c110-cb8b-416a-9dac-ad28a55b4402",
    "latitude": 59.791517,
    "longitude": 30.120332,
    "flat": null,
    "addressComment": "return warehouse, ask for the shift supervisor"
  }
}

Response

Response Codes and Messages

Code	Status	Message	Reason
200	OK	Order has been created	Everything completed successfully. The order was created in the courier service's IS
400	Bad Request	Missing or inappropriate required parameters	Required parameters are missing or invalid. The response body must list the names of the fields that failed validation, in an arbitrary string format.
401	Unauthorized	Token is invalid	Authentication error at the courier service
403	Forbidden	Has no permission	Insufficient permissions
500	Internal Server Error	Server unavailable	The server is unavailable

Successful Response Parameters

Parameter	Data type	Required	Description	Comment
ecsOrderNumber	string	1	Order identifier in the courier service	Delivery order number assigned in the courier service's IS.
orderNumber	string	1	Gold Apple order number sent in the request	Internal order number in the Gold Apple IS. Tracking number
createdAt	date	1	Date and time the order was registered	Per the "ISO 8601" standard, UTC0 (YYYY-MM-DDThh:mm:ssZ)

Successful response example

{
  "ecsOrderNumber": "f91ae5a4-3b1c-4e7a-8c29-72b1db2025a1",
  "orderNumber": "IAQ-126543",
  "createdAt": "2025-05-10T10:41:22Z"
}

Unsuccessful Response Parameters

Parameter	Data type	Required	Description
errorMessage	string	1	Human-readable description of the error
errorCode	string	0	see Appendix: Error Code Directory

Unsuccessful response example

{
  "errorMessage": "Missing or inappropriate required parameters",
  "errorCode": "Addr_01"
}