Customer API (current) (v0)

Download OpenAPI specification:Download

List categories

Retrieves all top-level categories. A product category is product attribute that organizes products in a hierarchy. For example, a pair of trousers could belong to the following categories: Men’s Clothing > Pants > Chinos

Authorizations:

newStoreAccessToken

query Parameters

depth	integer Specifies the depth of child categories to retrieve. When omitted, all categories are returned.
locale required	string A locale code. Can be used to fetch product information in different languages.
catalog	string DEPRECATED. Use `shop` instead. The identifier of the product catalog.
shop required	string The identifier of the shop the product belongs to.

Responses

Response samples

200
206

Content type

application/json

{"application/json": [{"name": "Shoes",
"path": ["Shoes"
],
"description": "Shoe category",
"position": 1,
"images": [{"url": "https://example.com/tenant/102291/categories/shoes_01.jpg",
"identifier": "a5di5p34i2drwl",
"is_main": true
},
{"url": "https://example.com/tenant/102291/categories/shoes_02.jpg",
"identifier": "t3412423wien",
"is_main": false
},
{"url": "https://example.com/tenant/102291/categories/shoes_03.jpg",
"identifier": "ahsitn9353628",
"is_main": false
}
],
"extended_attribute": [{"name": "my_property",
"value": "my_value"
}
]
},
{"name": "Necklaces",
"path": ["necklaces",
"accessories > necklaces"
],
"description": "Necklace category",
"position": 2,
"images": [{"url": "https://example.com/tenant/102291/categories/necklaces.jpg",
"title": "necklaces",
"identifier": "tahst39y523",
"is_main": true
}
]
}
]
}

List order history

Returns the history of orders for the given customer (or consumer) stored in NewStore Cloud.

Typically, customers are created automatically when they place an order online or when they provide their email address, during an in-store purchase.

Authorizations:

newStoreAccessToken

path Parameters

id

required

string

Customer ID (uuid)

query Parameters

offset	integer >= 0 Default: 0 The page offset.
count	integer >= 1 Default: 10 The number of requested documents.

Responses

Response samples

200

Content type

application/json

