Introduction

This is the documentation for Shopamine's RESTful API, version 2.1.

All data is transferred using JSON format.

1. Obtain an API token

In order to start working with Shopamine API you should obtain the API token for your store. You can generate your API token in your store admin panel.

2. Activate API interface

Please contact our support (support@shopamine.com) to activate the API interface for your store. Please include your store URL in the request.

3. Get familiar with the API

Probably the easiest way to familiarize yourself with the API is to play around in the admin interface, then see how the changes you made reflect in the API output. In almost all cases, the API expects exactly the same format back. Once you feel you know what’s going on, try making some updates.

How to form URLs (URL_BASE)

Each shop runs on its own domain name. Within that domain name, all API URLs have the prefix /api/v1/.

All API calls must be done via HTTPS. Because the large majority of shops don't have their own secure domains, this means that they must pass through on of Shopamine's HTTPS gateways, for example api.shopamine.com. So, a full URL to retrieve a list of items on www.example.com looks like this: URL_BASE = https://api.shopamine.com/www.example.com/api/v1/items/list The common prefix will be referred to as [URL_BASE] below.

All entities use the same URL patterns for the same operations. Here is the list of operations supported on most entities:

HTTP method URL pattern Description
GET [URL_BASE]/[entity]/list Retrieves the list of entities. See also common parameters for lists. The resulting JSON object will have a single field data, containing the array of entities.
POST [URL_BASE]/[entity]/create Creates a new entity. The result will be the entity, as if retrieved from its URL by GET.
GET [URL_BASE]/[entity]/[entity_id] Retrieves data for one entity. The result is a JSON representation of the entity, as defined in sections below.
POST [URL_BASE]/[entity]/[entity_id] Updates data for one entity. The result is again the entity, as if retrieved after update by GET.
DELETE [URL_BASE]/[entity]/[entity_id] Deletes one entity. The result will be either { "status": "ok" } on success, or { "status": "failed", "error_msg": "..." } on errors.

Authentication

To call any of the API functions, you must obtain a security token. Then, you must include it in a HTTP header in all calls made to the API, as described in OAuth2 Bearer Token Usage. Here is an example of what a HTTP call might look like: GET /www.example.com/api/v1/items/list HTTP/1.1
Authorization: Bearer 8vd9n8nv9wvm195v1vmanlksdmv The header is the only supported form of authentication, despite there being two additional modes (form-encoded body parameter, URI query parameter) described in the above-mentioned document.

How to update data

One of the main purposes of the API is to allow synchronization of data like item prices with external software. If entire documents had to be transferred all the time, the process would be slow and brittle. To make it both easier and faster to only update a few fields, whenever an update is being made, the incoming data is merged with existing data. Fields not present in the incoming JSON document are not modified. For example, if you only wish to update an item's first price and stock amount, it is enough to do a HTTP exchange like this: POST /www.example.com/api/v1/items/123 HTTP/1.0 Authorization: Bearer 8vd9n8nv9wvm195v1vmanlksdmv Content-Type: application/json Content-Length: 70 { "stock_amount": 18, "prices": { "p1": 124.99 } } This will leave all other fields intact, including other prices (if they are used). As a consequence, if you wish to delete one of the fields, you must explicitly set it to null.

Localized strings

Most strings visible to a shop's visitors are localized. In the API they are represented as JSON objects in which keys are locale identifiers (e.g. en_US) and values are the respective translations. A special locale identifier "__" is used for the default. The default must always be present and is used in all locales where a translation is missing. For single-language shops, it is recommended only the default is used. For multi-language shops, it is recommended the default is in shop owner's language, as that is what he/she will see in the administration interface. Here is an example localized string: { "__": "Chocolate cookies", "sl": "Čokoladni piškoti", "de": "Schokoladenkekse", "en_GB": "Chocolate biscuits" } Like other objects in the API, incoming localized string updates are merged with existing data. Therefore, if you wish to delete one of the translations, you must explicitly set it to null: { "__": "Apple iPhone 14", "sl": null }

Other types used

List parameters

Because some shops have very large inventories, all entity lists support/require pagination. Each entity type has a maximum page size you can use, documented in its section. The three URL parameters with which you can control retrieved data are these:

