ideal.shop API documentation

Make your calls to https://your-shop-domain.com/api/{endpoint}
Eg. https://your-shop-domain.com/api/orders

Authorization is required
Combine the username and secret, of your API user, in the following format: username:secret - Base64 encode the resulting string and use it in the HTTP Authentication header 
Example:
Authorization: Basic dXNlcm5hbWU6c2VjcmV0

Idempotency (optional) [beta]
API requests to the APIs can be retried without any side effects by providing an Idempotency-Key in the header
For example, in case the request fails because of network error, it can safely be retried with the same Idempotency-Key without causing a duplicate action. 
Idempotency-Key: A-unique-string-no-longer-than-64-chars
Within the first 5 minutes the original response will be returned
After that, a 400 error will be returned

cURL GET example
curl -X GET \
'https://your-shop-domain.com/api/orders' \
-H 'Authorization: Basic xxxxxxxxxxxxxxxxxx'

cURL PUT example
curl -X PUT \
'https://your-shop-domain.com/api/items/stock/16522' \
-H 'Authorization: Basic xxxxxxxxxxxxxxxxxxxxxx' \
-d 'stock=123'

GETs
When performing a GET (not all though), it's possible to only get some fields back, instead of all of them This is done using &fields_to_get[]=id&fields_to_get[]=time_created etc. Can also be JSON encoded - &fields_to_get=["id","time_created"] 
Example:
curl -X GET \
'https://your-shop-domain.com/api/orders?fields_to_get[]=id&fields_to_get[]=shop_order_number' \
-H 'Authorization: Basic xxxxxxxxxxxxxxxxxx'

time_deleted
Sometimes you'll get entries where time_deleted is more than zero, indicating that the entry was deleted
We still send those entries, because you might need it, with regard to older orders, etc.


Items

get
/items
Get items
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
page Pagination page query integer 1 No
page_size Posts per page query integer 20 No
Response Parameters
Parameter Description Data Type
id ID integer
item_number Item number string
weight Weight double
weight_net Weight net. double
url URL to the product string
post
/items
Create a new item
Create a new item

Example: 
&category_id=123&title={"da-DK":"Det danske varenavn","en-GB":"The english item name"}
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
title The titles for each language form json Yes
category_id The primary category form integer -1 No
delete
/items/{id}
Delete an item
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
id Id of the item to delete path integer Yes
put
/items/{id}
Update an item (BETA)
Content type of the request must be "application/json"
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
id Id of the item to update path integer Yes
active Should the item be active or inactive form integer No
primary_category Id of the primary category form integer No
secondary_categories Array of ids for the secondary categories form integer[] No
item_number Items item number form string No
sku Items SKU form string No
gtin Items GTIN/EAN form string No
mpn Items MPN form string No
brand Items Brand form string No
price Price of item in different currencies (excluding VAT), e.g. price[dkk] = 1.23 form double[currency_iso] No
cost_price Cost price of item in the shops primary currency (excluding VAT) form double No
vat_groups_id VAT group id to use form integer No
weight Weight (gross) of the item form double No
weight_net Weight (netto) of the item form double No
weight_unit Weight unit of the item form enum(g, kg, oz, lb) No
quantity_select_limit_min Minimum of item that must be purchased form integer No
quantity_select_limit_max Maximum of item that can be purchased form integer No
stock Stock of the item, will be added to the primary stock location form integer No
order_if_empty_stock Can the item be ordered even if it is out of stock form integer No
automatic_stock_control Should automatic stock control be enabled form integer No
time_expected_stock Time (in unix_timestamp) where stock is expected to be back form integer No
make_inactive_if_sold_out Should the item be made inactive if stock is sold out form integer No
email_when_stock_reaches_threshold Stock minimum notification form integer No
email_when_stock_reaches_threshold_max Stock maximum notification form integer No
title Title of the item in different languages, e.g. title[da-DK] = Navn på vare form string[language_iso] No
description_short Description of the item (short) in different languages, e.g. description_short[da-DK] = Kort beskrivelse af vare form string[language_iso] No
description_long Description of the item (long) in different languages, e.g. description_long[da-DK] = Lang beskrivelse af vare form string[language_iso] No
tags Tags/search words of the item in different languages, e.g. tags[da-DK] = Kanin, Legetøj, Stor form string[language_iso] No
stock_info_text Picking slip text for the item in different languages, e.g. stock_info_text[da-DK] = På hylde 245 form string[language_iso] No
url The url/path of the item in different languages, e.g. url[da-DK] = /webshop/kategorinavn/testvare1 form string[language_iso] No
meta_title The item pages title tag in different languages, e.g. roadmap_title[da-DK] = Navn på vare form string[language_iso] No
meta_description Meta description of the item in different languages, e.g. meta_description[da-DK] = En rigtig god vare form string[language_iso] No
og_title OG title of the item in different languages, e.g. og_title[da-DK] = Navn på vare form string[language_iso] No
og_description OG description of the item in different languages, e.g. og_description[da-DK] = En rigtig god vare form string[language_iso] No
put
/items/price/{id}
Update item prices
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
id ID path integer Yes
price_single Update price excl. VAT for this item in the shops default currency form double Yes
put
/items/stock/{id}
Update item stock
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
id ID path integer Yes
stock Stock set specific form integer No
stock_add Stock add form integer No
stock_remove Stock remove form integer No
stock_location_id Stock location to update, if not sent, the primary location is updated form integer No
put
/items/texts/{id}
Update item texts
Update texts for this item

