Yalo Studio

AddOns for Partners - Creating an Order

Suggest Edits

Creating an Order

INSTEAD

  • WHEN TO USE
    You need to use this add-on when you need to create an order in a Partner System.

  • ADDING TO MY COMMERCE (TECH)

    mutation CreateAddOn($data: AddOnInput!, $storefrontName: String!) {
  createAddOn(data: $data, storefrontName: $storefrontName) {
    id
    type
    config
    status
    callback
  }
}

    We will are have {
  "data": {
    "type": "CREATE_ORDER" || "CREATE_ORDERS",
    "flavor": "REST",
		"config": {
			"method": "POST",  
			"url": "https://www....",
			"authMethod": "BASIC",
			"token": "string",
			"headers": {},
			"updateCart": false,
			"updatePrice": false
	   },
    "executionTime": "INSTEAD"
  },
  "storefrontName": "STOREFRONTNAME"
}

  • DATA SENT TO THE ADD-ON (TECH)

    This would be the payload sent to the endpoint at the time an order confirmation is made from the commerce ecosystem:

    {
	"args":{
	  "sessionUId": string,
	  "storefrontName": string
	},
	"artifacts": {
		"session":{
	    "id": string,
	    "customerUid": string,
	    "customerAlias": string, // this is the value used to validate session on session create
	    "cartUid": string,
	    "configuration": {
	      // configuration give by storefront object in commerce
	    }
	    "startedAt": string,
	    "finishedAt": string,
	    "status": string,
	    "customFields": object,
	    "createdAt": date,
	    "updatedAt": date
	  },
		"orders": []
	}
]

    Description of the data sent in the payload:

    NameTypeDescription
    args.sessionUIdstringThe ID of the customer session
    args.storefrontNamestringThe name configured for the storefront
    artifacts.session.idstringThe ID of the session
    artifacts.session.customerUidstringThe customer ID in the headless system
    artifacts.session.cartUidstringThe cart ID generated in the headless system
    artifacts.session.statusstringThe status of the session can be
    ACTIVE
    FINISHED
    EXPIRED
    artifacts.order.idstringThe identifier for the order generated in the headless system
    artifacts.order.customerCodestringThe identifier for the customer
    artifacts.order.sessionUidstringThe identifier for the session
    artifacts.order.itemsArrayAn array of items that the order contains
    artifacts.order.statusstringThe status of the order can be:
    CREATED
    PROCESSED
    CANCELLED
    CONFIRMED
    artifacts.order.totalfloatThe total amount of the order

    Depending on the configuration saved in the splitter of orders (StoreFront splitter order configuration) there are the types of add-ons that are used:

    • CREATE_ORDER
      In the scenario that the store has turned OFF or does not have the order separation options configured: you must implement the addOn type CREATE_ORDER which the order field will return a single order object. 
      {
	...
	"artifacts": {
		...
		"order": {
			"id": string,
			"customerCode": string,
			"storeCode": string,
			"sessionUid": string,
			"items": [
			  ...
				{
					"sku": string,
					"quantity": integer,
					"price": float,
					"name": string,
					"brand": string,
					"imageURL": Array<string>,
					"description": string,
					"packageType": string,
					"unitDivision": string,
					"unitsPerPackage": integer,
					"divisionsByUnit": string,
					"attributes": Array<string>
				}
				...
			]
			"status": string,
			"processedAt": date,
			"notes": string,
			"total": float,
			"createdAt": date,
			"updatedAt": date
		}
	}
}
    • CREATE_ORDERS
      In the scenario that the store has turned ON or does have the order separation options configured: you must implement the addOn type CREATE_ORDERS which the order field will return a single order object. 
      {
	...
	"artifacts": {
		...
		"order": [
			{
				"id": string,
				"customerCode": string,
				"storeCode": string,
				"sessionUid": string,
				"items": [
				  ...
					{
						"sku": string,
						"quantity": integer,
						"price": float,
						"name": string,
						"brand": string,
						"imageURL": Array<string>,
						"description": string,
						"packageType": string,
						"unitDivision": string,
						"unitsPerPackage": integer,
						"divisionsByUnit": string,
						"attributes": Array<string>
					}
					...
				]
				"status": string,
				"processedAt": date,
				"notes": string,
				"total": float,
				"createdAt": date,
				"updatedAt": date
			},
			{
				"id": string,
				"customerCode": string,
				"storeCode": string,
				"sessionUid": string,
				"items": [
				  ...
					{
						"sku": string,
						"quantity": integer,
						"price": float,
						"name": string,
						"brand": string,
						"imageURL": Array<string>,
						"description": string,
						"packageType": string,
						"unitDivision": string,
						"unitsPerPackage": integer,
						"divisionsByUnit": string,
						"attributes": Array<string>
					}
					...
				]
				"status": string,
				"processedAt": date,
				"notes": string,
				"total": float,
				"createdAt": date,
				"updatedAt": date
			}
			...
		]
	}
}

  • RESPONSE STRUCT NEEDED FROM ADD-ON (TECH)
    After processing the information of the order collected from Commerce with the Partner System, it’s mandatory to update the same data of the order/orders sent in the order field, remember that there were two options to receive the data (StoreFront splitter order configuration), one is a simple order (unique object) or with a collection of orders (array).
    After doing an external information manipulation process, it is necessary to return the following payload:
    For CREATE_ORDER:

    {
	"id": string,
	"items": [
        ...
				{
					"id": string,
					"sku": string, // required
					"quantity": integer, // required
					"price": float, // required
				}
				...
	    ],
	  "total": float, // required
	  "externalOrderUid": string // required
}

    For CREATE_ORDERS:

    [
	{
		"id": string,
		"items": [
			...
					{
					"id": string,
					"sku": string, // required
					"quantity": integer, // required
					"price": float, // required
				}
					...
			],
		  "total": float, // required
		  "externalOrderUid": string // required
	},
	....
]
    💡 For the definition of the properties of an item, you can see the table [here](https://www.notion.so/e0dd669687a64223a8190caeef4f9fbf?pvs=21). This response is an array of products `externalOrderUid` It can be any unique value of type string that allows having a hard relationship (ID) that allows making a relationship between the data of the order and the data that will be processed by the Partner System

  • EXTRA PROCESSING

    1. An order is created on headless system prior to sending it to add on
    2. After the answer to the add will check total, prices and quantity are ok and update the order in headless
    3. If the order is different than the one stored in the database, the order gets canceled, except if update flags (updateCart or updatePrice) are enabled in add on config
    4. In case the callBack option is turned on, the externalRefStatus field is updated with the PROCESSING value of status still with CREATED

    AFTER

    • WHEN TO USE
      You need to use this add-on when you perform an action with the other created
      In the event that the AddOn has the callback option turned ON, it will be possible to access the mutation with the same name that will proceed to receive the data that is received as a response from the Partner System

    • ADDING TO MY COMMERCE (TECH)

      mutation OrderCallback($data: OrderData!, storefrontName: $storefrontName, externalOrderUid: $externalOrderUid) {
  orderCallback(data: $data, storefrontName: $storefrontName, externalOrderUid: $externalOrderUid) {
    externalOrderUid
		externalRefNumber
		externalMessage
    externalErrorMessage
    externalRefStatus
		items
		total
  }
}

    • RESPONSE STRUCT NEEDED FROM ADD-ON (TECH)

      The data sent to process the response from the partner system is as follows:

      {
    "externalOrderUid": string,
    "externalRefNumber": string,
    "externalMessage": string,
    "externalErrorMessage": string,
    "externalRefStatus": string,
    "items": {
			"id": string,
			"sku": string, // required
			"quantity": integer, // required
			"price": float, // required
		},
    "total": float
}
      NameTypeDescription
      externalOrderUidStringReference number with which the relationship is made between the data that is stored in the Commerce environment and with the partner system
      externalRefNumberStringAfter the processing of the client's system, a reference or confirmation ID can be stored after the process carried out by the system
      externalMessageStringIn the event that the information has been processed correctly with the partner system, it is required to save a message if the client's system so wishes.
      externalErrorMessageStringIn case of an error message, this field is required in order to identify the reason why an error was generated in the partner system.
      externalRefStatusStringThe status of the order can be:
      CONFIRMED
      REJECTED
      ERROR
      TIMEOUT
      itemsObjectThe list of items, in case the system makes any changes
      totalnumberIf the total has been modified by the system

    • EXTRA PROCESSING

      1. Update the information in the external fields with the information
      2. If the externalRefStatus field is CONFIRMED the status of the order will remain as CONFIRMED
      3. If the externalRefStatus field is not equal to CONFIRMED, the status will be an ERROR

Updated 11 months ago