OpenAPI Specification
swagger: '2.0'
info:
version: '1.0'
title: NewStore address fulfillment-requests 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: fulfillment-requests
description: Fulfillment Requests
paths:
/v0/fulfillment_request/{ffr_uuid}/set_items_states:
post:
description: 'Update the shipment status for items in the specified fulfillment request.
**Important:** Do not confuse this API with
[Fulfillment Provider API](/newstore-cloud/order_management/dc_fulfillment_node_api.html). For
DC orders please use the Fulfillment Provider API.
Items in a fulfillment request can be marked as shipped or rejected. When you use this API you can''t mix
shipment and rejection actions on the same call.
**Important:** If you are doing a partial rejection of items in a fulfillment request, the reroute
attempt will not happen until all items in the fulfillment request are in a terminal state.
For fulfillment requests which are routed to store fulfillment nodes, the item state update
will only be accepted if the request has not been picked by a store associate. The change in
status is only valid for items that are not in a final state (the fulfillment process for the
item is considered as complete). The remaining items are not
affected by this change.
**Important**: When you reject items that are currently fulfilled in DC we don''t notify DC about items rejection.
You are responsible for communicating with DC API to ensure these items will not be shipped.
**Rejection reason**:
For fulfillment requests which are routed to store fulfillment nodes, to reject a fulfillment request you must provide the rejection reason "rescinded". This will initiate
a re-routing attempt without any changes to inventory levels.
**Edge Cases:**
- If your organization''s settings allows rerouting by setting `reroute_to_rejected_fulfillment_nodes` (
described in this
[API](https://docs.newstore.net/api/configuration/inventory-fulfillment/logistic_order_config#operation/set-reroute-to-rejected-fulfillment-nodes))
to `true`, rejected fulfillment nodes will be downgraded in priority during the routing process. If all possible
nodes for a given `location_group` in [routing configuration](https://docs.newstore.net/api/integration/delivery/routing_ruleset_api#operation/get-routing-rules)
are exhausted, it will take the first available fulfillment node as part of the mechanism, resulting in a
potential route to the same location on further attempts.
- Setting `reroute_to_rejected_fulfillment_nodes` to `false`, fulfillment nodes will be ignored during future
routing attempts. If all fulfillment nodes are rejected and you don''t want to reroute to these nodes, the
rejected items will be put on hold.
**Important**: The platform emits a separate event for each line item that is marked as
shipped, and not a single event for all items. This should be considered when reconciling these
events in the ERP you are using to manage such events.
'
summary: updateFulfillmentRequestItemStates
tags:
- fulfillment-requests
operationId: updateFulfillmentRequestItemStates
deprecated: false
produces:
- application/problem+json
consumes:
- application/json
parameters:
- name: Content-Type
in: header
required: false
enum:
- application/json
type: string
description: ''
- name: body
in: body
required: true
description: ''
schema:
$ref: '#/definitions/FulfillmentRequestItemsStatesRequest'
- name: ffr_uuid
in: path
required: true
type: string
description: ''
responses:
default:
description: Unexpected error.
schema:
$ref: '#/definitions/Problem'
headers: {}
'204':
description: Operation succeeded
headers: {}
'400':
description: Bad Request Error.
schema:
$ref: '#/definitions/Problem'
headers: {}
'404':
description: Not found Error.
schema:
$ref: '#/definitions/Problem'
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: Service Unavailable
schema:
$ref: '#/definitions/Problem'
headers: {}
security:
- oauth: []
/v0/fulfillment_requests/{order_uuid}:
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 70 requests per second.\n</div>\n\nReturns all fulfillment requests created for an order, sorted by creation date in the\nascending order (earliest first).\n\nIf order wasn't found, then the empty list of fulfillment requests will be returned.\n\nIf order wasn't routed yet, then the empty list of fulfillment requests will be returned.\n\n**Important:** As for now this API will return fulfillment requests even for orders without\nrouting (like in_store_purchase) but this behavior will change soon. And this API will only\nwork for orders where routing is needed. So, build your integrations accordingly.\n\n**Important:** Maximum number of fulfillment requests this API will return is **2000**. If\nthere are more than **2000** fulfillment requests for the order, then the response will have\n400 status code (although it is actually not a bad request) and **2000** latest (according\nto the creaiton date) fulfillment requests.\n"
summary: listFulfillmentRequestsForOrder
tags:
- fulfillment-requests
operationId: listFulfillmentRequestsForOrder
deprecated: false
produces:
- application/problem+json
- application/json
parameters:
- name: order_uuid
in: path
required: true
type: string
description: ''
responses:
default:
description: Unexpected error.
schema:
$ref: '#/definitions/Problem'
headers: {}
'200':
description: Successful response
schema:
$ref: '#/definitions/OrderFulfillmentRequestsResponse'
headers: {}
'400':
description: Order has too many fulfillment requests
schema:
$ref: '#/definitions/Problem'
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: An internal error occurred.
schema:
$ref: '#/definitions/Problem'
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/Problem'
headers: {}
security:
- oauth: []
definitions:
FulfillmentRequestItemsStatesRequest:
title: FulfillmentRequestItemsStatesRequest
description: Request payload for marking fulfillment request items as shipped or rejected.
type: object
properties:
associate_id:
description: Identifier of the associate who is changing the items's states.
type: string
minLength: 1
carrier:
description: Carrier used to ship items, which state is being changed to `shipped`.
type: string
line_items:
description: List of fulfillment request items with the target state.
type: array
items:
$ref: '#/definitions/LineItem11'
reason: {}
tracking_code:
description: Tracking code applied to items, which state is being changed to `shipped`.
type: string
minLength: 1
required:
- line_items
Problem:
title: Problem
type: object
properties:
detail:
description: A human readable explanation specific to this occurrence of the problem that is helpful to locate the problem and give advice on how to proceed. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.
example: some description for the error situation
type: string
error_code:
type: string
instance:
description: A URI reference that identifies the specific occurrence of the problem, e.g. by adding a fragment identifier or sub-path to the problem type. May be used to locate the root of this problem in the source code.
example: /some/uri-reference#specific-occurrence-context
type: string
message:
type: string
messages:
type: array
items:
type: string
request_id:
type: string
status:
description: The HTTP status code generated by the origin server for this occurrence of the problem.
type: integer
minimum: 100.0
maximum: 600.0
exclusiveMaximum: true
format: int32
title:
description: A short summary of the problem type. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.
example: some title for the error situation
type: string
type:
description: A URI reference that uniquely identifies the problem type only in the context of the provided API. Opposed to the specification in RFC-7807, it is neither recommended to be dereferenceable and point to a human-readable documentation nor globally unique for the problem type.
example: /some/uri-reference
type: string
default: about:blank
Status2:
title: Status2
description: 'Status of this item: dispatched - item was routed to a store/DC (check status of fulfillment request to see whether DC/store service has already accepted this fulfillment request or not); shipped - item was marked as shipped; rejected - item was rejected by fulfillment node and going to be rerouted (or was rerouted if fulfillment request already completed); cancelled - item was cancelled.'
type: string
enum:
- dispatched
- shipped
- rejected
- cancelled
LineItem11:
title: LineItem11
description: Line item
type: object
properties:
item_id:
description: Sales order item UUID.
type: string
format: uuid
state:
type: object
allOf:
- $ref: '#/definitions/State'
- description: New state that should be applied to this item defined by sales order item UUID.
required:
- item_id
- state
Item8:
title: Item8
type: object
properties:
carrier:
description: Carrier for the item, if it was provided during after shipment. Otherwise `null`.
type: string
item_id:
description: Unique identifier of the line item.
type: string
minLength: 1
product_id:
type: string
minLength: 1
status:
type: object
allOf:
- $ref: '#/definitions/Status2'
- description: 'Status of this item: dispatched - item was routed to a store/DC (check status of fulfillment request to see whether DC/store service has already accepted this fulfillment request or not); shipped - item was marked as shipped; rejected - item was rejected by fulfillment node and going to be rerouted (or was rerouted if fulfillment request already completed); cancelled - item was cancelled.'
tracking_code:
description: Tracking code for the item, if it was provided after shipment. Otherwise `null`.
type: string
required:
- carrier
- item_id
- product_id
- status
- tracking_code
FulfillmentRequest:
title: FulfillmentRequest
description: The fulfillment request.
type: object
properties:
created_at:
description: Date and time when fulfillment request was created.
type: string
format: date-time
fulfillment_node_id:
description: Fulfillment node where fulfillment request was routed to.
type: string
minLength: 1
fulfillment_request_id:
description: The identifier of the fulfillment request.
type: string
minLength: 1
items:
type: array
items:
$ref: '#/definitions/Item8'
minItems: 1
service_level:
description: Service level fulfillment request was routed with.
type: string
minLength: 1
status:
type: object
allOf:
- $ref: '#/definitions/Status11'
- description: 'Current status of fulfillment request: dispatched - fulfillment request was sent to sent to store/DC services, but wasn''t acknowledged yet; acknowledged - fulfillment request was acknowledged by store/DC service and will be send to store/DC for fulfillment; partially_completed - some items of fulfillment request were already processed (cancelled, rejected, shipped) but not all of them; completed - all items of fulfillment request were processed (cancelled, rejected, shipped).'
required:
- created_at
- fulfillment_node_id
- fulfillment_request_id
- items
- service_level
- status
OrderFulfillmentRequestsResponse:
title: OrderFulfillmentRequestsResponse
description: Fulfillment requests for an order
type: object
properties:
fulfillment_requests:
description: All fulfillment requests that belongs to the order. Can be empty if order not routed yet, or if order doesn't exist.
type: array
items:
$ref: '#/definitions/FulfillmentRequest'
maxItems: 2000
required:
- fulfillment_requests
State:
title: State
description: New state that should be applied to this item defined by sales order item UUID.
type: string
enum:
- shipped
- rejected
Status11:
title: Status11
description: 'Current status of fulfillment request: dispatched - fulfillment request was sent to sent to store/DC services, but wasn''t acknowledged yet; acknowledged - fulfillment request was acknowledged by store/DC service and will be send to store/DC for fulfillment; partially_completed - some items of fulfillment request were already processed (cancelled, rejected, shipped) but not all of them; completed - all items of fulfillment request were processed (cancelled, rejected, shipped).'
type: string
enum:
- dispatched
- acknowledged
- partially_completed
- completed
securityDefinitions:
oauth:
type: oauth2
flow: application
tokenUrl: https://id.p.newstore.net/auth/realms/dodici-demo/protocol/openid-connect/token
scopes:
catalog:import-schemas:read: Grants privileges to read import schema
catalog:import-schemas:write: Grants privileges to write import schema
catalog:pricebook-export:read: Grants privileges to export pricebook data
catalog:product-export:read: Grants privileges to export product data
checkout:carts:read: Grants privileges to read cart data
checkout:carts:write: Grants privileges to write cart data
clienteling:profile:read: Grants privileges to read clienteling profiles
customer:profile:read: Grants privileges to read API customer data
customer:profile:write: Grants privileges to modify API customer data
newstore:configuration:read: Grants privileges to read configuration
newstore:configuration:write: Grants privileges to write configuration
fiscalization:orders:read: View orders with fiscal transactions and signatures
fiscalization:orders:write: Create orders with fiscal transactions and signatures
shipments:read: Read Shipping Options and Audits
iam:providers:read: ' Grants read privileges to provider resources'
iam:providers:write: ' Grants write privileges to provider resources'
iam:roles:read: ' Grants privileges to read roles data'
iam:roles:write: ' Grants privileges to write roles data'
iam:users:read: ' Grants privileges to read user data'
iam:users:write: ' Grants privileges to write user data'
inventory:reservations:read: Allows access to retrieve reservations
inventory:reservations:write: Allows access to create and update reservations
promotions:config:read: Grants privileges to read configuration
promotions:config:write: Grants privileges to write into configuration
promotions:reason-codes:read: Grants privileges to list reason codes
promotions:reason-codes:write: Grants privileges to create and update reason codes
audit-events:read: Grants read access to the tenant's audit events.
taxes:preview-transactions:write: Preview tax transactions
taxes:transactions:read: Read tax transactions