AMv2 FAQ's

Modified on Fri, 25 Nov 2022 at 10:36 AM

Assure Magic V2 FAQs

Technology

Are there any rate limiting applicable for AssureMagic2 APIs?

  • Yes, AssureMagic2 supports rate limiting. We can set custom values for the number of API calls that can hit AssureMagic2 in one minute. By default it is set to 200 API calls per minute.  

Are there any time out in AssureMagic2 APIs?

  • Yes, AssureMagic2 APIs gets timed out after 45 seconds.

Does AssureMagic2 support FTP?

  • No, only REST APIs

Can AssureMagic2 refresh the Client’s API credentials?

  • No, AssureMagic2 cannot refresh a client's API credentials. It only supports static credentials for authentication.

If 2 clients are in same instance, will the posting queue be the same?

  •     No, we maintain separate queue for each client.


Masters

What is a partner and partner location code for Assure?

  • Partners can either be of the type Supplier or of the type Customer.. Assure support multiple locations of suppliers and customers, hence all partners have at least one Partner Location.

Why is partner / partner location code required for Assure, What is the significance of Partners and Partner Locations in Assure?

  • Partners and their locations are used to identify the sources and destination of inward as well as outward orders. Partner and Partner Location information is also used within generated internal invoices. 

What happens on duplicate create requests for Customers and Vendors (Partners)?

  • Duplicate calls to create Customers and Vendors (Partners) are idempotent. No changes will be made to the existing Customers or Vendors and a 200-OK response will be sent by the API 

Is Partner Location creation mandatory and what to do if we don't have partner location code?

If you don't have PartnerLocation codes at your end then two approaches can be followed:

  1. Use a single, constant Location Code for all the Vendors

  2. Set the Location Code same as the Vendor code

What are the meanings of address(partner), billing(partnerLocation) and shipping address(partnerLocation) of partner and partner locations?

  • The Partner’s Address represents the geographic location of a Partner’s headquarters
  • The Partner’s Location has two aspects - the billing address and the shipping address. The address that the Partner desires to use for billing and shipping purposes must be specified in the Partner’s billing and shipping address data. These three addresses might or might not be the same

What are the unique fields (primary key) in partner and partner location creation?

  • For Partner, the name and partnerType values must be unique across all partners.
    For Partner Location, no unique constraints exist.

What if GSTIN is not available for partner location creation?

  • The GSTIN field is a mandatory field. A value must be provided for this field

What happens on duplicate Create requests with the same master data and sku attribute? (Applicable to all type of masters, SKU Attributes)

  • The calls made for creation of product masters are idempotent meaning that if duplicate requests are sent, no change will be made. Therefore, if the product master data was successfully saved after the first call, subsequent duplicate calls will have no impact on the data. Each duplicate call will result in a 200-OK response. 

What happens on duplicate Requests with the same master data and different sku attribute? (Applicable to all type of masters,SKU Attributes)

  • If different attribute data is passed for a specific product master using the create-article-master API endpoint, the SKU attributes will not be updated to the latest passed value. 
  • However, when using the add-or-update-SKU-attributes API endpoint, the SKU Attribute Data from the latest successful call will be saved for the specified product master, i.e. the SKU attributes will be updated. 

What if ERP is not able to send Tax code?

  • Assure is a WMS module, hence Clients should never rely on Assure to compute accurate taxation. This is ERP’s responsibility. So in case ERP is not able to send correct tax code for each sku, it can use a default value GIVEN that in such case Assure tax computation will never be used.  

What if ERP is capable of sending the tax breakup ? 

  • During packing, the Assure system can fetch the tax breakup from Order Source.

What if ERP is not able to send the Image URL?

  • The image URL is not a mandatory field and it may be left blank. 

  • If the image URL is absent or incorrect, the image of the product won’t be displayed on WMS screens. This will affect picking, packing and all QC related operations.

  • Image URLS can also be updated using the product data updation API or from Assure UI.

Note: The image URL must be a string under 255 characters

How to update an existing SKU master?

  • The SKU Masters can be updated using the updateArticleMaster endpoint (assuming that the listing for that product is present). OR Product master can also be updated from Assure OMS UI. 

Can ERP create marketplace listing/mapping using AssureMagic2?

  • No, this feature is not available at the moment.


Order Interface

Create Outward Order

What is the difference between Order with and without Partner Codes?

  • All B2B orders along with vendor/customer codes are placed through Order with Partner Code API, whereas all the B2C orders are placed through Order without Partner Codes API. 

What are the unique fields(Primary Keys) for order creation?
Check OMS, CIMS

  • Location code and same channel order Id are unique for one set of external credentials ( indicating the Marketplace / ERP). 

