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

Use this resource to retrieve and manage sales order resources.

Note: To receive the placed_at timestamp in UTC+0 in the format YYYY-MM-DDThh:mm:ss.sZ, please provide the Accept header application/x.newstore.orders+json;version=2.

Use type internal to retrieve orders by the system-generated UUID (by NewStore), and use type external to retrieve orders by the human-readable identifier.

Retrieve the order history for the customer identified by their ID (customer_id).

The order list is sorted by the date the order was placed (placed_at), with the newest order appearing first.

By default, the API responds with the application/json content type and only supports tenants that are integrated with an external Order Management System (OMS).

You can use this resource to list product or shipping prices, cancel an order or extend its grace period, and add serial numbers or items in the order.

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": [
    ]
}