Collapse Menu
Docs Home
Extensibility Options
Contact Support

/orders

Overview

This article provides information about the /orders endpoint of the FastSpring API.

Overview

This article provides information about the /orders endpoint of the FastSpring API.

You can use this endpoint to retrieve information about a single order or retrieve a list of multiple orders matching a set of criteria.

Orders can be retrieved by order ID, product path, or date range. You can optionally combine parameters in your request, for example retrieving all orders for a certain product that occurred in a given date range.

When retrieving multiple orders, the response will be paginated with a limit of 50 records per page by default. To assist with paging through the results, you can optionally specify a custom limit to the number of records per page, and the desired page number in your request.

 

 

Get Orders

Request Parameters

ParameterValuesDescription
beginyyyy-mm-ddfilters results to include transactions after the specified begin date (must be at least one day prior to specified end date)
endyyyy-mm-ddfilters results to include transactions before the specified end date
limitintegerlimits the number of order records returned per page (default is 50 records)
pageintegerspecifies page number of results to be returned; used together with limit to control pagination
productsstringfilters results to include only transactions involving the specified product ID(s) / product path(s)
rebilltrue/falsefilters results to include only subscription rebill transactions or exclude all subscription rebill transactions
returnstrue/falsefilters results to include orders with or without returns; response includes returns array with return IDs where applicable
scopeall, live, testfilters results to include live transactions, test transactions, or both
statuscompleted, canceled, failedfilters results by transaction status; "completed" = successful orders, "canceled" = declined orders, "failed" = transaction failed to complete (very uncommon)

 

Examples

Example 1: Get orders by ID
GET /orders/{id1}[,{id2},{id3},...]

 Note

