E-shop API – overview
The E-shop API connects any e-shop to BulkGate. Your e-shop uses it to report store events: a new order, a status change, a payment, a new customer and more. For each event, the portal finds the notification set up for the application, fills the variables from the request into its template and sends the message to the customer, to the store administrators, or to both.
The API itself does not set the message text. When no notification is set up for the event, the request succeeds and nothing is sent.
Endpoints
All endpoints accept POST at https://portal.bulkgate.com/api/1.0/eshop/<area>/<action>.
| ENDPOINT | EVENT | PAGE |
|---|---|---|
eshop/order/new |
New order | Orders |
eshop/order/change-status |
Order status change | Orders |
eshop/order/payment |
Order paid | Orders |
eshop/order/tracking-number |
Tracking number assigned | Orders |
eshop/order/product-cancel |
Product cancelled in an order | Orders |
eshop/order/slip-add |
Credit slip added to an order | Orders |
eshop/customer/new |
New customer | Customers |
eshop/product/out-of-stock |
Product out of stock | Products |
eshop/product/on-back-order |
Product on back order | Products |
eshop/product/update-quantity |
Stock quantity changed | Products |
eshop/product/delete |
Product deleted | Products |
eshop/return/new |
New return | Returns |
eshop/return/change-status |
Return status change | Returns |
eshop/contact/form |
Contact form submitted | Contact form |
eshop/setup |
Languages, stores and statuses setup | Setup |
If the request does not reach its destination, repeat it on the backup server backup1.bulkgate.com.
Request parameters
The event endpoints (all except eshop/setup) accept the same parameters. An unknown top-level parameter makes the request fail with invalid_input_parameters, so event data belongs in the variables object.
| PARAMETER NAME | VALUE | MANDATORY | DEFAULT VALUE |
|---|---|---|---|
| application_id | Application ID | Yes | - |
| application_token | Application authentication token | Yes | - |
| language | Language of the customer notification, e.g. en |
No | default |
| shop_id | Store identifier if you run multiple stores | No | 0 |
| variables | Event data — a name: value object with scalar values |
No | {} |
Send the request as application/json.
How the portal picks the notification
Notifications are set up in the portal for each application separately, in the Customer SMS and Admin SMS sections. Each one is tied to an event and a store (shop_id), and customer notifications also to a language. Your e-shop uploads the languages, stores and order and return statuses the portal offers notifications for via the setup.
- The customer notification is looked up for the language in the
languageparameter. When the application does not have language mutations turned on, the portal ignores the language and usesdefault. - The admin notification is always looked up for the
defaultlanguage and goes to the numbers of the administrators assigned to it. - The customer and admin notifications are evaluated independently — an event can send one, both or neither.
The portal does not send the same text to the same number twice within 24 hours. Calling the same event again therefore does not send the customer a duplicate message.
Customer phone number
The portal looks for the customer's number in variables. The order is set by the contact_address_preference variable:
contact_address_preference |
ORDER OF NUMBER VARIABLES | ORDER OF COUNTRY VARIABLES |
|---|---|---|
delivery (default) |
customer_mobile, customer_phone, customer_invoice_mobile, customer_invoice_phone, phone_mobile, phone, phone_number |
customer_country_id, customer_invoice_country_id, customer_country, customer_invoice_country, iso, country_iso |
invoice |
customer_invoice_mobile, customer_invoice_phone, customer_mobile, customer_phone, phone_mobile, phone, phone_number |
customer_invoice_country_id, customer_country_id, customer_invoice_country, customer_country, iso, country_iso |
The first variable that yields a valid number is used. The portal reads the country as a two-letter ISO code (cz, sk, …) and uses it to add the prefix to numbers entered without one. When no valid number is found, the customer notification is not sent.
Template variables
A notification template uses the variables from variables written as <name>, e.g. <order_id>. Write a default value right in the template as <name:value>. The portal also fills in:
shop_name— the name of the store matchingshop_idfrom the store list, unless you send it yourself,language_iso— the value of thelanguageparameter.
Variables you do not send are replaced in the text by their default value — an empty string for most, a dash for order_id, long_order_id and order_ref. These variables have a default value:
| GROUP | VARIABLES |
|---|---|
| Store | shop_id, shop_email, shop_name, shop_domain, shop_currency, shop_phone, store_id, lang_id, language_iso |
| Customer | customer_id, customer_company, customer_firstname, customer_lastname, customer_name, customer_address, customer_postcode, customer_city, customer_state, customer_country, customer_country_id, customer_phone, customer_mobile, customer_email, customer_vat_number, customer_fax, customer_message, customer_firstname_vokativ, customer_lastname_vokativ |
| Billing | customer_invoice_company, customer_invoice_firstname, customer_invoice_lastname, customer_invoice_address, customer_invoice_postcode, customer_invoice_city, customer_invoice_state, customer_invoice_country, customer_invoice_country_id, customer_invoice_phone, customer_invoice_mobile, customer_invoice_vat_number, customer_invoice_firstname_vokativ, customer_invoice_lastname_vokativ |
| Order | order_id, long_order_id, order_ref, order_reference, order_status, order_status_id, order_status_message, order_message, order_currency, order_payment, order_total_paid, order_total_locale, order_date, order_datetime, order_time, order_date1–order_date7, order_time1, order_products1–order_products8, order_smsprinter1–order_smsprinter4, cart_id, id_address_delivery, id_address_invoice |
| Shipping | carrier_id, order_carrier_name, order_carrier_code, order_carrier_url, order_carrier_delay, order_carrier_tracking_number, order_carrier_tracking_date, order_carrier_price, order_carrier_price_locale, order_carrier_weight, order_tracking |
| Product | product_id, product_name, product_quantity, product_minimal_quantity, product_model, product_ref, product_description, product_manufacturer, product_supplier, product_supplier_id, product_supplier_ref, product_price, product_price_locale, product_ean, product_ean13, product_upc, product_isbn, product_jan, product_mpn, product_sku |
| Return | return_id, return_status, return_status_id, return_action, return_action_id, return_reason, return_reason_id, return_date, return_customer_message, return_question, return_products1–return_products8 |
| Employee | employee_id, employee_email, employee_firstname, employee_lastname |
You can send your own variables as well — the template uses them the same way.
Response
On success it returns a data object with the result of each sent message, separately for the customer (customer) and for administrators (admin). A key is missing when that notification is not set up for the event. A customer notification that is set up but turned off returns an empty array.
When no notification is set up for the event, the response is {"data": []}.
If a notification cannot be sent (invalid sender, blacklisted number, duplicate message…), the request still succeeds and contains the error code instead of the message result:
On error:
Where:
- type and error (error description) are listed in the error types table
- code is the HTTP error code
- detail is additional information about the error
E-shop API error types
| TYPE | WHEN IT OCCURS |
|---|---|
unknown_identity |
application_id or application_token is missing or invalid. |
invalid_input_parameters |
The request contains an unknown parameter or a parameter of the wrong type. |
unknown_action |
The action in the URL does not exist, e.g. eshop/order/cancel. |
Thank you for your feedback.