{"pagination_info": {"count": 0,
"total": 0,
"offset": 0,
"prev_url": "http://example.com",
"next_url": "http://example.com"
},
"items": [{"order_uuid": "stringstringstringstringstringstring",
"order_id": "string",
"channel": "string",
"channel_type": "string",
"external_order_id": "string",
"customer_uuid": "stringstringstringstringstringstring",
"external_customer_id": "string",
"created_at": "2019-08-24T14:15:22Z",
"created_by_label": "string",
"taxation": "net",
"status_label": "string",
"status_description": "string",
"shipping_address": {"id": "string",
"title": "string",
"suffix": "string",
"salutation": "string",
"first_name": "string",
"second_name": "string",
"last_name": "string",
"address_line_1": "string",
"address_line_2": "string",
"province": "string",
"state": "string",
"zip_code": "string",
"city": "string",
"country_code": "AD",
"phone": "string"
},
"billing_address": {"id": "string",
"title": "string",
"suffix": "string",
"salutation": "string",
"first_name": "string",
"second_name": "string",
"last_name": "string",
"address_line_1": "string",
"address_line_2": "string",
"province": "string",
"state": "string",
"zip_code": "string",
"city": "string",
"country_code": "AD",
"phone": "string",
"email": "string"
},
"payments": [{"uuid": "stringstringstringstringstringstring",
"currency": "str",
"method": "string",
"payment_detail": "string",
"credit_card_number": "stri",
"instrument_id": "string",
"status_label": "string",
"status_description": "string"
}
],
"totals": {"merchandise_total": 0,
"shipping_total": 0,
"shipping_taxes": 0,
"taxes": 0,
"order_total": 0,
"gift_wrapping_taxes": 0,
"gift_wrapping_total": 0,
"grand_total": 0,
"currency": "str"
},
"shipments": [{"shipment_uuid": "stringstringstringstringstringstring",
"shipping_from": "string",
"links": {"return_label": "string",
"invoice": "string",
"sales_receipt": "string"
},
"price": {"net": 0,
"tax": 0,
"gross": 0,
"base": 0,
"adjustment": 0,
"adjusted_total": 0,
"currency": "str"
},
"totals": {"merchandise_total": 0,
"shipping_total": 0,
"shipping_taxes": 0,
"taxes": 0,
"order_total": 0,
"gift_wrapping_taxes": 0,
"gift_wrapping_total": 0,
"grand_total": 0,
"currency": "str"
},
"details": {"carrier": "string",
"method": "string",
"delivery_forecast_at": "2019-08-24T14:15:22Z",
"delivery_status_label": "Pending",
"delivery_status_id": "pending",
"delivery_status_date": "2019-08-24T14:15:22Z",
"delivered_at": "2019-08-24T14:15:22Z",
"shipping_packages": [{"shipment_id": "string",
"tracking_code": "string",
"carrier": "string",
"tracking_url": "http://example.com",
"delivery_from": "2019-08-24T14:15:22Z",
"delivery_to": "2019-08-24T14:15:22Z",
"delivered_at": "2019-08-24T14:15:22Z",
"product_ids": ["string"
],
"links": {"return_label": "string",
"return_form": "string"
}
}
]
},
"items": [{"id": "string",
"name": "string",
"image": "string",
"price": {"net": 0,
"tax": 0,
"gross": 0,
"base": 0,
"adjustment": 0,
"adjusted_total": 0,
"currency": "str",
"catalog": 0
},
"category": "string",
"variation_color_value": "string",
"variation_size_value": "string",
"variation_attribute_1_value": "string",
"variation_attribute_2_value": "string",
"product_sku": "string",
"extended_attributes": [{"name": "string",
"value": "string"
}
],
"custom_attributes": [{"name": "string",
"value": "string"
}
],
"discounts": [{"promotion_uuid": "stringstringstringstringstringstring",
"price_adjustment": 0,
"reason": "string",
"action": "fixed",
"value": 0,
"level": "item",
"coupon_code": "string",
"external_ref": "string"
}
],
"quantity": 0
}
],
"products": [{"id": "string",
"name": "string",
"image": "string",
"price": {"net": 0,
"tax": 0,
"gross": 0,
"base": 0,
"adjustment": 0,
"adjusted_total": 0,
"currency": "str",
"catalog": 0
},
"category": "string",
"variation_color_value": "string",
"variation_size_value": "string",
"variation_attribute_1_value": "string",
"variation_attribute_2_value": "string",
"product_sku": "string",
"extended_attributes": [{"name": "string",
"value": "string"
}
],
"custom_attributes": [{"name": "string",
"value": "string"
}
],
"discounts": [{"promotion_uuid": "stringstringstringstringstringstring",
"price_adjustment": 0,
"reason": "string",
"action": "fixed",
"value": 0,
"level": "item",
"coupon_code": "string",
"external_ref": "string"
}
]
}
],
"returns": [{"return_id": "string",
"items": [{"product_id": "string",
"quantity": 0,
"returned_at": "2019-08-24T14:15:22Z",
"return_code": 0,
"return_reason": "string"
}
],
"refund_note": "string"
}
],
"accounting_entity": {"id": "string",
"accounting_address": {"id": "string",
"title": "string",
"suffix": "string",
"salutation": "string",
"first_name": "string",
"second_name": "string",
"last_name": "string",
"address_line_1": "string",
"address_line_2": "string",
"province": "string",
"state": "string",
"zip_code": "string",
"city": "string",
"country_code": "AD",
"phone": "string"
}
},
"store_address": {"address_line_1": "string",
"address_line_2": "string",
"province": "string",
"state": "string",
"zip_code": "string",
"city": "string",
"country_code": "AD",
"latitude": 0,
"longitude": 0
},
"discounts": [{"promotion_uuid": "stringstringstringstringstringstring",
"price_adjustment": 0,
"reason": "string",
"action": "fixed",
"value": 0,
"level": "item",
"coupon_code": "string",
"external_ref": "string"
}
]
}
],
"value_added_services": [{"service_type": "string",
"options": { },
"price": {"net": 0,
"tax": 0,
"gross": 0,
"base": 0,
"adjustment": 0,
"adjusted_total": 0,
"currency": "str"
}
}
],
"ordered_products": [{"id": "string",
"name": "string",
"image": "string",
"price": {"net": 0,
"tax": 0,
"gross": 0,
"base": 0,
"adjustment": 0,
"adjusted_total": 0,
"currency": "str",
"catalog": 0
},
"category": "string",
"variation_color_value": "string",
"variation_size_value": "string",
"variation_attribute_1_value": "string",
"variation_attribute_2_value": "string",
"product_sku": "string",
"extended_attributes": [{"name": "string",
"value": "string"
}
],
"custom_attributes": [{"name": "string",
"value": "string"
}
],
"discounts": [{"promotion_uuid": "stringstringstringstringstringstring",
"price_adjustment": 0,
"reason": "string",
"action": "fixed",
"value": 0,
"level": "item",
"coupon_code": "string",
"external_ref": "string"
}
],
"quantity": 0
}
],
"extended_attributes": [{"name": "string",
"value": "string"
}
]
}
]
}

