Marketful API allows the user to create, obtain, update and delete information regarding orders and products, through the use of request in JSON format.
General information:
White fields are generally understood as null or empty string instead of being omitted.
API Version | Updated at | V1 | 22/07/2019 |
---|
URL for production requests: https://fulfillment.marketful.mx/
The following headers are required.
Name | Description |
---|---|
Access_token | “Authorization”: Access_token, “User”: user_id |
user_id |
Create Multi Channel Fulfillments: Orders the Marketful team to fulfill an order from any sales channel.
POST /shopi_orders/multicanal_api
Name | Type | Methods | “POST” |
---|---|
Headers | “Authorization”: Access_token, “User”: user_id |
Body/Parameters | "order": {
"contact_info": contact_info, "items": items } |
Field | Description | Datatype | Required | num_orden | Unique order number. May be repeated for a same seller but not on the same seller and sales channel. | string | Yes |
---|---|---|---|
orden_id | Unique order number by seller | string | Yes |
customer | Order recipient name | string | Yes |
carrier_name | We accept Marketful, Fedex, DHL, UPS, Estafeta, Will_Call | string | Yes |
telefono | Recipient Telephone Number | string | Yes |
calle | Street of shipment address | string | Yes |
no_exterior | Exterior number of shipment address | string | Yes |
no_interior | Interior number of shipment address | string | No |
colonia | Colonia of shipment address | string | Yes |
ciudad | City of shipment address | string | Yes |
Estado | State of shipment address. Must be in format “MX-XX”: e.g. MX - AG, MX - BC, etc. You can find a complete list of 2 letter codes in https://en.wikipedia.org/wiki/Tem plate:Mexico_State- Abbreviation_Codes | string | Yes |
codigo_postal | Shipment zipcode | string | Yes |
canal | Sales Channel | string | Yes |
tipo_envio | We accept “económico” and “dia_siguiente” | string | Yes |
asegurado | true if you wish the shipment to be insured. false if not. In case field is sent blank or not sent, it will be false by default | boolean | No |
Get Fulfillments by order_id.
GET /shopi_orders/get_orders
Name | Type | Method | “GET” |
---|---|
Headers | “Authorization”: Access_token, “User”: user_id |
Body/Parameters | canal: “order channel”, orden: “order number” |
Field | Description | Datatype | Required | Authorization | Unique key / Token.. | string | Yes |
---|---|---|---|
User | Password / Token to identify the user. | string | Yes |
canal | The order channel you wish to get, eg "Shopify", "Marketful", etc. | string | Yes |
orden | The order number you want to get. Ex: "2554", "# 1254", etc. | string | Yes |
Answer Received | Case | Type | { "message": "Orden no encontrada" } | If the parameters (channel / order) are incorrect, or do not match any order | string |
---|---|---|
{ "message": "Seller not found" } | If any of the values of the {Headers (Authorization / User) is incorrect | string |
{ "message": "Invalid Token" } | If any of the headers are not sent or missing | string |
{ "message": "Canal y numero de orden deben existir" } | If any of the body parameters are not sent or missing (channel / order) | string |
To send their stocks to Marketful, sellers must tell Marketful what they are going to send to the warehouse before sending it. This Entry Order allows Marketful to validate the amounts received against what was supposed to be received.
POST /entradas/nueva_entrada_api
Name | Type | Method | “POST” |
---|---|
Headers | “Authorization”: Access_token, “User”: user_id |
Body/Parameters | "entry_order" : entry_order |
Field | Description | Datatype | Required | entry_order | It includes an object for each item that is added to the entry order, its value being the amount of stock to send. | object | Yes |
---|
Answer Received | Case | Type | status: 200 , json: { message: "Success", order_token: description: "Order created successfully", | Success | int |
---|---|---|
status: 401, json: { message: "The following items were not found or their inventory is less than or equal to zero", items: items_falsos, } | Some items do not exist or the inventory has a value less than 0 |
int |
status: 402, json: { message: "entry_order is null", } | The "entry_orden" parameter is not present | int |
status: 403, json: { message: "Parameter 'entry_order' must be present", } | The entry is not present in the order | int |
status: 400, json: { message: "User Not Found", } | User is not found | int |
status: 404, json: { message: "Invalid Authorization", } | The headers and parameters were not found | int |
Get back the current stock levels available for sale.
GET /items/get_stock
Name | Type | Method | “GET” |
---|---|
Headers | “Authorization”: Access_token, “User”: user_id |
Body/Parameters | "sku" :sku |
Field | Description | Datatype | Required | sku | Product identification code ex. “Bottle234543” | string | Yes |
---|
Answer Received | Case | Type | status: 200 , json: { message: "Success", sku: item.sku, avariable_quantity, | Success | int |
---|---|---|
status: 402, json: { message: "Item #{sku} not found", } | Item not found |
int |
status: 403, json: { message: "SKU must be present", } | Product SKU not found | int |
status: 403, json: { message: "User Not Found", } | User is not found | int |
status: 404, json: { message: "Invalid Authorization", } | The headers and parameters were not found | int |
Retrieves current stock levels available for sale.
GET /items/get_stock_ean
Name | Type | Método | “GET” |
---|---|
Headers | “Authorization”: Access_token, “User”: user_id |
Body/parameters | "ean": Codigo EAN |
Field | Description | Datatype | Required | ean | EAN product code ej. "07852236842" | String | Yes |
---|
Answer Received | Case | Type | status: 200 body: { message: "Success", ean: EAN, available_quantity: number, item_id: Item ID, |
Success | JSON |
---|---|---|
status: 401 body: { message: "Item con EAN '07852236842' no encontrado", } |
Item not found |
JSON |
status: 402 body: { message: "ean must be present and must be String", } |
CWhen the "ean" parameter is not being sent or has an incorrect format | JSON |
status: 403 body: { message: "User Not Found", } |
If any of the values of the Headers (Authorization / User) is incorrect | JSON |
status: 404 body: { message: "Invalid Authorization", } |
If any of the headers are not sent or are missing. | JSON |
To request marketful to register products and thus be able to have an inventory control of these products.
It allows to register from multiple products in a single request.
POST /items/create_item
Name | Type | Method | “POST” |
---|---|
Headers | “Authorization”: Access_token, “User”: user_id |
Body/Parameters | “items”: products |
Field | Description | Datatype | Required | items | Object vector, where each object includes the parameters title, list_price, sku, height, width, lenght, wieght, ean | object | Yes |
---|---|---|---|
title | Product title | string | Yes |
list_price | Price of the product | float | Yes |
sku | Product identification code, (No special characters) | string | Yes |
height | Product height | float | No |
width | Product width | float | No |
length | Product length | float | No |
weigth | Product weigth | float | No |
ean | EAN Code for the product | string | No |
Answer Received | Case | Type |
---|---|---|
status: 200, json: { message: "Success", description: "All Items are now registered", items_saved: salida,} | All items were saved sucessfully |
int | status: 201 , json: { message: "The following Items could not be saved", items_errors: items_no_save, items_saved: salida, | it was not possible to save all items | int |
status: 401, json: { message: "Incomplete data", description: "No item was saved because the following items have either incorrect data or Incomplete data", items_errors: items_incomplete, } | The data is incomplete | int |
status: 402, json: { message: "Parameter 'items' must be present", } | When the “Items” parameter is not being sent | int |
status: 403, json: { message: "User Not Found", } | If any of the values of { Headers (Authorization / User) is incorrect | int |
status: 404, json: { message: "Invalid Authorization", } | If any of the headers are not sent or missing. | int |
It allows to delete a product by product id.
POST /items/delete_item
Name | Type | Method | “POST” |
---|---|
Headers | “Authorization”: Access_token, “User”: user_id |
Body/Parameters | “item_id”: item_id |
Field | Description | Datatype | Required | item_id | Product id to remove | int | Yes |
---|
Answer Received | Case | Type | status: 200 , json: { message: "Success", description: "Item #{item_id} deleted", | Item deleted successfully | int |
---|---|---|
status: 401, json: { message: "Item not found",} | Item not found |
int |
status: 402, json: { message: "item_id must be present", } | The parameter “item_id is not being sent or is not being sent | int |
status: 403, json: { message: "User Not Found", } | If any of the values of { Headers (Authorization / User) is incorrect | int |
status: 404, json: { message: "Invalid Authorization", } | If any of the headers are not sent or missing. | int |
Method that allows updating the attributes of a product by product id.
POST /items/update_item
Name | Type | Method | “POST” |
---|---|
Headers | “Authorization”: Access_token, “User”: user_id |
Body/Parameters | {"item_id"=> item_id, "title"=>"Pluma Roja", "height"=>12, "width"=> 12, "length"=> 12, "weigth"=> 12, "list_price"=>355, "sku"=>"ABCD12" |
Field | Description | Datatype | Required | item_id | Product id to remove | int | Yes |
---|---|---|---|
title | Product title | string | No |
height | Product height | float | No |
width | Product width | float | No |
length | Product length | float | No |
weigth | Product weigth | float | No |
list_price | Price of the product | float | No |
sku | Product identification code (no special characters) | string | No |
ean | EAN identification code(no special characters) | string | No |
"If no parameter is sent to update, the method returns status 200"
Answer Received | Case | Type | status: 200 , json: { message: "Success", description: "Item Updated " items_update: salida, | The item is updated successfully | int |
---|---|---|
status: 405, json: { message: "Item could not be updated",} | It was not possible to update the item |
int |
status: 400, json: { message: "Item not found",} | Item not found | int |
status: 402, json: { message: "item_id must be present", } | The “item_id” parameter is not found or is not being sent | int |
status: 403, json: { message: "User Not Found", } | If any of the values of { Headers (Authorization / User) is incorrect | int |
status: 404, json: { message: "Invalid Authorization", } | If any of the headers are not sent or missing. | int |
Method that allows consulting all shipping events related to an order through the order id.
GET /shipment_events/get_events
Name | Type | Method | GET |
---|---|
Headers | “Authorization”: Access_token, “User”: user_id |
Body/parameters | {"order_id" => 5021} |
Field | Description | Datatype | Required |
---|---|---|---|
order_id | order id | int | Yes |
Answer Received | Case | Type | status: 200 body: { message: "Success", orden: objeto |
Success response | JSON |
---|---|---|
status: 404 body:{ message: "Orden no encontrad"} |
If the order id does not correspond to any existing order. | JSON |
status: 404 body: { message: "order_id must be present", } |
The "order_id" parameter is not found or is not being sent with a valid format | JSON |
status: 404 body: { message: "Seller Not Found", } |
If the credentials provided do not correspond to a user | JSON |
status: 404 body: { message: "User Not Found", } |
If any of the values of the { Headers (Authorization / User) is incorrect | JSON |
status: 404 body: { message: "Invalid Authorization", } |
If they are not sent or are missing any of the headers.. | JSON |
Method that allows you to consult all the Webhhoks that you have registered.
GET /webhooks/consultar
Name | Type | Method | GET |
---|---|
Headers | “Authorization”: Access_token, “User”: user_id |
Field | Description | Datatype | Required |
---|---|---|---|
Answer Received | Case | Type | status: 200 body: { message: "Success", webhooks: Listado de los Webhooks |
Success response | JSON |
---|---|---|
status: 404 body: { message: "User Not Found", } |
If any of the values of the { Headers (Authorization / User) is incorrect | JSON |
status: 404 body: { message: "Invalid Authorization", } |
If they are not sent or are missing any of the headers.. | JSON |
Method that allows creating Webhooks to create orders, update orders and create Events of the order.
POST /webhooks/crear
Name | Type | Method | POST |
---|---|
Headers | “Authorization”: Access_token, “User”: user_id |
Body/parameters | {"url"=>"www.example.com/notificaciones", "tipo"=>"order/created"} |
Field | Description | Datatype | Required |
---|---|---|---|
url | Link / URL to which the Webhook will send the corresponding information. | String | Yes |
tipo | Name or type of the Webhook to create ("order/created", "order/updated", "shipment_event/created") | String | Yes |
Answer Received | Case | Type | status: 200 body: { message: "Success", webhook: Webkook |
The Webhook was created successfully | JSON |
---|---|---|
status: 404 body:{ message: "Ya existe un Webhook para order/created"} |
When there is already a Webhook with the same type / name and it has a different URL than the one being sent. In case of sending the same "type" and "url" and that there is already a Webhook with this information, the existing Webhook will return. | JSON |
status: 404 body:{ message: "Error al crear Webhook", error: "Explanation of the error"} |
When the Webhook could not be created for some reason, it will be specified in the ": error" field | JSON |
status: 404 body:{ message: "Webhook orders/CRATED desconocido/invalido"} |
If the type/name of the webhook is not within the list of existing webhooks. | JSON |
status: 404 body: { message: "Parametros incompletos (url y tipo deben estar presentes", } |
When the necessary parameters for the request ("type" and "url") are not present or have an invalid format. | JSON |
status: 404 body: { message: "User Not Found", } |
If any of the values of the { Headers (Authorization / User) is incorrect | JSON |
status: 404 body: { message: "Invalid Authorization", } |
If they are not sent or are missing any of the headers.. | JSON |
Method that allows you to delete a Webhook through its id.
POST /webhooks/eliminar
Name | Type | Method | POST |
---|---|
Headers | “Authorization”: Access_token, “User”: user_id |
Body/parameters | {"webhook_id"=>"3"} |
Field | Description | Datatype | Required |
---|---|---|---|
webhook_id | Webhook id to delete | Integer | Yes |
Answer Received | Case | Type | status: 200 body: { message: "Success" } |
The Webhook was successfully removed. | JSON |
---|---|---|
status: 404 body:{ message: "Webhook 4 no encontrado"} |
When the webhook_id does not match any registered webhook. | JSON |
status: 404 body: { message: "Parametro webhook_id no esta presente o esta en un formato invalido", } |
When the webhook_id parameter is not present or has an invalid format. | JSON |
status: 404 body: { message: "User Not Found", } |
If any of the values of the { Headers (Authorization / User) is incorrect | JSON |
status: 404 body: { message: "Invalid Authorization", } |
If they are not sent or are missing any of the headers.. | JSON |