Order Search

Note about Partners

If you work with Partners and need this functionality to limit what a client sees when calling either of the methods below, then you need to be sure that each of your Partners are issued a unique API Key and that API Key is associated with their Partner registration in the Spectrum System. Your Spectrum customer representative will be able to help you get this set up.

Single Purchase Order

To query for a single purchase order within Spectrum, use the following API:

GET https://{SpectrumEnvironment}/api/order/order-number/{PurchaseOrderNumber} HTTP/1.1
SPECTRUM_API_TOKEN: {SpectrumApiToken}

The available {SpectrumEnvironment} base URLs are listed in the Environments page.

See example response below.

Multiple Purchase Orders

To query for multiple purchase orders within Spectrum, use the following API to search for orders with line items of a defined status. By default, only 31 days of orders are able to be searched at one time. This can be overridden by the ignoreDateRestriction parameter, but should only be used when the client will wait for a response beyond normal timeout ranges.

POST https://{SpectrumEnvironment}/api/orders/search HTTP/1.1
SPECTRUM_API_TOKEN: {SpectrumApiToken}
Content-Type: application/json

Multiple Order Search

POST https://{SpectrumEnvironment}/api/orders/search

Search for orders within a time range with defined statuses. Note: a Spectrum API Key must be sent via the header to enable this API call.

Headers

Name	Type	Description
SPECTRUM_API_TOKEN*	String	{SpectrumApiToken}
Content-Type*	String	application/json

Request Body

Name	Type	Description
*	JSON	JSON payload (see below example)

200: OK Indicates a successful response with an array of Order Search Results.

{
    // Response
}

400: Bad Request Indicates that the date query goes beyond the default response time. Note: for queries beyond 31 days, you may set the ignoreDateRestriction to true to bypass the restriction.

{
    // Response
}

500: Internal Server Error Indicates that an error was encountered with the request or an internal operation. These error are logged and a Log Identifier is sent in the response for tracking.

{
    // Response
}

Required

• lastModificationStartDate (ISO 8601 date string)
• workflowStatuses (array of Workflow Status strings)

Optional

• lastModificationEndDate (ISO 8601 date string default: current DateTime)
• ignoreDateRestriction (Boolean, default: false): set to true when searching over 1 month of orders. Note: API response may take more than 30 seconds to return.

Workflow Statuses

• not-started
• in-progress
• in-progress-step-1
• completed
• revision
• on-hold
• approved
• released
• delivered
• cancelled

Example request body

The call below will return all orders that have line items with a workflow status of “in-progress” or “completed” within the defined dates.

{
    "lastModificationStartDate": "2022-01-31T00:00:00.00000-00:00",
    "lastModificationEndDate": "2022-02-02T00:00:00.00000-00:00",
    "workflowStatuses": ["in-progress", "completed"]
}

See example response below.

Order Search Response Example

For a single purchase order search, up to one order is returned. For multiple purchase order search, an array of matching orders would be returned.

{
	"clientHandle": "spectrum",
	"purchaseOrderNumber": "SP-US02141505",
	"orderDateTime": "2022-01-31T13:15:05.2151663-05:00",
	"locale": "en-US",
	"orderType": "self",
	"orderStatus": "completed",
 	"emailAddress": "john.smith@acme.com",
	"phoneNumber": "1015551212",
	"lineItems": [{
		"recipeSetId": "W7WU2TWC",
		"giftMessage": "",
		"workflowStatus": "in-progress",
		"isReorder": false,
		"lastModification": "2021-05-01T13:31:21.057",
		"shipmentTracking": "1Z9R62E60219095885",
	        "serialNumbers": ["BR7MWPKFZP76NK8U"],
		"unitPrice": 25.00,
		"skuQuantities": [{
			"sku": "T-Shirt",
			"quantity": 1
		}]
	}],
	"customerAddress": {
		"firstName": "John",
		"lastName": "Smith",
		"address1": "123 Fake Street",
		"address2": "",
		"city": "Portland",
		"state": "OR",
		"province": "",
		"postalCode": "97205",
		"country": "US"
	},
	"shippingAddress": {
		"firstName": "John",
		"lastName": "Smith",
		"address1": "123 Fake Street",
		"address2": "",
		"city": "Portland",
		"state": "OR",
		"province": "",
		"postalCode": "97205",
		"country": "US"
	}
}