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 information related to orders being processed in the NewStore platform or via an external order management system.

Orders by ID and type

Use this resource to retrieve orders using the order ID and type of ID. 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.

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.

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

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"
}

Order history for customers

Retrieve the order history for the customer identified by their ID (customer_id). If the tenant is configured to use Personally Identifiable Information (PII) in a data privacy compliant way, use the PII token for the customer ID. Otherwise, use the platform's internal identifier.

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).

To retrieve the order history regardless of whether the tenant is integrated with the NewStore OMS or an external OMS, include the Accept header application/x.newstore.orders+json;version=2 in your request. In this case, the server will respond with the application/x.newstore.orders+json;version=2 content type and an updated API schema.

Retrieve order history for customers

Authorizations:
newStoreAccessToken
query Parameters
customer_id
required
string

NewStore's unique UUID or PII token identifier 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

Response samples

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

Manage orders

Use this resource to manage orders being processed in the NewStore platform or via an external order management system, and update related information for these orders.

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

Response samples

Content type
application/json
{
  • "currency": "USD",
  • "items": [
    ]
}

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 or null

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"
}

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
uuid
required
string

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

Request Body schema: application/json
required
Array of objects [ 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.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/problem+json
Example
{
  • "error_code": "bad_request",
  • "message": "The number of products can't exceed 500.",
  • "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
}

Cancel line items

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
order_uuid
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"
}