Newstore sales-orders API
Operations related to sales order management.
OpenAPI Specification
swagger: '2.0'
info:
version: '1.0'
title: NewStore address sales-orders API
description: NewStore public APIs
contact:
email: support@newstore.com
name: NewStore API Support
url: https://developer.newstore.com
host: dodici-demo.p.newstore.net
basePath: /
schemes:
- https
consumes:
- application/json
produces:
- application/json
security: []
tags:
- name: sales-orders
description: Operations related to sales order management.
paths:
/v0/orders:
get:
description: "\n<div style=\"background-color: rgba(23, 162, 184, 0.15); border: 1px solid #17a2b8; border-left: 4px solid #17a2b8; padding: 12px; margin: 10px 0; border-radius: 4px; color: #17a2b8;\">\n <strong>ℹ️ Rate Limit:</strong> This endpoint is rate limited to 30 requests per second.\n</div>\n\n"
summary: showOrderHistoryForCustomer
tags:
- sales-orders
operationId: showOrderHistoryForCustomer
deprecated: false
produces:
- application/json
- application/x.newstore.orders+json;version=2
- application/problem+json
parameters:
- name: customer_id
in: query
required: true
type: string
description: NewStore's unique UUID for the customer
- name: offset
in: query
required: false
default: 0
type: integer
format: int32
minimum: 0.0
exclusiveMinimum: false
description: 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``.
- name: count
in: query
required: false
default: 10
type: integer
format: int32
minimum: 1.0
maximum: 50.0
exclusiveMaximum: false
exclusiveMinimum: false
description: The number of requested orders. Will only be accepted when using the ``Accept`` header with ``application/x.newstore.orders+json;version=2``.
responses:
default:
description: Unexpected Error
headers: {}
'200':
description: 'Returns the list of orders. If the ``Accept`` headers with ``application/x.newstore.orders+json;version=2`` is used,
it returns a paginated list as specified by the ``offset`` and ``count`` parameters.'
schema:
$ref: '#/definitions/SalesOrderListResponse'
examples:
application/json:
orders: []
headers: {}
'400':
description: Bad Request Error.
schema:
$ref: '#/definitions/Problem'
examples:
application/problem+json:
error_code: bad_request
message: Query param 'customer_id' is required.
request_id: ec2f3c9bb016ba971bf6074098363
headers: {}
'404':
description: Customer not found. Only applicable when ``Accept`` header is ``application/json``.
schema:
$ref: '#/definitions/Problem'
examples:
application/problem+json:
error_code: customer_not_found
message: customer with given customer_id not found
request_id: ec2f3c9bb016ba971bf6074098363
headers: {}
'409':
description: External webhook payload validation failed. Only applicable when ``Accept`` header is ``application/json``.
schema:
$ref: '#/definitions/Problem'
examples:
application/problem+json:
error_code: conflict
message: 'Failed JSON schema validation with schema /opt/schema.json. Error: "orders" is a required attribute.'
request_id: ec2f3c9bb016ba971bf6074098363
headers: {}
'412':
description: Webhook configuration error. Only applicable when ``Accept`` header is ``application/json``.
schema:
$ref: '#/definitions/Problem'
examples:
application/problem+json:
error_code: precondition_error
message: API Key is required to access external OMS
request_id: ec2f3c9bb016ba971bf6074098363
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: Internal Server Error.
schema:
$ref: '#/definitions/Problem'
examples:
application/problem+json:
error_code: internal_server_error
message: Couldn't process request due to an internal error.
request_id: ec2f3c9bb016ba971bf6074098363
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: External Server Error.
schema:
$ref: '#/definitions/Problem'
examples:
application/problem+json:
error_code: external_server_error
message: API Key to the webhook is expired
request_id: ec2f3c9bb016ba971bf6074098363
headers: {}
security:
- oauth: []
/v0/orders/{id}:
get:
description: "\n<div style=\"background-color: rgba(23, 162, 184, 0.15); border: 1px solid #17a2b8; border-left: 4px solid #17a2b8; padding: 12px; margin: 10px 0; border-radius: 4px; color: #17a2b8;\">\n <strong>ℹ️ Rate Limit:</strong> This endpoint is rate limited to 100 requests per second.\n</div>\n\nRetrieves the specified order by order ID and ID type for the order.\n\nThis method allows you to retrieve information about orders that were placed in the platform,\nas well as outside of the NewStore platform.\n\n**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.\nIn 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.\n"
summary: showSalesOrderByIdAndIdType
tags:
- sales-orders
operationId: showSalesOrderByIdAndIdType
deprecated: false
produces:
- application/json
- application/x.newstore.orders+json;version=2
- application/problem+json
parameters:
- name: id
in: path
required: true
type: string
description: ID of the order.
- name: id_type
in: query
required: true
type: string
description: 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).
- name: Accept
in: header
required: false
type: string
description: 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:
default:
description: Unexpected Error
headers: {}
'200':
description: Successfully fetch order by ID and ID type
schema:
$ref: '#/definitions/SalesOrderDetailResponse'
headers: {}
'400':
description: Validation for the request failed
schema:
$ref: '#/definitions/Problem'
headers: {}
'404':
description: Order with provided ID and ID type was not found
headers: {}
'409':
description: External webhook payload validation failed.
schema:
$ref: '#/definitions/Problem'
examples:
application/problem+json:
error_code: conflict
message: 'Failed JSON schema validation with schema /opt/schema.json. Error: "orders" is a required attribute.'
request_id: ec2f3c9bb016ba971bf6074098363
headers: {}
'412':
description: Webhook configuration error.
schema:
$ref: '#/definitions/Problem'
examples:
application/problem+json:
error_code: precondition_error
message: API Key is required to access external OMS
request_id: ec2f3c9bb016ba971bf6074098363
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: Internal Server Error.
schema:
$ref: '#/definitions/Problem'
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: External Server Error.
schema:
$ref: '#/definitions/Problem'
examples:
application/problem+json:
error_code: external_server_error
message: API Key to the webhook is expired
request_id: ec2f3c9bb016ba971bf6074098363
headers: {}
security:
- oauth: []
/v0/orders/{id}/_extend_grace_period:
post:
description: 'Use this method to extend the [grace period](https://docs.newstore.com/docs/glossary#remorse-period) timer
for the specified order by **15 minutes**, if the grace period of the order has not yet expired.
'
summary: createGracePeriod
tags:
- sales-orders
operationId: createGracePeriod
deprecated: false
produces:
- application/json
- application/problem+json
parameters:
- name: id
in: path
required: true
type: string
description: ID of the order.
- name: id_type
in: query
required: true
type: string
description: 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:
default:
description: Unexpected Error
headers: {}
'200':
description: The grace period got extended by 15 minutes.
schema:
$ref: '#/definitions/Extendorder%27sgraceperiodtimer'
headers: {}
'404':
description: Order with id and id type not found.
schema:
$ref: '#/definitions/Problem'
headers: {}
'409':
description: A concurrent request extended the grace period already.
schema:
$ref: '#/definitions/Problem'
headers: {}
'412':
description: The order is not in the grace period.
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: Internal Server Error.
schema:
$ref: '#/definitions/Problem'
examples:
application/problem+json:
error_code: internal_server_error
message: Couldn't process request due to an internal error.
request_id: ec2f3c9bb016ba971bf6074098363
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/Problem'
headers: {}
security:
- oauth: []
/v0/orders/{id}/cancel:
get:
description: API to get cancellation status by order ID
summary: showCancellationStatus
tags:
- sales-orders
operationId: showCancellationStatus
deprecated: false
produces:
- application/json
- application/problem+json
parameters:
- name: id
in: path
required: true
type: string
description: ID of the order.
- name: id_type
in: query
required: true
type: string
description: ID type on which order should be fetched. Example "external".
responses:
default:
description: Unexpected Error
headers: {}
'200':
description: Successfully fetched cancellation status for the order.
schema:
$ref: '#/definitions/SalesOrderCancellationResponse'
examples:
application/json:
cancelable: true
canceled: false
is_safe: true
headers: {}
'400':
description: Bad request
schema:
$ref: '#/definitions/Problem'
headers: {}
'404':
description: Order with given order ID does not exist
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: Internal server error
schema:
$ref: '#/definitions/Problem'
examples:
application/problem+json:
error_code: internal_server_error
message: Couldn't process request due to an internal error.
request_id: ec2f3c9bb016ba971bf6074098363
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/Problem'
headers: {}
security:
- oauth: []
post:
description: '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.
'
summary: createCancellation
tags:
- sales-orders
operationId: createCancellation
deprecated: false
produces:
- application/problem+json
consumes:
- application/json
parameters:
- name: id
in: path
required: true
type: string
description: ID of the order.
- name: id_type
in: query
required: true
type: string
description: Type of order id which should be used for cancellation. Example "external".
- name: Content-Type
in: header
required: false
enum:
- application/json
type: string
description: ''
- name: body
in: body
required: false
description: ''
schema:
$ref: '#/definitions/SalesOrderCancellationRequest'
responses:
default:
description: Unexpected Error
headers: {}
'200':
description: Successfully cancelled order by ID and ID type
headers: {}
'400':
description: Bad request
schema:
$ref: '#/definitions/Problem'
examples:
application/problem+json:
error_code: bad_request
message: 'Validation of cancel order request failed with error: ''reason'' is a required property.'
request_id: ec2f3c9bb016ba971bf6074098363
headers: {}
'404':
description: Order with provided ID and ID type was not found.
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: Internal Server Error.
schema:
$ref: '#/definitions/Problem'
examples:
application/problem+json:
error_code: internal_server_error
message: Couldn't process request due to an internal error.
request_id: ec2f3c9bb016ba971bf6074098363
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/Problem'
headers: {}
security:
- oauth: []
/v0/orders/{id}/items/{item_uuid}/cancel:
post:
description: '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.
'
summary: createLineItemCancellation
tags:
- sales-orders
operationId: createLineItemCancellation
deprecated: false
produces:
- application/problem+json
parameters:
- name: id
in: path
required: true
type: string
description: UUID of the order.
- name: item_uuid
in: path
required: true
type: string
description: UUID of the order item.
- name: id_type
in: query
required: true
type: string
description: 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:
default:
description: Unexpected Error
headers: {}
'200':
description: Successfully cancelled order item by UUID.
headers: {}
'400':
description: Bad request
schema:
$ref: '#/definitions/Problem'
examples:
application/problem+json:
error_code: bad_request
message: 'Validation of cancel order request failed with error: ''reason'' is a required property.'
request_id: ec2f3c9bb016ba971bf6074098363
headers: {}
'404':
description: Order item with provided UUID was not found.
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: Internal Server Error.
schema:
$ref: '#/definitions/Problem'
examples:
application/problem+json:
error_code: internal_server_error
message: Couldn't process request due to an internal error.
request_id: ec2f3c9bb016ba971bf6074098363
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/Problem'
headers: {}
security:
- oauth: []
/v0/orders/{id}/prices:
post:
description: '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.
'
summary: createPriceInformationForItems
tags:
- sales-orders
operationId: createPriceInformationForItems
deprecated: false
produces:
- application/json
- application/problem+json
consumes:
- application/json
parameters:
- name: id
in: path
required: true
type: string
description: The identifier of the order.
- name: Content-Type
in: header
required: false
enum:
- application/json
type: string
description: ''
- name: body
in: body
required: true
description: ''
schema:
$ref: '#/definitions/SalesOrderPricesRequest'
responses:
default:
description: Unexpected Error
headers: {}
'200':
description: Price information for the provided items.
schema:
$ref: '#/definitions/SalesOrderPricesResponse'
headers: {}
'400':
description: Bad Request Error.
schema:
$ref: '#/definitions/Problem'
examples:
application/problem+json:
error_code: bad_request
message: The number of products can't exceed 500.
request_id: ec2f3c9bb016ba971bf6074098363
headers: {}
'404':
description: Not found Error.
schema:
$ref: '#/definitions/Problem'
examples:
application/problem+json:
error_code: not_found
message: The order '57787cdb-3474-47b5-b3ec-7b776731309e' couldn't be found.
request_id: ec2f3c9bb016ba971bf6074098363
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: Internal Server Error.
schema:
$ref: '#/definitions/Problem'
examples:
application/problem+json:
error_code: internal_server_error
message: Couldn't process request due to an internal error.
request_id: ec2f3c9bb016ba971bf6074098363
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/Problem'
headers: {}
security:
- oauth: []
/v0/orders/{id}/serial_numbers:
patch:
description: '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.
'
summary: updateSalesOrderSerialNumbers
tags:
- sales-orders
operationId: updateSalesOrderSerialNumbers
deprecated: false
produces:
- application/problem+json
consumes:
- application/json
parameters:
- name: id
in: path
required: true
type: string
description: The internal identifier of the order, for example, ``b604ffda-7e31-4338-beab-7f939a8c2322``.
- name: Content-Type
in: header
required: false
enum:
- application/json
type: string
description: ''
- name: body
in: body
required: true
description: ''
schema:
$ref: '#/definitions/SalesOrderSerialNumbersRequest'
responses:
default:
description: Unexpected Error
headers: {}
'204':
description: Serial numbers added.
headers: {}
'400':
description: Bad request Error.
schema:
$ref: '#/definitions/Problem'
examples:
application/problem+json:
error_code: bad_request
message: The number of products can't exceed 500.
request_id: ec2f3c9bb016ba971bf6074098363
headers: {}
'404':
description: Not found Error.
schema:
$ref: '#/definitions/Problem'
examples:
application/problem+json:
error_code: not_found
message: The order '57787cdb-3474-47b5-b3ec-7b776731309e' couldn't be found.
request_id: ec2f3c9bb016ba971bf6074098363
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: Internal Server Error.
schema:
$ref: '#/definitions/Problem'
examples:
application/problem+json:
error_code: internal_server_error
message: Couldn't process request due to an internal error.
request_id: ec2f3c9bb016ba971bf6074098363
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/Problem'
headers: {}
security:
- oauth: []
definitions:
CountryCode:
title: CountryCode
description: Country code for this address. Must be <a href='https://www.iso.org/iso/country_codes.htm'>ISO-3166 reference</a>
type: string
enum:
- AD
- AE
- AF
- AG
- AI
- AL
- AM
- AO
- AQ
- AR
- AS
- AT
- AU
- AW
- AX
- AZ
- BA
- BB
- BD
- BE
- BF
- BG
- BH
- BI
- BJ
- BL
- BM
- BN
- BO
- BQ
- BR
- BS
- BT
- BV
- BW
- BY
- BZ
- CA
- CC
- CD
- CF
- CG
- CH
- CI
- CK
- CL
- CM
- CN
- CO
- CR
- CU
- CV
- CW
- CX
- CY
- CZ
- DE
- DJ
- DK
- DM
- DO
- DZ
- EC
- EE
- EG
- EH
- ER
- ES
- ET
- FI
- FJ
- FK
- FM
- FO
- FR
- GA
- GB
- GD
- GE
- GF
- GG
- GH
- GI
- GL
- GM
- GN
- GP
- GQ
- GR
- GS
- GT
- GU
- GW
- GY
- HK
- HM
- HN
- HR
- HT
- HU
- ID
- IE
- IL
- IM
- IN
- IO
- IQ
- IR
- IS
- IT
- JE
- JM
- JO
- JP
- KE
- KG
- KH
- KI
- KM
- KN
- KP
- KR
- KW
- KY
- KZ
- LA
- LB
- LC
- LI
- LK
- LR
- LS
- LT
- LU
- LV
- LY
- MA
- MC
- MD
- ME
- MF
- MG
- MH
- MK
- ML
- MM
- MN
- MO
- MP
- MQ
- MR
- MS
- MT
- MU
- MV
- MW
- MX
- MY
- MZ
- NA
- NC
- NE
- NF
- NG
- NI
- NL
- 'NO'
- NP
- NR
- NU
- NZ
- OM
- PA
- PE
- PF
- PG
- PH
- PK
- PL
- PM
- PN
- PR
- PS
- PT
- PW
- PY
- QA
- RE
- RO
- RS
- RU
- RW
- SA
- SB
- SC
- SD
- SE
- SG
- SH
- SI
- SJ
- SK
- SL
- SM
- SN
- SO
- SR
- SS
- ST
- SV
- SX
- SY
- SZ
- TC
- TD
- TF
- TG
- TH
- TJ
- TK
- TL
- TM
- TN
- TO
- TR
- TT
- TV
- TW
- TZ
- UA
- UG
- UM
- US
- UY
- UZ
- VA
- VC
- VE
- VG
- VI
- VN
- VU
- WF
- WS
- YE
- YT
- ZA
- ZM
- ZW
SalesOrderSerialNumbersRequestItemEpc:
title: SalesOrderSerialNumbersRequestItemEpc
description: The epc which should be assigned to the specified order line item.
type: object
properties:
code:
description: The epc code.
type: string
external_id:
description: The external identifier for the epc.
type: string
serial_number:
description: The serial number associated with the epc.
type: string
required:
- code
- external_id
- serial_number
SalesOrderItemPaymentHistory:
title: SalesOrderItemPaymentHistory
description: Contains the payments/refunds history for the order. Can also include multiple payments against multiple credit sources (i.e. gift card + credit card)
type: object
properties:
amount:
description: The monetary value of the payment/refund.
type: number
minimum: 0.0
format: double
category:
type: object
allOf:
- $ref: '#/definitions/Category'
- description: Describes if it is a Payment (authorization or capture) or Refund.
currency:
description: The currency of the amount as 3 character ISO-4217 code. Example USD, EUR.
type: string
minLength: 3
maxLength: 3
method:
type: object
allOf:
- $ref: '#/definitions/SalesOrderPaymentMethod'
- description: The method customer paid for the order.
payment_information:
description: Any payment information related to the payment method used. For example, it can contain the card type along with the last 4 digits of the credit card number.
example: Visa (**** 1111)
type: string
required:
- amount
- category
- currency
- method
SalesOrderExternalIdentifier:
title: SalesOrderExternalIdentifier
description: External identifier for the order item
type: object
properties:
epc:
description: EPC (Electronic Product Code) for order item
type: string
serial_number:
description: Serial number of order item
type: string
SalesOrderPricesResponse:
title: SalesOrderPricesResponse
description: The response for retrieving price information.
type: object
properties:
currency:
description: The currency that was used to buy the order, ISO 4217.
type: string
minLength: 3
maxLength: 3
items:
type: array
items: {}
required:
- currency
- items
SalesOrderFulfillment:
title: SalesOrderFulfillment
type: object
properties:
item_ids:
description: The order item UUIDs belonging to this fulfillment group.
type: array
items:
type: string
origin:
type: object
allOf:
- $ref: '#/definitions/Origin'
- description: The ship-from origin for this fulfillment group. Omitted when neither zip code nor country code is known.
required:
- item_ids
SalesOrderDiscount:
title: SalesOrderDiscount
type: object
properties:
coupon_code:
description: The coupon code used for this discount.
type: string
level:
type: object
allOf:
- $ref: '#/definitions/Level'
- description: On which level the discount was applied, either on the entire order or only on this item.
price_adjustment:
description: The applied discount.
type: number
minimum: 0.0
format: double
promotion_uuid:
description: The UUID of the the discount.
type: string
reason:
description: The reason of the discount.
type: string
type:
type: object
allOf:
- $ref: '#/definitions/Type1'
- description: The type of the discount, either 'fixed' or 'percentage'.
value:
description: If the discount is of type 'fixed', this is equal to the adjusted price amount. If the discount is of type 'percentage', this is the percentage, e.g. 20%.
type: number
minimum: 0.0
format: double
required:
- level
- price_adjustment
- type
- value
SalesOrderTotals:
title: SalesOrderTotals
type: object
properties:
discount:
description: The appli
# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/newstore/refs/heads/main/openapi/newstore-sales-orders-api-openapi.yml