Example: 
&texts={"title":{"en-GB":"New title in english"},"description_short":{"da-DK":"Kort beskrivelse på dansk<br>Ny linje","en-GB":"Short description in english<br>New line"},"description_long":{"da-DK":"Lang beskrivelse på dansk<br>Ny linje","en-GB":"Long description in english<br>New line"}}
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
id ID path integer Yes
texts The texts (with locale) to update form json Yes
get
/items/offers/{id}
Get item offers
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
id Item id path integer Yes
Response Parameters
Parameter Description Data Type
offers Array of offers that this item has array
put
/items/offers/{id}
Update item offers
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
id Item id path integer Yes
offers Complete array of offers that this item should have. eg: &offers=[{"time_start":0,"time_end":0,"prices":{"dkk":"200.22"}},{"time_start":1636975050,"time_end":0,"prices":{"dkk":"100.11","sek":"95.11"}}] form JSON array Yes
get
/items/{id}/images
Get images on item
Response Parameters
Parameter Description Data Type
id ID integer
hash Hash string
filename Filename string
filesize Filesize in bytes int
time_created Time created (UNIX timestamp) int
width Width of the image in px int
height Height of the image in px int
url URL to the image string
post
/items/{id}/images
Add image to an item (BETA)
Content type of the request must be "application/json"
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
image_filename Image filename (e.g. an-awesome-image.jpg) form string Yes
image_data_b64 Image data base64 encoded form string Yes
alt_text Alt text for the image in different languages, e.g. alt_text[da-DK] = En kanin form string[language_iso] No
post
/items/{id}/variants
Create variants under an item (BETA)
Content type of the request must be "application/json"



