`getSalesOrderByDate()`

This method returns detailed information about sales orders, filtered by time range.

Syntax

module.exports = async function getSalesOrderByDate(transaction, range) {
  // Your code here
}

import { Transaction, SalesOrderTimeRange, SalesOrderArray } from "@shipengine/connect";
export default async function getSalesOrderByDate(
  transaction: Transaction,
  range: SalesOrderTimeRange
): Promise<SalesOrderArray> {
  // Your code here
}

Paging

For returning large numbers of sales orders, you can take advantage of cursor based pagination to return the needed data in more consumable chunks.

To accomplish this you will need to populate the paging.cursor property with your preferred cursor structure and the getSalesOrderByDate method will be called again with the paging.cursor property populated with the return object.

The method will continue to be called until the paging.cursor property is returned as undefined.

Parameters

`transaction`

A transaction object containing information about the transaction and session state.

`range`

Specifies a date/time range to retrieve sales orders for.

Name	Type	Nullable?	Description
`startDateTime`	DateTime	✔	The start date/time of the range.
`endDateTime`	DateTime	✔	The end date/time of the range.
`toString`	method		A method that returns the time range as a string.
`paging`	object	✔	An object that indicates that page preferences for the items that are returned from this method. This property may be null. If it is provided, all its required properties, listed below, will be included.
`paging.pageSize`	number		The desired maximum number of items to return. This value will always be provided and will be greater than zero.
`paging.pageCount`	number		he desired maximum number of pages to return. This value is optional.
`paging.pageNumber`	number	✔	The desired page number to return. This value will always be provided and will be zero or greater.
`paging.cursor`	string	✔	Identifies the next page of results to return. This value is optional.
`statusMappings`	object	✔	A customer specified mapping for status codes. The keys of this object will be the custom status strings provided by a user, and the values will be one of the following valid status codes: `awaiting_payment` - The sales order is awaiting payment. `awaiting_shipment` - This sales order is awaiting shipment. `on_hold` - This sales order is on hold. `completed` - This sales order is completed. `cancelled` - This sales order has been cancelled.
`fieldMappings`	object	✔	A custom specified mapping for supported custom fields. The supported custom fields will be predefined by the app developer.
`fieldMappings .customField1`	number	✔	The custom field whose value that will map to the RequestedFulfillmentExtensions.CustomField1.
`fieldMappings .customField2`	number	✔	The custom field whose value that will map to the RequestedFulfillmentExtensions.CustomField2.
`fieldMappings .customField3`	string	✔	The custom field whose value that will map to the RequestedFulfillmentExtensions.CustomField3.

Return Value

`salesOrders`

An array of sales orders matching the date range.

