Skip to main content
API docs by Redocly

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

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