List products

Returns a list of products via the Search API.

Authorizations:

newStoreAccessToken

query Parameters

path	string Example: path=All > Men > Tops The path of the category to return products from. The value needs to be URL encoded. You can fetch subcategories as shown in the below examples: `All > Men > T-shirts > Rafa Tennis T-shirts` `All > Women > Hats > Burton Hats`
q	string A search term to restrict products.
show_variations	boolean Flag to return the `variations` field.
show_variation_attributes	boolean Flag to return the `variation_attributes` field.
is_preorder	boolean Flag to filter by `is_preorder`.
locale required	string A locale code. Can be used to fetch product information in different languages.
catalog	string DEPRECATED. Use `shop` instead. The identifier of the product catalog.
shop required	string The identifier of the shop the product belongs to.
offset	integer >= 0 Default: 0 The page offset.
count	integer >= 1 Default: 10 The number of requested documents.
sort	string Sorts the returned values. Takes two values separated by the pipe character (`\|`), the field to sort and the sort order.
location_id	string Use Stock on Hand values from this location using sorting or filtering by Stock on Hand.
min_soh	integer Minimum (inclusive) Stock on Hand.
facetfilter[variation_size_value]	string Comma-separated values of different sizes to match.
facetfilter[variation_color_value]	string Comma-separated values of different colors to match.
facetfilter[<fieldname>]	string Comma-separated values of different attribute values to apply. The name of the supported fields are in the Import API's `filterable_fields` property.

Responses

Response samples

200

Content type

application/json

{"pagination_info": {"count": 0,
"total": 0,
"offset": 0,
"prev_url": "http://example.com",
"next_url": "http://example.com"
},
"items": [{"product_id": "string",
"is_available": true,
"title": "string",
"images": [{"url": "http://example.com",
"title": "string",
"identifier": "string",
"is_main": true,
"alt_text": "string",
"dominant_color": "string",
"width": 0,
"height": 0,
"aspect_ratio": 0,
"tags": ["string"
]
}
],
"preorder_start": "2020-03-16T05:00:14Z",
"online_from": "2021-01-01T17:00:00Z",
"online_to": "2021-12-01T10:01:00Z",
"price": 0,
"currency_code": "string",
"markdown_price": 0,
"main_category_path": ["string"
],
"main_category_full_path": "string",
"main_category_position": 0,
"material": "string",
"country_of_origin": "string",
"product_hts_number": "string",
"schedule_b": "string",
"caption": "string",
"description": "string",
"extended_attributes": [{"name": "string",
"value": "string"
}
],
"variations": [{"product_id": "string",
"is_available": true,
"variation_color_value": "string",
"color_swatch": {"url": "http://example.com",
"alt_text": "string",
"title": "string",
"dominant_color": "string",
"width": 0,
"height": 0,
"aspect_ratio": 0
},
"variation_size_value": "string",
"variation_size_gender": "male",
"variation_size_type": "string",
"variation_size_system": "string",
"variation_additional_1_value": "string",
"variation_additional_2_value": "string",
"price": 0,
"markdown_price": 0
}
],
"is_preorder": true,
"serialized_inventory": true,
"variable_pricing": true,
"inventory_tracked": true
}
],
"facets": [{"field": "string",
"type": "string",
"values": [{"value": "string",
"count": 0
}
]
}
]
}

Get product details

Returns product detail information including product variant specific information (prices, quantities, ...).

Authorizations:

newStoreAccessToken

path Parameters

