Returning a list of sales transactions

Learn how to get a list of sales transactions.

You can retrieve a list using specific query parameters to access detailed information about sales transactions. It allows you to filter, sort, and paginate the data according to your requirements, ensuring you receive only the most relevant and streamlined transactions. You can customize the returned data to best suit your operational or analytical needs by specifying parameters such as date ranges, transaction types, and identifiers.

Setting the sales transaction query parameters

You can set the appropriate query parameters to manage and analyze sales transactions. These parameters enable you to filter, sort, and paginate transaction data, making retrieving the information you need easier. By adjusting criteria such as date ranges, transaction identifiers, types, and amounts, you can streamline the data retrieval process, ensuring it aligns with operational requirements or analytical goals. Configure your queries to maximize the relevance and efficiency of the data you access.

Parameter	Optional/Required	Description
createdTime	Optional	A filter on the list based on the createdTime field. The value can be a string with an ISO-601 UTC format datetime, or it can be a dictionary with the following options: gt–return values where the createdTime field is after this timestamp gte–return values where the createdTime field is after or equal to this timestamp lt–return values where the createdTime field is before this timestamp lte–return values where the createdTime field is before or equal to this timestamp
updatedTime	Optional	A filter on the list based on the updatedTime field. The value can be a string with an ISO-601 UTC format datetime, or it can be a dictionary with the following options: gt–return values where the updatedTime field is after this timestamp gte–return values where the updatedTime field is after or equal to this timestamp lt–return values where the updatedTime field is before this timestamp lte–return values where the updatedTime field is before or equal to this timestamp
endingBefore	Optional	A cursor for use in pagination. The endingBefore parameter is an object identifier that defines your place in the list. For instance, if you make a list request and receive 100 objects starting with xyz, your subsequent calls can include endingBefore=xyz to fetch the previous page of the list.
startingAfter	Optional	A cursor for use in pagination. The startingAfter parameter is an object identifier that defines your place in the list. For instance, if you make a list request and receive 100 objects ending with xyz, your subsequent calls can include startingAfter=xyz to fetch the next page of the list.
limit	Optional	A limit on the number of objects returned. The limit can range between 1 and 100, and the default is 10.
ids	Optional	Only return objects with these identifiers.
saleTime	Optional	A filter on the list based on the sales transaction saleTime field. The value can be a string with an ISO-601 UTC format datetime or it can be a dictionary with the following options: gt–return values where the saleTime field is after this timestamp gte–return values where the saleTime field is after or equal to this timestamp lt–return values where the saleTime field is before this timestamp lte–return values where the saleTime field is before or equal to this timestamp
salesSummaryId		Only return sales transactions with this sales summary identifier.
type	Optional	Only return sales transactions of this type. The enum are sale, replacement, replacement_refund, replacement, replacement_return, fraud_chargeback, non_fraud_chargeback, refund, return, fraud_detection, or declined_settlement.
currency	Optional	Only return sales transactions in this currency.
orderId	Optional	Only return sales transactions with this order identifier.
skuId	Optional	Only return sales transactions with this SKU identifier.
quantity	Optional	A filter on the list based on the sales transaction quantity field. The value can be a string or it can be a dictionary with the following options: gt–return values where the quantity field is greater than this amount gte–return values where the quantity field is greater than or equal to this amount lt–return values where the quantity field is less than this amount lte–return values where the quantity field is less than or equal to this amount
amount	Optional	A filter on the list based on the sales transaction amount field. The value can be a string or it can be a dictionary with the following options: gt–return values where the amount field is greater than this amount gte–return values where the amount field is greater than or equal to this amount lt–return values where the amount field is less than this amount lte–return values where the amount field is less than or equal to this amount
digitalRiverShare	Optional	A filter on the list based on the sales transaction digitalRiverShare field. The value can be a string, or it can be a dictionary with the following options: gt–return values where the digitalRiverSharefield is greater than this amount gte–return values where the digitalRiverSharefield is greater than or equal to this amount lt–return values where the digitalRiverSharefield is less than this amount lte–return values where the digitalRiverSharefield is less than or equal to this amount
payoutAmount	Optional	A filter on the list based on the sales transaction payoutAmount field. The value can be a string, or it can be a dictionary with the following options: gt–return values where the payoutAmount field is greater than this amount gte–return values where the payoutAmount field is greater than or equal to this amount lt–return values where the payoutAmount field is less than this amount lte–return values where the payoutAmount field is less than or equal to this amount

Get sales transaction request and response example

You can use a GET /sales-transactions request to retrieve sales transaction details. This request fetches an array of sales transaction objects, each enriched with specific attributes such as id, createdTime, amount, and more. Below is an example showing how to perform this request using cURL, followed by a sample JSON response structure illustrating the comprehensive data returned by the API. This enables streamlined data handling and supports various operational needs.

Retrieve the details of sales transactions with a GET request:

cURL

curl https://api.digitalriver.com/sales-transactions

A 200 OK response returns an array of Sales Transaction objects:

JSON

{
  "hasMore": true,
  "data": [
    {
      "id": "0206802584_000010_3700005504",
      "createdTime": "2019-04-25T20:36:00Z",
      "updatedTime": "2019-04-26T20:36:00Z",
      "saleTime": "2019-04-25T00:00:00Z",
      "salesSummaryId": "8100000400_1410_2019",
      "currency": "GBP",
      "amount": 443.08,
      "type": "sale",
      "orderId": "37031462099",
      "skuId": "945-0198",
      "skuName": "test sku name",
      "quantity": 1,
      "payoutAmounts": {
        "currency": "USD",
        "exchangeRate": 1.24535,
        "amount": 551.79,
        "tax": -91.97,
        "shipping": -14.36,
        "regulatoryFees": 0,
        "landedCost": 0,
        "productPrice": 445.46,
        "digitalRiverShare": -41.38,
        "distributorShare": -375.61,
        "transactionFees": 0,
        "commission": 0,
        "shippingDiscount": 0,
        "regulatoryFeeDiscount": 0,
        "remitShipping": 0,
        "payoutAmount": 28.47
      },
      "payerId": "1410",
      "payerName": "DR globalTech, Inc.",
      "payeeId": "0013900100",
      "payeeName": "ACME, Inc.",
      "liveMode": true,
      "orderUpstreamId": "1fda6503-8399-43df-97e3-56d9912af7ed",
      "skuTaxCode": "55111509.12",
      "shipFromCountry": "US",
      "shipToCountry": "US",
      "billToCountry": "US",
      "shipFromState": "MN",
      "shipToState": "MN",
      "billToState": "MN",
      "paymentType": "creditCard",
      "orderMetadata": {
          "coupon": "iOS"
      },
      "lineItemMetadata": {
          "coupon": "iOS"
      }
  ]
}

Key sales transaction attributes

The following details the key attributes returned in response to a request for sales transaction information. For complete details, refer to the Sales transactions API reference.

id

A unique identifier is assigned to the sales transaction. A sales transaction is a fulfilled sales order line. Sales transactions are created at the fulfillment level. For example, let's say you have an order with line item 1 and line item 2. You'll see a single sales transaction if you fulfill line item 1. If you fulfill only half of the quantity of line item 2, you'll see another sales transaction created. When you finally fulfill the other half of the quantity of line 2, you will see a third new sales transaction.

createdTime

The time when the sales transaction was created in the reporting environment.

updatedTime

The time when the sales transaction was updated in the reporting environment.

saleTime

The time when the order line item was fulfilled. Digital River handles sales transactions at the fulfillment level. For example, let's say you have an order with line item 1 and line item 2. You'll see a single sales transaction if you fulfill line item 1. If you fulfill only half of the quantity of line item 2, you'll see another sales transaction created. When you finally fulfill the other half of the quantity of line 2, you will again see a new sales transaction.

salesSummaryId

A unique identifier for a sales summary associated with the specific sales transaction. Digital River initially creates the sales transactions without a salesSummaryId. This value is updated when the sales transaction and other sales transactions are added to the sales summary.

currency

The three-letter ISO currency code represents the currency used in the sales transaction.

amount

The total sales transaction amount in the customer's currency. This amount multiplied by the payoutAmounts.exchangeRate (see below) gives you the payoutAmounts.amount in the requested payout currency.

type

Designates the type of transaction, such as sale, return, refund, fraud_chargeback, and non_fraud_chargeback.

orderId

A unique identifier for the order.

skuId

A unique identifier for the SKU.

skuName

The name of the SKU

quantity

The quantity fulfilled for that SKU.

payoutAmounts

This section of returned data describes all information related to the payout amount. For example, in the payout process, you might sell something in Norwegian kroner, but in the payout step of the sales transaction, it would be converted to US dollars if that is the requested payout currency.

payoutAmounts.currency

The three-letter ISO currency code represents the type of currency used in the sales transaction payout.

payoutAmounts.exchangeRate

The exchange rate converts the sales amount from the sales order currency into the payout currency. Theamount (above) multiplied by the payoutAmounts.exchangeRate (see below) gives you the payoutAmounts.amount.

payoutAmounts.amount

The amount charged to the shopper for the fulfilled line item. The amount(see above) multiplied by the payoutAmounts.exchangeRate (see below) gives you the payoutAmounts.amount.

payoutAmounts.tax

The sales transaction tax amount in the currency used for the payout. The payoutAmounts.amount minus the payout tax, shipping, regulatory fees, and landed costs gets you thepayoutAmounts.productPrice.

payoutAmounts.shipping

The sales transaction shipping amount in the currency used for the payout. The payoutAmounts.amount minus payout tax, shipping, regulatory fees, and landed costs gets you thepayoutAmounts.productPrice.

payoutAmounts.regulatoryFees

The regulatory fees amount in the currency used for the payout. The payoutAmounts.amount minus payout tax, shipping, regulatory fees, and landed costs gets you thepayoutAmounts.productPrice.

payoutAmounts.landedCost

The landed costs amount. The payoutAmounts.amountminus payout tax, shipping, regulatory fees, and landed costs gets you the payoutAmounts.productPrice.

payoutAmounts.productPrice

The product price does not include any taxes or fees. The payoutAmounts.amount minus payout tax, shipping, regulatory fees, and landed costs gets you the payoutAmounts.productPrice.

payoutAmounts.digitalRiverShare

The margin that Digital River receives for services. The payoutAmounts.productPrice plus or minus the Digital River share, transaction fees, shipping discount, regulatory fee discount, and the shipping remittance amount gets you the total payout amount payoutAmounts.payoutAmount.

payoutAmounts.distributorShare

The distributor share amount. The value is always a "0."

payoutAmounts.transactionFees

The transaction fees amount. The payoutAmounts.productPrice plus or minus the Digital River share, transaction fees, shipping discount, regulatory fee discount, and the shipping remittance amount gets you the total payout amount payoutAmounts.payoutAmount.

payoutAmounts.commission

The commission is the amount allocated to compensate sales agents or partners for their service. The payoutAmounts.productPrice is adjusted by adding or subtracting this commission along with other elements like the Digital River share, transaction fees, and discounts to arrive at the total payoutAmounts.payoutAmount.

payoutAmounts.shippingDiscount

The shipping discount amount. The payoutAmounts.productPrice plus or minus the Digital River share, transaction fees, shipping discount, regulatory fee discount, and the shipping remittance amount gets you the total payout amount payoutAmounts.payoutAmount.

payoutAmounts.regulatoryFeeDiscount

The regulatory fee discount amount. The payoutAmounts.productPrice plus or minus the Digital River share, transaction fees, shipping discount, regulatory fee discount, and the shipping remittance amount gets you the total payout amount payoutAmounts.payoutAmount.

payoutAmounts.remitShipping

The shipping remittance amount. The payoutAmounts.productPrice plus or minus the Digital River share, transaction fees, shipping discount, regulatory fee discount, and the shipping remittance amount gets you the total payout amount payoutAmounts.payoutAmount.

payoutAmounts.payoutAmount

Total payout amount. The payoutAmounts.productPrice plus or minus the Digital River share, transaction fees, shipping discount, regulatory fee discount, and the shipping remittance amount gets you the total payout amount payoutAmounts.payoutAmount.

payerId

The ID of the payer.

payerName

The name of the payer.

payeeId

The ID of the payee.

payeeName

The name of the payee.

liveMode

If the value is true, the object exists in live mode. If the value is false, the object exists in test mode. Only live mode is supported.

orderUpstreamId

A unique identifier generated by the upstream application or commerce platform.

orderMetadata

This key-value pair stores additional order-level data. The values can be strings, booleans, or integers.

skuTaxCode

The skuTaxCode is a unique code assigned to a stock keeping unit (SKU) to categorize it for tax purposes. This code helps determine the applicable tax rate or exemptions based on the product's classification.

shipFromCountry

The shipFromCountry refers to the country from which the goods are dispatched. This information is crucial for determining international shipping rates, customs duties, and delivery times. The value is typically represented using the ISO 3166-1 alpha-2 country code format.

shipToCountry

The shipToCountry specifies the destination country where the goods are to be delivered. This information is essential for calculating appropriate shipping costs and taxes and ensuring compliance with local import regulations. The value is represented using the ISO 3166-1 alpha-2 country code format.

billToCountry

The billToCountry indicates the country where the billing for the transaction is processed. This information is necessary for determining applicable sales taxes and compliance with regional financial regulations. The value is represented using the ISO 3166-1 alpha-2 country code format.

shipFromState

The shipFromState indicates the state or region from which the goods are shipped. This information is vital for determining origin-based taxes and shipping logistics. The value is usually represented using standard state or region codes applicable to the shipping country.

shipToState

The shipToState indicates the state or region where the goods are being delivered. This information is essential for determining destination-based taxes and optimizing delivery routes. The value is typically represented using standard state or region codes applicable to the destination country.

billToState

The billToState specifies the state or region within the billing country where the transaction is processed. This information is crucial for calculating accurate regional taxes and ensuring compliance with state-level regulations. The value is typically represented using the standard state or region codes relevant to the billing country.

paymentType

The paymentType specifies the method of payment used in the transaction. Common values include credit cards, debit cards, PayPal, and bank transfers. This information is critical for processing transactions and may influence applicable service fees or processing times.

lineItemMetadata

This key-value pair stores additional line-item-level data. The values can be strings, booleans, or integers.