URL Parameter Description Examples
limit Sets the maximum number of entities to retrieve. If not specified, the entity's default page size is used. The default page size is defined for each entity. .../[entity]/list?limit=40
To retrieve first 40 entities instead of default page size value.
offset Sets the number of entities to skip from the beginning of the list. If not specified, it defaults to 0, meaning the first limit entities will be retrieved. .../[entity]/list?offset=40&limit=20
To retrieve the third page of entities, where page size is 20.
order Sets the field(s) by which the results are sorted. Multiple fields may be used, separated by , (commas). Each field may also be prefixed with - to reverse the order. Available sort field(s) are defined for each entity. .../[entity]/list
By default, entities are sorted by id.

.../[entity]/list?order=-date_updated
To find most recently edited entities.

.../[entity]/list?order=[sort_field],id
When using fields where multiple entities can have the same value, it's a good idea to add id (or something else which is unique) as the last field to ensure a stable sort.

Entities

The following are all the entities that are currently implemented in the API.

Items / Products

[URL_BASE]/items/...
List parameters:
Endpoint Method Description
[URL_BASE]/items/[id] GET, POST, DELETE Used to refer to an item based on its Shopamine ID.
[URL_BASE]/items/list GET Used to retrieve lists of items. See also List parameters.
[URL_BASE]/items/create POST Used to create new items.
[URL_BASE]/items/by_bar_code/{bar_code} GET, POST, DELETE Find/Update/Delete item by bar code value (EAN)
[URL_BASE]/items/by_external_id/{external_id} GET, POST, DELETE Used to refer to an item based on its external ID. Find/Update/Delete item by user code value
[URL_BASE]/items/by_sku/{sku} GET, POST, DELETE Used to refer to an item based on its SKU. Find/Update/Delete item by sku code value
Field descriptions:
Field Restrictions Description
id Required Shopamine's ID number for this item
external_id Optional External ID for this item (in Shopamine admin dashboard this field is called User Code)
type Required The type of this item. If it is "variants", the item represents a collection of items, one of which must be selected when placing into basket. Otherwise, the item can be bought stand-alone.
name Required The localized name of this item.
list_desc Optional The localized list description.
short_desc Optional The localized short description.
long_desc Optional The localized long description.
nodes Optional Contains IDs of nodes to which this item belongs. They are separated by type, so each can be updated separately.
prices Required Contains base prices for this item. p1 is required, while the other two are optional.
discounts Optional Contains discount rates for this item. Note that these are not percentages, so a 20% discount is represented as 0.2.
shipping_dimensions Optional Contains the shipping dimensions for this object. weight can be present on its own (in grams), but the other three (width, depth, height) must either all be present, or none of them. weight is used in shipping fee calculation. (sizes are currently not used for any calculation).
model Optional This is the model designation for this item.
sku Optional This is the SKU code for this item.
bar_code Optional This is the bar code (EAN) for this item.
supplier_code Optional This is the supplier code for this item.
stock_amount Required This is the number of items that are immediately available.
avail_in_days Required This is the number of days in which this item is available when out of stock.
tax_class_id Required This is the ID of the tax class to which this item belongs.
buyable Required This determines if this item can currently be bought. as_part_only means that it can be bought only as a variant of a container item.
default_buyable Optional Determines the default buyable status for items of type variant.
I.e. if an Item with default_buyable="as_part_only" is updated with buyable = "yes" the buyable value will automatically be converted to "as_part_only"
date_updated Required This is the date/time at which the last change to this item was made. It updates automatically.
warranty_months Optional This is the length of warranty for this item, in months.
variants_configuration Optional For items with type variants, this field contains the configuration. If chooser_type is "names", the user will choose one of the variants by their respective names. If it is "specs", the user will choose by choosing relevant spec values. In that case, the specs have to be listed in chooser_specs.
images Optional This field contains the image IDs for this item. Gallery is the list of images shown on item's page. list is the image to be used when displaying the item in lists; if missing, the first image from the gallery will be used. The variant_chooser image is used when the item is in a variant and the variant selection happens using images.
customization Optional This field contains information about customization options for this item. There can be any number of them, and each is represented as either a choice of options (type: "choices"), or a field for the user to enter (type: "text"). price_delta is the change in price of the item, applied if the user chooses to use the option. pricing_steps determines in which order price deltas are appliced. It is useful when combining relative and absolute price deltas.
sys_tags Optional This is a list of system tags that the item has. By default, they do nothing, but skins may use them for various purposes. For example, many skins will display some sort of a marker for items with tag "new".
seo_data Optional This field contains SEO-related data, currently this means <meta> tags. The two most commonly used are represented directly, and there can also be any number of extra tags inside custom_meta_tags.
external_buy_settings Optional This rarely used field is used for items that are actually bought on other sites.
extra_search_kws Optional This field is used to enter additional search keywords that this item can be found by, in the (rare) case when they don't appear in any of the other fields.
generic_data Optional This field can contain any extra data that doesn't fit into other fields. By default it is ignored, but custom skins can use the data in some way.
specs Optional This field contains spec values for this item. The actual values are separate from the layout, so it's possible to update them without touching the layout. The layout itself is a recursive tree of specs and groups, the latter containing other groups and specs.
related_items Optional Contains IDs of related items
variant_members Optional Contains variant items
warehouses Optional Contains warehouse id and stock
Sample object:

