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.

NameTypeNullable?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.

pagingobject

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.pageSizenumber

The desired maximum number of items to return. This value will always be provided and will be greater than zero.

paging.pageCountnumber

he desired maximum number of pages to return. This value is optional.

paging.pageNumbernumber

The desired page number to return. This value will always be provided and will be zero or greater.

paging.cursorstring

Identifies the next page of results to return. This value is optional.

statusMappingsobject

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.
fieldMappingsobject

A custom specified mapping for supported custom fields. The supported custom fields will be predefined by the app developer.

fieldMappings   .customField1number

The custom field whose value that will map to the RequestedFulfillmentExtensions.CustomField1.

fieldMappings   .customField2number

The custom field whose value that will map to the RequestedFulfillmentExtensions.CustomField2.

fieldMappings   .customField3string

The custom field whose value that will map to the RequestedFulfillmentExtensions.CustomField3.

Return Value

salesOrders

An array of sales orders matching the date range.

NameTypeRequired?Description
idstring

The marketplace's unique ID for the sales order. This string must not contain newline characters.

orderNumberstring

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.

statusstring

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.
buyerobject

The buyer who bought the order. This is not necessarily the same person as the shipTo.

buyer.idstring

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.nameobject

The name of the contact.

buyer.name.titlestring

The title of the contact (eg "Mr", "Mrs", "Dr"). This string must not include newline characters.

buyer.name.givenstring

The first name of the signer. This string must not include newline characters.

buyer.name.middlestring

The middle name of the signer. This string must not include newline characters.

buyer.name.familystring

The last name or family name of the signer. This string must not include newline characters.

buyer.name.suffixstring

The suffix of the signer (eg "Sr", "Jr", "IV"). This string must not include newline characters.

buyer.emailstring

The email address of the contact. This string must be a valid email address.

buyer.phoneNumberstring

The phone number of the contact. and must not include newline characters.

requestedFulfillmentsobject[]

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.

originalOrderSourceobject

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   .sourceIdstring

A unique identifier for the source marketplace.

originalOrderSource   .marketplaceCodestring

The code for the type of marketplace.

originalOrderSource   .orderIdstring

The unique identifier for the order at the source marketplace.

notesobject[]

An array of objects containing additional information about this sales order.

notes[].type

notes type string

The type for this note.

notes[].textstring

The note text itself.

metadataobject

Custom data about this sales order that was persisted by ShipEngine Connect. Must be JSON serializable.

pagingobject

An object that indicates that page preferences for the items that are returned from this method.

paging.pageSizenumber

The desired maximum number of items to return. This value will always be provided and will be greater than zero.

paging.pageNumbernumber

The desired page number to return. This value will always be provided and will be zero or greater.

paging.pageCountnumber

he desired maximum number of pages to return. This value is optional.

paging.cursorstring

Identifies the next page of results to return. This value is optional.

identifiers

identifiers object

Your own identifiers for this sales order.

paymentMethodstring

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.
paymentStatusstring

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.
paymentAmountobject

The amount the customer has paid for the order.

paymentAmount.valuenumber

The value for paymentAmount.

paymentAmount.currencystring

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);
}