Nothing found

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
Note

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 language parameter. When the application does not have language mutations turned on, the portal ignores the language and uses default.
  • The admin notification is always looked up for the default language 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.
Important

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 matching shop_id from the store list, unless you send it yourself,
  • language_iso — the value of the language parameter.

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.

{ "data": { "customer": [ { "status": "accepted", "message_id": "tmpde1bcd4b1d1", "part_id": ["tmpde1bcd4b1d1"], "number": "420777777777", "channel": "sms" } ] } }

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:

{ "data": { "customer": [ ["duplicity_message"] ] } }

On error:

{ "type": "unknown_identity", "code": 401, "error": "Unknown identity / unauthorized / empty application_id", "detail": null }

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.
Was this page helpful?