Note on prices and discounts: Prices and discounts fields can be combined in different ways (as specified in Shopamine admin dashboard under Store settings) to produce item prices for buyers. It should be noted that when a store is using External prices service or Contract prices, the values here (p1, p2, p3) are basically completely ignored, except as fallback values in case of errors. It should also be noted that these prices (including those from the external service) are still not final - promotions (e.g. coupons) can be applied on top of these "standard" discounts, taxes may be added, and they are subject to rounding settings. In case external_supplier is true than final_price is used for the item price. Final price is calculated using implemented bussines rules and various prices supplied by various suppliers. How the final price is calculated is settable in Shopamine admin dashboard.

Item Bulk Update

[URL_BASE]/items/createUpdateBulk

Items can be updated in bulk of maximum 100 entities per request. If a corresponding entity is found it will be updated, otherwise a new one will be created. An entity is found when one of the identificators is found: id, external_id, bar_code, sku (in this order).

Sample object:

Nodes

[URL_BASE]/nodes/...
List parameters:
Field descriptions:
Field Restrictions Description
id Required Shopamine's ID number for this node
external_id Optional External ID for this node
type Required The type of this node. Nodes can switch types, but not to or from "home". There is always exactly one home page, and it also cannot be deleted.
url_key Required This is what goes into the URL for this node. Allowed characters are a-z, A-Z, 0-9, - and _.
parent_node_id Required This is the ID of the parent node for this node. All nodes, except home page, must have this set. Cycles of nodes are forbidden.
show_in_parent Required This field sets whether the node is considered to belong to its parent. If not, it starts a new separate sub-tree of nodes, and the parent(s) only contribute URL parts.
order_weight Optional By default, the nodes are displayed to visitors sorted by name. When another order is desired, this field can be used. Nodes with the same order weight are still sorted by name. Nodes without an order weight come last, again sorted by name.
name Required This is the name of the node.
sys_tags Optional Like with items, these can be used to tell skins that the nodes are somehow special, but don't do anything by default.
visibility Required This field determines whether the node is visible or not. If it is hidden, visitors can still reach it if they know the URL or if it is linked from somewhere. If it is 404, it is as if the node doesn't exist.
date_created Required This is the date/time at which the node was first created. Set automatically.
date_updated Required This is the date/time at which the node was last edited. Set automatically.
date_published Optional This is the date/time at which the node was published. Set automatically.
image_id Optional This is the ID of the image that represents this node.
generic_data Optional Like with items, this field can store generic attributes, occasionally used with custom skins.
specs Optional This field can contain a spec layout that can be then used as the template for items in this node.
seo_data Optional This field contains SEO-related data, currently this means <meta> tags. The two most commonly used are represented directly, and there can also be any number of extra tags inside custom_meta_tags.
filters Optional This field contains settings about which filters are available when looking at items in this node. Each filter can be one of the predefined ones (price, brand, category), or it can be a filter based on a spec. In the latter case, it's ID must be set.
sort_orders Optional This field contains settings about which sort orders are available to visitors when looking at items in this node. It is similar to filters, except that directions allowed must also be specified.
Sample object:

Specs

[URL_BASE]/specs/...
List parameters:
Field descriptions:
Field Restrictions Description
id Required Shopamine's ID number for this spec
external_id Optional External ID for this spec
type Required This is the type of this spec. numeric and numeric_discrete are interchangeable, the only difference is how they are displayed when used in filters. For specs of type choice, see more information below.
name Required The localized name of this spec.
description Optional A description, useful for administrators, when multiple unrelated specs have the same name (for example, "Capacity" might refer to a hard drive or to a barrel).
unit Optional The unit of measurement, used for numeric specs.
Sample object:

