# 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 representitive 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](https://docs.spectrumcustomizer.com/integration/api/environments) page.

See [example response](#order-search-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 search at one time.  This can be overridden by the ignoreDateRetriction 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

<mark style="color:green;">`POST`</mark> `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<mark style="color:red;">\*</mark> | String | {SpectrumApiToken} |
| Content-Type<mark style="color:red;">\*</mark>         | String | application/json   |

#### Request Body

| Name                               | Type | Description                      |
| ---------------------------------- | ---- | -------------------------------- |
| <mark style="color:red;">\*</mark> | JSON | JSON payload (see below example) |

{% tabs %}
{% tab title="200: OK Indicates a successful response with an array of Order Search Results." %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="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.   " %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="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. " %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

#### 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.&#x20;

**Workflow Statuses**

* not-started
* in-progress
* completed
* revision
* on-hold
* approved
* 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.

```javascript
{
    "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](#order-search-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.&#x20;

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