If you specify more than one order ID in the same GET request, the response will include an orders array (e.g. { orders: [ ) at the top level, consisting of each individual order object. The example below illustrates the response when requesting a single order ID.
Response example
{
    "order": "oN5eASPKTM2Jwkx15ICNyg",                                // internal order ID
    "id": "oN5eASPKTM2Jwkx15ICNyg",                                   // backward compatibility
    "reference": "FUR191015-1265-35113",                              // customer-facing order reference
    "buyerReference": null,                                           // optional purchase order number entered by the customer
    "completed": true,                                                // false if order failed, was declined, or is pending
    "changed": 1571172709980,                                         // date of the most recent update to this order record, in milliseconds
    "changedValue": 1571172709980,                                    // date of the most recent update to this order record, in milliseconds (backward compatibility)
    "changedInSeconds": 1571172709,                                   // date of the most recent update to this order record, in seconds
    "changedDisplay": "10/15/19",                                     // date of the most recent update to this order record, formatted for display based on the language in which the order was processed, as selected by the customer
    "language": "en",                                                 // ISO 2-character language code for the language in which the order was processed, as selected by the customer
    "live": false,                                                    // true if not a test order
    "currency": "USD",
    "payoutCurrency": "USD",
    "invoiceUrl": "https://furiousfalcon.onfastspring.com/account/order/FUR191015-1265-35113/invoice",
    "account": "N8FjcSWcQNeYCc-suM1O8g",                              // FastSpring-generated customer account ID
    "total": 36.15,
    "totalDisplay": "$36.15",
    "totalInPayoutCurrency": 36.15,
    "totalInPayoutCurrencyDisplay": "$36.15",
    "tax": 0.0,
    "taxDisplay": "$0.00",
    "taxInPayoutCurrency": 0.0,
    "taxInPayoutCurrencyDisplay": "$0.00",
    "subtotal": 36.15,
    "subtotalDisplay": "$36.15",
    "subtotalInPayoutCurrency": 36.15,
    "subtotalInPayoutCurrencyDisplay": "$36.15",
    "discount": 0.0,
    "discountDisplay": "$0.00",
    "discountInPayoutCurrency": 0.0,
    "discountInPayoutCurrencyDisplay": "$0.00",
    "discountWithTax": 0.0,
    "discountWithTaxDisplay": "$0.00",
    "discountWithTaxInPayoutCurrency": 0.0,
    "discountWithTaxInPayoutCurrencyDisplay": "$0.00",
    "billDescriptor": "FS* FALCON",
    "payment": {
        "type": "test",                                               // payment method: "paypal", "amazon", "creditcard", "test", "bank", "alipay", "purchase-order", "free"
        "creditCard": "visa",                                         // ONLY appears when "type" = "creditcard". Values = "visa", "mastercard", "amex", "discover", "jcb", "carteblanche", "dinersclub", "unionpay"
	"cardEnding": "4242",                                         // ONLY appears when "type" = "creditcard". Last four digits of the card number
	"bank": "sofort"                                              // ONLY appears when "type" = "bank". Values = "wire", "brazilwire", "ideal", "giropay", "sofort", "ecard", "sepa", "alipay"
    },
    "customer": {
        "first": "Leeroy",
        "last": "Jenkins",
        "email": "ne1@all.com",
        "company": null,
        "phone": null
    },
    "address": {
        "addressLine1": "801 Garden St.",                             // for physical product purchase or when Storefront is configured to force collection
		"city": "Santa Barbara",
        "regionCode": "CA",                                           // US orders only; ISO 2-character state code; only appears for physical product purchase or when Storefront is configured to force collection
        "regionDisplay": "California",                                // state or region of the address, formatted for display
        "region": "California",                                       // for physical product purchase or when Storefront is configured to force collection                 
        "postalCode": "93101",
        "country": "US",
        "display": "Santa Barbara, California, 93101, US"
    },
    "recipients": [
        {
            "recipient": {
                "first": "Leeroy",
                "last": "Jenkins",
                "email": "ne1@all.com",
                "company": null,
                "phone": null,
                "account": "N8FjcSWcQNeYCc-suM1O8g",
                "address": {
                    "city": "Santa Barbara",
                    "regionCode": "CA",
                    "regionDisplay": "California",
                    "region": "California",
                    "postalCode": "93101",
                    "country": "US",
                    "display": "Santa Barbara, California, 93101, US"
                }
            }
        }
    ],
    "notes": [],
    "items": [
        {
            "product": "falcon-monthly-subscriptions",
            "quantity": 1,
            "display": "Falcon Monthly Subscription",
            "sku": "furious10",
            "subtotal": 14.95,
            "subtotalDisplay": "$14.95",
            "subtotalInPayoutCurrency": 14.95,
            "subtotalInPayoutCurrencyDisplay": "$14.95",
            "attributes": {
                "CustomAttribute1": "CustomValue1",                   // key and value are defined under Products > More > Custom Attributes (Advanced)
                "CustomAttribute2": "CustomValue2",                   // key and value are defined under Products > More > Custom Attributes (Advanced)
                "Furious": "Falcon"                                   // key and value are defined under Products > More > Custom Attributes (Advanced)
            },
            "discount": 0.0,
            "discountDisplay": "$0.00",
            "discountInPayoutCurrency": 0.0,
            "discountInPayoutCurrencyDisplay": "$0.00",
            "coupon": "FREE",                                         // coupon code (not coupon path / ID) applied to the current order item (ONLY appears when applicable)                               
    	    "subscription": "73lsX5kvRsWKLzwRNMkcow",                 // FastSpring-generated subscription ID for the subscription associated with the current item
            "fulfillments": {
                "falcon-monthly-subscriptions_file_0": [
                    {
                        "display": "FALCON4.exe",
                        "size": 129,
                        "file": "https://furiousfalcon.onfastspring.com/account/file/FUR191015-1265-46134F",
                        "type": "file"
                    }
                ],
                "falcon-monthly-subscriptions_license_1": [
                    {
                        "license": "s5cMEOpM0zP5KQqD5Wps",
                        "display": "License Key",
                        "type": "license"
                    }
                ],
                "instructions": "Thank you for subscribing to Falcon."
            }
        },
        {
            "product": "nest-basic",
            "quantity": 1,
            "display": "Nest Basic",
            "sku": "falcon9",
            "subtotal": 9.95,
            "subtotalDisplay": "$9.95",
            "subtotalInPayoutCurrency": 9.95,
            "subtotalInPayoutCurrencyDisplay": "$9.95",
            "discount": 0.0,
            "discountDisplay": "$0.00",
            "discountInPayoutCurrency": 0.0,
            "discountInPayoutCurrencyDisplay": "$0.00",
            "coupon": "FREE",                                         // coupon code (not coupon path / ID) applied to the current order item (ONLY appears when applicable)
            "fulfillments": {
                "nest-basic_license_0": [
                    {
                        "license": "ejTUv8dpuJWZQ5lMN6YE",
                        "display": "License Key",
                        "type": "license"
                    }
                ],
                "nest-basic_file_1": [
                    {
                        "display": "Nest.exe",
                        "size": 5769,
                        "file": "https://furiousfalcon.onfastspring.com/account/file/FUR191015-1265-67116F",
                        "type": "file"
                    }
                ]                
            },
            "driver": {                                              // when the current order item is linked to another item (e.g. offered as a cross-sell or a subscription addon), this describes that relationship and identifies the parent item
                "type": "addon",                                     // current item's relationship to the parent item:  "cross-sell", "options", "bundle", "configuration", "addon" or "one_time_fee"
                "path": "falcon-monthly-subscriptions"               // product path / ID of the parent or triggering item
            }
        },
        {
            "product": "falcon-monthly-subscriptions.setupFee",
            "quantity": 1,
            "display": "One-time Setup Fee",
            "sku": null,
            "subtotal": 10.0,
            "subtotalDisplay": "$10.00",
            "subtotalInPayoutCurrency": 10.0,
            "subtotalInPayoutCurrencyDisplay": "$10.00",
            "discount": 0.0,
            "discountDisplay": "$0.00",
            "discountInPayoutCurrency": 0.0,
            "discountInPayoutCurrencyDisplay": "$0.00",
            "coupon": "FREE",                                         // coupon code (not coupon path / ID) applied to the current order item (ONLY appears when applicable)
            "fulfillments": {},
            "driver": {                                              // when the current order item is linked to another item (e.g. offered as a cross-sell or a subscription addon), this describes that relationship and identifies the parent item
                "type": "one_time_fee",                              // current item's relationship to the parent item:  "cross-sell", "options", "bundle", "configuration", "addon" or "one_time_fee"
                "path": "falcon-monthly-subscriptions"               // product path / ID of the parent or triggering item
            }
        },
        {
            "product": "eggs",
            "quantity": 1,
            "display": "Eggs",
            "sku": "falcon1",
            "subtotal": 1.25,
            "subtotalDisplay": "$1.25",
            "subtotalInPayoutCurrency": 1.25,
            "subtotalInPayoutCurrencyDisplay": "$1.25",
            "attributes": {
                "conditions": "{exclude:{countries:['AT','GB']}}"
            },
            "discount": 0.0,
            "discountDisplay": "$0.00",
            "discountInPayoutCurrency": 0.0,
            "discountInPayoutCurrencyDisplay": "$0.00",
            "coupon": "FREE",                                         // coupon code (not coupon path / ID) applied to the current order item (ONLY appears when applicable)
            "fulfillments": {
                "eggs_file_1": [
                    {
                        "display": "Eggs.exe",
                        "size": 5769,
                        "file": "https://furiousfalcon.onfastspring.com/account/file/FUR191015-1265-14137F",
                        "type": "file"
                    }
                ],
                "instructions": "Thank you for purchasing Eggs. To register, please launch the trial version and select Help -> Register Eggs. Then, copy and paste the license key below into the License Key field and click Submit."
            },
            "driver": {                                              // when the current order item is linked to another item (e.g. offered as a cross-sell or a subscription addon), this describes that relationship and identifies the parent item
                "type": "cross-sell",                                // current item's relationship to the parent item:  "cross-sell", "options", "bundle", "configuration", "addon" or "one_time_fee"
                "path": "falcon-monthly-subscriptions"               // product path / ID of the parent or triggering item
            }
        }
    ]
}



 
Possible Error Response Example
{
  "orders": [
    {
      "action": "order.get",
      "order": "zSprqRHITGeW0kSGC7AKmh",                                // order ID requested
      "result": "error",
      "error": {
        "order": "Not found"
      }
    }  
  ]
}

 

 

Get orders by product path

Example 2: Get orders by product path
GET /orders?products=product1,product2&limit=20&page=1
Response example
{
   "action": "order.lookup",
   "result": "success",
   "page": 1,
   "limit": 20,
   "nextPage": 2,
   "total": 1006,
   "orders":    [
            {
         "order": "nlqoczuZSaGKzuNNK5IDiQ",
         "id": "nlqoczuZSaGKzuNNK5IDiQ",
         "reference": null,
         "completed": false,
         "changed": 1471997419992,
         "changedValue": 1471997419992,
         "changedInSeconds": 1471997419,
         "changedDisplay": "8/24/16",
         "language": "en",
         "live": false,
         "currency": "USD",
         "account": "KJRTYQByS_WIcVQ-AZp6kw",
         "payoutCurrency": "USD",
         "invoiceUrl": "https://furiousfalcon.onfastspring.com/account/order/null/invoice",
         "total": 10,
         "totalDisplay": "$10.00",
         "totalInPayoutCurrency": 10,
         "totalInPayoutCurrencyDisplay": "$10.00",
         "tax": 0,
         "taxDisplay": "$0.00",
         "taxInPayoutCurrency": 0,
         "taxInPayoutCurrencyDisplay": "$0.00",
         "subtotal": 10,
         "subtotalDisplay": "$10.00",
         "subtotalInPayoutCurrency": 10,
         "subtotalInPayoutCurrencyDisplay": "$10.00",
         "discount": 0,
         "discountDisplay": "$0.00",
         "discountInPayoutCurrency": 0,
         "discountInPayoutCurrencyDisplay": "$0.00",
         "discountWithTax": 0,
         "discountWithTaxDisplay": "$0.00",
         "discountWithTaxInPayoutCurrency": 0,
         "discountWithTaxInPayoutCurrencyDisplay": "$0.00",
         "payment": {},
         "customer":          {
            "first": "New",
            "last": "Order",
            "email": "ne1@all.com",
            "company": null,
            "phone": "1234567890"
         },
         "address":          {
              "city": "Santa Barbara",
              "regionCode": "CA",
              "regionDisplay": "California",
              "region": "California",
              "postalCode": "93101",
              "country": "US",
              "display": "Santa Barbara, California, 93101, US"         
         },
         "recipients": [
              {
                 "recipient": {
                     "first": "New",
                     "last": "Order",
                     "email": "ne1@all.com",
                     "company": null,
                     "phone": "1234567890",
                     "account": "KJRTYQByS_WIcVQ-AZp6kw",
                     "address": {
                         "city": "Santa Barbara",
                         "regionCode": "CA",
                         "regionDisplay": "California",
                         "region": "California",
                         "postalCode": "93101",
                         "country": "US",
                         "display": "Santa Barbara, California, 93101, US"
                     }
                 }
             }
         ],
         "notes": [],
         "items": [         {
            "product": "suba",
            "quantity": 1,
            "display": "PaymentReminderBeforeUpdate",
            "sku": "SKU111",
            "subtotal": 10,
            "subtotalDisplay": "$10.00",
            "subtotalInPayoutCurrency": 10,
            "subtotalInPayoutCurrencyDisplay": "$10.00",
            "discount": 0,
            "discountDisplay": "$0.00",
            "discountInPayoutCurrency": 0,
            "discountInPayoutCurrencyDisplay": "$0.00",
            "subscription": "YDnZ-ExrQ3mWe0YTmSsQaQ"
         }
         ]
      }
     ...
    ]
  }
  

Get orders by date range

Example 3: Get orders by date range
GET /orders?begin=yyyy-mm-dd&end=yyyy-mm-dd&limit=30&page=4
Response example
{
   "action": "order.lookup",
   "result": "success",
   "begin": "6/1/16",
   "end": "8/30/16",
   "page": 4,
   "limit": 30,
   "nextPage": 5,
   "total": 1048,
   "orders":    [
            {
         "order": "Qf1jNhlCSKGW5RJdfM7cTg",
         "id": "Qf1jNhlCSKGW5RJdfM7cTg",
         "reference": "FUR160824-6097-31167",
         "completed": true,
         "changed": 1472061802969,
         "changedValue": 1472061802969,
         "changedInSeconds": 1472061802,
         "changedDisplay": "8/24/16",
         "language": "en",
         "live": false,
         "currency": "USD",
         "account": "cZnOkAUIQ2qCtcrTtyXgYQ",
         "payoutCurrency": "USD",
         "invoiceUrl": "https://furiousfalcon.onfastspring.com/account/order/FUR160824-6097-31167/invoice",
         "total": 19.44,
         "totalDisplay": "$19.44",
         "totalInPayoutCurrency": 19.44,
         "totalInPayoutCurrencyDisplay": "$19.44",
         "tax": 1.44,
         "taxDisplay": "$1.44",
         "taxInPayoutCurrency": 1.44,
         "taxInPayoutCurrencyDisplay": "$1.44",
         "subtotal": 18,
         "subtotalDisplay": "$18.00",
         "subtotalInPayoutCurrency": 18,
         "subtotalInPayoutCurrencyDisplay": "$18.00",
         "discount": 2,
         "discountDisplay": "$2.00",
         "discountInPayoutCurrency": 2,
         "discountInPayoutCurrencyDisplay": "$2.00",
         "discountWithTax": 2.16,
         "discountWithTaxDisplay": "$2.16",
         "discountWithTaxInPayoutCurrency": 2.16,
         "discountWithTaxInPayoutCurrencyDisplay": "$2.16",
         "payment": {
           "type": "free",                                                 // payment method: "paypal", "amazon", "creditcard", "test", "bank", "alipay", "purchase-order", "free"
           "creditcard": "visa",                                           // ONLY appears when "type" = "creditcard". Values = "visa", "mastercard", "amex", "discover", "jcb", "carteblanche", "dinersclub", "unionpay"
           "cardEnding": "4242",                                           // ONLY appears when "type" = "creditcard". Last four digits of the card number
           "bank": "sofort"                                                // ONLY appears when "type" = "bank". Values = "wire", "brazilwire", "ideal", "giropay", "sofort", "ecard", "sepa", "alipay"         
         },
         "customer":          {
            "first": "Reenable",
            "last": "MailingList",
            "email": "ne1@all.com",
            "company": null,
            "phone": "1234567890"
         },
         "address":          {
              "city": "Santa Barbara",
              "regionCode": "CA",
              "regionDisplay": "California",
              "region": "California",
              "postalCode": "93101",
              "country": "US",
              "display": "Santa Barbara, California, 93101, US"
         },         
         "recipients": [
              {
                 "recipient": {
                     "first": "Reenable",
                     "last": "MailingList",
                     "email": "ne1@all.com",
                     "company": null,
                     "phone": "1234567890",
                     "account": "KJRTYQByS_WIcVQ-AZp6kw",
                     "address": {
                         "city": "Santa Barbara",
                         "regionCode": "CA",
                         "regionDisplay": "California",
                         "region": "California",
                         "postalCode": "93101",
                         "country": "US",
                         "display": "Santa Barbara, California, 93101, US"
                     }
                 }
             }
         ],
         "notes": [],
         "items":          [
                        {
               "product": "physical",
               "quantity": 1,
               "display": "Physical",
               "sku": null,
               "subtotal": 9,
               "subtotalDisplay": "$9.00",
               "subtotalInPayoutCurrency": 9,
               "subtotalInPayoutCurrencyDisplay": "$9.00",
               "attributes": {"SystemExtension.eds": "true"},
               "discount": 1,
               "discountDisplay": "$1.00",
               "discountInPayoutCurrency": 1,
               "discountInPayoutCurrencyDisplay": "$1.00",
               "coupon": "TEST",
               "fulfillments": {"physical_file_0": [               {
                  "display": "malware.zip",
                  "size": 4106,
                  "file": "https://furiousfalcon.onfastspring.com/account/file/FUR160824-6097-46172F",
                  "type": "file"
               }]}
            },
                        {
               "product": "SystemExtension.eds",
               "quantity": 1,
               "display": "EDS",
               "sku": null,
               "subtotal": 9,
               "subtotalDisplay": "$9.00",
               "subtotalInPayoutCurrency": 9,
               "subtotalInPayoutCurrencyDisplay": "$9.00",
               "attributes": {"SystemExtension.eds": "true"},
               "discount": 1,
               "discountDisplay": "$1.00",
               "discountInPayoutCurrency": 1,
               "discountInPayoutCurrencyDisplay": "$1.00",
               "coupon": "TEST",
               "fulfillments": {}
            }
         ],
         "coupons": ["TEST"]
      }
      ...
    ]
  }
  
 
Possible Error Response Example
// invalid begin or end date
{
  "action": "order.lookup",
  "result": "error",
  "error": {

    "begin": "Invalid begin date"
    "end": "End date must be after begin date"
  }
}

 

 

Get orders by product path AND date range

Example 4: Get orders by product path AND date range
GET /orders?products=product1&begin=yyyy-mm-dd&end=yyyy-mm-dd&limit=10&page=1
Response example
{
   "action": "order.lookup",
   "result": "success",
   "begin": "6/1/16",
   "end": "7/30/16",
   "page": 1,
   "limit": 10,
   "nextPage": null,
   "total": 5,
   "orders":    [
            {
         "order": "sHwVlGLER9qJHKr6lkX5oA",
         "id": "sHwVlGLER9qJHKr6lkX5oA",
         "reference": "FUR160710-2490-94117",
         "completed": true,
         "changed": 1468120080887,
         "changedValue": 1468120080887,
         "changedInSeconds": 1468120080,
         "changedDisplay": "7/10/16",
         "language": "en",
         "live": false,
         "currency": "USD",
         "account": "E93cH9zLS6ebdnrUjCYLFA",
         "payoutCurrency": "USD",
         "invoiceUrl": "https://furiousfalcon.onfastspring.com/account/order/FUR160710-2490-94117/invoice",
         "total": 66.96,
         "totalDisplay": "$66.96",
         "totalInPayoutCurrency": 66.96,
         "totalInPayoutCurrencyDisplay": "$66.96",
         "tax": 4.96,
         "taxDisplay": "$4.96",
         "taxInPayoutCurrency": 4.96,
         "taxInPayoutCurrencyDisplay": "$4.96",
         "subtotal": 62,
         "subtotalDisplay": "$62.00",
         "subtotalInPayoutCurrency": 62,
         "subtotalInPayoutCurrencyDisplay": "$62.00",
         "discount": 0,
         "discountDisplay": "$0.00",
         "discountInPayoutCurrency": 0,
         "discountInPayoutCurrencyDisplay": "$0.00",
         "discountWithTax": 0,
         "discountWithTaxDisplay": "$0.00",
         "discountWithTaxInPayoutCurrency": 0,
         "discountWithTaxInPayoutCurrencyDisplay": "$0.00",
         "payment": {
            "type": "free",                                                 // payment method: "paypal", "amazon", "creditcard", "test", "bank", "alipay", "purchase-order", "free"
            "creditcard": "visa",                                           // ONLY appears when "type" = "creditcard". Values = "visa", "mastercard", "amex", "discover", "jcb", "carteblanche", "dinersclub", "unionpay"
            "cardEnding": "4242",                                           // ONLY appears when "type" = "creditcard". Last four digits of the card number
            "bank": "sofort"                                                // ONLY appears when "type" = "bank". Values = "wire", "brazilwire", "ideal", "giropay", "sofort", "ecard", "sepa", "alipay"
         },
         "customer":          {
            "first": "test",
            "last": "order",
            "email": "ne1@all.com",
            "company": null,
            "phone": "1234567890"
         },
         "address":          {
            "addressLine1": "801 Garden Street",
             "city": "Santa Barbara",
             "regionCode": "CA",
             "regionDisplay": "California",
             "region": "California",
             "postalCode": "93101",
             "country": "US",
             "display": "Santa Barbara, California, 93101, US"
         },
         "recipients": [
              {
                 "recipient": {
                     "first": "New",
                     "last": "Order",
                     "email": "ne1@all.com",
                     "company": null,
                     "phone": "1234567890",
                     "account": "KJRTYQByS_WIcVQ-AZp6kw",
                     "address": {
                         "addressLine1": "801 Garden Street",
                         "city": "Santa Barbara",
                         "regionCode": "CA",
                         "regionDisplay": "California",
                         "region": "California",
                         "postalCode": "93101",
                         "country": "US",
                         "display": "Santa Barbara, California, 93101, US"
                     }
                 }
             }
         ],
         "notes": [],
         "items":          [
                        {
               "product": "testbundle",
               "quantity": 3,
               "display": "TestBundle",
               "sku": null,
               "subtotal": 30,
               "subtotalDisplay": "$30.00",
               "subtotalInPayoutCurrency": 30,
               "subtotalInPayoutCurrencyDisplay": "$30.00",
               "attributes": {"SystemExtension.eds": "true"},
               "discount": 0,
               "discountDisplay": "$0.00",
               "discountInPayoutCurrency": 0,
               "discountInPayoutCurrencyDisplay": "$0.00",
               "fulfillments": {}
            },
                        {
               "product": "physical",
               "quantity": 3,
               "display": "Physical",
               "sku": null,
               "subtotal": 0,
               "subtotalDisplay": "$0.00",
               "subtotalInPayoutCurrency": 0,
               "subtotalInPayoutCurrencyDisplay": "$0.00",
               "attributes": {"SystemExtension.eds": "true"},
               "discount": 0,
               "discountDisplay": "$0.00",
               "discountInPayoutCurrency": 0,
               "discountInPayoutCurrencyDisplay": "$0.00",
               "fulfillments": {"physical_file_0": [               {
                  "display": "malware.zip",
                  "size": 4106,
                  "file": "https://automation.test.qa.onfastspring.com/account/file/FUR160710-2490-43134F",
                  "type": "file"
               }]}
            },
                        {
               "product": "firstsub",
               "quantity": 3,
               "display": "firstSub",
               "sku": null,
               "subtotal": 0,
               "subtotalDisplay": "$0.00",
               "subtotalInPayoutCurrency": 0,
               "subtotalInPayoutCurrencyDisplay": "$0.00",
               "attributes": {"SystemExtension.eds": "true"},
               "discount": 0,
               "discountDisplay": "$0.00",
               "discountInPayoutCurrency": 0,
               "discountInPayoutCurrencyDisplay": "$0.00",
               "subscription": "KNj-JrZyQ7i2yALyv5nv7Q",
               "fulfillments":                {
                  "firstsub_license_0": [                  {
                     "license": "1",
                     "display": "License Key",
                     "type": "license"
                  }],
                  "firstsub_file_0": [                  {
                     "display": "poty2006.zip",
                     "size": 538835908,
                     "file": "https://automation.test.qa.onfastspring.com/account/file/FUR160710-2490-80119F",
                     "type": "file"
                  }]
               }
            },
                        {
               "product": "digitalphysical",
               "quantity": 1,
               "display": "digitalPhysical",
               "sku": null,
               "subtotal": 10,
               "subtotalDisplay": "$10.00",
               "subtotalInPayoutCurrency": 10,
               "subtotalInPayoutCurrencyDisplay": "$10.00",
               "attributes": {"SystemExtension.eds": "true"},
               "discount": 0,
               "discountDisplay": "$0.00",
               "discountInPayoutCurrency": 0,
               "discountInPayoutCurrencyDisplay": "$0.00",
               "fulfillments": {"digitalphysical_file_0": [               {
                  "display": "Anaconda2-2.4.1-MacOSX-x86_64.pkg",
                  "size": 257787337,
                  "file": "https://automation.test.qa.onfastspring.com/account/file/FUR160710-2490-25147F",
                  "type": "file"
               }]}
            },
                        {
               "product": "SystemExtension.shippingcalculation",
               "quantity": 1,
               "display": "Shipping",
               "sku": null,
               "subtotal": 12,
               "subtotalDisplay": "$12.00",
               "subtotalInPayoutCurrency": 12,
               "subtotalInPayoutCurrencyDisplay": "$12.00",
               "attributes": {"SystemExtension.eds": "true"},
               "discount": 0,
               "discountDisplay": "$0.00",
               "discountInPayoutCurrency": 0,
               "discountInPayoutCurrencyDisplay": "$0.00",
               "fulfillments": {}
            },
                        {
               "product": "SystemExtension.eds",
               "quantity": 1,
               "display": "EDS",
               "sku": null,
               "subtotal": 10,
               "subtotalDisplay": "$10.00",
               "subtotalInPayoutCurrency": 10,
               "subtotalInPayoutCurrencyDisplay": "$10.00",
               "attributes": {"SystemExtension.eds": "true"},
               "discount": 0,
               "discountDisplay": "$0.00",
               "discountInPayoutCurrency": 0,
               "discountInPayoutCurrencyDisplay": "$0.00",
               "fulfillments": {}
            }
         ]
      }
      ...
    ]
  }
  

 

Get orders using only an end date

Example 5: Get orders by specifying only the end date
// When no begin date is specified, the beginning date for the range defaults to 30 days
GET /orders?end=yyyy-mm-dd
Response example
{
   "action": "order.lookup",
   "result": "success",
   "end": "6/30/16",
   "page": 1,
   "limit": 50,
   "nextPage": null,
   "total": 9,
   "orders":    [
            {
         "order": "US5oKN5sRU2OUWxVwivl_Q",
         "id": "US5oKN5sRU2OUWxVwivl_Q",
         "reference": "FUR160629-3229-57108B",
         "completed": true,
         "changed": 1467239032151,
         "changedValue": 1467239032151,
         "changedInSeconds": 1467239032,
         "changedDisplay": "6/29/16",
         "language": "en",
         "live": false,
         "currency": "USD",
         "account": "E93cH9zLS6ebdnrUjCYLFA",
         "payoutCurrency": "USD",
         "invoiceUrl": "https://furiousfalcon.onfastspring.com/account/order/FUR160629-3229-57108B/invoice",
         "total": 10,
         "totalDisplay": "USD 10.00",
         "totalInPayoutCurrency": 10,
         "totalInPayoutCurrencyDisplay": "USD 10.00",
         "tax": 0,
         "taxDisplay": "USD 0.00",
         "taxInPayoutCurrency": 0,
         "taxInPayoutCurrencyDisplay": "USD 0.00",
         "subtotal": 10,
         "subtotalDisplay": "USD 10.00",
         "subtotalInPayoutCurrency": 10,
         "subtotalInPayoutCurrencyDisplay": "USD 10.00",
         "discount": 0,
         "discountDisplay": "USD 0.00",
         "discountInPayoutCurrency": 0,
         "discountInPayoutCurrencyDisplay": "USD 0.00",
         "discountWithTax": 0,
         "discountWithTaxDisplay": "USD 0.00",
         "discountWithTaxInPayoutCurrency": 0,
         "discountWithTaxInPayoutCurrencyDisplay": "USD 0.00",
         "payment": {
           "type": "free",                                                 // payment method: "paypal", "amazon", "creditcard", "test", "bank", "alipay", "purchase-order", "free"
           "creditcard": "visa",                                           // ONLY appears when "type" = "creditcard". Values = "visa", "mastercard", "amex", "discover", "jcb", "carteblanche", "dinersclub", "unionpay"
           "cardEnding": "4242",                                           // ONLY appears when "type" = "creditcard". Last four digits of the card number
           "bank": "sofort"                                                // ONLY appears when "type" = "bank". Values = "wire", "brazilwire", "ideal", "giropay", "sofort", "ecard", "sepa", "alipay"
         },
         "customer":          {
            "first": "test",
            "last": "test",
            "email": "ne1@all.com",
            "company": null,
            "phone": "1234567890"
         },
         "address":          {
            "addressLine1": "272 Gonghang-ro",
            "city": "Jung-gu",
            "region": "Incheon",
            "postalCode": "40765",
            "country": "KR",
            "display": "272 Gonghang-ro, Jung-gu, Incheon, 40765, KR"
         },
         "recipients": [
             {
                 "recipient": {
                     "first": "test",
                     "last": "test",
                     "email": "ne1@all.com",
                     "company": null,
                     "phone": 1234567890,
                     "account": "E93cH9zLS6ebdnrUjCYLFA",
                     "address": {
                         "addressLine1": "272 Gonghang-ro",
                         "city": "Jung-gu",
                         "region": "Incheon",
                         "postalCode": "40765",
                         "country": "KR",
                         "display": "272 Gonghang-ro, Jung-gu, Incheon, 40765, KR"
                     }
                 }
             }
         ],
         "notes": [],
         "items": [         {
            "product": "firstsub",
            "quantity": 1,
            "display": "firstSub",
            "sku": null,
            "subtotal": 10,
            "subtotalDisplay": "USD 10.00",
            "subtotalInPayoutCurrency": 10,
            "subtotalInPayoutCurrencyDisplay": "USD 10.00",
            "discount": 0,
            "discountDisplay": "USD 0.00",
            "discountInPayoutCurrency": 0,
            "discountInPayoutCurrencyDisplay": "USD 0.00",
            "subscription": "1hrkNaKxRyizVyj_Lv9RCA"
         }]
      }
      ...	  
    ]
  }

 

Get orders with returns only

Example 6: Get orders with returns only
GET /orders?begin=2018-07-16&end=2018-07-17&returns=true
Response example
{
    "action": "order.lookup",
    "result": "success",
    "begin": "7/16/18",
    "end": "7/17/18",
    "page": 1,
    "limit": 50,
    "nextPage": null,
    "total": 1,
    "orders": [
        {
            "order": "sLvABUuPTOmxuxxme6zyBA",
            "id": "sLvABUuPTOmxuxxme6zyBA",
            "reference": "FUR180716-1320-39108",
            "buyerReference": null,
            "completed": true,
            "changed": 1531768631874,
            "changedValue": 1531768631874,
            "changedInSeconds": 1531768631,
            "changedDisplay": "7/16/18",
            "language": "en",
            "live": false,
            "currency": "USD",
            "payoutCurrency": "USD",
            "invoiceUrl": "https://furiousfalcon.onfastspring.com/account/order/FUR180716-1320-39108/invoice",
            "account": "5ta9yueaQ2mlc3UeSZi2Ew",
            "total": 59.99,
            "totalDisplay": "USD 59.99",
            "totalInPayoutCurrency": 59.99,
            "totalInPayoutCurrencyDisplay": "USD 59.99",
            "tax": 0,
            "taxDisplay": "USD 0.00",
            "taxInPayoutCurrency": 0,
            "taxInPayoutCurrencyDisplay": "USD 0.00",
            "subtotal": 59.99,
            "subtotalDisplay": "USD 59.99",
            "subtotalInPayoutCurrency": 59.99,
            "subtotalInPayoutCurrencyDisplay": "USD 59.99",
            "discount": 0,
            "discountDisplay": "USD 0.00",
            "discountInPayoutCurrency": 0,
            "discountInPayoutCurrencyDisplay": "USD 0.00",
            "discountWithTax": 0,
            "discountWithTaxDisplay": "USD 0.00",
            "discountWithTaxInPayoutCurrency": 0,
            "discountWithTaxInPayoutCurrencyDisplay": "USD 0.00",
            "billDescriptor": "FS* fsprg.com",
            "payment": {
                "type": "test",
                "cardEnding": "4242"
            },
            "customer": {
                "first": "John",
                "last": "Doe",
                "email": "ne1@all.com",
                "company": null,
                "phone": null
            },
            "address": {
                "addressLine1": "123 Elm St",
                "city": "Lisbon",
                "regionDisplay": "",
                "region": "",
                "postalCode": "93101",
                "country": "DE",
                "display": "123 Elm St, Lisbon, , 93101, DE"
            },
            "recipients": [
               {
                   "recipient": {
                       "first": "John",
                       "last": "Doe",
                       "email": "ne1@all.com",
                       "company": null,
                       "phone": null,
                       "account": "5ta9yueaQ2mlc3UeSZi2Ew",
                       "address": {
                           "addressLine1": "123 Elm St",
                           "city": "Lisbon",
                           "regionDisplay": "",
                           "region": "",
                           "postalCode": "93101",
                           "country": "DE",
                           "display": "123 Elm St, Lisbon, , 93101, DE"
                       }
                   }
               }
            ],
            "notes": [],
            "items": [
                {
                    "product": "falcon",
                    "quantity": 1,
                    "display": "Furious Falcon",
                    "sku": "falcon6abc123",
                    "subtotal": 59.99,
                    "subtotalDisplay": "USD 59.99",
                    "subtotalInPayoutCurrency": 59.99,
                    "subtotalInPayoutCurrencyDisplay": "USD 59.99",
                    "discount": 0,
                    "discountDisplay": "USD 0.00",
                    "discountInPayoutCurrency": 0,
                    "discountInPayoutCurrencyDisplay": "USD 0.00",
                    "fulfillments": {
                        "falcon_license_0": [
                            {
                                "license": "Falcon-8QEl7sD8FKI56r4siL9c",
                                "display": "License Key",
                                "type": "license"
                            }
                        ],
                        "falcon_file_2": [
                            {
                                "display": "FALCON4.EXE",
                                "size": 129,
                                "file": "https://furiousfalcon.onfastspring.com/account/file/FUR180716-1320-64112F",
                                "type": "file"
                            }
                        ],
                        "instructions": "Thank you for purchasing Falcon."
                    }
                }
            ],
            "returns": [
                {
                    "return": "YxCkQcnTR_iX1iZJgQly8Q",
                    "amount": 59.99,
                    "amountDisplay": "USD 59.99",
                    "amountInPayoutCurrency": 59.99,
                    "amountInPayoutCurrencyDisplay": "USD 59.99"
                }
            ]
        }
    ]
}

 

Update Order Tags and Attributes

POST/orders

 Note

If you update order tags and / or product attributes, the current order tags or attributes will be replaced (the update does not append additional tags or attributes).

Subscription-related webhook events and API responses automatically pull order tags and product attributes from the original subscription order, so updating the tags or attributes of an order that created a subscription will effectively update the subscription as well.
Request Example
{
  "orders": [
    {
      "order": "JL4ltRyBSTS0myETu7yJIA",                                // order ID to be updated
      "tags": {
        "TagKey1": "TagValue1",                                         // order tag to be added or updated
        "TagKey2": "TagValue2"                                          // order tag to be added or updated
      },
      "items": [
        {
          "product": "product-path",                                    // product path of the product whose attributes will be added or updated
          "attributes": {
            "AttributeKey1": "AttributeValue1",                         // attribute to be added or updated
            "AttributeKey2": "AttributeValue2"                          // attribute to be added or updated
          }
        }
      ]
    }
  ]
}
 
Possible Error Responses
// Order ID not found


{
    "orders": [
        {
            "action": "order.update",
            "order": "[0]",
            "result": "error",
            "error": {
                "order": "Not found"
            }
        }
    ]
}


// Specified product path not found in specified order record


{
    "orders": [
        {
            "action": "order.update",
            "order": "JL4ltRyBSTS0myETu7yJIA",
            "result": "error",
            "error": {
                "items.eggs": "Product is not specified as a valid item in the order"
            }
        }
    ]
}

 

Try FastSpring

Get a free account and see why FastSpring is the ecommerce partner of choice for software providers around the world. Try our full-service ecommerce solution today to unlock revenue growth for your online company.