Choices

Specs of type choices each have a corresponding list of the actual choices. They are accessed with the following URL patterns:

HTTP method URL pattern Description
GET [URL_BASE]/specs/[spec_id]/choices/list Retrieves the list of choices. See also common parameters for lists
POST [URL_BASE]/specs/[spec_id]/choices/create Creates a new choice
GET [URL_BASE]/specs/[spec_id]/choices/[choice_id] Retrieves data for one choice.
POST [URL_BASE]/specs/[spec_id]/choices/[choice_id] Updates data for one choice.
DELETE [URL_BASE]/specs/[spec_id]/choices/[choice_id] Deletes one choice
List parameters:
Field descriptions:
Field Description
id Required Shopamine's ID number for this choice
external_id Optional External ID for this choice
value Required This is the localized textual value visitors will see.
order_weight Optional By default, choices are sorted by value. If another order is required, this field can be used.
Sample object:

Users

[URL_BASE]/users/...
List parameters:
Endpoint Parameter Description
[URL_BASE]/users/by_email/{value}/ Customer email Find/Update/Delete customer by email value
[URL_BASE]/users/by_external_id/{value}/ Customer user code Find/Update/Delete customer by user code value
Field descriptions:
Field Restrictions Description
id Required Shopamine's ID number for this user
external_id Optional The external ID of this user.
email Required The e-mail address of this user
name Optional The name of this user.
nickname Optional The nickname of this user.
date_created Required The date/time at which the user was created. Set automatically.
date_updated Required The date/time at which the user was updated. Set automatically.
user_type_id Optional The ID of the user type of this user.
gdpr_permissions Optional Array of gdpr permissions associated with the users. Including if the permission is required and if the user agreed with the permission
Sample object:

GDPR Permissions field description

A creation of a new permission is only possible in the Shopamine admin dashboard. Not all fields are updatable with an API call. Adding a new permission is possible only if an existing id or external_id is sent. You can delete a permission for the user, by removing it from the array.

Field Restrictions Description
id Required User permision Shopamine ID number.
required Required If the value is true, the user must agree to it, to finalize an order.
external_id Optional User permission external ID.
name Not Updatable User permision label that is displayed to the user.
text Not Updatable Info text displayed to the user.
mailchimp_id Optional User permision Mailchimp ID (if the store is connected to a Mailchimp account).
agreed Optional If the user agreed to the permission.

Addresses

Each user can have a number of addresses associated with him, used in checkout. Addresses, once created, cannot be changed or deleted. They are accessed with the following URL patterns:

HTTP method URL pattern Description
GET [URL_BASE]/users/[user_id]/addresses/list Retrieves the list of addresses. See also common parameters for lists
POST [URL_BASE]/users/[user_id]/addresses/create Creates a new address
GET [URL_BASE]/users/[user_id]/addresses/[address_id] Retrieves data for one address.
List parameters:
Field descriptions:
Field Restrictions Description
id Required Shopamine's ID number for this address
name Required The name of the person.
company Optional The company name.
street_addr_1 Required First line of street address.
street_addr_2 Optional The second line of street address.
postal_code Required The postal code of this address.
city Required The city of this address
state_code Optional The code of the state, in countries which have states.
country_code Required The 2-letter country code.
tax_code Optional The tax code (e.g. VAT number in EU)
phone Optional The phone number to call when issues arise.
deleted Optional Signifies whether the user has deleted this address from his list of addresses.
Sample object:

Contract Prices

Note: to use the Contract Prices API you need to contact support as is not enabled by default!

Each user can have a number of contract prices associated with them. Each contract price object includes an item with its price before discounts and taxes and the discount used to calculate that price. The price must be pre-calculated. The discount value is meant to be displayed only (if needed). The contract prices can be created, read, updated and deleted.

HTTP method URL pattern Description
GET [URL_BASE]/users/[user_id]/contract_prices/list Retrieves the list of the contract prices. See also common parameters for lists
POST [URL_BASE]/users/[user_id]/contract_prices/create Creates a new contract price
POST [URL_BASE]/users/[user_id]/contract_prices/delete Delete an existing contract price
POST [URL_BASE]/users/[user_id]/contract_prices/deleteAll Delete all contract prices for the selected user
List parameters:
Field descriptions:
Field Restrictions Description
item_id Required [1] Shopamine's ID number for this item. [1]
item_sku Required [1] This is the SKU code for this item. [1]
item_bar Required [1] This is the bar code for this item. [1]
item_external_id Required [1] The external ID of this item. [1]
price_base Optional Contract final price for the item/user combination.
discount_rate Optional Discount rate (%) associated to this item/user combination
sync_name Optional Your integration name or additional info for this price