What is the difference between OrderItem Code and ChannelSKU Code?

  • Channel SKU Code is the unique identifier for an SKU the Marketplace / ERP whereas, OrderItem Code is the unique identifier for an order line item.
  • Note: Two order line items can have the same ChannelSKU Code, but no two line items can have the same Order Item Code.

Can we pass EAN in the channelSkuCode/orderItemCode field when creating order?

  • EAN can be passed in the ChannelSKU code field during order creation if and only if both are the same, and were mapped as the same during the Article Master Creation process in Assure.
  • EAN can be passed  as the Order Item Code during order creation if and only if there is only one order line item (with ‘n’ quantity)  of the same EAN in the order. This will ensure no two order line items have the same Order Item Code.

What are the fields we can update for existing orders?

  • Channel Order Status, Required By Time, Start Processing Time and On Hold(updating to false only) property of an existing outward order can be updated.

Can we cancel/update an existing Inward order?

  • Cancellation / Updation of an Inward order once placed is not allowed.

What if the same call for order cancellation / creation / update order properties is made twice to AssureMagic2?

  • Success will be returned with no action performed in ASSURE.

What if a different request with duplicate channelOrderIds is made?

  • Success will be returned as Order with the same channel Order Id would have been already existing in ASSURE and duplicate order will not be created in ASSURE.

Can line Items be appended once the order is created in the system?

  • No.

What is the purpose of on-hold and Start Processing Time fields of an order in ASSURE?

  • An order with on hold value as true will be created in ASSURE but will not be moved to ASSURE WMS for processing. 
  • An order will be moved to ASSURE WMS for processing once the real time exceeds or equals the Start Processing Time of the order and order is not on hold.

Can we set the value of on-hold as TRUE after the order is placed?

  •  No.

What does Order with QC status : Fail mean?

  • Order with QC status Fail indicates that only the inventory marked as QC Fail in ASSURE will be allocated to the order. Generally QC fail orders are used for liquidation of QC fail inventory from the warehouse. All marketplace outward orders are QC pass only.

What if Marketplace doesn't support Seller Cancellation?

  • Upon doing seller cancellations from OMS UI, an error will be thrown indicating the channel does not support seller cancellation. 

What enums are applicable for inward / outward orders during order creation ? 


Enums

Inward Order

Outward Order

PO

Purchase Order

Not Applicable

RTV

Not Applicable

Return To Vendor

SO

Not Applicable

Customer Sales Order

RO

B2B Customer Return Order

Not Applicable(Currently RO/RTV are interchangeably used)

RPO

Not Applicable

Replacement Order

STO

Stock Transfer Order

Stock Transfer Order


How B2B return, RTV , STO is created and which APIs and Enums to use?

  • Refer to the above table.


Why is the order Ack call not instantaneous?

  • While sending an order, a 200 OK response means that we have received the order. So it is already instantaneous in that sense.
  • An ACK call back to you means we can process it. For this our system has to allocate inventory. Since we are designed for multi-channel order processing, we have to put orders in a queue and allocate inventory to them in FIFO order. This would obviously mean that it cannot be instantaneous"

Push Customer Cancellation

What fields Assure considers for partial customer cancellation?

  • Assure cancels the order line Item based on the Order Item Code. The cancelled quantity is  passed in the order cancellation request to ASSURE against the Order Item Code. 
  • ASSURE cancels the entire order if the cancelled quantity for all line items equal the ordered quantity.


Order Posting from Assure 

What are the triggers for order posting from Assure?

Order posting is triggered on the following events:

  • Order completion(When order is marked as handover) 

  • Cancellation of order.

  • Creation of order(This will have both fulfillable and unfulfillable orders)

GRN Interface

What are the trigger points for GRN Posting Order Wise?

  • When the order is marked as completed then this GRN posting is triggered.

What are the trigger points for GRN Posting Gate Entry Wise?

  • When the gate entry is marked as completed then this GRN posting is triggered.

What are the trigger points for GRN notifications?

  • When item status is marked as GRN and associated with a bin post that depending on the frequency of GRN sync to ERP the updates are sent at an order level.

Is the frequency configurable for GRN notification?

  • GRN sync time frequency can be changed on request to Assure customer success team.

What is the max line Item in one GRN notification message?

  • At maximum the number of line items in GRN notification requests can be 5000.

Are the message Ids unique across postings or specifically for posting of one kind?

  • All message Ids shared across postings of all kinds are unique.
  • Same message IDs can be created when request is success on ERP end and fails on Omni end(due to timeouts or any other error)so Omni retries to sync the same API call again to and passes the message ID for identification at ERP end to mark the call as duplicate. 
  • Please check if this deduplication logic is implemented at your end.