type required	string The type of the external ID. It must contain `=`. The product ID is denoted by the `id` parameter. To use the internal ID, remove the `type` parameter (including the `=`).
id required	string The product identifier. By default, it must be the internal product ID. To use an external ID, set the `type` parameter. Important: When retrieving a product whose id contains special characters (reserved, unreserved, and escaped characters based on the RFC guidelines, the value of the product ID must be encoded. For more information, see Section 2.1 in the RFC guidelines.

query Parameters

include_variations	boolean Whether to include/populate the product's variations field or not. Variations are included by default.
show_hidden	boolean Default: false Return details even if the product is hidden in catalog listings.
locale required	string A locale code. Can be used to fetch product information in different languages.
catalog	string DEPRECATED. Use `shop` instead. The identifier of the product catalog.
shop required	string The identifier of the shop the product belongs to.

Responses

Response samples

200

Content type

application/json

{"product_id": "string",
"variant_group_id": "string",
"is_available": true,
"categories": [{"path": ["string"
],
"full_path": "string",
"position": 0
}
],
"main_category_path": ["string"
],
"main_category_full_path": "string",
"main_category_position": 0,
"external_identifiers": {"sku": "string",
"gtin": "string",
"upc": "string",
"ean13": "string",
"jan": "string",
"isbn": "string",
"additionalProperties": "string"
},
"extended_attributes": [{"name": "string",
"value": "string"
}
],
"sku": "string",
"title": "string",
"brand": "string",
"caption": "string",
"description": "string",
"keywords": ["string"
],
"images": [{"url": "http://example.com",
"title": "string",
"identifier": "string",
"is_main": true,
"alt_text": "string",
"dominant_color": "string",
"width": 0,
"height": 0,
"aspect_ratio": 0,
"tags": ["string"
]
}
],
"gtin": "string",
"template_id": "string",
"price": 0,
"currency_code": "string",
"tax_class_id": "string",
"preorder_start": "2020-03-16T05:00:14Z",
"online_from": "2021-01-01T17:00:00Z",
"online_to": "2021-12-01T10:01:00Z",
"variation_color_value": "string",
"color_swatch": {"url": "http://example.com",
"alt_text": "string",
"title": "string",
"dominant_color": "string",
"width": 0,
"height": 0,
"aspect_ratio": 0
},
"variation_size_value": "string",
"variation_size_gender": "male",
"variation_size_type": "string",
"variation_size_system": "string",
"variation_additional_1_value": "string",
"variation_additional_2_value": "string",
"markdown_price": 0,
"product_hts_number": "string",
"schedule_b": "string",
"variation_attributes": {"variation_color_values": ["string"
],
"variation_size_values": ["string"
],
"variation_additional_1_name": "string",
"variation_additional_1_values": ["string"
],
"variation_additional_2_name": "string",
"variation_additional_2_values": ["string"
]
},
"variations": [{"product_id": "string",
"is_available": true,
"variation_color_value": "string",
"color_swatch": {"url": "http://example.com",
"alt_text": "string",
"title": "string",
"dominant_color": "string",
"width": 0,
"height": 0,
"aspect_ratio": 0
},
"variation_size_value": "string",
"variation_size_gender": "male",
"variation_size_type": "string",
"variation_size_system": "string",
"variation_additional_1_value": "string",
"variation_additional_2_value": "string",
"price": 0,
"markdown_price": 0
}
],
"shipping_weight_value": 0,
"shipping_weight_unit": "g",
"is_preorder": true,
"serialized_inventory": true,
"variable_pricing": true,
"inventory_tracked": true
}

Get prices

Retrieves price information for a list of products.

Authorizations:

newStoreAccessToken

query Parameters

product_id required	Array of strings
pricebook required	string
catalog	string DEPRECATED. Use `shop` instead. The identifier of the product catalog.
shop required	string The identifier of the shop the product belongs to.

Responses

Response samples

200

Content type

application/json

{"items": [{"product_id": "string",
"value": 0,
"currency_code": "string",
"traits": ["string"
]
}
]
}

List locales

Retrieves the locales/translations available in a given shop.

Authorizations:

newStoreAccessToken

query Parameters

catalog	string DEPRECATED. Use `shop` instead. The identifier of the product catalog.
shop required	string The identifier of the shop the product belongs to.

Responses

Response samples

200

Content type

application/json

{"locales": ["string"
]
}

List currencies

Retrieves the currencies available in a given shop.

Authorizations:

newStoreAccessToken

query Parameters

catalog	string DEPRECATED. Use `shop` instead. The identifier of the product catalog.
shop required	string The identifier of the shop the product belongs to.

Responses

Response samples

200

Content type

application/json

{"currency_codes": ["string"
]
}

List shops

Retrieves all shops configured for your business, along with the associated locales and pricebooks.

Authorizations:

newStoreAccessToken

Responses

Response samples

200

Content type

application/json

[{"id": "string",
"locales": [{"locale": "string",
"display_name": "string",
"is_master": true
}
],
"pricebooks": [{"id": "string",
"currency_code": "string"
}
]
}
]

Get shop

Retrieves the specified shop along with the associated locales and pricebooks.

Authorizations:

newStoreAccessToken

path Parameters

shop

required

string

The identifier of the shop to be returned.

Responses

Response samples

200

Content type

application/json

{"id": "string",
"locales": [{"locale": "string",
"display_name": "string",
"is_master": true
}
],
"pricebooks": [{"id": "string",
"currency_code": "string"
}
]
}