Name	Type	Required?	Description
`id`	string	✔	The marketplace's unique ID for the sales order. This string must not contain newline characters.
`orderNumber`	string		Use this field when a marketplace provides a customer facing identifier for the order that is different from that order's unique id.
`createdDateTime`	Date Time, or Date object, or a string representing the date and time in ISO format.	✔	The date/time that the sales order was originally placed.
`lastModifiedDateTime`	Date Time, or Date object, or a string representing the date and time in ISO format.		The date/time that the sales order was last modified.
`status`	string	✔	The current status of this sales order. Valid values include the following: `awaiting_payment` - The sales order is awaiting payment. `awaiting_shipment` - This sales order is awaiting shipment. `on_hold` - This sales order is on hold. `completed` - This sales order is completed. `cancelled` - This sales order has been cancelled.
`buyer`	object	✔	The buyer who bought the order. This is not necessarily the same person as the `shipTo`.
`buyer.id`	string		The marketplace's unique ID for the buyer. This string must not contain newline characters.
`buyer.address`	address object		The address of the buyer.
`buyer.name`	object	✔	The name of the contact.
`buyer.name.title`	string		The title of the contact (eg "Mr", "Mrs", "Dr"). This string must not include newline characters.
`buyer.name.given`	string	✔	The first name of the signer. This string must not include newline characters.
`buyer.name.middle`	string		The middle name of the signer. This string must not include newline characters.
`buyer.name.family`	string		The last name or family name of the signer. This string must not include newline characters.
`buyer.name.suffix`	string		The suffix of the signer (eg "Sr", "Jr", "IV"). This string must not include newline characters.
`buyer.email`	string		The email address of the contact. This string must be a valid email address.
`buyer.phoneNumber`	string		The phone number of the contact. and must not include newline characters.
`requestedFulfillments`	object[]	✔	An array of fulfillment requests.
`requestedFulfillments[] .items`	sales order item object[]	✔	The items in this sales order.
`requestedFulfillments[] .shipTo`	address + contact info + pickup location object	✔	The address or pickup location where the sales order should be shipped. Be sure to include the extra contact info fields as indicated in the reference doc.
`requestedFulfillments[] .shippingPreferences`	shipping preferences object		Preferences on how this order should be fulfilled.
`originalOrderSource`	object		Information regarding the original order source. This is used when an order source is acting on behalf of other order sources, in order to persist information regarding the original order.
`originalOrderSource .sourceId`	string	✔	A unique identifier for the source marketplace.
`originalOrderSource .marketplaceCode`	string	✔	The code for the type of marketplace.
`originalOrderSource .orderId`	string	✔	The unique identifier for the order at the source marketplace.
`notes`	object[]		An array of objects containing additional information about this sales order.
`notes[].type`	notes type string	✔	The type for this note.
`notes[].text`	string	✔	The note text itself.
`metadata`	object		Custom data about this sales order that was persisted by ShipEngine Connect. Must be JSON serializable.
`paging`	object		An object that indicates that page preferences for the items that are returned from this method.
`paging.pageSize`	number		The desired maximum number of items to return. This value will always be provided and will be greater than zero.
`paging.pageNumber`	number		The desired page number to return. This value will always be provided and will be zero or greater.
`paging.pageCount`	number		he desired maximum number of pages to return. This value is optional.
`paging.cursor`	string		Identifies the next page of results to return. This value is optional.
`identifiers`	identifiers object		Your own identifiers for this sales order.
`paymentMethod`	string		Indicates how the customer has paid for the order. Valid values include the following: `cash` - The sales order was paid for with cash. `cash_equivalent` - The sales order was paid for with guaranteed funds, such as a cashier's check or money order. `check` - This sales order was paid for with a check. `credit_card` - This sales order was paid for with a credit card. `bank_transfer` - This sales order was paid for with a bank transfer.
`paymentStatus`	string		Indicates the status of the customer payment for the order. Valid values include the following: `awaiting_payment` - The sales order is still waiting on the customer's payment. `payment_cancelled` - The sales order payment was cancelled. `payment_failed` - The sales order payment failed. `payment_in_process` - The sales order payment is currently being processed. `paid` - The sales order has been payed for. `other` - The sales order payment is in an unknown state.
`paymentAmount`	object		The amount the customer has paid for the order.
`paymentAmount.value`	number	✔	The value for paymentAmount.
`paymentAmount.currency`	string	✔	The currency for paymentAmount.
`orderURL`	URL or string		The URL of a webpage where the customer can view the order. Must be a valid HTTP or HTTPS url.
`charges`	charge object[]		Any additional charges for this order that aren't tied to a line item.

Example

async function getSalesOrdersByDate(transaction, range) {
  // STEP 1: Validation
  // Add any desired validation here
  // STEP 2: Create the data that the order's API expects
  const data = {
    operation: "retrieve_sales_orders_by_date",
    session_id: transaction.session.id,
    start_date:  range.startDateTime,
    end_date: range.endDateTime
  };
  // STEP 3: Call the order source's API
  const response = await apiClient.request({ data });
  // Step 4: Create the output data that ShipEngine expects
  return formatSalesOrders(response.data);
}
function formatSalesOrders(salesOrders) {
  return salesOrders.map(salesOrder => {
    return {
      id: salesOrder.id,
      createdDateTime: salesOrder.createdDateTime,
      status: mapSalesOrderStatus(salesOrder.status),
      paymentMethod: mapPaymentMethod(salesOrder.payment.method),
      buyer: {
        id: salesOrder.buyer.id,
        name: salesOrder.buyer.name
      },
      requestedFulfillments: [
        {
          items: salesOrder.shipping_items.map((item) => {
            return {
              id: item.id,
              name: item.name,
              quantity: {
                value: item.quantity,
                unit: "ea"
              },
              unitPrice: {
                value: item.price_per_unit,
                currency: "USD"
              }
            }
        }),
        shipTo: salesOrder.ship_to
      }]
    }
  });
}

export default async function getSalesOrdersByDate(
  transaction: Transaction<Session>,
  range: SalesOrderTimeRange,
): Promise<Iterable<SalesOrder>> {
  // STEP 1: Validation
  // Add any desired validation here
  // STEP 2: Create the data that the order's API expects
  const data = {
    operation: "retrieve_sales_orders_by_date",
    session_id: transaction.session.id,
    start_date:  range.startDateTime,
    end_date: range.endDateTime
  };
  // STEP 3: Call the order source's API
  const response = await apiClient.request<RetrieveSalesOrdersByDateResponse>({ data });
  // Step 4: Create the output data that ShipEngine expects
  return formatSalesOrders(response.data);
}