Shipment Interface

At what stage pack order call is triggered?

  • Pack call is triggered when items are on the packing desk in the warehouse.

What are the different mandatory APIs required to be implemented for B2B vs B2C orders?

  • In case of B2C invoice and shipping label APIs are mandatory. For B2B order both invoice and shipping label flows APIs are optional.

What If there is only one document for invoice and shipping label?

  • In this case the document URLs in both invoice and shipping label details API response will be the same. Assure Magic will call for documents only once.

What if the shipping label url is not present, especially in case of B2b order?

  • In the case of B2C order shipping, label flow is compulsory. For B2B orders shipping label flow is not compulsory.

What is the expected response when a manifest is called with the same and different payload?

  • In case a manifest is already created on the client side and Assure magic makes the same payload request again, then the manifest code already generated with success 200 HTTP status code should be sent in response. In case of different payloads a new manifest code should be generated corresponding to the new manifest.

When is the handover call triggered?

  • Handover call is triggered when shipments are being handed over to the courier partner in the warehouse. This is the last step in the forward order cycle.

Will the postings be sent for the OMS UI uploaded orders in ASSURE?

  • Order posting is only sent for orders created from Assure Magic or other channels and not for orders uploaded from OMS UI.

What will be the partnerCode and partnerLocation code for B2c orders?

  • In Assure there is a default customer that gets created against every client. The B2C orders for the client get created in Assure against this default customer.


Returns Order Interface

What is the trigger for return order posting?

  • When return processing is completed in Assure and return order status is completed then return sync to ERP is triggered.

Inventory Interface


In Inventory update call what is the difference between an error being thrown and Failure List ?

  • Failure list is used to convey that Inventory update for these many SKUs was not successful. This might occur when SKUs sent in the payload are not present in the client's system(Marketplace/ERP).
  • But in case of Error, it could be Bad_Data or Internal Server Error.

In Inventory get calls how to use channelSkuCode and pageNumber fields ?

  • In this API call, we can accommodate Get requests for any number of channelSkuCodes. PageNumber field denotes the range in which these required channelSkuCode will be searched in. If pageNumber is 1 then 1 to 10,000 records of the inventory will be searched and matched inventory will come in the response body. If you want to search records from 10,000 to 20,000 SKU then pageNumber can be sent as 2 and so on. Response body has one field named as ‘hasMore’ which denotes if there are more pages in response or not. If you are searching for pageNumber 1 and few channelSkuCodes were found in the next 10,000 to 20,000 then hasMore will be TRUE.


Why is there a batching of calls? What scenario requires batching ?

It is an industry standard to use batching wherever possible. 

  1. This reduces no. of calls,

  2. Improves scalability

  • We try to build things for scale. Imagine receiving 10000 orders per hour. If we sequentially respond to every single order, and one call takes 100 ms, then without batching it would take a long time to send acks for all orders.
  • This in turn can result in your order processing pipelines to get delayed (e.g. sending confirmation mails to customers, booking AWB nos. etc) 
  • Companies like Amazon also follow the same mechanism for their EDI integrations and we've followed the best industry practice over here"

Why is the batch processing accumulated if one batch fails and why subsequent batches are not processed?

If we cannot trust a system for 1 batch then it cannot be trusted for other batches also. The simple reason is that there are no guarantees that subsequent batches won't fail. If one cannot give a guarantee, then effectively, we are asking a computer system to keep trying other batches and "hopefully" some of them will succeed.


Such a system would also be complex to develop. There would be many considerations to make:

  1. What strategy would be used to retry the failed batch? Exponential backoff, fixed delay, fixed rate?

  2. How long (hours, days) should the system keep retrying for a failed batch ? 

  3. What happens when there are too many failed batches? Because, eventually you would reach a point where you have too many failed batches, and those batches would themselves become a bottleneck for "good" batches. Because retrying for bad batches would delay good batches.

  4. What happens if we stop retrying after 2-3 days, and then you fix the system at your end? How do you develop a mechanism to re-activate those batches? How do you develop a mechanism to authorize retries of such batches? Who will authorize it ? Client or Increff? How do you automate such a process?

  5. How would you develop a "measure" of success of this mechanism? Is < 1% batch failure rate acceptable? 0.1% etc.



How is Inventory Synching Ensured b/w Assure and  ERP?

B2C Scenario


B2B Scenario






Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select atleast one of the reasons

Feedback sent

We appreciate your effort and will try to fix the article