Minimal example:
must-be-replaced-with-an-id must be replaced with ids from items_characteristics "Use POST /items_characteristics to create them" 
{"variants":[{"title":{"da-DK":"Min nye variant - R\u00f8d \/ Stor","en-Gb":"My new variant - Red \/ Large"},"price":{"dkk":14.99,"eur":2.49},"stock":2,"items_characteristics":[{"id":"must-be-replaced-with-an-id","title":{"da-DK":"R\u00f8d","en-GB":"Red"}},{"id":"must-be-replaced-with-an-id","title":{"da-DK":"Stor","en-GB":"Large"}}]},{"title":{"da-DK":"Min nye variant - Gr\u00f8n \/ Stor","en-Gb":"My new variant - Green \/ Large"},"price":{"dkk":14.99,"eur":2.49},"stock":2,"items_characteristics":[{"id":"must-be-replaced-with-an-id","title":{"da-DK":"Gr\u00f8n","en-GB":"Green"}},{"id":"must-be-replaced-with-an-id","title":{"da-DK":"Stor","en-GB":"Large"}}]}]}
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
variants An array of the variants to create form array Yes
variants[][active] Should the variant be active or inactive form int 0 No
variants[][automatic_title] Should the title be generated based on the title of the characteristics form int 1 No
variants[][item_number] The variants item number form string No
variants[][sku] Variants SKU form string No
variants[][gtin] Variants GTIN/EAN form string No
variants[][weight] Weight (gross) of the variant form double No
variants[][weight_net] Weight (netto) of the variant form double No
variants[][price] Price of variant in different currencies (excluding VAT), e.g. price[dkk] = 1.23 form double[currency_iso] No
variants[][cost_price] Cost price of variant in the shops primary currency (excluding VAT) form double No
variants[][sort] Sorting of the variant within the item form int No
variants[][stock] Stock of the variant, will be added to the primary stock location form int No
variants[][email_when_stock_reaches_threshold] Stock minimum notification form int 0 No
variants[][email_when_stock_reaches_threshold_max] Stock maximum notification form int 0 No
variants[][automatic_stock_control] Should the stock of the variant be automatically adjusted when an order is made form int 0 No
variants[][order_if_empty_stock] Should it be possible to order the variant even if it is out of stock form int 0 No
variants[][make_inactive_if_sold_out] Should the variant be made inactive if it is sold out form int 0 No
variants[][items_characteristics] An array of the characteristics of this variant form int Yes
variants[][items_characteristics][][id] items_characteristics.id form int Yes
variants[][items_characteristics][][title] Title in different languages form string[language_iso] Yes
variants[][title] Title of the variant in different languages form string[language_iso] No
variants[][stock_info_text] Picking slip text for the variant in different languages form string[language_iso] No
get
/items/customer_group_prices/{id}
Get customer group prices
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
id Item id path integer Yes
Response Parameters
Parameter Description Data Type
customer_group_prices Array of customer group prices that this item has array
customer_group_prices[][id] Id of the customer group integer
customer_group_prices[][name] Name of the customer group string
customer_group_prices[][active] If the customer group is active integer
customer_group_prices[][item_available_for_group] If item is available for that customer group integer
customer_group_prices[][default_group] If the customer group is the default group integer
customer_group_prices[][prices] An array of the prices that this customer group has on this item array
customer_group_prices[][prices][currency_iso] The currency that this price is in string
customer_group_prices[][prices][price] The price without VAT double
put
/items/customer_group_prices/{id}
Update customer group prices
Content type of the request must be "application/json"



Minimal example: 
{"customer_group":12345,"item_available_for_group":1,"prices":[{"currency_iso":"dkk","price":12.99},{"currency_iso":"eur","price":1.33}]}
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
id Item id path integer Yes
customer_group id of the customer group to change form integer Yes
item_available_for_group Should the item be available for this group form integer Yes
prices An array of all prices that this customer group should have form array Yes
prices[][currency_iso] The currency to use form string Yes
prices[][price] The price without VAT to use form double Yes

Items categories

post
/categories
Create a new category (BETA)
Create a new category

Example: 
&parent_id=123&title={"da-DK":"Mit danske kategorinavn","en-GB":"My english category name"}
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
title The titles for each language form json Yes
parent_id The parent category id (set to 0 to create a root category) form integer 0 No
put
/categories/{id}
Update a category (BETA)
Content type of the request must be "application/json"
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
id Id of the category to update path integer Yes
active Should the category be active or inactive form integer No
sort Sorting of the item in its category 0 = First in category form integer No
parent_id The parent category id (set to 0 to place this in the root category) form integer 0 No
title Title of the category in different languages, e.g. title[da-DK] = Navn på kategori form string[language_iso] No
description Description of the category (shown at the top) in different languages, e.g. description[da-DK] = Beskrivelse af kategori form string[language_iso] No
description_bottom Description of the category (shown at the bottom) in different languages, e.g. description_bottom[da-DK] = Beskrivelse af kategori form string[language_iso] No

Items categories

get
/categories_aggregated
Get items categories
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
ids Category ids query array No
page Pagination page query integer 1 No
page_size Posts per page query integer 20 No
language The language to return data in, da-DK, en-GB, etc. query string No
Response Parameters
Parameter Description Data Type
categories An array of categories array
language The used language string

Items with variants

get
/items_aggregated
Get items with variants
Note:
type = normal, booking, giftcard or subscription (only 'normal' should be purchasable via API)
show_price = 'false' should not be purchasable via API
can_be_bought = 'false' should not be purchasable via API

