Skip to main content
API docs by Redocly

Order information retrieval API (0.1.0)

Download OpenAPI specification:Download

team-order-management: team-order-management@newstore.com

Use this API to retrieve and update information related to orders being processed in the NewStore platform or via an external order management system.

sales-orders

Sales Orders

List product or shipping prices

Use this method to retrieve price information for products or shipping options, defined in items in the request payload. The price information includes the gross price of the item, the net price, and the tax levied on the item.

If the prices you requested are for products, the response payload also contains the status of the product. For example, cancelled or pending, or in_fulfillment, and so on.

Important: You can only request for the pricing information of a maximum of 500 items, exceeding which the method returns a 400 error.

Authorizations:
newStoreAccessToken
path Parameters
id
required
string

The identifier of the order.

Request Body schema: application/json
required
Array of objects or objects non-empty
Array (non-empty)
One of
type
required
string
Value: "product"
id
required
string = 36 characters

The identifier of the item.

Responses

Request samples

Content type
application/json
{
  • "value": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get order by ID and ID type

Retrieves the specified order by order ID and ID type for the order.

This method allows you to retrieve information about orders that were placed in the platform, as well as outside of the NewStore platform.

Note: In case of internal id type the API will only return orders that exists in the NewStore database and will NOT call the external OMS webhook. Furthermore, the payment_history field will be empty in this case. In case of external id type this API will check if the external OMS webhook is configured. In this case the API will fetch the order data from the configured webhook. If no external OMS is configured then the order will be fetched from the NewStore database.

Authorizations:
newStoreAccessToken
path Parameters
id
required
string

ID of the order.

query Parameters
id_type
required
string

ID type on which order should be fetched. Example "external" in case of human-readable identifier of the order, else "internal" in case of system-generated UUID (by NewStore).

header Parameters
Accept
string

Accepted values are application/json and application/x.newstore.orders+json;version=2. When application/x.newstore.orders+json;version=2 is provided, the placed_at timestamp is returned with UTC+0.

Responses

Callbacks

Response samples

Content type
Example
{
  • "id": "GD000001234",
  • "origin": "newstore",
  • "origin_id": "c2569449-1d0d-4ca5-8d00-d80c38d5efcb",
  • "channel_type": "store",
  • "placed_at": "2021-11-22T12:51:39.30",
  • "status": "closed",
  • "currency": "USD",
  • "fulfillment_type": "in_store_purchase",
  • "store_id": "NY5AVE",
  • "associate_id": "b9a144c2-3bd2-4066-983e-b2f2aa0c21e3",
  • "is_offline": false,
  • "customer": {
    },
  • "shipping_address": {
    },
  • "billing_address": {
    },
  • "items": [
    ],
  • "gift_wrapping": {
    },
  • "extended_attributes": [
    ],
  • "shipments": [
    ],
  • "totals": {
    },
  • "tax_method": "vat_included",
  • "tax_exempt": false,
  • "shop_locale": "en-us"
}

Update order information

Updates specific fields of an order.

Supported updates:

  • Order Status
Authorizations:
newStoreAccessToken
path Parameters
id
required
string

ID of the order.

Request Body schema: application/json
status
string

The new status of the order. Only on_hold is currently supported.

Responses

Request samples

Content type
application/json
{
  • "status": "string"
}

Response samples

Content type
application/problem+json
{
  • "error_code": "string",
  • "message": "string",
  • "request_id": "string"
}

Retrieve order history for customers

Authorizations:
newStoreAccessToken
query Parameters
customer_id
required
string

NewStore's unique UUID for the customer

offset
integer <int32> >= 0
Default: 0

The offset to be used for the resulting order list. Will only be accepted when using the Accept header with application/x.newstore.orders+json;version=2.

count
integer <int32> [ 1 .. 50 ]
Default: 10

The number of requested orders. Will only be accepted when using the Accept header with application/x.newstore.orders+json;version=2.

Responses

Callbacks

Response samples

Content type
Example
{
  • "pagination_info": {
    },
  • "orders": [
    ]
}

Cancel order

Initiates the cancellation of the specified order.

When using this method to cancel an order, you must specify a reason for cancellation, such as Item was damaged during shipping. You can also include a note to provide a longer explanation for the cancellation of the order.

Authorizations:
newStoreAccessToken
path Parameters
id
required
string

ID of the order.

query Parameters
id_type
required
string

Type of order id which should be used for cancellation. Example "external".

Request Body schema: application/json
reason
required
string non-empty

The reason why the order was cancelled.

note
string

An optional note.

Responses

Request samples

Content type
application/json
{
  • "reason": "Customer remorse",
  • "note": "Example note"
}

Response samples

Content type
application/problem+json
Example

Bad request because the request is not valid.

{
  • "error_code": "bad_request",
  • "message": "Validation of cancel order request failed with error: 'reason' is a required property.",
  • "request_id": "ec2f3c9bb016ba971bf6074098363"
}

Get Cancellation Status

API to get cancellation status by order ID

Authorizations:
newStoreAccessToken
path Parameters
id
required
string

ID of the order.

query Parameters
id_type
required
string

ID type on which order should be fetched. Example "external".

Responses

Response samples

Content type
application/json
{
  • "cancelable": true,
  • "canceled": false,
  • "is_safe": true
}

Update grace period

Use this method to extend the grace period timer for the specified order by 15 minutes, if the grace period of the order has not yet expired.

Authorizations:
newStoreAccessToken
path Parameters
id
required
string

ID of the order.

query Parameters
id_type
required
string

Type of the order id which should be used to extend the order grace period. Example "external" for human-readable identifiers, and "internal" for system-generated UUIDs (by NewStore).

Responses

Response samples

Content type
application/json
{
  • "due_at": "2019-08-24T14:15:22Z"
}

Add serial numbers to order items

Use this method to add serial numbers to specified items of the order. Serial numbers will be overwritten in case some or all of the items have already serial numbers attached.

The maximum number of items in this request cannot exceed 500, otherwise this method will return a 400 error.

Authorizations:
newStoreAccessToken
path Parameters
id
required
string

The internal identifier of the order, for example, b604ffda-7e31-4338-beab-7f939a8c2322.

Request Body schema: application/json
required
Array of objects (SalesOrderSerialNumbersRequestItem) [ 1 .. 500 ] items
Array ([ 1 .. 500 ] items)
id
required
string = 36 characters

The identifier of the order line item.

serial_number
required
string

The serial number which should be assigned to the specified order line item.

object (SalesOrderSerialNumbersRequestItemEpc)

The epc which should be assigned to the specified order line item.

Responses

Request samples

Content type
application/json
{
  • "value": {
    }
}

Response samples

Content type
application/problem+json
Example
{
  • "error_code": "bad_request",
  • "message": "The number of products can't exceed 500.",
  • "request_id": "ec2f3c9bb016ba971bf6074098363"
}

Cancel line items

Use this resource to cancel line items.

Note:

  1. This API currently only supports pre-ordered line items and will throw an error for other line items.
  2. The line item can only be cancelled for non-terminal item statuses.
Authorizations:
newStoreAccessToken
path Parameters
id
required
string

UUID of the order.

item_uuid
required
string

UUID of the order item.

query Parameters
id_type
required
string

Type of order id which should be used for cancellation of line items. Example "external" for human-readable identifiers, and "internal" for system-generated UUIDs (by NewStore).

Responses

Response samples

Content type
application/problem+json
Example

Bad request because the request is not valid.

{
  • "error_code": "bad_request",
  • "message": "Validation of cancel order request failed with error: 'reason' is a required property.",
  • "request_id": "ec2f3c9bb016ba971bf6074098363"
}

Cancel multiple orders in bulk

Use this resource to cancel multiple orders in bulk. This endpoint is designed for internal use by NewStore support team / agents.

Important Notes:

  • This endpoint temporarily enables DC (Distribution Center) cancellations if not already enabled
  • The original cancellation configuration is automatically restored after processing
  • Orders are assumed to be with ID type 'internal'
  • The response includes both succeeded and failed cancellations with detailed error information
  • Order can only be cancelled if it is in a state that allows cancellation (e.g. not closed, not in fulfillment)

Use Cases:

  • Bulk cancellation of orders for customer service scenarios in response to an incident that caused multiple orders to be created with wrong information
Authorizations:
newStoreAccessToken
Request Body schema: application/json
order_ids
required
Array of strings non-empty [ items non-empty ]

List of order IDs to cancel

reason
required
string non-empty

Reason for cancellation

note
string

Optional note for cancellation

Responses

Request samples

Content type
application/json
{
  • "order_ids": [
    ],
  • "reason": "Techincal issue",
  • "note": "Orders canceled in bulk due to technical issue causing multiple orders to be created with wrong information"
}

Response samples

Content type
application/json
{
  • "succeeded": [
    ],
  • "failed": [
    ]
}

external-oms-configuration

If you want to continue using your legacy order management system (OMS) for primary order fulfillment tasks, use this resource to configure NewStore as an OMS that completes the other basic order management tasks.

When NewStore is not the primary OMS for your business, you can achieve the following tasks for order routing and fulfillment:

  • Order placement and returns via NewStore Associate App. Orders placed via the app are then routed to the external OMS for fulfillment.
  • Managing payments for all orders.
  • Store fulfillment and handling shipping for orders fulfilled via stores.
  • Inventory management of stores, as NewStore will be the inventory master for your business in the stores.

When NewStore is secondary OMS, the primary OMS is responsible for the following in your business:

  • ATP, order routing, order modifications, and customer support.
  • Rerouting rejected store fulfillment orders.
  • Handling shipping for orders fulfilled from a DC or warehouse.
  • Managing payments for all order that need fulfillment. Please note that it is possible to capture payments with NewStore for in-store (no additional configuration required), endless aisle and mixed cart orders (configuration required). More information in: Mixed Cart support for 3rd party OMS.

Get external OMS configuration

Retrieves the current configuration for the external order management system enabled for the retailer.

Note: To understand what NewStore is responsible for when it is the secondary OMS for your business and an external OMs is integrated with the platform, see the API definition.

Authorizations:
newStoreAccessToken

Responses

Response samples

Content type
application/json

The external OMS is disabled for the retailer.

{
  • "value": {
    },
  • "updated_at": "2021-07-13T20:18:25Z"
}

Enable external OMS configuration

Specify that the retailer will use an external order management system configuration for order fulfillment.

If you want to disable the external OMS for the retailer, in the request payload, specify false as the value for the enabled property.

Note: To understand what NewStore is responsible for when it is the secondary OMS for your business, see the API definition.

Authorizations:
newStoreAccessToken
Request Body schema: application/json
required
object
enabled
required
boolean

Specifies if the tenant is using an external OMS.

Responses

Request samples

Content type
application/json

Enables the external OMS for the retailer.

{
  • "value": {
    }
}

Response samples

Content type
application/problem+json

The request payload failed validation.

{
  • "error_code": "bad_request",
  • "message": "Value provided should be a string.",
  • "request_id": "ec2f3c9bb016ba971bf6074098363"
}

sales-order-configuration

Use this resource to configure sales order parameters and their behavior in the NewStore platform.

Get order ID sequence parameters

Retrieves order ID sequence parameters, that are used to generate human-readable order identifiers. These are required for order processing, as unique IDs are assigned to orders in the NewStore platform via these parameters.

Authorizations:
newStoreAccessToken

Responses

Response samples

Content type
application/json

The configured order ID sequence and when it was last updated.

{
  • "value": {
    },
  • "updated_at": "2021-07-13T20:18:25Z"
}

Set order ID sequence parameters

Sets or creates order ID sequence parameters for the retailer, that are used to generate human-readable order identifiers. These are required for order processing, as unique IDs are assigned to orders in the NewStore platform via these parameters. Once the configuration was applied, it can't be changed.

Authorizations:
newStoreAccessToken
Request Body schema: application/json
required
object
prefix
string

Prefix for human-readable order identifiers.

size
integer <int64> >= 1

Size of human-readable order identifiers.

start
integer <int64> >= 1

Start of human-readable order identifiers, any value greater than 0.

step
integer <int64> >= 1

Step of human-readable order identifiers, any value greater than 0.

Responses

Request samples

Content type
application/json

Order IDs with the prefix NS and size 16, starting at 1 in steps of 2.

{
  • "value": {
    }
}

Response samples

Content type
application/json

The configured order ID sequence and when it was last updated.

{
  • "value": {
    },
  • "updated_at": "2021-07-13T20:18:25Z"
}

Get grace period for orders

Retrieves the grace period for orders in your business. This is the duration for an on hold order in seconds, after which it is routed for fulfillment.

Note: You can also set the grace period for orders via the fulfillment configuration set up for your business.

This configuration only sets a grace period for orders that do not have a grace period assigned already. A grace period for an order is usually assigned when an order is imported into NewStore from an external system, with no default routing and a service level already assigned to it.

For more information on how routing works, see About order routing and the Checkout configuration.

Authorizations:
newStoreAccessToken

Responses

Response samples

Content type
application/json

Orders are held for 20 seconds before routing.

{
  • "value": 20,
  • "updated_at": "2021-07-13T20:18:25Z"
}

Create grace period for orders

Sets the grace period for orders in your business. This is the duration for an on hold order in seconds, after which it is routed for fulfillment.

Note: You can also set the grace period for orders via the fulfillment configuration set up for your business.

This method only sets a grace period for orders that do not have a grace period assigned already. A grace period for an order is usually assigned when an order is imported into NewStore from an external system, with no default routing and a service level already assigned to it.

For more information on how routing works, see About order routing and the Checkout configuration.

Authorizations:
newStoreAccessToken
Request Body schema: application/json
value
required
integer <int32>

Timer duration in seconds

Responses

Request samples

Content type
application/json

Holds orders for 20 seconds before routing them.

{
  • "value": 20
}

Response samples

Content type
application/json

Orders are held for 20 seconds before routing.

{
  • "value": 20,
  • "updated_at": "2021-07-13T20:18:25Z"
}

List locations from which orders can be canceled

Retrieves the locations from which orders in your business can be canceled.

Note: By default, orders routed to stores can be canceled by all retailers, unless it is excluded from this configuration. If not specified in a configuration, orders cannot be canceled from DCs.

Authorizations:
newStoreAccessToken

Responses

Response samples

Content type
application/json

Orders can be canceled from stores and DCs.

{
  • "value": [
    ],
  • "updated_at": "2021-07-13T20:18:25Z"
}

Set locations from which orders can be canceled

Sets the locations from which orders in your business can be canceled.

Note: By default, orders routed to stores can be canceled by all retailers, unless it is excluded from this configuration. If not specified in a configuration, orders cannot be canceled from DCs.

Authorizations:
newStoreAccessToken
Request Body schema: application/json
value
required
Array of strings non-empty [ items non-empty ]
Items Enum: "store" "dc"

Defines from which location type orders can be canceled. By default (if no config is set) orders routed to stores can be canceled by every tenant, unless it is excluded from this list.

Responses

Request samples

Content type
application/json

Allows orders to be canceled from stores and DCs.

{
  • "value": [
    ]
}

Response samples

Content type
application/json

Orders can be canceled from stores and DCs.

{
  • "value": [
    ],
  • "updated_at": "2021-07-13T20:18:25Z"
}

Get limits on items for large orders

Retrieves the order item limits that determine if the order is routed or is considered a big order and placed on hold.

You can set the number of items an order can contain, exceeding which it is put on hold for manual approval instead of being routed. The highest limit you can set is 300, which matches the maximum number of items an order can contain.

Authorizations:
newStoreAccessToken

Responses

Response samples

Content type
application/problem+json

Orders with more than 300 items are put on hold.

{
  • "value": {
    },
  • "updated_at": "2021-07-13T20:18:25Z"
}

Set limits on items for large orders

Specifies the order item limits that determine if the order is routed or is considered a big order and placed on hold.

You can set the number of items an order can contain, exceeding which it is put on hold for manual approval instead of being routed. The highest limit you can set is 300, which matches the maximum number of items an order can contain. A higher value is rejected with 400.

Authorizations:
newStoreAccessToken
Request Body schema: application/json
required
object
soft_limit_for_big_orders
required
integer <int32> <= 300

The number of items above which an order is placed on hold for manual approval instead of being routed. The maximum accepted value is 300, matching the maximum number of items an order can contain. If not set, 100 is used as the default value.

Responses

Request samples

Content type
application/json

Puts orders with more than 300 items on hold.

{
  • "value": {
    }
}

Response samples

Content type
application/json

Orders with more than 300 items are put on hold.

{
  • "value": {
    },
  • "updated_at": "2021-07-13T20:18:25Z"
}

external-order-webhook

Use this resource to configure the webhook NewStore uses to retrieve order details and customer purchase history from an external order management system.

Get webhook configuration

Retrieves the current webhook configuration that enables NewStore to retrieve order details and customer purchase history from an external order management system. For more information, see the integration guide.

Authorizations:
newStoreAccessToken

Responses

Response samples

Content type
application/json

The configured webhook and when it was last updated.

{
  • "value": {},
  • "updated_at": "2021-07-13T20:18:25Z"
}

Set webhook configuration

Sets up the webhook configuration to enable NewStore to retrieve order details and customer purchase history from an external order management system. For more information, see the integration guide.

Note: The provided URL is a base URL, the platform will add respective routes accordingly.

To remove the webhook configuration, send {"value": null}. NewStore then serves order details and customer purchase history from its own data.

Authorizations:
newStoreAccessToken
Request Body schema: application/json
required
object or null

The webhook configuration, or null to remove it.

url
required
string <uri> non-empty

The URL used to send the request to.

api_key
required
string non-empty

The API key used for authentication.

timeout
integer <int32> <= 25

Timeout in seconds, the default is 15 and the maximum allowed value is 25.

Responses

Request samples

Content type
application/json

Webhook base URL, API key and timeout in seconds.

{}

Response samples

Content type
application/problem+json

The request payload failed validation.

{
  • "error_code": "bad_request",
  • "message": "Value provided should be a string.",
  • "request_id": "ec2f3c9bb016ba971bf6074098363"
}

customer-profile-amendments

Use this resource to manage customer profiles that are associated with orders in the NewStore platform.

Using this API, you can create a request to update the customer profile information for specified orders, and add details such as an updated name or external ID, email, or internal customer ID to the order. The order details in the NewStore platform are updated in the background, with an update rate limit of 20,000 orders/hour.

Once updated, the orders are listed for the associated customer profile in NOM or Associate App.

Important:.

  • There is no validation check for the profile details in the platform, and no external events are emitted. When using this API, ensure that the correct details are being updated for the order and associated customer, and that you reconcile these changes in any external systems that require these modifications.
  • Ensure that the customer profile exists in the platform before you add the details to an associated order via this API.

Update customer profile for order

Updates the customer profile information for the specified order.

For information about the limitations of this method, refer to the parent resource.

Note: The profile update is not persisted in the GraphQL API.

Authorizations:
newStoreAccessToken
Request Body schema: application/json
consumer_id
required
string non-empty

The internal id of the consumer profile which should be used to override the existing data. E.g. 0f18d068-8bf6-4126-a5b3-e00270f9f5d8.

display_id
required
string non-empty

The public id of the consumer profile which should be used to override the existing data. E.g. GDOLV9NG.

email
required
string <email> non-empty

The new email address which should be used to override the existing data.

orders
required
Array of strings [ 1 .. 100 ] items

A list of internal order ids for which the data should be updated.

Responses

Request samples

Content type
application/json

Assigns a customer profile to two orders.

{
  • "consumer_id": "8e0e99a2-a2ad-4328-9e59-2769aca7687a",
  • "display_id": "92292500-c666-4c8f-b54b-7a9c1bc427c8",
  • "email": "newstore@test.com",
  • "orders": [
    ]
}

Response samples

Content type
application/problem+json

The request payload failed validation.

{
  • "error_code": "bad_request",
  • "message": "Value provided should be a string.",
  • "request_id": "ec2f3c9bb016ba971bf6074098363"
}