Skip to main content

API to manage sales order configurations (0.1.0)

Download OpenAPI specification:Download

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

Use these APIs to manage order configurations in the NewStore platform.

External OMS configuration

Use this resource to configure NewStore as a secondary order management system for retailers, to allow them to continue using their legacy order management system (OMS) for primary order fulfillment tasks.

When NewStore is the secondary OMS for your business, it provides the following features from the perspective of order routing and fulfillment:

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 resource definition.

Authorizations:
newStoreAccessToken

Responses

Response samples

Content type
application/json
{
  • "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 resource 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
{
  • "value": {
    }
}

Response samples

Content type
application/problem+json
{
  • "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
{
  • "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

Size of human-readable order identifiers.

start
integer

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

step
integer

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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "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
{
  • "schema": {
    },
  • "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

Timer duration in seconds

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "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
{
  • "schema": {
    },
  • "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
{
  • "value": [
    ]
}

Response samples

Content type
application/json
{
  • "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 specific limits for items that orders can contain in your business. For example, you can specify the maximum number of items an order can contain (such as 300 items), exceeding which it is put on hold.

Authorizations:
newStoreAccessToken

Responses

Response samples

Content type
application/problem+json
{
  • "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 specific limits for items that orders can contain in your business. For example, you can specify the maximum number of items an order can contain (such as 300 items), exceeding which it is put on hold.

Authorizations:
newStoreAccessToken
Request Body schema: application/json
required
object
soft_limit_for_big_orders
required
integer

The order item limits that determine if the order is routed or is considered a big order and placed on hold. If the limit if not set, 100 is used as the default value.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "value": {
    },
  • "updated_at": "2021-07-13T20:18:25Z"
}

External order webhook

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
{
  • "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.

Authorizations:
newStoreAccessToken
Request Body schema: application/json
required
object
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 <= 25

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

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/problem+json
{
  • "error_code": "bad_request",
  • "message": "Value provided should be a string.",
  • "request_id": "ec2f3c9bb016ba971bf6074098363"
}