Order placement API (0.1.0)

Download OpenAPI specification:Download

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

Beta - self-checkout / Associate App slice. Use this API to place orders for processing in the NewStore platform. A successful response means the order has been accepted; payment capture, receipt generation, and downstream processing complete asynchronously.

order-placement

Place orders into the NewStore platform.

Place an order

Place an order for processing in the NewStore platform. A successful response means the order has been accepted; payment capture, receipt generation, and downstream processing complete asynchronously.

Authorizations:

oauth2

header Parameters

idempotency-key required	string (Idempotency-Key) [ 1 .. 256 ] characters Caller-provided idempotency key. Reserved: retry de-duplication is being reworked and is not currently enforced, so callers must not rely on it to prevent duplicate orders.
x-newstore-request-id	string <= 255 characters Example: 2a0295b0-50a8-459c-82cd-5079d3f35bfb Optional caller-provided request correlation identifier. Generated by the service when omitted.

Request Body schema: application/json

The order to place.

id	string or null <uuid> (Id) Deprecated Deprecated. Caller-supplied order id, used verbatim as the order's primary identifier. Exists only for backwards compatibility with legacy callers that mint the order id before placement and require the persisted order id to match it. Do not use for new integrations: the system generates the order id and returns it in the response. When omitted, the system generates the order id.
external_id	string or null (External Id) [ 1 .. 64 ] characters .\S. Caller-supplied external identifier for correlation and external lookup. Must be unique per tenant when supplied. The order number is generated by the system.
checkout_id	string or null (Checkout Id) [ 1 .. 64 ] characters Associated checkout ID for reconciliation.
	object or null (Customer) The customer placing the order. Omitted for anonymous orders.
	Array of objects (Extended Attributes) <= 100 items Tenant-defined name/value pairs for the order, propagated through the platform.
required	object (Channel) Describes the origin of the order.
required	object (Catalog) The catalogue and locale used to resolve the order's items.
required	object (Pricing) Currency and tax treatment for all prices in the payload.
required	Array of objects (Line Items) [ 1 .. 240 ] items
required	Array of objects (Fulfillments) [ 1 .. 10 ] items
	Array of objects (Gift Wrappings) <= 1 items Gift wrapping applied to the order's line items. At most one, and it must cover every line item — partial gift wrapping (wrapping only some items) is not yet supported. Omitted when nothing is gift-wrapped.
required	object (Payment) The payments attached to an order.

Responses

Request samples

Payload

Content type

application/json

{"external_id": "client-order-000123",
"channel": {"name": "self_checkout",
"type": "STORE",
"store_id": "store-01",
"associate_id": "associate-01"
},
"catalog": {"name": "storefront-catalog-en",
"locale": "en-US"
},
"pricing": {"currency": "USD",
"method": "TAX_INCLUDED"
},
"line_items": [{"line_item_id": "item-1",
"product_id": "SKU-123",
"unit_external_id": "ext-item-1",
"price": {"list_price": 1999,
"price": 1999
}
}
],
"fulfillments": [{"line_item_ids": ["item-1"
],
"fulfillment_option": {"service_level_identifier": "IN_STORE_HANDOVER",
"price": 0,
"tax": 0
}
}
],
"payment": {"instruments": [{"payment_method": "CARD",
"amount": 1999,
"currency": "USD",
"payment_provider": "newstore",
"status": "CAPTURED",
"processed_at": "2026-06-05T12:00:00Z",
"card": {"origin": "terminal",
"reference": "pi_3abc",
"card_brand": "Visa",
"card_last4": "4242"
}
}
]
}
}

Response samples

Content type

application/json

{"id": "2a0295b0-50a8-459c-82cd-5079d3f35bfb",
"order_number": "ORD0000123456",
"external_id": "client-order-000123",
"items": [{"product_id": "SKU-123",
"external_item_id": "ext-item-1",
"line_item_id": "item-1",
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}
]
}