Request Parameters
Parameter Description Parameter Type Data Type Default Required?
ids Item ids query array No
item_numbers Item numbers query array No
variant_ids Variant ids query array No
variant_item_numbers Variant item numbers query array No
include_more_texts Will include additional texts: stock_info_text query int 0 No
time_updated Only get entries younger than the given timestamp, or if array in the given period query int or array No
time_stock_updated Only get entries that had stock updated since the given timestamp, or if array in the given period query int or array No
page Pagination page query integer 1 No
page_size Posts per page query integer 20 No
language The language to return data in, da-DK, en-GB, etc. query string No
currency The currency to return data in, DKK, EUR, etc. query string No
Response Parameters
Parameter Description Data Type
items An array of items array
items[variants] An array of variants the item has array
language The used language string
currency The used currency string

Items characteristics

get
/items_characteristics
Get item characteristic (BETA)
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
ids Item characteristic ids to get query array No
page Pagination page query integer 1 No
page_size Posts per page query integer 20 No
language The language to return data in, da-DK, en-GB, etc. query string No
Response Parameters
Parameter Description Data Type
item_characteristics An array of item characteristics array
language The used language string
post
/items_characteristics
Create an item characteristic (BETA)
Content type of the request must be "application/json"
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
name Internal name of the characteristic form string Yes
type Type of characteristic (values / values-multi / range) form enum values-multi No
sort_type The way that this characteristic should be sorted (alphabetical / clothes / natural) form enum alphabetical No
title Title of the characteristic in different languages, e.g. title[da-DK] = Navn på vare egenskab form string[language_iso] No
type_unit The unit of this range in different languages, e.g. type_unit[da-DK] = Centimeter (Only relevant when type is set to range) form string[language_iso] No

Items variants

put
/items_variants/price/{id}
Update item variant prices
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
id ID path integer Yes
price_single Set/update base price excl. VAT for this variant in the shops default currency form double Yes
put
/items_variants/stock/{id}
Update item variant stock
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
id ID path integer Yes
stock Stock set specific form integer No
stock_add Stock add form integer No
stock_remove Stock remove form integer No
stock_location_id Stock location to update, if not sent, the primary location is updated form integer No
get
/items_variants/images/{id}
Get images on item variant
Response Parameters
Parameter Description Data Type
id ID integer
hash Hash string
filename Filename string
filesize Filesize in bytes int
time_created Time created (UNIX timestamp) int
width Width of the image in px int
height Height of the image in px int
url URL to the image string
put
/items_variants/images/{id}
Define which images should be used on item variant
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
use_images_from_item If set to 1, this variant will just use the images from the item form int No
image_ids_to_use An array of image_ids, from the item, that this variant should use form int[] No
get
/items_variants/offers/{id}
Get item variant offers
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
id Variant id path integer Yes
Response Parameters
Parameter Description Data Type
offers Array of offers that this item variant has array
put
/items_variants/offers/{id}
Update item variant offers
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
id Variant id path integer Yes
offers Complete array of offers that this variant should have. eg: &offers=[{"time_start":0,"time_end":0,"prices":{"dkk":"200.22"}},{"time_start":1636975050,"time_end":0,"prices":{"dkk":"100.11","sek":"95.11"}}] form JSON array Yes

Customer groups

get
/customer_groups
Get customer groups
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
ids Customer group ids to get query array No
page Pagination page query integer 1 No
page_size Posts per page query integer 1000 No
Response Parameters
Parameter Description Data Type
customer_groups An array of customer groups array
customer_groups[][id] Id of the customer group integer
customer_groups[][name] Name of the customer group string
customer_groups[][active] If the customer group is active integer
customer_groups[][default_group] If the customer group is the default group integer

Customer addresses

get
/customers_addresses/{id}
Get customer address
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
id ID path integer Yes
Response Parameters
Parameter Description Data Type
id ID integer
customers_id Customer ID integer
type billing/shipping string
name Name string
company Company string
vat_id VAT ID string
ean EAN string
address Address string
address2 Address2 string
zip Zip string
city City string
country Country (ISO 3166-1 alpha-2) string
email Email string
phone Phone string

Newsletter receivers