[1] At least one code must be included, otherwise the API call will fail!

Sample object:

Note: it's required to send a data object with an array of values, also when sending a single contract price

External Prices Service

When internal capabilities are not enough (typically this happens with B2B stores which have customer-specific rules and contracts to follow), Shopamine has the ability to obtain prices from an external web service in real-time. To use this capability you should implement a HTTP-accessible service which will receive queries from Shopamine as they are needed, and which should respond with price data for the given query.

The incoming query will contain the user's email address and a number of item IDs together with quantities of interest (usually the quantity will be 1, but when in basket and in checkout the quantity might be bigger). The incoming item ID can be either "external_id" or "sku" from the rest of the API, configurable in Shopamine. Quantities will always be integers.

There are two ways in which the query can be encoded, either as parameters in the URL, or as a JSON document. The latter is probably slightly more robust, but also probably a bit harder to implement. Which way is used is configurable in Shopamine.

URL query format

If the query is in the URL, you have four choices:

  1. The entire query is in one parameter, and you can configure the separator between items and between an item's ID and quantity. For example, it the separators are , and : respectively, a query for three SKUs might look like this:

    http://.../getUserPrices?user=john@example.com&items=SKU0001:1,SKU0015:1,SKU0451:12

    You specify the URL, both parameter names (user and items in the example) and the separators in configuration.

  2. The query includes one parameter for each item. The parameter name is always the same or can include a counter, and there is a separator between the item's ID and quantity. For example, if separator is : and a counter is included, the query from above would instead look like this:

    http://.../getUserPrices?email=john@example.com&item1=SKU0001:1&item2=SKU0015:1&item3=SKU0451:12

    For something PHP-like, it would probably be easier if there was no counter and the parameter name included brackets instead:

    http://.../getUserPrices.php?who=john@example.com&item[]=SKU0001:1&item[]=SKU0015:1&item[]=SKU0451:12

    Again, you can specify the URL, both parameter names, whether to include a counter or not and the separator in configuration.

  3. The query includes two parameters for each item. One contains the item's ID and the other its quantity. You can include counters or not. With a counter, the query might look like this:

    http://.../prices?user=john@example.com&item1=SKU0001&qty1=1&item2=SKU0015&qty2=1&item3=SKU0451&qty3=12

  4. The last option is to have the item's ID be the parameter name and the quantity its value:

    http://.../getPrices?_email=john@example.com&SKU0001=1&SKU0015=1&SKU0451=12

To Shopamine they are all the same. You should choose the one which you find the easiest to implement in your system of choice. If you're using any of the separator-based modes (the first two), you should choose a separator which will not conflict with any characters in item IDs.

JSON query format

If you'd prefer to receive queries in JSON format, that is also an option. Shopamine will make a POST request to an URL of your choice with contents like this example:

{ "v": 1, "user_email": "john@example.com", "query": { "SKU0001": 1, "SKU0015": 1, "SKU0451": 12 } }

The "v" field contains the version, which will currently always be 1. If a richer query format will eventually be introduced, it will be of a different version and we plan to support version 1 indefinitely.

Response format

The response expected is basically a table of data, with one line per item. For encoding efficiency, it is simply an JSON array of arrays, with some metainfo in the envelope document to describe what the table actually contains. For example, here's a simple response to the above query:

