Documentation for Product Stock Update via Soulmkt Marketplace API (V1 and V2)
This documentation is designed to guide you step-by-step through the process of updating product stock in a Soulmkt Marketplace store using APIs V1 and V2. Even if you are not familiar with the process, this detailed explanation will help you understand how to perform the task.
1. Introduction
The Soulmkt Marketplace provides two API versions (V1 and V2) to interact with the system and perform operations such as stock updates. Both versions use the SOAP protocol (Simple Object Access Protocol) to send and receive data in XML format.
Here, we will explain how to update product stock using APIs V1 and V2, with XML request examples that can be submitted through tools like Postman.
2. Prerequisites
Before starting, make sure you have the following:
- Access to the Soulmkt API: You will need access credentials (username and password) to obtain a sessionId required to authenticate requests.
- Product Identifier: The SKU (Stock Keeping Unit) or ID of the product you want to update.
- Request Submission Tool: We recommend using Postman or any other tool that allows sending SOAP requests.
3. Step-by-Step: Updating Product Stock
3.1. Getting the sessionId
Before performing any API operation, you must obtain a sessionId to authenticate your requests. This is done through a login call to the API.
Example Login Request:
XML
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:OpenMage"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:login>
<username xsi:type="xsd:string">User</username>
<apiKey xsi:type="xsd:string">Password</apiKey>
</ns1:login>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Response:
If the login is successful, you will receive a sessionId in the following format:
XML
<SOAP-ENV:Envelope>
<SOAP-ENV:Body>
<ns1:loginResponse>
<result xsi:type="xsd:string">1234567890abcdef1234567890abcdef</result>
</ns1:loginResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>Keep this sessionId to use in future requests.
3.2. Updating Stock via API V2
The Soulmkt V2 API uses a more straightforward structure to update a product’s stock. Below is an example of how to do this.
Example Stock Update Request (API V2):
XML
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:OpenMage"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SOAP-ENV:Body>
<ns1:catalogInventoryStockItemUpdate>
<sessionId xsi:type="xsd:string">1234567890abcdef1234567890abcdef</sessionId>
<product xsi:type="xsd:string">product-sk123</product>
<data xsi:type="ns1:catalogInventoryStockItemUpdateEntity">
<qty xsi:type="xsd:string">50</qty>
<is_in_stock xsi:type="xsd:int">1</is_in_stock>
</data>
</ns1:catalogInventoryStockItemUpdate>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>Field Explanation:
- sessionId: The authentication token obtained in the previous step.
- product: The SKU or ID of the product to be updated.
- data: Contains the stock data, including quantity and availability.
- qty: The new stock quantity (e.g., 50 units).
- is_in_stock: Indicates if the product is in stock (1 for yes, 0 for no).
Response:
If the update is successful, you will receive a response like:
XML
<SOAP-ENV:Envelope>
<SOAP-ENV:Body>
<ns1:catalogInventoryStockItemUpdateResponse>
<result xsi:type="xsd:boolean">true</result>
</ns1:catalogInventoryStockItemUpdateResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>3.3. Updating Stock via API V1
The V1 API uses a slightly different structure, where the stock data is passed in map format.
Example Stock Update Request (API V1):
XML
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:OpenMage"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SOAP-ENV:Body>
<ns1:call>
<sessionId xsi:type="xsd:string">1234567890abcdef1234567890abcdef</sessionId>
<resourcePath xsi:type="xsd:string">product_stock.update</resourcePath>
<args SOAP-ENC:arrayType="xsd:ur-type[2]" xsi:type="SOAP-ENC:Array">
<item xsi:type="xsd:string">product-sk123</item>
<item xsi:type="ns2:Map">
<item>
<key xsi:type="xsd:string">qty</key>
<value xsi:type="xsd:string">50</value>
</item>
<item>
<key xsi:type="xsd:string">is_in_stock</key>
<value xsi:type="xsd:int">1</value>
</item>
</item>
</args>
</ns1:call>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>Field Explanation:
- sessionId: The authentication token obtained in the previous step.
- resourcePath: The API resource path to be called (product_stock.update).
- args: A list of arguments where:
- The first item is the SKU or ID of the product.
- The second item is a map containing the fields to be updated (in this case, quantity and availability).
Response:
If the update is successful, you will receive a response like:
XML
<SOAP-ENV:Envelope>
<SOAP-ENV:Body>
<ns1:callResponse>
<result xsi:type="xsd:boolean">true</result>
</ns1:callResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>4. Final Considerations
- Testing: Always test your requests in a development environment before applying them in production.
- Common Errors: Make sure the sessionId is valid and that the product SKU is correct. Authentication failures or incorrect SKUs are the most common causes of errors.
- Tools: Use tools like Postman to simplify sending and viewing request responses.
With this documentation, you are ready to update product stock in the Soulmkt Marketplace using APIs V1 and V2. If you have any questions, contact the support team.
Note: The data used in the examples is fictitious and should be replaced with actual values from your environment.