get
/newsletter_receivers
Get all newsletter receivers
Response Parameters
Parameter Description Data Type
email The email address string
name The name string
source How the recipient was obtained (empty for very old entries) string
language da-DK, en-GB, de-DE, etc. string
time_created Created time integer

Orders

get
/orders
Get orders
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
page Pagination page query integer 1 No
page_size Posts per page query integer 20 No
sort_by Property to sort by query string id No
sort_dir Sort direction query string (asc, desc) desc No
status_id Get orders with specific status ID query integer No
email Get orders related to email query string No
Response Parameters
Parameter Description Data Type
id ID integer
shop_order_number Order number integer
invoice_number Invoice number (0 if not yet created) integer
status_id Status ID integer
address_billing_id ID of the billing address (use /customers_addresses endpoint) integer
address_shipping_id ID of the shipping address (use /customers_addresses endpoint) integer
shipping_method_id Shipping method id integer
payment_method_id Payment method id integer
amount_total Order total amount with VAT decimal
amount_total_without_vat Order total amount without VAT decimal
currency_order Order currency string
customer_language Customer language string
time_created Order created time integer
time_paid Order paid time integer
time_captured Order payment captured time integer
time_invoice Order invoice created time integer
time_last_status_change Order last status change time integer
test_order Test order (1=Yes) integer
overwritten_delivery_address If delivery adresse is overwritten because of package shop, then this will be filled with a JSON string string
weight_gross_in_grams Weight of the order in grams integer
address_billing_custom A JSON array of any custom fields this billing address might have string
address_shipping_custom A JSON array of any custom fields this shipping address might have string
amount_shipping_with_vat Shipping cost with VAT decimal
amount_shipping_without_vat Shipping cost without VAT decimal
amount_payment_with_vat Payment cost with VAT decimal
amount_payment_without_vat Payment cost without VAT decimal
patch
/orders/{id}/status
Set a new status for the order
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
status_id form int No
get
/orders/status_types
Get order status types
Response Parameters
Parameter Description Data Type
id ID integer
name Name string
get
/orders/{id}/shipping_tracking_url
Get shipping tracking urls
put
/orders/{id}/shipping_tracking_url
Update shipping tracking url
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
shipping_tracking_url Must be a full URL, including http(s):// form string No

Order lines

get
/orders_lines
Get an orders lines
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
orders_id The orders id query integer No
shop_order_number The orders number query integer No
language The language to return data in, da-DK, en-GB, etc. query string No
currency The currency to return data in, DKK, EUR, etc. query string No
Response Parameters
Parameter Description Data Type
lines An array of order lines array
language The used language string
currency The used currency string

Payment methods

get
/payment_methods
Get payment methods
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
id Id of a specific payment method query integer No
page Pagination page query integer 1 No
page_size Posts per page query integer 20 No
sort_by Property to sort by query string id No
sort_dir Sort direction query string (asc, desc) desc No
language The language to return data in, da-DK, en-GB, etc. query string No
Response Parameters
Parameter Description Data Type
id ID integer
type_id Type ID integer
type_name Type Name string
title Title string
description_short Description short string
description_email Description email string
time_created Created time integer
time_updated Updated time integer
time_deleted Deleted time integer

Shipping methods

get
/shipping_methods
Get shipping methods
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
page Pagination page query integer 1 No
page_size Posts per page query integer 20 No
sort_by Property to sort by query string id No
sort_dir Sort direction query string (asc, desc) desc No
language The language to return data in, da-DK, en-GB, etc. query string No
Response Parameters
Parameter Description Data Type
id ID integer
type_id Type ID integer
type_name Type Name string
title Title string
description_short Description short string
description_email Description email string
time_created Created time integer
time_updated Updated time integer
time_deleted Deleted time integer

Videos

get
/videos
Get videos
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
page Pagination page query integer 1 No
page_size Posts per page query integer 20 No
Response Parameters
Parameter Description Data Type
id ID integer
type Video type string
location Hash/location string
get
/videos/{type}
Get videos of {type}
Request Parameters
Parameter Description Parameter Type Data Type Default Required?
page Pagination page query integer 1 No
page_size Posts per page query integer 20 No
type Video type path string Yes
Response Parameters
Parameter Description Data Type
id ID integer
type Video type string
location Hash/location string