{ "v": 1, "currency": "EUR", "columns": [ "id", "base_price", "final_price" ], "data: [ [ "SKU0001", 180.0, 155.0 ], [ "SKU0015", 12.0, 12.0 ], [ "SKU0451", 75.0, 44.5 ] ] }

We currently support the following columns:

The response must include "id", and at least one of "base_price" or "final_price". If "discount_rate" is included it will be taken into account. If not, it will be computed from "base_price" and "final_price" if both are present, and assumed to be 0 otherwise.

The recommended combinations of fields are these (in order of preference):

The prices returned should always be for one item, regardless of the quantity in the query. They should also not include any taxes. Future versions may allow returning prices for total quantities and with taxes included.

Currently, the response must be in the shop's base currency, in EU that's typically EUR.

Error responses

If the user is not recognized or has no special prices, please simply return this:

{ "v": 1 }

In that case (and also for items not included in the returned data) the user will be shown the default prices configured in Shopamine.

On the other hand, if some error occurs, please return a response like this:

{ "error": "...", "public_error": "..." }

If public_error is present, it will be shown to the user as-is. Otherwise he will be shown a generic error message.

Any/both of the errors will be logged in the shop's logs to help resolve problems.

Other considerations

The response should include a header Content-Type: application/json. The charset used must be UTF-8.

The request can be done either via HTTP or HTTPS. HTTP is considerably faster, so provides a better user experience, but obviously it is less secure. If the pricing information is considered very sensitive, HTTPS should be used instead.

The request can be done without authentication, or by any of these authentication methods:

For queries involving many items using URL parameters, several HTTP requests will be made so that the URLs are not too long. The default limit is 2000 total characters.

If JSON queries are used, there will usually be only one request per page view containing all the items.

User types

[URL_BASE]/user_types/...
List parameters:
Field descriptions:
Field Restrictions Description
id Shopamine's ID number for this user type
name The name of this user type.
sys_tags Optional The list of system tags skins can use for special handling of this user type.
pricing_settings Optional If this user type uses different pricing settings than the shop's default, the settings will be here.
Sample object:

Purchases attempts [URL_BASE]/purchase_attempts/...

List parameters:

Sample object:
Expand
Field descriptions:
Field Description
id Shopamine's ID number for this purchase
shipping_address_id (optional) The shipping address for this purchase. Will not be present on purchases that only have virtual goods or on purchases which have no shipping.
shipping_address (optional) Object representing the shipping_address entity
date_created The date/time at which the purchase was made.
items Contains the list of items that were bought in this purchase. container_item_id is only present with variants. customization is only present with items that have customization; when so, the values are stored under values, and configuration contains the snapshot of the item's settings when the purchase was made.
payment (optional) Contains information on the payment method for this purchase.
items_total This field contains the total cost of all the items in this purchase, excluding shipping and billing costs.
grand_total This field contains the grand total for this purchase, including items, shipping and billing costs.

All purchase-attempt-related prices and costs are stored as so-called complex prices. You will likely only use a field or two, but they are there for audit purposes.

Complex price field description
value The final value, with taxes and discounts applied.
currency The currency of this price.
base This is the base price, before taxes and discounts.
base_with_discounts This is the base price, with discounts applied, but without taxes.
base_with_taxes This is the base price with taxes, but without discounts.
discounts_applied This field lists all the discounts that were applied to this price. The default discount has discount_id of 0.
taxes_applied This field lists all the taxes that were applied to this price. It should be used in combination with purchase's tax_conf_snapshot, rather than with current shop's settings.

Purchases

[URL_BASE]/purchases/...
List parameters:
Field descriptions:
Field Restricions Description
id Required Shopamine's ID number for this purchase
external_id Optional The external ID of this purchase.
user_id Required The ID of the user that made this purchase.
user [1] Required Object representing the user entity
shipping_address_id Required The shipping address for this purchase. Will not be present on purchases that only have virtual goods or on purchases which have no shipping.
shipping_address [1] Required Object representing the shipping_address entity
billing_address_id Optional The billing address for this purchase. Will not be present on purchases that only contain free items.
billing_address [1] Required Object representing the billing_address entity
date_bought Required The date/time at which the purchase was made.
status Required The status of the order.
domain Required On which domain the order was made.
locale Required In which locale the order was made.
payment_status Required The payment status of the order.
items Required Contains the list of items that were bought in this purchase. container_item_id is only present with variants. customization is only present with items that have customization; when so, the values are stored under values, and configuration contains the snapshot of the item's settings when the purchase was made. Also includes promotion if present.
shipping Optional Contains information about shipping for this purchase. Some types of shipping will calculate how the items should be distributed into parcels, but most do not. type and name serve as a snapshot of the shipping's settings at the time the purchase was made. Also includes promotion if present.
payment Optional Contains information on the payment method for this purchase.
user_notes Optional There are the user's comments when he made the purchase.
system_notes Optional If Shopamine had anything to say about this purchase (usually related to billing), it will be stored here.
items_total Required This field contains the total cost of all the items in this purchase, excluding shipping and billing costs.
grand_total Required This field contains the grand total for this purchase, including items, shipping and billing costs.
tax_conf_snapshot Required This field contains a snapshot of the relevant tax computation settings that were used with this purchase.

[1] By using GET parameter ?exploded in the request, the fields user, billing_address, shipping_address will display all the serialized entity data. For what data please check the corresponding segments users and addresses.

All purchase-related prices and costs are stored as so-called complex prices. You will likely only use a field or two, but they are there for audit purposes.

Complex price field description
Field Restricions Description
value The final value, with taxes and discounts applied.
currency The currency of this price.
base This is the base price, before taxes and discounts.
base_with_discounts This is the base price, with discounts applied, but without taxes.
base_with_taxes This is the base price with taxes, but without discounts.
discounts_applied This field lists all the discounts that were applied to this price. The default discount has discount_id of 0.
taxes_applied This field lists all the taxes that were applied to this price. It should be used in combination with purchase's tax_conf_snapshot, rather than with current shop's settings.
Promotion field description
Field Restricions Description
promotion_id Shopamine's ID number for this promotion
user_code Custom identification for this promotion
promotion_rate How much of a discount is applied by this promotion
type What type of promotion, possible values: GIFT, DISCOUNT, FREE_SHIPPNG
applied_type On what entities is this promotion applied/triggered, possible values: PRODUCTS, BRANDS_CATEGORIES, QUANTITY, CUSTOM
Sample object:

Updating a purchase

Only a handful of fields can be changed via an API call:

Sample object:

Note: a purchase cannot be created via an API call at the moment.


Updating documents on purchase

Adding documents to the purchase needs a purchase id.

We can add a document as an external link or upload a binary (both sample objects present below).

When a purchase_document id is already present then your post will result in an update. Otherwise your post will result in a create. You can create (add) many documents to an order.

When a purchase_document id is already present then your post will result in an update. Otherwise your post will result in a create. You can create (add) many documents to an order.

Sample object:

Tax classes

[URL_BASE]/tax_classes/...
List parameters:
Field descriptions:
Field Restriction Description
id Required Shopamine's ID number for this tax class
name Required The name of this tax class.
external_id Optional The external ID of this tax class.
Sample object:

Images

[URL_BASE]/images/...
List parameters:
Field descriptions:
Field Restrictions Description
id Shopamine's ID number for this tax class
media_type The media type of this image.
width The width of the image in pixels.
height The height of the image in pixels.
title The localized title of this image.
description The localized description of this image.
md5_hash The MD5 hash of this image's file's contents. Used for preventing duplicates.
Sample object:

Images cannot be changed once uploaded, except for their title and description. They can be uploaded either directly, using data URLs, or fetched from an external server, using HTTP/S or FTP. For FTP, if username and password are required, you can provide them directly in the URL.

Physical Store

[URL_BASE]/physical_store/...
List parameters:
Field descriptions:
Field Restrictions Description
id Shopamine's ID number for this tax class
admin_label Warehouse lable
external_id Optional External reference id
public_name Optional Name to be displayed on store front
opened Optional Time when store opens ("2023-12-03T08:15:00+01:00[Europe/Ljubljana]" - only time part is relavent)
closed Optional Time when store closes ("2023-12-03T18:15:00+01:00[Europe/Ljubljana]" - only time part is relavent)
address Optional Address
latitude Optional Latitude as double
longitude Optional Longitude as double
order_weight Optional Max order weight
node_id Optional Node id of page with store information
Sample object:

Warehouses

[URL_BASE]/warehouse/...
List parameters:
Field descriptions:
Field Restrictions Description
id Shopamine's ID number for this tax class
admin_label Warehouse lable
external_id External reference id
physical_store Optional
public_in_store Store pickup
Sample object:

Web Hooks

Shopamine can send notification to an external app via a webhook call for an specified entity create, change and delete request.

The entire Shopamine entity is sent as a POST entity or the entity Id is added to the called url.

Note: The webhook call is fire and forget (at the moment). Shopamine will not retry to call the provided url if the first call fails.

Purchase Web Hook

Purchase ID as an URL query parameter

Your provided endpoint is called with an additional parameter purchase_id
For example: https://www.example.com/your/path?purchase_id=123

Entire Purchase JSON entity

The purchase JSON entity will be added as a POST entity when calling your url: https://www.example.com/your/path.

Calling the webhook on specific status change

Firing the webhook call can be restricted on specific Purchase status, see the purchase sample object - status

RESTful API v2.1

Need help? Contact us: support@shopamine.com